feat: mv renderingOptions => blockedResourceTypes

BREAKING CHANGE: renames “renderingOptions” to “blockedResourceTypes”. Default is now “None”

fix for issue #113

Author: blakebyrnes

client/interfaces/IAgentDefaults.ts

@@ -1,7 +1,7 @@
-import { IRenderingOption } from '@secret-agent/core-interfaces/ITabOptions';
+import { IBlockedResourceType } from '@secret-agent/core-interfaces/ITabOptions';
 import IUserProfile from '@secret-agent/core-interfaces/IUserProfile';
 
 export default interface IAgentDefaults {
-  defaultRenderingOptions?: IRenderingOption[];
+  defaultBlockedResourceTypes?: IBlockedResourceType[];
   defaultUserProfile?: IUserProfile;
 }

client/lib/Agent.ts

@@ -1,5 +1,5 @@
 // eslint-disable-next-line max-classes-per-file
-import { RenderingOption } from '@secret-agent/core-interfaces/ITabOptions';
+import { BlockedResourceType } from '@secret-agent/core-interfaces/ITabOptions';
 import StateMachine from 'awaited-dom/base/StateMachine';
 import initializeConstantsAndProperties from 'awaited-dom/base/initializeConstantsAndProperties';
 import { bindFunctions } from '@secret-agent/commons/utils';
@@ -33,7 +33,7 @@ import createConnection from '../connections/createConnection';
 import IAgentConfigureOptions from '../interfaces/IAgentConfigureOptions';
 
 export const DefaultOptions = {
-  defaultRenderingOptions: [RenderingOption.All],
+  defaultBlockedResourceTypes: [BlockedResourceType.None],
   defaultUserProfile: {},
 };
 const scriptInstance = new ScriptInstance();
@@ -71,7 +71,8 @@ export default class Agent extends AwaitedEventTarget<{ close: void }> {
     initializeConstantsAndProperties(this, [], propertyKeys);
     bindFunctions(this);
 
-    options.renderingOptions = options.renderingOptions || Agent.options.defaultRenderingOptions;
+    options.blockedResourceTypes =
+      options.blockedResourceTypes || Agent.options.defaultBlockedResourceTypes;
     options.userProfile = options.userProfile || Agent.options.defaultUserProfile;
 
     const sessionName = scriptInstance.generateSessionName(options.name);

core-interfaces/IConfigureSessionOptions.ts

@@ -3,5 +3,10 @@ import ICreateSessionOptions from './ICreateSessionOptions';
 export default interface IConfigureSessionOptions
   extends Pick<
     ICreateSessionOptions,
-    'userProfile' | 'viewport' | 'timezoneId' | 'locale' | 'upstreamProxyUrl' | 'renderingOptions'
+    | 'userProfile'
+    | 'viewport'
+    | 'timezoneId'
+    | 'locale'
+    | 'upstreamProxyUrl'
+    | 'blockedResourceTypes'
   > {}

core-interfaces/ITabOptions.ts

@@ -1,16 +1,15 @@
 export default interface ITabOptions {
-  renderingOptions?: IRenderingOption[];
+  blockedResourceTypes?: IBlockedResourceType[];
 }
 
-export enum RenderingOption {
-  AwaitedDOM = 'AwaitedDOM',
+export enum BlockedResourceType {
   JsRuntime = 'JsRuntime',
-  LoadJsResources = 'LoadJsResources',
-  LoadCssResources = 'LoadCssResources',
-  LoadImages = 'LoadImages',
-  LoadResources = 'LoadResources',
+  BlockJsResources = 'BlockJsResources',
+  BlockCssResources = 'BlockCssResources',
+  BlockImages = 'BlockImages',
+  BlockAssets = 'BlockAssets',
   All = 'All',
   None = 'None',
 }
 
-export type IRenderingOption = keyof typeof RenderingOption;
+export type IBlockedResourceType = keyof typeof BlockedResourceType;

core/lib/Session.ts

@@ -88,15 +88,18 @@ export default class Session extends TypedEventEmitter<{
       log.warn('BrowserEmulators.PolyfillNotSupported', {
         sessionId: this.id,
         browserEmulatorId: this.browserEmulatorId,
-    userAgentString: this.browserEmulator.userAgentString,
+        userAgentString: this.browserEmulator.userAgentString,
         runtimeOs: Os.platform(),
       });
     }
 
     this.timezoneId = options.timezoneId;
     this.viewport = options.viewport;
     if (!this.viewport) {
-      this.viewport = Viewports.getDefault(this.browserEmulator.windowFraming, this.browserEmulator.windowFramingBase);
+      this.viewport = Viewports.getDefault(
+        this.browserEmulator.windowFraming,
+        this.browserEmulator.windowFramingBase,
+      );
     }
 
     this.humanEmulatorId = options.humanEmulatorId || HumanEmulators.getRandomId();
@@ -131,8 +134,8 @@ export default class Session extends TypedEventEmitter<{
       this.upstreamProxyUrl = options.upstreamProxyUrl;
       this.mitmRequestSession.upstreamProxyUrl = options.upstreamProxyUrl;
     }
-    if (options.renderingOptions !== undefined) {
-      for (const tab of this.tabs) await tab.setRenderingOptions(options.renderingOptions);
+    if (options.blockedResourceTypes !== undefined) {
+      for (const tab of this.tabs) await tab.setBlockedResourceTypes(options.blockedResourceTypes);
     }
     if (options.viewport !== undefined) this.viewport = options.viewport;
     if (options.userProfile !== undefined) {

core/lib/Tab.ts

@@ -1,6 +1,6 @@
 import { v1 as uuidv1 } from 'uuid';
 import Log from '@secret-agent/commons/Logger';
-import { IRenderingOption } from '@secret-agent/core-interfaces/ITabOptions';
+import { IBlockedResourceType } from '@secret-agent/core-interfaces/ITabOptions';
 import {
   ILocationStatus,
   ILocationTrigger,
@@ -143,27 +143,31 @@ export default class Tab extends TypedEventEmitter<ITabEventParams> {
     ]);
   }
 
-  public async setRenderingOptions(renderingOptions: IRenderingOption[]): Promise<void> {
+  public async setBlockedResourceTypes(
+    blockedResourceTypes: IBlockedResourceType[],
+  ): Promise<void> {
     const mitmSession = this.session.mitmRequestSession;
     const blockedResources = mitmSession.blockedResources.types;
     let enableJs = true;
 
-    if (renderingOptions.includes('All')) {
+    if (blockedResourceTypes.includes('None')) {
       blockedResources.length = 0;
-    } else if (renderingOptions.includes('None')) {
+    } else if (blockedResourceTypes.includes('All')) {
       blockedResources.push('Image', 'Stylesheet', 'Script', 'Font', 'Ico', 'Media');
       enableJs = false;
+    } else if (blockedResourceTypes.includes('BlockAssets')) {
+      blockedResources.push('Image', 'Stylesheet', 'Script');
     } else {
-      if (!renderingOptions.includes('LoadImages')) {
+      if (blockedResourceTypes.includes('BlockImages')) {
         blockedResources.push('Image');
       }
-      if (!renderingOptions.includes('LoadCssResources')) {
+      if (blockedResourceTypes.includes('BlockCssResources')) {
         blockedResources.push('Stylesheet');
       }
-      if (!renderingOptions.includes('LoadJsResources')) {
+      if (blockedResourceTypes.includes('BlockJsResources')) {
         blockedResources.push('Script');
       }
-      if (!renderingOptions.includes('JsRuntime')) {
+      if (blockedResourceTypes.includes('JsRuntime')) {
         enableJs = false;
       }
     }
@@ -513,8 +517,8 @@ export default class Tab extends TypedEventEmitter<ITabEventParams> {
     }
 
     await this.interactor.initialize();
-    if (this.session.options?.renderingOptions) {
-      await this.setRenderingOptions(this.session.options.renderingOptions);
+    if (this.session.options?.blockedResourceTypes) {
+      await this.setBlockedResourceTypes(this.session.options.blockedResourceTypes);
     }
   }
 

emulate-browsers/base/lib/DomDiffLoader.ts

@@ -30,7 +30,8 @@ function extractFilename(filenames: string[]) {
   for (const filename of filenames) {
     const matches = filename.match(/^dom-diffs-when-using-([a-z-]+)(-([0-9-]+))?.json$/);
     if (!matches) continue;
-    const [osName, _, osVersion] = matches.slice(1); // eslint-disable-line @typescript-eslint/naming-convention
+
+    const [osName, _, osVersion] = matches.slice(1); // eslint-disable-line @typescript-eslint/naming-convention,@typescript-eslint/no-unused-vars
     filenameMap[osName] = filenameMap[osName] || {};
     filenameMap[osName][osVersion || 'ALL'] = filename;
   }

full-client/test/basic.test.ts

@@ -1,4 +1,5 @@
 import { Helpers } from '@secret-agent/testing';
+import Resource from '@secret-agent/client/lib/Resource';
 import { Handler } from '../index';
 
 let koaServer;
@@ -22,6 +23,42 @@ describe('basic Full Client tests', () => {
     expect(url).toBe(koaServer.baseHost);
   });
 
+  it('allows you to block resources', async () => {
+    koaServer.get('/block', ctx => {
+      ctx.body = `<html>
+<head>
+  <link rel="stylesheet" href="/test.css" />
+</head>
+<body>
+  <img src="/img.png" alt="Image"/>
+</body>
+</html>`;
+    });
+
+    koaServer.get('/img.png', ctx => {
+      ctx.statusCode = 500;
+    });
+    koaServer.get('/test.css', ctx => {
+      ctx.statusCode = 500;
+    });
+
+    const agent = await handler.createAgent({
+      blockedResourceTypes: ['BlockAssets'],
+    });
+    Helpers.needsClosing.push(agent);
+
+    const resources: Resource[] = [];
+    await agent.activeTab.on('resource', event => resources.push(event));
+    await agent.goto(`${koaServer.baseUrl}/block`);
+    await agent.waitForAllContentLoaded();
+    expect(resources).toHaveLength(3);
+    for (const resource of resources) {
+      const status = await resource.response.statusCode;
+      if (resource.type === 'Document') expect(status).toBe(200);
+      else expect(status).toBe(404);
+    }
+  });
+
   it('should get unreachable proxy errors in the client', async () => {
     const agent = await handler.createAgent({
       upstreamProxyUrl: koaServer.baseUrl,

puppet-chrome/lib/BrowserContext.ts

@@ -17,7 +17,6 @@ import IRegisteredEventListener from '@secret-agent/core-interfaces/IRegisteredE
 import { Page } from './Page';
 import { Browser } from './Browser';
 import { CDPSession } from './CDPSession';
-import { Worker } from './Worker';
 import Frame from './Frame';
 import CookieParam = Protocol.Network.CookieParam;
 import TargetInfo = Protocol.Target.TargetInfo;

website/docs/BasicInterfaces/Agent.md

@@ -59,7 +59,7 @@ const { Agent } = require('secret-agent');
   - timezoneId `string`. Overrides the host timezone. A list of valid ids are available at [unicode.org](https://unicode-org.github.io/cldr-staging/charts/37/supplemental/zone_tzid.html)
   - locale `string`. Overrides the host languages settings (eg, en-US). Locale will affect navigator.language value, Accept-Language request header value as well as number and date formatting rules.
   - viewport `IViewport`. Sets the emulated screen size, window position in the screen, inner/outer width and height. If not provided, the most popular resolution is used from [statcounter.com](https://gs.statcounter.com/screen-resolution-stats/desktop/united-states-of-america).
-  - renderingOptions `string[]`. Controls browser functionality.
+  - blockedResourceTypes `string[]`. Controls browser resource loading.
   - userProfile `IUserProfile`. Previous user's cookies, session, etc.
   - showReplay `boolean`. Whether or not to show the Replay UI. Can also be set with an env variable: `SA_SHOW_REPLAY=true`.
   - upstreamProxyUrl `string`. A socks5 or http proxy url (and optional auth) to use for all HTTP requests in this session. Dns over Tls requests will also use this proxy, if provided. The optional "auth" should be included in the UserInfo section of the url, eg: `http://username:password@proxy.com:80`.
@@ -165,7 +165,7 @@ Update existing configuration settings.
   - timezoneId `string`. Overrides the host timezone. A list of valid ids are available at [unicode.org](https://unicode-org.github.io/cldr-staging/charts/37/supplemental/zone_tzid.html)
   - locale `string`. Overrides the host languages settings (eg, en-US). Locale will affect navigator.language value, Accept-Language request header value as well as number and date formatting rules.
   - viewport `IViewport`. Sets the emulated screen size, window position in the screen, inner/outer width.
-  - renderingOptions `string[]`. Controls enabled browser rendering features.
+  - blockedResourceTypes `string[]`. Controls browser resource loading.
   - upstreamProxyUrl `string`. A socks5 or http proxy url (and optional auth) to use for all HTTP requests in this session. The optional "auth" should be included in the UserInfo section of the url, eg: `http://username:password@proxy.com:80`.
   - coreConnection `options | CoreClientConnection`. An object containing `ICoreConnectionOptions` used to connect, or an already created `CoreClientConnection` instance. Defaults to automatically connecting to a local `Core`.