browser-commander 0.23.0 → 0.24.0

package/tests/e2e/engine-matrix.e2e.test.js

@@ -0,0 +1,107 @@
+/** Native common launch and commander contracts for every JS engine (#124). */
+import assert from 'node:assert/strict';
+import { existsSync } from 'node:fs';
+import { createServer } from 'node:http';
+import { describe, it } from 'node:test';
+import { launchBrowser } from '../../src/browser/launcher.js';
+import { makeBrowserCommander } from '../../src/factory.js';
+import {
+  CHROME_LAUNCH_OPTIONS,
+  PARITY_CHROME,
+} from '../helpers/e2e-browser.js';
+
+// feature-parity: engines.webdriver@native-typed engines.cli-matrix@native-typed
+describe('Common native engine API', { skip: !process.env.RUN_E2E }, () => {
+  it(
+    'selenium restores portable cookies and BiDi origin state',
+    { timeout: 60000 },
+    async () => {
+      const server = createServer((_request, response) => {
+        response.end('<title>Portable state</title>');
+      });
+      await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
+      const origin = `http://127.0.0.1:${server.address().port}`;
+      let session;
+      try {
+        session = await launchBrowser({
+          engine: 'selenium',
+          launch: 'engine',
+          bidi: true,
+          headless: true,
+          executablePath: PARITY_CHROME,
+          ...CHROME_LAUNCH_OPTIONS,
+          storageState: {
+            cookies: [{ name: 'session', value: 'restored', url: origin }],
+            origins: [
+              { origin, localStorage: [{ name: 'theme', value: 'dark' }] },
+            ],
+          },
+        });
+        await session.page.goto(origin);
+        assert.equal(
+          await session.page.evaluate(() =>
+            globalThis.localStorage.getItem('theme')
+          ),
+          'dark'
+        );
+        assert.match(
+          await session.page.evaluate(() => document.cookie),
+          /session=restored/u
+        );
+      } finally {
+        await session?.close();
+        await new Promise((resolve) => server.close(resolve));
+      }
+    }
+  );
+  for (const engine of ['playwright', 'puppeteer', 'selenium']) {
+    for (const launch of ['real', 'engine']) {
+      it(
+        `${engine}/${launch}: input, click, native handles, PDF, cleanup`,
+        { timeout: 120000 },
+        async () => {
+          const session = await launchBrowser({
+            engine,
+            launch,
+            headless: true,
+            executablePath: PARITY_CHROME,
+            ...CHROME_LAUNCH_OPTIONS,
+          });
+          const commander = makeBrowserCommander({
+            page: session.page,
+            enableNetworkTracking: false,
+            enableNavigationManager: false,
+          });
+          const profile = session.userDataDir;
+          try {
+            assert.equal(commander.engine, engine);
+            await commander.goto({
+              url: `data:text/html,${encodeURIComponent('<input id="name"><button id="go" onclick="document.title=document.querySelector(\'#name\').value">Go</button>')}`,
+            });
+            await commander.fill({ selector: '#name', text: 'Ada' });
+            assert.equal(
+              await commander.inputValue({ selector: '#name' }),
+              'Ada'
+            );
+            await commander.click({ selector: '#go' });
+            assert.equal(await session.page.title(), 'Ada');
+            assert.ok(
+              Buffer.from(await session.page.pdf({ format: 'A4' }))
+                .subarray(0, 5)
+                .equals(Buffer.from('%PDF-'))
+            );
+            if (engine === 'selenium') {
+              assert.equal(await session.driver.getTitle(), 'Ada');
+            }
+          } finally {
+            await commander.destroy();
+            await session.close();
+          }
+          if (session.temporaryProfile) {
+            assert.equal(existsSync(profile), false);
+          }
+        }
+      );
+    }
+  }
+});

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

@@ -9,6 +9,7 @@
 
 import { describe, it, before, after } from 'node:test';
 import assert from 'node:assert';
+import { CHROME_LAUNCH_OPTIONS } from '../helpers/e2e-browser.js';
 
 // Dynamic import for playwright since it may not be installed
 let playwright;
@@ -25,23 +26,16 @@ describe(
     const BASE_URL = process.env.TEST_URL || 'http://localhost:3000';
 
     before(async () => {
-      try {
-        playwright = await import('playwright');
-        const module = await import('../../src/index.js');
-        createCommander = module.createCommander;
-
-        browser = await playwright.chromium.launch({
-          headless: process.env.HEADLESS !== 'false',
-        });
-        const context = await browser.newContext();
-        page = await context.newPage();
-        commander = createCommander({ page, verbose: true });
-      } catch (error) {
-        console.log(
-          'Skipping E2E tests - playwright not available or test app not running'
-        );
-        console.log('Error:', error.message);
-      }
+      playwright = await import('playwright');
+      const module = await import('../../src/index.js');
+      createCommander = module.createCommander;
+      browser = await playwright.chromium.launch({
+        headless: process.env.HEADLESS !== 'false',
+        ...CHROME_LAUNCH_OPTIONS,
+      });
+      const context = await browser.newContext();
+      page = await context.newPage();
+      commander = createCommander({ page, verbose: true });
     });
 
     after(async () => {

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

@@ -9,6 +9,7 @@
 
 import { describe, it, before, after } from 'node:test';
 import assert from 'node:assert';
+import { CHROME_LAUNCH_OPTIONS } from '../helpers/e2e-browser.js';
 
 // Dynamic import for puppeteer since it may not be installed
 let puppeteer;
@@ -22,22 +23,15 @@ describe('E2E Tests - Puppeteer Engine', { skip: !process.env.RUN_E2E }, () => {
   const BASE_URL = process.env.TEST_URL || 'http://localhost:3000';
 
   before(async () => {
-    try {
-      puppeteer = await import('puppeteer');
-      const module = await import('../../src/index.js');
-      createCommander = module.createCommander;
-
-      browser = await puppeteer.default.launch({
-        headless: process.env.HEADLESS !== 'false' ? 'new' : false,
-      });
-      page = await browser.newPage();
-      commander = createCommander({ page, verbose: true });
-    } catch (error) {
-      console.log(
-        'Skipping E2E tests - puppeteer not available or test app not running'
-      );
-      console.log('Error:', error.message);
-    }
+    puppeteer = await import('puppeteer');
+    const module = await import('../../src/index.js');
+    createCommander = module.createCommander;
+    browser = await puppeteer.default.launch({
+      headless: process.env.HEADLESS !== 'false',
+      ...CHROME_LAUNCH_OPTIONS,
+    });
+    page = await browser.newPage();
+    commander = createCommander({ page, verbose: true });
   });
 
   after(async () => {
@@ -352,7 +346,9 @@ describe('E2E Tests - Puppeteer Engine', { skip: !process.env.RUN_E2E }, () => {
       }
 
       // Scroll to specific item
-      await commander.scroll({ selector: '[data-testid="scroll-item-15"]' });
+      await commander.scrollIntoView({
+        locatorOrElement: await page.$('[data-testid="scroll-item-15"]'),
+      });
       await commander.wait({ ms: 500 });
 
       // Target should be visible

package/tests/unit/cli/dispatcher.test.js

@@ -272,7 +272,7 @@ describe('dispatcher: high-level methods', () => {
     await assert.rejects(dispatcher.dispatch('nope'), { code: -32601 });
     await assert.rejects(dispatcher.dispatch('version', []), { code: -32602 });
     await assert.rejects(
-      dispatcher.dispatch('session.launch', { engine: 'selenium' }),
+      dispatcher.dispatch('session.launch', { engine: 'unknown' }),
       { code: -32602 }
     );
     await assert.rejects(
@@ -351,7 +351,7 @@ describe('dispatcher: generic handle methods', () => {
       'launched with puppeteer'
     );
     await assert.rejects(
-      dispatcher.dispatch('handle.root', { name: 'selenium' }),
+      dispatcher.dispatch('handle.root', { name: 'unknown' }),
       { code: -32602 }
     );
   });

package/tests/unit/cli/selenium-parity.test.js

@@ -0,0 +1,186 @@
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import { createDispatcher } from '../../../src/cli/dispatcher.js';
+import { buildLaunchOptions } from '../../../src/cli/sessions.js';
+import { launchBrowserWithDependencies } from '../../../src/browser/launcher.js';
+import { connectBrowserWithDependencies } from '../../../src/browser/connector.js';
+
+// feature-parity: engines.webdriver@native-typed engines.cli-matrix@native-typed
+
+describe('Selenium uses the common engine entry points', () => {
+  it('restores portable cookies and origin state through the common launcher', async () => {
+    const visited = [];
+    const seeded = [];
+    const page = {
+      url: () => 'about:blank',
+      goto: async (url) => {
+        visited.push(url);
+      },
+      setCookie: async (...cookies) => {
+        seeded.push(...cookies);
+      },
+      evaluateOnNewDocument: async () => {},
+      evaluate: async () => {},
+      bringToFront: async () => {},
+    };
+    const cookie = {
+      name: 'session',
+      value: 'value',
+      domain: 'example.com',
+      path: '/',
+      secure: true,
+    };
+    const result = await launchBrowserWithDependencies(
+      {
+        engine: 'selenium',
+        launch: 'engine',
+        storageState: {
+          cookies: [cookie],
+          origins: [
+            {
+              origin: 'https://example.com',
+              localStorage: [{ name: 'theme', value: 'dark' }],
+            },
+          ],
+        },
+      },
+      {
+        launchWebDriver: async () => ({
+          driver: {},
+          page,
+          close: async () => {},
+        }),
+        settleMs: 0,
+      }
+    );
+    assert.deepEqual(seeded, [cookie]);
+    assert.deepEqual(visited, ['https://example.com', 'about:blank']);
+    await result.close();
+  });
+  it('preserves WebDriver browser and driver options in the CLI', () => {
+    assert.deepEqual(
+      buildLaunchOptions({
+        engine: 'selenium',
+        browser: 'firefox',
+        driverPath: '/driver',
+        bidi: true,
+      }),
+      {
+        engine: 'selenium',
+        headless: false,
+        browser: 'firefox',
+        driverPath: '/driver',
+        bidi: true,
+      }
+    );
+  });
+
+  it('launches through the native driver without loading a CDP engine', async () => {
+    const page = { bringToFront: async () => {} };
+    const driver = {};
+    let options;
+    let closed = false;
+    const result = await launchBrowserWithDependencies(
+      { engine: 'selenium', launch: 'engine', extraArgs: ['--no-sandbox'] },
+      {
+        launchWebDriver: async (value) => {
+          options = value;
+          return {
+            driver,
+            page,
+            close: async () => {
+              closed = true;
+            },
+          };
+        },
+        settleMs: 0,
+      }
+    );
+    assert.equal(result.browser, driver);
+    assert.equal(result.page, page);
+    assert.deepEqual(options.args, ['--no-sandbox']);
+    await result.close();
+    assert.equal(closed, true);
+  });
+
+  it('connects to a Selenium Grid through the common connector', async () => {
+    const driver = {};
+    const page = {};
+    let options;
+    const result = await connectBrowserWithDependencies(
+      {
+        engine: 'selenium',
+        serverUrl: 'http://grid:4444',
+        capabilities: { browserName: 'firefox' },
+      },
+      {
+        connectWebDriver: async (value) => {
+          options = value;
+          return { driver, page, close: async () => {} };
+        },
+      }
+    );
+    assert.equal(result.browser, driver);
+    assert.equal(options.capabilities.browserName, 'firefox');
+  });
+
+  it('exposes the raw Selenium module and driver over generic handles', async () => {
+    const driver = { getTitle: async () => 'native driver' };
+    const page = {
+      waitForSelector: async () => ({
+        clear: async () => {},
+        sendKeys: async () => {},
+      }),
+      url: () => 'about:blank',
+    };
+    const dispatcher = createDispatcher({
+      dependencies: {
+        loadEngine: async (name) => {
+          assert.equal(name, 'selenium');
+          return { Builder: class Builder {} };
+        },
+        launchBrowser: async () => ({
+          browser: driver,
+          driver,
+          page,
+          close: async () => {},
+        }),
+      },
+    });
+    try {
+      const root = await dispatcher.dispatch('handle.root', {
+        name: 'selenium',
+      });
+      assert.ok(root.$handle);
+      const builder = await dispatcher.dispatch('handle.get', {
+        handle: root,
+        property: 'Builder',
+      });
+      const instance = await dispatcher.dispatch('handle.construct', {
+        handle: builder,
+      });
+      assert.equal(
+        (await dispatcher.dispatch('handle.describe', { handle: instance }))
+          .type,
+        'Builder'
+      );
+      await dispatcher.dispatch('session.launch', { engine: 'selenium' });
+      await dispatcher.dispatch('page.fill', {
+        selector: '#name',
+        value: 'Ada',
+      });
+      const handles = await dispatcher.dispatch('handle.root', {
+        name: 'session:s1',
+      });
+      assert.equal(
+        await dispatcher.dispatch('handle.call', {
+          handle: handles.browser,
+          method: 'getTitle',
+        }),
+        'native driver'
+      );
+    } finally {
+      await dispatcher.close();
+    }
+  });
+});

package/tests/unit/tests/index.test.js

@@ -26,12 +26,13 @@ describe('browser-commander/tests', () => {
     assert.deepStrictEqual(normalizeBrowserTestEngines(), [
       'playwright',
       'puppeteer',
+      'selenium',
     ]);
     assert.deepStrictEqual(normalizeBrowserTestEngines('Playwright'), [
       'playwright',
     ]);
     assert.throws(
-      () => normalizeBrowserTestEngines('selenium'),
+      () => normalizeBrowserTestEngines('unknown'),
       /Unsupported browser test engine/
     );
   });

package/tests/unit/traces/links.test.js

@@ -544,8 +544,8 @@ describe('trace links export (issue #94)', () => {
     // The notation's formatter and parser decide whether an export can be read
     // back, so the range this package depends on and the version the tests
     // proved are the same range.
-    assert.strictEqual(manifest.dependencies['links-notation'], '^0.20.0');
-    assert.match(installed.version, /^0\.20\./);
+    assert.strictEqual(manifest.dependencies['links-notation'], '^0.22.0');
+    assert.match(installed.version, /^0\.22\./);
   });
 
   it('should export a bundle named by path as readily as an open one', async () => {