Feat configure plugins

core/lib/CorePlugins.ts

@@ -9,12 +9,14 @@ import ICorePlugins from '@ulixee/hero-interfaces/ICorePlugins';
 import { PluginTypes } from '@ulixee/hero-interfaces/IPluginTypes';
 import IEmulationProfile from '@ulixee/unblocked-specification/plugin/IEmulationProfile';
 import Agent from '@ulixee/unblocked-agent/lib/Agent';
+import { PluginConfigs } from '@ulixee/unblocked-specification/plugin/IUnblockedPlugin';
 import Core from '../index';
 
 interface IOptionsCreate {
   dependencyMap?: IDependencyMap;
   corePluginPaths?: string[];
   getSessionSummary?: () => ISessionSummary;
+  pluginConfigs?: PluginConfigs;
 }
 
 interface IDependencyMap {
@@ -34,13 +36,15 @@ export default class CorePlugins implements ICorePlugins {
   private readonly logger: IBoundLog;
   private agent: Agent;
   private getSessionSummary: IOptionsCreate['getSessionSummary'];
+  private pluginConfigs: PluginConfigs;
 
   constructor(
     agent: Agent,
     options: IOptionsCreate,
     private corePluginsById: { [id: string]: ICorePluginClass },
   ) {
     const { dependencyMap, corePluginPaths, getSessionSummary } = options;
+    this.pluginConfigs = options.pluginConfigs ?? {};
     this.agent = agent;
 
     if (getSessionSummary) this.getSessionSummary = getSessionSummary;
@@ -53,9 +57,14 @@ export default class CorePlugins implements ICorePlugins {
     this.logger = agent.logger.createChild(module);
 
     for (const plugin of Object.values(corePluginsById)) {
-      const shouldActivate =
-        plugin.shouldActivate?.(agent.emulationProfile, getSessionSummary()) ?? true;
-      if (shouldActivate) this.use(plugin);
+      const config = this.pluginConfigs[plugin.id];
+      // true shortcircuits and skips shouldActivate check, we also skip running the shouldActivate function.
+      const shouldActivate = (): boolean | undefined =>
+        plugin.shouldActivate?.(agent.emulationProfile, getSessionSummary(), config);
+      if (config !== true && (config === false || shouldActivate() === false)) {
+        continue;
+      }
+      this.use(plugin);
     }
 
     if (Core.allowDynamicPluginLoading) {
@@ -101,11 +110,14 @@ export default class CorePlugins implements ICorePlugins {
 
   public use(CorePlugin: ICorePluginClass): void {
     if (this.instanceById[CorePlugin.id]) return;
+
+    const config = this.pluginConfigs[CorePlugin.id];;
     const corePlugin = new CorePlugin({
       emulationProfile: this.agent.emulationProfile,
       logger: this.logger,
       corePlugins: this,
       sessionSummary: this.sessionSummary,
+      customConfig: typeof config === 'boolean' ? undefined : config,
     });
     this.instances.push(corePlugin);
     this.instanceById[corePlugin.id] = corePlugin;

core/lib/Session.ts

@@ -582,6 +582,8 @@ export default class Session
       id: this.id,
       commandMarker: this.commands,
       userAgentOption: userProfile?.userAgent,
+      plugins: options.unblockedPlugins,
+      pluginConfigs: options.pluginConfigs,
     });
 
     this.plugins = new CorePlugins(
@@ -590,6 +592,7 @@ export default class Session
         corePluginPaths: options.corePluginPaths,
         dependencyMap: options.dependencyMap,
         getSessionSummary: this.getSummary.bind(this),
+        pluginConfigs: options.pluginConfigs,
       },
       this.core.corePluginsById,
     );

core/test/connection.test.ts

@@ -15,7 +15,7 @@ afterEach(Helpers.afterEach);
 describe('basic connection tests', () => {
   it('should throw an error informing how to install dependencies', async () => {
     class CustomEmulator extends DefaultBrowserEmulator {
-      public static id = 'emulate-test';
+      public static override id = 'emulate-test';
       public override onNewBrowser() {
         // don't change launch args so it doesn't reuse a previous one
       }

core/test/domRecorder.test.ts

@@ -12,6 +12,7 @@ let connectionToClient: ConnectionToHeroClient;
 beforeAll(async () => {
   Core.defaultUnblockedPlugins.push(
     class BasicHumanEmulator {
+      static id = 'BasicHumanEmulator';
       async playInteractions(interactionGroups, runFn): Promise<void> {
         for (const group of interactionGroups) {
           for (const step of group) {

docs/basic-client/hero.md

@@ -90,6 +90,7 @@ const Hero = require('@ulixee/hero-playground');
     - proxyIp `string`. The optional IP address of your proxy, if known ahead of time.
     - publicIp `string`. The optional IP address of your host machine, if known ahead of time.
   - sessionPersistence `boolean`. Do not save the [Session](../advanced-concepts/sessions.md) database if set to `false`. Defaults to `true` so you can troubleshoot errors, and load/extract data from previous sessions.
+  - pluginConfigs `Record<PluginId=string, boolean | object>`: object use to configure hero core and unblocked plugins. Object is indexed with the id of a specific plugin. Storing `true` will always enable the plugin (if loaded) and skip shouldEnable function. Same for `false` but that will disable it instead. It also possible to storing a custom `object` in there that the plugin can then use to configure itself.
 
 ## Properties
 

interfaces/ICorePlugin.ts

@@ -1,5 +1,8 @@
 import { IFrame } from '@ulixee/unblocked-specification/agent/browser/IFrame';
-import IUnblockedPlugin from '@ulixee/unblocked-specification/plugin/IUnblockedPlugin';
+import IUnblockedPlugin, {
+  PluginCustomConfig,
+} from '@ulixee/unblocked-specification/plugin/IUnblockedPlugin';
+
 import IEmulationProfile from '@ulixee/unblocked-specification/plugin/IEmulationProfile';
 import { IPage } from '@ulixee/unblocked-specification/agent/browser/IPage';
 import { PluginTypes } from './IPluginTypes';
@@ -11,13 +14,14 @@ export default interface ICorePlugin extends ICorePluginMethods, IUnblockedPlugi
   readonly sessionSummary?: ISessionSummary;
 }
 
-export interface ICorePluginClass {
+export interface ICorePluginClass<C extends object = any> {
   id: string;
   type: keyof typeof PluginTypes;
   new (createOptions: ICorePluginCreateOptions): ICorePlugin;
   shouldActivate?(
     emulationProfile: IEmulationProfile<unknown>,
     sessionSummary: ISessionSummary,
+    customConfig?: PluginCustomConfig<C>,
   ): boolean;
 }
 

interfaces/ICorePluginCreateOptions.ts

@@ -1,11 +1,13 @@
 import { IBoundLog } from '@ulixee/commons/interfaces/ILog';
 import IEmulationProfile from '@ulixee/unblocked-specification/plugin/IEmulationProfile';
+import { PluginCustomConfig } from '@ulixee/unblocked-specification/plugin/IUnblockedPlugin';
 import ICorePlugins from './ICorePlugins';
 import { ISessionSummary } from './ICorePlugin';
 
-export default interface ICorePluginCreateOptions {
+export default interface ICorePluginCreateOptions<C extends object = any> {
   emulationProfile: IEmulationProfile;
   corePlugins: ICorePlugins;
   sessionSummary: ISessionSummary;
   logger: IBoundLog;
+  customConfig?: PluginCustomConfig<C>
 }

interfaces/ISessionCreateOptions.ts

@@ -1,4 +1,5 @@
 import { IEmulationOptions } from '@ulixee/unblocked-specification/plugin/IEmulationProfile';
+import { IUnblockedPluginClass, PluginConfigs } from '@ulixee/unblocked-specification/plugin/IUnblockedPlugin';
 import IUserProfile from './IUserProfile';
 import ISessionOptions from './ISessionOptions';
 import IScriptInvocationMeta from './IScriptInvocationMeta';
@@ -24,4 +25,7 @@ export default interface ISessionCreateOptions extends ISessionOptions, IEmulati
   showChromeAlive?: boolean;
   desktopConnectionId?: string;
   showChromeInteractions?: boolean;
+  // Config use to configure all unblocked, and hero core plugins
+  pluginConfigs?: PluginConfigs;
+  unblockedPlugins?: IUnblockedPluginClass[];
 }

package.json

@@ -19,6 +19,7 @@
     "clean": "tsc -b --clean  tsconfig.json",
     "test:build": "cross-env NODE_ENV=test ULX_DATA_DIR=.data-test jest",
     "test": "ulx-repo-after-build && cd build && yarn test:build",
+    "test:debug": "yarn build && yarn copy:build && cd ./build && cross-env ULX_DATA_DIR=.data-test NODE_ENV=test node --inspect node_modules/.bin/jest --runInBand",
     "lint": "eslint --cache ./",
     "version:check": "ulx-repo-version-check fix",
     "version:bump": "ulx-repo-version-bump"

plugins/execute-js/package.json

@@ -12,6 +12,7 @@
     "@ulixee/execute-js-plugin": "2.0.0-alpha.28",
     "@ulixee/hero": "2.0.0-alpha.28",
     "@ulixee/hero-core": "2.0.0-alpha.28",
+    "@ulixee/net": "2.0.0-alpha.28",
     "@ulixee/hero-testing": "2.0.0-alpha.28"
   }
 }

plugins/execute-js/test/config.test.ts

@@ -0,0 +1,124 @@
+import { Helpers, Hero } from '@ulixee/hero-testing';
+import Core from '@ulixee/hero-core';
+import { CorePlugin } from '@ulixee/execute-js-plugin';
+import ICorePluginCreateOptions from '@ulixee/hero-interfaces/ICorePluginCreateOptions';
+import ICorePlugin, { ISessionSummary } from '@ulixee/hero-interfaces/ICorePlugin';
+import type IEmulationProfile from '@ulixee/unblocked-specification/plugin/IEmulationProfile';
+import type { PluginCustomConfig } from '@ulixee/unblocked-specification/plugin/IUnblockedPlugin';
+import { TransportBridge } from '@ulixee/net';
+import { ConnectionToHeroCore } from '@ulixee/hero';
+
+let core: Core;
+let connectionToCore: ConnectionToHeroCore;
+afterAll(Helpers.afterAll);
+afterEach(async () => {
+  await Helpers.afterEach();
+  await core.close();
+});
+
+beforeEach(async () => {
+  core = await Core.start();
+  const bridge = new TransportBridge();
+  core.addConnection(bridge.transportToClient);
+  connectionToCore = new ConnectionToHeroCore(bridge.transportToCore);
+});
+
+test('it should receive a custom config', async () => {
+  const testConfig = { test: 'testData' };
+  const constructor = jest.fn();
+  const shouldActivate = jest.fn();
+
+  class TestingExecuteJsCorePlugin1 extends CorePlugin {
+    static override id = 'TestingExecuteJsCorePlugin1';
+    constructor(opts: ICorePluginCreateOptions) {
+      super(opts);
+      constructor(opts.customConfig);
+    }
+
+    static shouldActivate?(
+      _emulationProfile: IEmulationProfile<unknown>,
+      _sessionSummary: ISessionSummary,
+      customConfig?: PluginCustomConfig,
+    ): boolean {
+      shouldActivate(customConfig);
+      return true;
+    }
+  }
+
+  core.use(TestingExecuteJsCorePlugin1);
+  const hero = new Hero({
+    connectionToCore,
+    pluginConfigs: {
+      [TestingExecuteJsCorePlugin1.id]: testConfig,
+    },
+  });
+
+  Helpers.onClose(() => hero.close(), true);
+
+  await hero.sessionId;
+  expect(constructor).toHaveBeenCalledWith(testConfig);
+  expect(shouldActivate).toHaveBeenCalledWith(testConfig);
+  await hero.close();
+});
+
+test('it should not activate if config === false', async () => {
+  const constructor = jest.fn();
+  const shouldActivate = jest.fn();
+
+  class TestingExecuteJsCorePlugin2 extends CorePlugin implements ICorePlugin {
+    static override id = 'TestingExecuteJsCorePlugin2';
+    constructor(opts: ICorePluginCreateOptions) {
+      super(opts);
+      constructor();
+    }
+
+    static shouldActivate(): boolean {
+      shouldActivate();
+      return true;
+    }
+  }
+  core.use(TestingExecuteJsCorePlugin2);
+
+  const hero = new Hero({
+    pluginConfigs: {
+      [TestingExecuteJsCorePlugin2.id]: false,
+    },
+  });
+  Helpers.onClose(() => hero.close(), true);
+
+  await hero.sessionId;
+  expect(shouldActivate).not.toHaveBeenCalled();
+  expect(constructor).not.toHaveBeenCalled();
+  await hero.close();
+});
+
+test('it should skip shouldActivate if config === true', async () => {
+  const constructor = jest.fn();
+  const shouldActivate = jest.fn();
+
+  class TestingExecuteJsCorePlugin3 extends CorePlugin implements ICorePlugin {
+    static override id = 'TestingExecuteJsCorePlugin3';
+    constructor(opts: ICorePluginCreateOptions) {
+      super(opts);
+      constructor();
+    }
+
+    static shouldActivate(): boolean {
+      shouldActivate();
+      return false;
+    }
+  }
+  core.use(TestingExecuteJsCorePlugin3);
+
+  const hero = new Hero({
+    pluginConfigs: {
+      [TestingExecuteJsCorePlugin3.id]: true,
+    },
+  });
+  Helpers.onClose(() => hero.close(), true);
+
+  await hero.sessionId;
+  expect(shouldActivate).not.toHaveBeenCalled();
+  expect(constructor).toHaveBeenCalled();
+  await hero.close();
+});

testing/TestHero.ts

@@ -5,7 +5,7 @@ import TransportBridge from '@ulixee/net/lib/TransportBridge';
 let core: Core;
 export default class TestHero extends DefaultHero {
   constructor(createOptions: IHeroCreateOptions = {}) {
-    createOptions.connectionToCore = TestHero.getDirectConnectionToCore();
+    createOptions.connectionToCore ??= TestHero.getDirectConnectionToCore();
     super(createOptions);
   }