browser-commander 0.25.0 → 0.26.1

package/tests/e2e/safari.e2e.test.js

@@ -0,0 +1,105 @@
+// feature-parity: safari.control@native-typed
+import { it } from 'node:test';
+import assert from 'node:assert/strict';
+import { createServer } from 'node:http';
+import {
+  launchRealBrowser,
+  SafariUnsupportedError,
+  makeBrowserCommander,
+} from '../../src/index.js';
+import { createDispatcher } from '../../src/cli/dispatcher.js';
+import { closeServer } from '../helpers/fixture-server.js';
+
+it(
+  'Safari drives a local page in an isolated automation session',
+  {
+    skip:
+      process.platform !== 'darwin' || process.env.RUN_SAFARI_E2E !== 'true',
+    timeout: 60_000,
+  },
+  async () => {
+    const server = createServer((_request, response) => {
+      response.writeHead(200, { 'content-type': 'text/html' });
+      response.end(
+        '<title>Safari smoke</title><input id="name"><button id="go" onclick="document.querySelector(\'#out\').textContent=document.querySelector(\'#name\').value">Go</button><p id="out"></p>'
+      );
+    });
+    await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
+    const url = `http://127.0.0.1:${server.address().port}/`;
+    let session;
+    let commander;
+    const cli = createDispatcher();
+    const phase = (message) =>
+      console.info(`[Safari smoke] ${new Date().toISOString()} ${message}`);
+    try {
+      phase('launch seeded session');
+      session = await launchRealBrowser({
+        channel: 'safari',
+        startupTimeout: 20_000,
+        seedCookies: [{ name: 'seed', value: 'yes', url, httpOnly: true }],
+      });
+      const { page, driver } = session;
+      phase('exercise page commands');
+      commander = makeBrowserCommander({ page });
+      await page.goto(url);
+      assert.equal(commander.engine, 'selenium');
+      await commander.fill({ selector: '#name', text: 'Safari' });
+      await commander.click({ selector: '#go' });
+      assert.equal(
+        await page.evaluate(() => document.querySelector('#out').textContent),
+        'Safari'
+      );
+      assert.equal(await page.evaluateAsync(async (value) => value + 1, 4), 5);
+      assert.ok((await page.screenshot()).length > 100);
+      assert.equal((await driver.manage().getCookie('seed')).value, 'yes');
+      phase('exercise windows and tabs');
+      const initial = await driver.getWindowHandle();
+      for (const type of ['tab', 'window']) {
+        const handle = await page.newWindow(type);
+        assert.ok((await page.windows()).includes(handle));
+        await page.goto(url);
+        await driver.close();
+        await page.switchToWindow(initial);
+      }
+      await assert.rejects(() => page.pdf(), SafariUnsupportedError);
+      await assert.rejects(
+        () => page.setRequestInterception(true),
+        SafariUnsupportedError
+      );
+      phase('close seeded session');
+      await session.close();
+      phase('launch fresh session');
+      session = await launchRealBrowser({ channel: 'safari' });
+      await session.page.goto(url);
+      assert.equal(
+        (await session.driver.manage().getCookies()).some(
+          (cookie) => cookie.name === 'seed'
+        ),
+        false
+      );
+      phase('close fresh session');
+      await session.close();
+      phase('launch CLI session');
+      await cli.dispatch('session.launch', {
+        browser: 'safari',
+        engine: 'selenium',
+      });
+      phase('exercise CLI commands');
+      await cli.dispatch('page.goto', { url });
+      assert.equal(
+        (await cli.dispatch('page.eval', { expression: 'document.title' }))
+          .value,
+        'Safari smoke'
+      );
+    } finally {
+      phase('close CLI session');
+      await cli.close();
+      phase('destroy commander');
+      await commander?.destroy();
+      phase('close remaining session and server');
+      await session?.close();
+      await closeServer(server);
+      phase('cleanup complete');
+    }
+  }
+);

package/tests/e2e/webdriver.e2e.test.js

@@ -20,6 +20,7 @@ import path from 'node:path';
 import { launchWebDriver } from '../../src/browser/webdriver.js';
 import { makeBrowserCommander } from '../../src/factory.js';
 import { CHROME_LAUNCH_OPTIONS } from '../helpers/e2e-browser.js';
+import { closeServer } from '../helpers/fixture-server.js';
 
 const PAGE = `<!doctype html>
 <title>WebDriver e2e</title>
@@ -42,7 +43,7 @@ async function startPageServer() {
   await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
   return {
     url: `http://127.0.0.1:${server.address().port}/`,
-    close: () => new Promise((resolve) => server.close(resolve)),
+    close: () => closeServer(server),
   };
 }
 

package/tests/helpers/fixture-server.js

@@ -31,6 +31,23 @@ export function sendNotFound(res) {
   res.end('not found');
 }
 
+/**
+ * Close an HTTP server without waiting for the browser's idle connections.
+ *
+ * Browsers open speculative connections they may never send a request on.
+ * Node 24's http.Server#close() waits for those until the client drops them,
+ * which stalled the Safari smoke cleanup for ~30s (issue #128), so stop
+ * listening first and then drop every connection that is left.
+ *
+ * @param {import('node:http').Server} server - Listening server
+ * @returns {Promise<void>} Resolves once the server is closed
+ */
+export function closeServer(server) {
+  const closed = new Promise((resolve) => server.close(() => resolve()));
+  server.closeAllConnections();
+  return closed;
+}
+
 /**
  * Start a fixture server on an ephemeral port.
  *
@@ -50,7 +67,7 @@ export async function startFixtureHost(handle, onClose) {
     baseUrl: `http://127.0.0.1:${port}`,
     close: async () => {
       await onClose?.();
-      await new Promise((resolve) => server.close(resolve));
+      await closeServer(server);
     },
   };
 }

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

@@ -204,7 +204,7 @@ describe('launchAndConnectRealBrowser', () => {
   });
 
   it('rejects non-CDP catalogue browsers before resolving or spawning them', async () => {
-    for (const channel of ['firefox', 'librewolf', 'safari', 'duckduckgo']) {
+    for (const channel of ['firefox', 'librewolf', 'duckduckgo']) {
       await assert.rejects(
         launchAndConnectRealBrowserWithDependencies(
           { channel },

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

@@ -0,0 +1,192 @@
+// feature-parity: safari.control@native-typed safari.setup@native-typed safari.seed@native-typed safari.unsupported@native-typed
+import { it } from 'node:test';
+import assert from 'node:assert/strict';
+import vm from 'node:vm';
+import { findBrowserSource } from '../../../src/browser/browser-sources.js';
+import {
+  buildDriverServerArgs,
+  resolveWebDriverExecutable,
+} from '../../../src/browser/webdriver.js';
+import {
+  WebDriverPage,
+  createWebDriverPage,
+} from '../../../src/core/webdriver-page.js';
+import { createMockDriver } from '../../helpers/webdriver-mocks.js';
+import { launchBrowserWithDependencies } from '../../../src/browser/launcher.js';
+import { launchAndConnectRealBrowserWithDependencies } from '../../../src/browser/real-browser.js';
+import {
+  SafariSetupError,
+  SafariUnsupportedError,
+  safariLaunchError,
+  openSafariSettings,
+} from '../../../src/browser/safari-support.js';
+import { startTrace } from '../../../src/traces/recorder.js';
+import {
+  buildLaunchOptions,
+  sessionFromLaunch,
+} from '../../../src/cli/sessions.js';
+
+it('catalogue exposes both Safari WebDriver executables', () => {
+  for (const channel of ['safari', 'safari-tp']) {
+    const source = findBrowserSource(channel);
+    assert.equal(source.controlProtocol, 'webdriver');
+    assert.ok(source.executables.darwin[0].endsWith('/safaridriver'));
+  }
+});
+
+it('Safari channels route real/common launch and CLI to Selenium and seed cookies', async () => {
+  for (const launch of [
+    launchBrowserWithDependencies,
+    launchAndConnectRealBrowserWithDependencies,
+  ]) {
+    const driver = createMockDriver({
+      capabilities: { browserName: 'safari' },
+    });
+    const page = await createWebDriverPage(driver);
+    let calls = 0;
+    const launched = await launch(
+      {
+        channel: 'safari-tp',
+        seedCookies: [
+          {
+            name: 'auth',
+            value: 'yes',
+            domain: '.example.test',
+            secure: true,
+            httpOnly: true,
+            expires: -1,
+          },
+        ],
+      },
+      {
+        launchWebDriver: async (options) => {
+          calls++;
+          assert.equal(options.browser, 'safari-technology-preview');
+          return {
+            driver,
+            page,
+            close: () => driver.quit(),
+            driverPath: '/Safari TP/safaridriver',
+          };
+        },
+        resolveExecutable: () => assert.fail('Safari must bypass CDP'),
+        resolveSystem: () =>
+          assert.fail('Safari must bypass Chromium resolution'),
+      }
+    );
+    assert.equal(calls, 1);
+    assert.equal(launched.engine, 'selenium');
+    assert.equal(launched.browser, driver);
+    assert.equal(driver.state.url, 'about:blank');
+    assert.ok(
+      driver.calls.some(
+        ([method, url]) => method === 'get' && url === 'https://example.test'
+      )
+    );
+    assert.ok(
+      driver.calls.some(
+        ([method, cookie]) => method === 'addCookie' && cookie.httpOnly
+      )
+    );
+    assert.equal(sessionFromLaunch('playwright', launched).engine, 'selenium');
+    await launched.close();
+  }
+  assert.equal(buildLaunchOptions({ browser: 'safari' }).channel, 'safari');
+});
+
+it('Safari fails unsupported launch options before starting and page features before writes', async () => {
+  for (const options of [
+    { headless: true },
+    { userDataDir: '/tmp/profile' },
+    { args: ['--flag'] },
+    { fingerprint: {} },
+    { downloads: true },
+  ]) {
+    await assert.rejects(
+      () =>
+        launchBrowserWithDependencies(
+          { channel: 'safari', ...options },
+          { launchWebDriver: () => assert.fail('must reject before starting') }
+        ),
+      SafariUnsupportedError
+    );
+  }
+  const page = new WebDriverPage(createMockDriver(), { browserName: 'safari' });
+  await assert.rejects(
+    () => page.pdf(),
+    (error) =>
+      error instanceof SafariUnsupportedError && error.feature === 'PDF'
+  );
+  await assert.rejects(
+    () => page.setRequestInterception(true),
+    SafariUnsupportedError
+  );
+  await assert.rejects(
+    () => startTrace({ page, output: '/must-not-create' }),
+    SafariUnsupportedError
+  );
+});
+
+it('Safari async evaluation uses execute/async and returns rejected promises as errors', async () => {
+  const driver = createMockDriver();
+  let mode = 'success';
+  driver.executeAsyncScript = (source, ...args) =>
+    new Promise((resolve) => {
+      vm.runInNewContext(`(function(){${source}}).apply(null, args)`, {
+        args: [...args, resolve],
+        location: { href: 'https://example.test' },
+        setTimeout,
+        mode,
+      });
+    });
+  const page = new WebDriverPage(driver, { browserName: 'safari' });
+  assert.equal(await page.evaluateAsync(async (value) => value + 1, 4), 5);
+  mode = 'error';
+  await assert.rejects(
+    () =>
+      page.evaluateAsync(async () => {
+        throw new Error('rejected');
+      }),
+    /rejected/
+  );
+});
+
+it('setup errors identify both authorization steps and offer an explicit settings opener', async () => {
+  for (const message of [
+    "You must enable the 'Allow Remote Automation' option",
+    'safaridriver requires --enable authorization',
+  ]) {
+    const error = safariLaunchError(
+      new Error(message),
+      'safari-technology-preview'
+    );
+    assert.ok(error instanceof SafariSetupError);
+    assert.match(error.message, /Show features for web developers/);
+    assert.match(error.message, /admin password/);
+    assert.match(error.message, /Safari Technology Preview.app/);
+    assert.equal(typeof error.openSettings, 'function');
+  }
+  const other = new Error('port already in use');
+  assert.equal(safariLaunchError(other, 'safari'), other);
+  let argv;
+  await openSafariSettings({
+    channel: 'safari-tp',
+    platform: 'darwin',
+    run: async (file, args) => {
+      assert.equal(file, 'osascript');
+      argv = args;
+    },
+  });
+  assert.ok(argv.some((arg) => arg.includes('Safari Technology Preview')));
+});
+
+it('Safari uses its bundled driver and the native --port argument', async () => {
+  assert.deepEqual(buildDriverServerArgs('safari', 12345), ['--port', '12345']);
+  const result = await resolveWebDriverExecutable({
+    browser: 'safari',
+    platform: 'darwin',
+    checkAccess: async () => {},
+    runCommand: () => assert.fail('Safari needs no Selenium Manager'),
+  });
+  assert.equal(result.driverPath, '/usr/bin/safaridriver');
+});

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

@@ -92,7 +92,7 @@ function createMockSelenium(driver = createMockDriver()) {
     record,
     driver,
     selenium: {
-      webdriver: { Builder },
+      webdriver: { Builder, Capabilities: Options },
       chrome: {
         Options: class extends Options {
           constructor() {
@@ -265,8 +265,8 @@ describe('resolveWebDriverExecutable', () => {
 
   it('rejects browsers it has no driver for', async () => {
     await assert.rejects(
-      () => resolveWebDriverExecutable({ browser: 'safari' }),
-      /Unsupported WebDriver browser: safari/
+      () => resolveWebDriverExecutable({ browser: 'unknown-browser' }),
+      /Unsupported WebDriver browser: unknown-browser/
     );
   });
 });
@@ -446,6 +446,151 @@ describe('launchWebDriver', () => {
   });
 });
 
+function safariDependencies() {
+  return launchDependencies({
+    platform: 'darwin',
+    checkAccess: async () => {},
+  });
+}
+
+describe('Safari driver lifecycle', () => {
+  it('uses no disk profile or Chromium/BiDi capabilities and closes idempotently', async () => {
+    const { dependencies, started, mock } = safariDependencies();
+    mock.driver.state.url = '';
+    const result = await launchWebDriver(
+      { browser: 'safari-technology-preview' },
+      dependencies
+    );
+    assert.equal(result.page.url(), 'about:blank');
+    assert.equal(result.userDataDir, undefined);
+    assert.equal(result.temporaryProfile, false);
+    assert.equal(
+      mock.record.builders[0].capabilities.capabilities.browserName,
+      'Safari Technology Preview'
+    );
+    assert.deepEqual(started[0].args, ['--port', '41001']);
+    assert.match(started[0].file, /Safari Technology Preview.app/);
+    await Promise.all([result.close(), result.close()]);
+    assert.equal(
+      mock.driver.calls.filter(([name]) => name === 'quit').length,
+      1
+    );
+    assert.ok(started[0].child.killed);
+  });
+
+  it('cleans up the driver if Safari authorization fails', async () => {
+    const { dependencies, started, mock } = safariDependencies();
+    mock.selenium.webdriver.Builder.prototype.build = () => {
+      throw new Error("You must enable the 'Allow Remote Automation' option");
+    };
+    await assert.rejects(
+      () => launchWebDriver({ browser: 'safari' }, dependencies),
+      (error) => error.code === 'SAFARI_SETUP_REQUIRED'
+    );
+    assert.ok(started[0].child.killed);
+    assert.equal(started.length, 1, 'setup errors are not retried');
+  });
+});
+
+/**
+ * Safari dependencies whose first `failures` driver starts fail the way CI
+ * saw right after the previous session closed: `'exit'` is a safaridriver that
+ * exits with code 1 before /status answers, `'refused'` is one that answered
+ * /status and then refused the new-session request.
+ */
+function flakySafariDependencies(failures) {
+  const setup = safariDependencies();
+  const { dependencies, started, mock } = setup;
+  let port = 49000;
+  dependencies.reservePort = async () => (port += 1);
+  dependencies.safariRetryDelay = 0;
+  const startProcess = dependencies.startProcess;
+  dependencies.startProcess = (...args) => {
+    const child = startProcess(...args);
+    if (failures[started.length - 1] === 'exit') {
+      child.exitCode = 1;
+      child.stdout = {
+        on: (_event, listener) => listener('safaridriver: busy\n'),
+      };
+    }
+    return child;
+  };
+  dependencies.fetch = async () => ({
+    ok: true,
+    json: async () => ({ value: { ready: true } }),
+  });
+  const build = mock.selenium.webdriver.Builder.prototype.build;
+  mock.selenium.webdriver.Builder.prototype.build = function () {
+    if (failures[started.length - 1] === 'refused') {
+      throw new Error(
+        `ECONNREFUSED connect ECONNREFUSED 127.0.0.1:${port} (attempt ${started.length})`
+      );
+    }
+    return build.call(this);
+  };
+  return setup;
+}
+
+describe('Safari launch right after a previous session', () => {
+  for (const failure of ['exit', 'refused']) {
+    it(`starts a new driver when the first one fails with '${failure}'`, async () => {
+      const { dependencies, started } = flakySafariDependencies([failure]);
+      const result = await launchWebDriver({ browser: 'safari' }, dependencies);
+      assert.equal(started.length, 2);
+      assert.equal(result.driverProcess, started[1].child);
+      assert.ok(started[0].child.killed || started[0].child.exitCode === 1);
+      assert.equal(result.serverUrl, 'http://127.0.0.1:49002');
+      await result.close();
+    });
+  }
+
+  it('gives up after three attempts and reports what the driver printed', async () => {
+    const { dependencies, started } = flakySafariDependencies([
+      'exit',
+      'refused',
+      'exit',
+    ]);
+    await assert.rejects(
+      () => launchWebDriver({ browser: 'safari' }, dependencies),
+      /exited with code 1 before it was ready: safaridriver: busy/
+    );
+    assert.equal(started.length, 3);
+  });
+
+  it('adds the driver exit status to a refused session request', async () => {
+    const { dependencies } = flakySafariDependencies([
+      'refused',
+      'refused',
+      'refused',
+    ]);
+    await assert.rejects(
+      () => launchWebDriver({ browser: 'safari' }, dependencies),
+      (error) =>
+        /ECONNREFUSED .*\(attempt 3\)/.test(error.message) &&
+        /WebDriver server at http:\/\/127\.0\.0\.1:49003/.test(error.message)
+    );
+  });
+
+  it('does not retry other browsers', async () => {
+    const { dependencies, started, mock } = launchDependencies({
+      checkAccess: accessOnly('/opt/drivers/chromedriver'),
+      safariRetryDelay: 0,
+    });
+    mock.selenium.webdriver.Builder.prototype.build = () => {
+      throw new Error('ECONNREFUSED connect ECONNREFUSED 127.0.0.1:41001');
+    };
+    await assert.rejects(
+      () =>
+        launchWebDriver(
+          { driverPath: '/opt/drivers/chromedriver' },
+          dependencies
+        ),
+      /ECONNREFUSED/
+    );
+    assert.equal(started.length, 1);
+  });
+});
+
 describe('connectWebDriver', () => {
   it('opens a session on a running server with the given capabilities', async () => {
     const mock = createMockSelenium();

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

@@ -280,7 +280,7 @@ describe('dispatcher: high-level methods', () => {
       { code: -32602 }
     );
     await assert.rejects(
-      dispatcher.dispatch('session.launch', { browser: 'safari' }),
+      dispatcher.dispatch('session.launch', { browser: 'unknown-browser' }),
       { code: -32602 }
     );
     await assert.rejects(dispatcher.dispatch('page.goto', { url: 'x' }), {

package/tests/unit/elements/selectors.test.js

@@ -192,6 +192,81 @@ describe('selectors', () => {
     });
   });
 
+  describe('normalizeSelector with Playwright text selectors', () => {
+    /** A page whose evaluate records the parsed selector it was given. */
+    function capturingPage() {
+      const page = {
+        parsed: null,
+        evaluate: async (_fn, parsed) => {
+          page.parsed = parsed;
+          return 'button:nth-of-type(1)';
+        },
+      };
+      return page;
+    }
+
+    it('splits :has-text into base selector and text', async () => {
+      const page = capturingPage();
+      await normalizeSelector({
+        page,
+        engine: 'playwright',
+        selector: 'nav a:has-text("Sign in")',
+      });
+      assert.deepStrictEqual(page.parsed, {
+        baseSelector: 'nav a',
+        text: 'Sign in',
+        exact: false,
+      });
+    });
+
+    it('splits :text-is into base selector and exact text', async () => {
+      const page = capturingPage();
+      await normalizeSelector({
+        page,
+        engine: 'playwright',
+        selector: 'button:text-is("Submit")',
+      });
+      assert.deepStrictEqual(page.parsed, {
+        baseSelector: 'button',
+        text: 'Submit',
+        exact: true,
+      });
+    });
+
+    it('returns an unparseable selector unchanged', async () => {
+      for (const selector of [
+        ':has-text("no base")',
+        'a:has-text("")',
+        'a:has-text("unclosed',
+      ]) {
+        const page = capturingPage();
+        const result = await normalizeSelector({
+          page,
+          engine: 'playwright',
+          selector,
+        });
+        assert.strictEqual(result, selector);
+        assert.strictEqual(page.parsed, null);
+      }
+    });
+
+    it('rejects a long unparseable selector in linear time', async () => {
+      // The former /^(.+?):has-text\("(.+?)"\)$/ backtracked quadratically
+      // on this input: about 18s at this length (CodeQL js/polynomial-redos,
+      // issue #128; experiments/issue-128/text-selector-redos.mjs).
+      const selector = `a${':has-text("'.repeat(50_000)}`;
+      const started = performance.now();
+      const result = await normalizeSelector({
+        page: capturingPage(),
+        engine: 'playwright',
+        selector,
+      });
+      const elapsed = performance.now() - started;
+      assert.strictEqual(result, selector);
+      assert.ok(elapsed < 1000, `took ${elapsed.toFixed(0)}ms`);
+    });
+  });
+
   describe('normalizeSelector', () => {
     it('should throw when selector is not provided', async () => {
       const page = createMockPlaywrightPage();

package/tests/unit/helpers/fixture-server.test.js

@@ -0,0 +1,60 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { createServer } from 'node:http';
+import { connect } from 'node:net';
+import { closeServer, startFixtureHost } from '../../helpers/fixture-server.js';
+
+/**
+ * Open a connection the way a browser preconnects: TCP only, no request.
+ * Node 24's http.Server#close() waits for such a socket until the client
+ * drops it, which is what stalled the Safari smoke cleanup (issue #128).
+ */
+async function preconnect(url) {
+  const { hostname, port } = new URL(url);
+  const socket = connect(Number(port), hostname);
+  socket.on('error', () => {});
+  await new Promise((resolve) => socket.once('connect', resolve));
+  return socket;
+}
+
+/** Fail instead of hanging when a close does not finish in time. */
+function within(promise, ms) {
+  let timer;
+  return Promise.race([
+    promise,
+    new Promise((_resolve, reject) => {
+      timer = setTimeout(
+        () => reject(new Error(`did not close within ${ms}ms`)),
+        ms
+      );
+    }),
+  ]).finally(() => clearTimeout(timer));
+}
+
+describe('fixture server shutdown', { timeout: 10_000 }, () => {
+  it('closeServer does not wait for a preconnected idle socket', async () => {
+    const server = createServer((_request, response) => response.end('ok'));
+    await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
+    const socket = await preconnect(
+      `http://127.0.0.1:${server.address().port}/`
+    );
+    try {
+      await within(closeServer(server), 2_000);
+      assert.equal(server.listening, false);
+    } finally {
+      socket.destroy();
+    }
+  });
+
+  it('startFixtureHost close does not wait for a preconnected idle socket', async () => {
+    const host = await startFixtureHost((_path, _request, response) =>
+      response.end('ok')
+    );
+    const socket = await preconnect(host.baseUrl);
+    try {
+      await within(host.close(), 2_000);
+    } finally {
+      socket.destroy();
+    }
+  });
+});