browser-commander 0.11.0 → 0.13.0

package/tests/e2e/playwright.e2e.test.js

@@ -522,5 +522,24 @@ describe(
         // Test passes if no error is thrown
       });
     });
+
+    describe('In-memory Content', () => {
+      it('should load HTML through commander.setContent', async () => {
+        if (!commander) {
+          return;
+        }
+
+        const result = await commander.setContent({
+          html: '<main><h1 data-testid="content-title">In memory</h1></main>',
+          waitUntil: 'load',
+        });
+        const title = await commander.textContent({
+          selector: '[data-testid="content-title"]',
+        });
+
+        assert.strictEqual(result.loaded, true);
+        assert.strictEqual(title, 'In memory');
+      });
+    });
   }
 );

package/tests/e2e/puppeteer.e2e.test.js

@@ -476,4 +476,23 @@ describe('E2E Tests - Puppeteer Engine', { skip: !process.env.RUN_E2E }, () => {
       assert.strictEqual(modalClosed, false);
     });
   });
+
+  describe('In-memory Content', () => {
+    it('should load HTML through commander.setContent', async () => {
+      if (!commander) {
+        return;
+      }
+
+      const result = await commander.setContent({
+        html: '<main><h1 data-testid="content-title">In memory</h1></main>',
+        waitUntil: 'load',
+      });
+      const title = await commander.textContent({
+        selector: '[data-testid="content-title"]',
+      });
+
+      assert.strictEqual(result.loaded, true);
+      assert.strictEqual(title, 'In memory');
+    });
+  });
 });

package/tests/helpers/mocks.js

@@ -90,6 +90,7 @@ export function createMockPlaywrightPage(options = {}) {
     _isPlaywrightPage: true,
     url: () => url,
     goto: async (targetUrl, opts = {}) => {},
+    setContent: async (html, opts = {}) => {},
     waitForNavigation: async (opts = {}) => {},
     waitForSelector: async (sel, opts = {}) => locatorMock(sel),
     $: async (sel) => locatorMock(sel),
@@ -196,6 +197,7 @@ export function createMockPuppeteerPage(options = {}) {
     _isPuppeteerPage: true,
     url: () => url,
     goto: async (targetUrl, opts = {}) => {},
+    setContent: async (html, opts = {}) => {},
     waitForNavigation: async (opts = {}) => {},
     waitForSelector: async (sel, opts = {}) => elementMock(sel),
     $: async (sel) => {
@@ -441,6 +443,7 @@ export function createMockNavigationManager(options = {}) {
       url = opts.url || url;
       return true;
     },
+    setContent: async (opts = {}) => true,
     waitForNavigation: async (opts = {}) => true,
     waitForPageReady: async (opts = {}) => true,
     isNavigating: () => navigating,

package/tests/unit/bindings.test.js

@@ -61,6 +61,10 @@ describe('bindings', () => {
         typeof bindings.goto === 'function',
         'goto should be a function'
       );
+      assert.ok(
+        typeof bindings.setContent === 'function',
+        'setContent should be a function'
+      );
       assert.ok(
         typeof bindings.getUrl === 'function',
         'getUrl should be a function'

package/tests/unit/browser/connector.test.js

@@ -0,0 +1,129 @@
+import assert from 'node:assert';
+import { describe, it } from 'node:test';
+
+import {
+  connectBrowser,
+  connectBrowserWithDependencies,
+} from '../../../src/browser/connector.js';
+import { connectBrowser as publicConnectBrowser } from '../../../src/index.js';
+
+describe('connectBrowser', () => {
+  it('is exported from the package API', () => {
+    assert.equal(publicConnectBrowser, connectBrowser);
+  });
+
+  it('attaches Playwright over an HTTP CDP endpoint and reuses its first page', async () => {
+    const calls = [];
+    const page = { id: 'playwright-page' };
+    const context = {
+      pages: () => [page],
+      addCookies: async (cookies) => calls.push(['cookies', cookies]),
+    };
+    const browser = { contexts: () => [context] };
+    const chromium = {
+      connectOverCDP: async (endpoint, options) => {
+        calls.push(['connect', endpoint, options]);
+        return browser;
+      },
+    };
+    const seedCookies = [
+      { name: 'SID', value: 'saved', domain: '.example.com', path: '/' },
+    ];
+
+    const result = await connectBrowserWithDependencies(
+      {
+        engine: 'playwright',
+        cdpEndpoint: 'http://127.0.0.1:9222',
+        slowMo: 25,
+        timeout: 5_000,
+        seedCookies,
+      },
+      { loadPlaywright: async () => ({ chromium }) }
+    );
+
+    assert.equal(result.browser, browser);
+    assert.equal(result.page, page);
+    assert.deepEqual(calls, [
+      ['connect', 'http://127.0.0.1:9222', { slowMo: 25, timeout: 5_000 }],
+      ['cookies', seedCookies],
+    ]);
+  });
+
+  it('maps a WebSocket endpoint to Puppeteer and creates a page when needed', async () => {
+    const calls = [];
+    const page = {
+      id: 'new-puppeteer-page',
+      setCookie: async (...cookies) => calls.push(['cookies', cookies]),
+    };
+    const browser = {
+      pages: async () => [],
+      newPage: async () => {
+        calls.push(['newPage']);
+        return page;
+      },
+    };
+    const puppeteer = {
+      connect: async (options) => {
+        calls.push(['connect', options]);
+        return browser;
+      },
+    };
+    const seedCookies = [
+      { name: 'session', value: 'saved', domain: '.example.com', path: '/' },
+    ];
+
+    const result = await connectBrowserWithDependencies(
+      {
+        engine: 'puppeteer',
+        wsEndpoint: 'ws://127.0.0.1:9222/devtools/browser/id',
+        slowMo: 10,
+        protocolTimeout: 30_000,
+        seedCookies,
+      },
+      { loadPuppeteer: async () => ({ default: puppeteer }) }
+    );
+
+    assert.equal(result.browser, browser);
+    assert.equal(result.page, page);
+    assert.deepEqual(calls, [
+      [
+        'connect',
+        {
+          browserWSEndpoint: 'ws://127.0.0.1:9222/devtools/browser/id',
+          defaultViewport: null,
+          slowMo: 10,
+          protocolTimeout: 30_000,
+        },
+      ],
+      ['newPage'],
+      ['cookies', seedCookies],
+    ]);
+  });
+
+  it('requires exactly one endpoint and a supported engine', async () => {
+    await assert.rejects(
+      () => connectBrowserWithDependencies({ engine: 'playwright' }, {}),
+      /exactly one of cdpEndpoint or wsEndpoint/
+    );
+    await assert.rejects(
+      () =>
+        connectBrowserWithDependencies(
+          {
+            engine: 'playwright',
+            cdpEndpoint: 'http://127.0.0.1:9222',
+            wsEndpoint: 'ws://127.0.0.1:9222/devtools/browser/id',
+          },
+          {}
+        ),
+      /exactly one of cdpEndpoint or wsEndpoint/
+    );
+    await assert.rejects(
+      () =>
+        connectBrowserWithDependencies(
+          { engine: 'invalid', cdpEndpoint: 'http://127.0.0.1:9222' },
+          {}
+        ),
+      /Invalid engine: invalid/
+    );
+  });
+});

package/tests/unit/browser/navigation.test.js

@@ -5,6 +5,7 @@ import {
   verifyNavigation,
   waitForUrlStabilization,
   goto,
+  setContent,
   waitForNavigation,
   waitForPageReady,
   waitAfterAction,
@@ -203,6 +204,66 @@ describe('navigation', () => {
     });
   });
 
+  describe('setContent', () => {
+    it('should throw when html is not provided', async () => {
+      const page = createMockPlaywrightPage();
+
+      await assert.rejects(() => setContent({ page }), /html is required/);
+    });
+
+    it('should load content using navigationManager', async () => {
+      const page = createMockPlaywrightPage();
+      const navigationManager = createMockNavigationManager();
+      let receivedOptions;
+      navigationManager.setContent = async (options) => {
+        receivedOptions = options;
+        return true;
+      };
+
+      const result = await setContent({
+        page,
+        navigationManager,
+        html: '<h1>Hi</h1>',
+        waitUntil: 'networkidle',
+        timeout: 5000,
+      });
+
+      assert.deepStrictEqual(receivedOptions, {
+        html: '<h1>Hi</h1>',
+        waitUntil: 'networkidle',
+        timeout: 5000,
+      });
+      assert.deepStrictEqual(result, {
+        loaded: true,
+        actualUrl: 'https://example.com',
+      });
+    });
+
+    it('should load content directly without navigationManager', async () => {
+      const page = createMockPlaywrightPage();
+      let receivedArguments;
+      page.setContent = async (...args) => {
+        receivedArguments = args;
+      };
+
+      const result = await setContent({
+        page,
+        html: '',
+        waitUntil: 'load',
+        timeout: 5000,
+      });
+
+      assert.deepStrictEqual(receivedArguments, [
+        '',
+        { waitUntil: 'load', timeout: 5000 },
+      ]);
+      assert.deepStrictEqual(result, {
+        loaded: true,
+        actualUrl: 'https://example.com',
+      });
+    });
+  });
+
   describe('waitForNavigation', () => {
     it('should delegate to navigationManager if available', async () => {
       const page = createMockPlaywrightPage();

package/tests/unit/browser/real-browser.test.js

@@ -0,0 +1,165 @@
+import assert from 'node:assert';
+import { mkdtemp, rm } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { afterEach, describe, it } from 'node:test';
+
+import {
+  assertDedicatedUserDataDir,
+  buildRealBrowserArgs,
+  launchAndConnectRealBrowser,
+  launchAndConnectRealBrowserWithDependencies,
+} from '../../../src/browser/real-browser.js';
+import { launchAndConnectRealBrowser as publicHelper } from '../../../src/index.js';
+
+describe('launchAndConnectRealBrowser', () => {
+  let temporaryDirectory;
+
+  afterEach(async () => {
+    if (temporaryDirectory) {
+      await rm(temporaryDirectory, { recursive: true, force: true });
+      temporaryDirectory = undefined;
+    }
+  });
+
+  it('is exported from the package API', () => {
+    assert.equal(publicHelper, launchAndConnectRealBrowser);
+  });
+
+  it('builds a loopback-only CDP command with a dedicated profile', () => {
+    const args = buildRealBrowserArgs({
+      userDataDir: '/tmp/browser-commander-dedicated',
+      remoteDebuggingPort: 9333,
+      headless: true,
+      args: ['--lang=en-US'],
+    });
+
+    assert.deepEqual(args, [
+      '--remote-debugging-address=127.0.0.1',
+      '--remote-debugging-port=9333',
+      '--user-data-dir=/tmp/browser-commander-dedicated',
+      '--no-first-run',
+      '--no-default-browser-check',
+      '--headless=new',
+      '--lang=en-US',
+    ]);
+  });
+
+  it('rejects custom arguments that could bypass protected CDP settings', () => {
+    for (const argument of [
+      '--remote-debugging-address=0.0.0.0',
+      '--remote-debugging-port=9222',
+      '--user-data-dir=/tmp/other',
+    ]) {
+      assert.throws(
+        () =>
+          buildRealBrowserArgs({
+            userDataDir: '/tmp/browser-commander-dedicated',
+            remoteDebuggingPort: 0,
+            args: [argument],
+          }),
+        /managed by launchAndConnectRealBrowser/
+      );
+    }
+  });
+
+  it('rejects Chrome default user-data directories', () => {
+    for (const profile of ['google-chrome', 'google-chrome-beta']) {
+      assert.throws(
+        () =>
+          assertDedicatedUserDataDir(
+            path.join(os.homedir(), '.config', profile),
+            {
+              platform: 'linux',
+              homeDir: os.homedir(),
+              environment: {},
+            }
+          ),
+        /dedicated userDataDir/
+      );
+    }
+  });
+
+  it('spawns, waits, connects, and returns process metadata', async () => {
+    temporaryDirectory = await mkdtemp(
+      path.join(os.tmpdir(), 'browser-commander-real-browser-test-')
+    );
+    const calls = [];
+    const browserProcess = { exitCode: null, kill: () => calls.push(['kill']) };
+    const browser = { id: 'browser' };
+    const page = { id: 'page' };
+
+    const result = await launchAndConnectRealBrowserWithDependencies(
+      {
+        engine: 'puppeteer',
+        channel: 'chrome',
+        userDataDir: temporaryDirectory,
+        remoteDebuggingPort: 0,
+        seedCookies: [{ name: 'SID', value: 'saved' }],
+      },
+      {
+        resolveExecutable: async () => '/opt/google/chrome',
+        spawnBrowser: (executablePath, args) => {
+          calls.push(['spawn', executablePath, args]);
+          return browserProcess;
+        },
+        waitForEndpoint: async (options) => {
+          calls.push(['wait', options.remoteDebuggingPort]);
+          return 'http://127.0.0.1:9444';
+        },
+        connect: async (options) => {
+          calls.push(['connect', options]);
+          return { browser, page };
+        },
+      }
+    );
+
+    assert.equal(result.browser, browser);
+    assert.equal(result.page, page);
+    assert.equal(result.browserProcess, browserProcess);
+    assert.equal(result.cdpEndpoint, 'http://127.0.0.1:9444');
+    assert.equal(result.executablePath, '/opt/google/chrome');
+    assert.equal(result.userDataDir, temporaryDirectory);
+    assert.deepEqual(calls[1], ['wait', 0]);
+    assert.deepEqual(calls[2], [
+      'connect',
+      {
+        engine: 'puppeteer',
+        cdpEndpoint: 'http://127.0.0.1:9444',
+        seedCookies: [{ name: 'SID', value: 'saved' }],
+        verbose: false,
+      },
+    ]);
+  });
+
+  it('terminates the spawned browser when connection fails', async () => {
+    temporaryDirectory = await mkdtemp(
+      path.join(os.tmpdir(), 'browser-commander-real-browser-test-')
+    );
+    let killed = false;
+    const browserProcess = {
+      exitCode: null,
+      kill: () => {
+        killed = true;
+      },
+    };
+
+    await assert.rejects(
+      () =>
+        launchAndConnectRealBrowserWithDependencies(
+          { userDataDir: temporaryDirectory },
+          {
+            resolveExecutable: async () => '/opt/google/chrome',
+            spawnBrowser: () => browserProcess,
+            waitForEndpoint: async () => 'http://127.0.0.1:9222',
+            connect: async () => {
+              throw new Error('connection failed');
+            },
+          }
+        ),
+      /connection failed/
+    );
+
+    assert.equal(killed, true);
+  });
+});

package/tests/unit/browser/storage-state.test.js

@@ -0,0 +1,148 @@
+import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { afterEach, describe, it } from 'node:test';
+import assert from 'node:assert';
+
+import {
+  loadStorageState,
+  restorePlaywrightStorageState,
+  restorePuppeteerStorageState,
+  saveStorageState,
+} from '../../../src/browser/storage-state.js';
+import { saveStorageState as publicSaveStorageState } from '../../../src/index.js';
+
+describe('browser storage state', () => {
+  let temporaryDirectory;
+
+  afterEach(async () => {
+    if (temporaryDirectory) {
+      await rm(temporaryDirectory, { recursive: true, force: true });
+      temporaryDirectory = undefined;
+    }
+  });
+
+  it('loads storage state from a path and accepts an object unchanged', async () => {
+    temporaryDirectory = await mkdtemp(
+      path.join(os.tmpdir(), 'browser-commander-storage-state-')
+    );
+    const filePath = path.join(temporaryDirectory, 'state.json');
+    const state = {
+      cookies: [{ name: 'session', value: 'saved', domain: '.example.com' }],
+      origins: [],
+    };
+    await writeFile(filePath, JSON.stringify(state));
+
+    assert.deepEqual(await loadStorageState(filePath), state);
+    assert.equal(await loadStorageState(state), state);
+  });
+
+  it('rejects invalid storage state input', async () => {
+    await assert.rejects(
+      () => loadStorageState(null),
+      /storageState must be a file path or an object/
+    );
+  });
+
+  it('exports saveStorageState from the package API', () => {
+    assert.equal(publicSaveStorageState, saveStorageState);
+  });
+
+  it('restores Puppeteer cookies and localStorage before navigation', async () => {
+    const calls = [];
+    const state = {
+      cookies: [{ name: 'session', value: 'saved', domain: '.example.com' }],
+      origins: [
+        {
+          origin: 'https://example.com',
+          localStorage: [{ name: 'theme', value: 'dark' }],
+        },
+      ],
+    };
+    const page = {
+      setCookie: async (...cookies) => calls.push(['cookies', cookies]),
+      evaluateOnNewDocument: async (fn, value) =>
+        calls.push(['new-document', fn, value]),
+      evaluate: async (fn, value) => calls.push(['current-page', fn, value]),
+    };
+
+    await restorePuppeteerStorageState({ page, storageState: state });
+
+    assert.deepEqual(calls[0], ['cookies', state.cookies]);
+    assert.equal(calls[1][0], 'new-document');
+    assert.equal(calls[1][2], state.origins);
+    assert.equal(calls[2][0], 'current-page');
+    assert.equal(calls[2][2], state.origins);
+  });
+
+  it('restores Playwright cookies and localStorage before navigation', async () => {
+    const calls = [];
+    const state = {
+      cookies: [{ name: 'session', value: 'saved', domain: '.example.com' }],
+      origins: [
+        {
+          origin: 'https://example.com',
+          localStorage: [{ name: 'theme', value: 'dark' }],
+        },
+      ],
+    };
+    const page = {
+      evaluate: async (fn, value) => calls.push(['current-page', fn, value]),
+    };
+    const context = {
+      addCookies: async (cookies) => calls.push(['cookies', cookies]),
+      addInitScript: async (fn, value) =>
+        calls.push(['new-document', fn, value]),
+      pages: () => [page],
+    };
+
+    await restorePlaywrightStorageState({ context, storageState: state });
+
+    assert.deepEqual(calls[0], ['cookies', state.cookies]);
+    assert.equal(calls[1][0], 'new-document');
+    assert.equal(calls[1][2], state.origins);
+    assert.equal(calls[2][0], 'current-page');
+    assert.equal(calls[2][2], state.origins);
+  });
+
+  it('delegates Playwright saves to the page context', async () => {
+    const savedState = { cookies: [], origins: [] };
+    const calls = [];
+    const page = {
+      context: () => ({
+        storageState: async (options) => {
+          calls.push(options);
+          return savedState;
+        },
+      }),
+    };
+
+    assert.equal(await saveStorageState(page, '/tmp/state.json'), savedState);
+    assert.deepEqual(calls, [{ path: '/tmp/state.json' }]);
+  });
+
+  it('saves Puppeteer cookies and current-origin localStorage', async () => {
+    temporaryDirectory = await mkdtemp(
+      path.join(os.tmpdir(), 'browser-commander-storage-state-')
+    );
+    const filePath = path.join(temporaryDirectory, 'state.json');
+    const cookies = [
+      { name: 'session', value: 'saved', domain: '.example.com' },
+    ];
+    const localStorage = [{ name: 'theme', value: 'dark' }];
+    const page = {
+      browserContext: () => ({}),
+      cookies: async () => cookies,
+      url: () => 'https://example.com/inbox',
+      evaluate: async () => localStorage,
+    };
+
+    const state = await saveStorageState(page, filePath);
+
+    assert.deepEqual(state, {
+      cookies,
+      origins: [{ origin: 'https://example.com', localStorage }],
+    });
+    assert.deepEqual(JSON.parse(await readFile(filePath, 'utf8')), state);
+  });
+});

package/tests/unit/core/navigation-manager.test.js

@@ -0,0 +1,62 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+import { createNavigationManager } from '../../../src/core/navigation-manager.js';
+import {
+  createMockPlaywrightPage,
+  createMockLogger,
+} from '../../helpers/mocks.js';
+
+describe('navigation manager', () => {
+  describe('setContent', () => {
+    it('should apply the full managed navigation lifecycle', async () => {
+      const page = createMockPlaywrightPage();
+      const log = createMockLogger();
+      const calls = [];
+      page.setContent = async (...args) => calls.push(['setContent', ...args]);
+
+      const manager = createNavigationManager({
+        page,
+        engine: 'playwright',
+        log,
+      });
+      manager.configure({ redirectStabilizationTime: 0 });
+      manager.onSessionCleanup(() => calls.push(['cleanup']));
+      manager.on('onNavigationStart', () => calls.push(['navigationStart']));
+      manager.on('onPageReady', () => calls.push(['pageReady']));
+
+      const loaded = await manager.setContent({
+        html: '<h1>Hi</h1>',
+        waitUntil: 'networkidle',
+        timeout: 5000,
+      });
+
+      assert.strictEqual(loaded, true);
+      assert.strictEqual(manager.getSessionId(), 1);
+      assert.strictEqual(manager.isNavigating(), false);
+      assert.deepStrictEqual(calls, [
+        ['cleanup'],
+        ['navigationStart'],
+        [
+          'setContent',
+          '<h1>Hi</h1>',
+          { waitUntil: 'networkidle', timeout: 5000 },
+        ],
+        ['pageReady'],
+      ]);
+    });
+
+    it('should require html while accepting an empty string', async () => {
+      const page = createMockPlaywrightPage();
+      const log = createMockLogger();
+      const manager = createNavigationManager({
+        page,
+        engine: 'playwright',
+        log,
+      });
+      manager.configure({ redirectStabilizationTime: 0 });
+
+      await assert.rejects(() => manager.setContent(), /html is required/);
+      await assert.doesNotReject(() => manager.setContent({ html: '' }));
+    });
+  });
+});