browser-commander 0.19.0 → 0.21.0

package/tests/unit/fingerprint/automation-parity.test.js

@@ -22,7 +22,7 @@ describe('AutomationControlled triggers', () => {
     }
   });
 
-  it('finds each switch Chromium maps onto the feature', () => {
+  it('finds each switch that turns the feature on', () => {
     const found = detectAutomationControlledTriggers([
       '--enable-automation',
       '--headless=new',
@@ -32,16 +32,29 @@ describe('AutomationControlled triggers', () => {
 
     assert.deepEqual(found, [
       '--enable-automation',
-      '--headless',
       '--remote-debugging-pipe',
       '--remote-debugging-port=0',
     ]);
   });
 
+  it('does not treat headless as a trigger', () => {
+    // Measured: a hand-started headless Chrome reports navigator.webdriver
+    // false, because the renderer never sees the --headless switch.
+    assert.deepEqual(
+      detectAutomationControlledTriggers([
+        '--headless',
+        '--headless=new',
+        '--headless=old',
+      ]),
+      []
+    );
+  });
+
   it('reports the argument as written next to the switch it matched', () => {
     assert.deepEqual(
-      detectAutomationControlledTriggers(['--headless=new'])[0].argument,
-      '--headless=new'
+      detectAutomationControlledTriggers(['--remote-debugging-port=0'])[0]
+        .argument,
+      '--remote-debugging-port=0'
     );
   });
 

package/tests/unit/fingerprint/limitations.test.js

@@ -44,7 +44,7 @@ describe('the documented limitations', () => {
 
   it('is the shared JSON asset Python and Rust also publish', () => {
     // The catalogue is data, not code, so the three packages ship one file
-    // rather than three translations of the same eleven paragraphs.
+    // rather than three translations of the same sixteen paragraphs.
     const asset = JSON.parse(
       readFileSync(
         new URL('../../../src/fingerprint/limitations.json', import.meta.url),

package/tests/unit/parity/harness.test.js

@@ -0,0 +1,138 @@
+/**
+ * The reference capture starts a browser nothing automates and waits for the
+ * probe page to POST its report. A browser that cannot start at all (no usable
+ * sandbox, a rejected switch) never reports, so the capture has to fail with
+ * the browser's own exit code and stderr rather than a bare 60 s timeout.
+ */
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+
+import { captureReferenceReport } from '../../../src/parity/harness.js';
+
+function fakeProcess({ exitCode, stderr = '' }) {
+  const listeners = new Set();
+  let resolveExit;
+  const child = {
+    exited: new Promise((resolve) => {
+      resolveExit = resolve;
+    }),
+    stderr: {
+      on(event, listener) {
+        listeners.add(listener);
+      },
+    },
+    kill() {
+      resolveExit(143);
+    },
+  };
+  setTimeout(() => {
+    for (const listener of listeners) {
+      listener(stderr);
+    }
+    if (exitCode !== null) {
+      resolveExit(exitCode);
+    }
+  }, 0);
+  return child;
+}
+
+function fakeServer({ report = null } = {}) {
+  return {
+    url: (token) => `http://127.0.0.1:1/probe/${token}`,
+    waitForReport: (token, timeoutMs) =>
+      report
+        ? new Promise((resolve) => setTimeout(() => resolve(report), 20))
+        : new Promise((resolve, reject) =>
+            setTimeout(
+              () => reject(new Error(`timed out waiting for report ${token}`)),
+              timeoutMs
+            )
+          ),
+  };
+}
+
+describe('captureReferenceReport', () => {
+  it('fails fast with the exit code and stderr of a browser that died', async () => {
+    const started = Date.now();
+    await assert.rejects(
+      captureReferenceReport({
+        executablePath: '/usr/bin/chromium',
+        server: fakeServer(),
+        token: 't1',
+        timeoutMs: 3000,
+        start: () =>
+          fakeProcess({
+            exitCode: 1,
+            stderr: 'FATAL: No usable sandbox!',
+          }),
+      }),
+      (error) => {
+        assert.match(error.message, /\/usr\/bin\/chromium exited with code 1/);
+        assert.match(error.message, /No usable sandbox/);
+        return true;
+      }
+    );
+    assert.ok(Date.now() - started < 5000);
+  });
+
+  it('includes stderr when the report times out', async () => {
+    await assert.rejects(
+      captureReferenceReport({
+        server: fakeServer(),
+        token: 't2',
+        timeoutMs: 50,
+        start: () => fakeProcess({ exitCode: null, stderr: 'GPU init failed' }),
+      }),
+      /timed out waiting for report t2\nbrowser stderr:\nGPU init failed/
+    );
+  });
+
+  it('retries a fresh profile after the browser network service crashes', async () => {
+    const tokens = [];
+    let starts = 0;
+    const report = await captureReferenceReport({
+      server: {
+        url: (token) => {
+          tokens.push(token);
+          return `http://127.0.0.1:1/probe/${token}`;
+        },
+        waitForReport: (token) =>
+          token === 't4'
+            ? new Promise((resolve, reject) =>
+                setTimeout(
+                  () =>
+                    reject(new Error(`timed out waiting for report ${token}`)),
+                  20
+                )
+              )
+            : Promise.resolve({ navigator: { webdriver: false } }),
+      },
+      token: 't4',
+      timeoutMs: 50,
+      start: () => {
+        starts += 1;
+        return fakeProcess({
+          exitCode: null,
+          stderr:
+            starts === 1
+              ? 'Network service crashed or was terminated, restarting service.'
+              : '',
+        });
+      },
+    });
+    assert.deepEqual(report, { navigator: { webdriver: false } });
+    assert.equal(starts, 2);
+    assert.equal(tokens.length, 2);
+    assert.notEqual(tokens[0], tokens[1]);
+  });
+
+  it('keeps waiting when a launcher script exits cleanly', async () => {
+    const report = await captureReferenceReport({
+      server: fakeServer({ report: { navigator: { webdriver: false } } }),
+      token: 't3',
+      start: () => fakeProcess({ exitCode: 0 }),
+    });
+    assert.deepEqual(report, { navigator: { webdriver: false } });
+    assert.ok(Array.isArray(report.commandLine));
+  });
+});

package/tests/unit/scripts/ci-timeout-budgets.test.js

@@ -196,7 +196,11 @@ describe('CI execution budgets', () => {
     assert.deepEqual(budgeted, [
       'docs.yml build-docs Rust API docs',
       'js.yml test Node.js test suite',
+      'parity.yml cli CLI and API coverage suites',
+      'parity.yml cli Cross-language CLI contract',
+      'parity.yml cli Rust CLI build',
       'parity.yml parity Fingerprint parity suite',
+      'parity.yml parity WebDriver suite',
       'python.yml test pytest suite',
       'rust.yml coverage Rust code coverage',
       'rust.yml test Rust doc tests',

package/tests/unit/scripts/ci-workflow-policy.test.js

@@ -155,6 +155,14 @@ jobs:
     assert.equal(countFailures(content), 2);
   });
 
+  it('rejects download-artifact v7 after its runtime emitted DEP0005', () => {
+    const content = workflow({
+      steps: '      - uses: actions/download-artifact@v7',
+    });
+
+    assert.equal(countFailures(content), 1);
+  });
+
   it('accepts a base_ref bound to any environment variable name', () => {
     const content = workflow({
       on: 'pull_request',

package/tests/unit/scripts/feature-parity.test.js

@@ -0,0 +1,221 @@
+/**
+ * The generated feature-parity matrix (issue #104).
+ *
+ * `scripts/generate-feature-parity.mjs` builds the per-language matrix in
+ * docs/feature-parity.md from the `feature-parity:` tags in the three test
+ * suites, and fails when a feature is tested in one language and missing in
+ * another without a reason in docs/feature-parity/limitations.json. These
+ * tests pin those rules against a fixture tree, then pin the repository
+ * itself: the committed document must be what the generator writes.
+ *
+ * Fixture tags are assembled at run time, because the generator scans this
+ * file too and a literal tag here would claim a feature.
+ */
+
+import assert from 'node:assert/strict';
+import * as fs from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { describe, it } from 'node:test';
+import { pathToFileURL } from 'node:url';
+
+import { repoPath } from '../../helpers/repo.js';
+
+const {
+  BEGIN_MARKER,
+  END_MARKER,
+  escapeCell,
+  generate,
+  parseTags,
+  renderTable,
+} = await import(
+  pathToFileURL(repoPath('scripts/generate-feature-parity.mjs'))
+);
+
+const TAG = ['feature', 'parity:'].join('-');
+
+function tag(comment, ids) {
+  return `${comment} ${TAG} ${ids}\n`;
+}
+
+function fixture({ tests, limitations = [] }) {
+  const root = fs.mkdtempSync(path.join(tmpdir(), 'feature-parity-'));
+  const write = (relative, content) => {
+    const full = path.join(root, relative);
+    fs.mkdirSync(path.dirname(full), { recursive: true });
+    fs.writeFileSync(full, content);
+  };
+  write(
+    'docs/feature-parity/features.json',
+    JSON.stringify({
+      sections: [
+        {
+          title: 'Launch',
+          features: [
+            { id: 'launch.real', title: 'Real launch' },
+            { id: 'launch.attach', title: 'Attach | snapshot' },
+          ],
+        },
+      ],
+    })
+  );
+  write(
+    'docs/feature-parity/limitations.json',
+    JSON.stringify(limitations, null, 2)
+  );
+  write(
+    'docs/feature-parity.md',
+    `# Parity\n\nprose\n\n${BEGIN_MARKER}\n${END_MARKER}\n\ntail\n`
+  );
+  for (const [relative, content] of Object.entries(tests)) {
+    write(relative, content);
+  }
+  return root;
+}
+
+const ALL_LANGUAGES = {
+  'js/tests/unit/launch.test.js': tag('//', 'launch.real launch.attach'),
+  'python/tests/unit/test_launch.py': tag('#', 'launch.real, launch.attach'),
+  'rust/src/launch.rs': `fn x() {}\n${tag('    //', 'launch.real')}${tag('//', 'launch.attach')}`,
+};
+
+describe('feature parity generator', () => {
+  it('reads space- and comma-separated tags from line comments only', () => {
+    assert.deepEqual(parseTags(tag('//', 'a.b c-d')), ['a.b', 'c-d']);
+    assert.deepEqual(parseTags(tag('  #', 'a.b,c.d')), ['a.b', 'c.d']);
+    assert.deepEqual(parseTags(`const s = '${tag('//', 'a.b').trim()}';`), []);
+    assert.deepEqual(parseTags(tag('//', 'a.b').replaceAll('\n', '\r\n')), [
+      'a.b',
+    ]);
+  });
+
+  it('escapes both Markdown pipes and backslashes in feature names', () => {
+    assert.equal(escapeCell('a\\b|c\nx'), 'a\\\\b\\|c x');
+  });
+
+  it('accepts a generated document checked out with CRLF endings', () => {
+    const root = fixture({ tests: ALL_LANGUAGES });
+    try {
+      const documentPath = path.join(root, 'docs/feature-parity.md');
+      const { next } = generate(root);
+      fs.writeFileSync(documentPath, next.replaceAll('\n', '\r\n'));
+      const generated = generate(root);
+      assert.equal(generated.current, generated.next);
+      assert.equal(generated.next.includes('\r'), false);
+    } finally {
+      fs.rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  it('pads tables so the output is stable under Prettier', () => {
+    assert.equal(
+      renderTable(['A', 'Long header'], [['wide cell', 'x']]),
+      [
+        '| A         | Long header |',
+        '| --------- | ----------- |',
+        '| wide cell | x           |',
+      ].join('\n')
+    );
+  });
+
+  it('writes a matrix with links to the claiming tests', () => {
+    const root = fixture({ tests: ALL_LANGUAGES });
+    try {
+      const { next, errors } = generate(root);
+      assert.deepEqual(errors, []);
+      assert.match(next, /^# Parity\n\nprose\n\n<!-- feature-parity/u);
+      assert.match(
+        next,
+        /\| Real launch +\| \[Supported\]\(\.\.\/js\/tests\/unit\/launch\.test\.js\) +\| \[Supported\]\(\.\.\/python\/tests\/unit\/test_launch\.py\) +\| \[Supported\]\(\.\.\/rust\/src\/launch\.rs\) +\|/u
+      );
+      assert.match(next, /Attach \\\| snapshot/u);
+      assert.match(next, /None: every feature is tested in every language/u);
+      assert.match(next, /\n\ntail\n$/u);
+    } finally {
+      fs.rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  it('fails on a gap without a limitation', () => {
+    const tests = { ...ALL_LANGUAGES };
+    tests['rust/src/launch.rs'] = tag('//', 'launch.real');
+    const root = fixture({ tests });
+    try {
+      const { errors, next } = generate(root);
+      assert.deepEqual(errors, [
+        'feature "launch.attach" is tested in javascript, python but not in ' +
+          'rust, and docs/feature-parity/limitations.json gives no reason',
+      ]);
+      assert.match(next, /\| Missing +\|/u);
+    } finally {
+      fs.rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  it('accepts a gap with a technical reason and links to it', () => {
+    const tests = { ...ALL_LANGUAGES };
+    tests['rust/src/launch.rs'] = tag('//', 'launch.real');
+    const root = fixture({
+      tests,
+      limitations: [
+        {
+          id: 'rust-no-attach',
+          features: ['launch.attach'],
+          languages: ['rust'],
+          reason: 'The crate has no WebSocket server.',
+        },
+      ],
+    });
+    try {
+      const { errors, next } = generate(root);
+      assert.deepEqual(errors, []);
+      assert.match(next, /\[Limitation\]\(#rust-no-attach\)/u);
+      assert.match(
+        next,
+        /<a id="rust-no-attach"><\/a>\*\*`rust-no-attach`\*\* \(Rust\): The crate has no WebSocket server\./u
+      );
+    } finally {
+      fs.rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  it('rejects stale, reasonless and unknown entries', () => {
+    const tests = {
+      ...ALL_LANGUAGES,
+      'js/tests/unit/extra.test.js': tag('//', 'launch.unknown'),
+    };
+    const root = fixture({
+      tests,
+      limitations: [
+        {
+          id: 'stale',
+          features: ['launch.real', 'launch.missing'],
+          languages: ['rust', 'cobol'],
+          reason: ' ',
+        },
+      ],
+    });
+    try {
+      const { errors } = generate(root);
+      assert.deepEqual(errors.sort(), [
+        'limitation "stale" covers launch.real in rust, but rust/src/launch.rs tests it; remove the stale entry',
+        'limitation "stale" gives no technical reason',
+        'limitation "stale" names unknown feature "launch.missing"',
+        'limitation "stale" names unknown language "cobol"',
+        'unknown feature "launch.unknown" claimed by js/tests/unit/extra.test.js; add it to docs/feature-parity/features.json',
+      ]);
+    } finally {
+      fs.rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  it('keeps docs/feature-parity.md in sync with the tests', () => {
+    const { current, next, errors } = generate(repoPath());
+    assert.deepEqual(errors, []);
+    assert.equal(
+      current,
+      next,
+      'run node scripts/generate-feature-parity.mjs and commit the result'
+    );
+  });
+});

package/tests/unit/scripts/npm-release-helpers.test.js

@@ -131,6 +131,7 @@ describe('test runner helper', () => {
       buildNodeTestArgs(options, ['tests/unit/a.test.js'], '24.18.0'),
       [
         '--test',
+        '--throw-deprecation',
         '--test-isolation=none',
         '--experimental-test-coverage',
         '--test-reporter',
@@ -144,8 +145,8 @@ describe('test runner helper', () => {
     const options = parseTestRunnerArgs(['tests/unit']);
 
     assert.deepEqual(
-      buildNodeTestArgs(options, ['tests/unit/a.test.js'], '20.20.2'),
-      ['--test', 'tests/unit/a.test.js']
+      buildNodeTestArgs(options, ['tests/unit/a.test.js'], '22.22.3'),
+      ['--test', '--throw-deprecation', 'tests/unit/a.test.js']
     );
   });
 });

package/tests/unit/scripts/pre-commit-config.test.js

@@ -48,7 +48,8 @@ const MIRRORED_COMMANDS = [
   {
     id: 'python-mypy-scripts',
     workflow: 'python.yml',
-    command: 'mypy --python-version 3.13 scripts tests/unit/scripts',
+    command:
+      'mypy --no-warn-unused-configs --python-version 3.13 scripts tests/unit/scripts',
   },
   {
     id: 'rust-fmt',

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

@@ -16,10 +16,14 @@ import {
   TRACE_MODE,
   TRACE_OUTCOME,
 } from '../../../src/traces/schema.js';
-import { useTempTraceDirectory } from '../../helpers/trace-fixtures.js';
+import {
+  useTempTraceDirectory,
+  useTraceBundleCleanup,
+} from '../../helpers/trace-fixtures.js';
 
 describe('trace bundle writer (issue #87)', () => {
   const directory = useTempTraceDirectory();
+  const cleanup = useTraceBundleCleanup();
 
   /**
    * Open a bundle inside the suite's temporary directory.
@@ -27,8 +31,13 @@ describe('trace bundle writer (issue #87)', () => {
    * @param {Object} [options] - Options for `openTraceBundle`
    * @returns {Promise<Object>} The bundle writer
    */
-  const open = (options = {}) =>
-    openTraceBundle({ output: path.join(directory.path, 'run'), ...options });
+  const open = async (options = {}) =>
+    cleanup(
+      await openTraceBundle({
+        output: path.join(directory.path, 'run'),
+        ...options,
+      })
+    );
 
   /**
    * List a bundle's members, relative to its root.
@@ -66,6 +75,18 @@ describe('trace bundle writer (issue #87)', () => {
     await assert.rejects(openTraceBundle({}), /trace output must be a path/);
   });
 
+  it('should abort an unfinished bundle without writing a manifest', async () => {
+    const bundle = await open();
+    await bundle.appendEvent({ kind: TRACE_EVENT.CHECKPOINT });
+
+    await bundle.abort();
+    await bundle.abort();
+
+    await assert.rejects(
+      fs.access(path.join(bundle.root, TRACE_FILES.MANIFEST))
+    );
+  });
+
   it('should write the layout the format documents', async () => {
     const bundle = await open();
 

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

@@ -27,6 +27,7 @@ import {
   createFakePage,
   makeSnapshot,
   useTempTraceDirectory,
+  useTraceBundleCleanup,
 } from '../../helpers/trace-fixtures.js';
 
 /**
@@ -66,6 +67,7 @@ function parseExport(text) {
 
 describe('trace links export (issue #94)', () => {
   const directory = useTempTraceDirectory();
+  const trackOpenBundle = useTraceBundleCleanup();
 
   /**
    * Write a bundle holding one of everything the export has to say.
@@ -76,6 +78,7 @@ describe('trace links export (issue #94)', () => {
   const writeBundle = async ({ close = true } = {}) => {
     const root = path.join(directory.path, 'run.bc-trace');
     const bundle = await openTraceBundle({ output: root });
+    trackOpenBundle(bundle);
     const owner = {
       traceId: 'trace-1',
       browserContextId: 'context-1',
@@ -457,6 +460,10 @@ describe('trace links export (issue #94)', () => {
     );
     // No closing link, which is how a reader tells this run never finished.
     assert.ok(!links.some((link) => link.id === 'result'));
+
+    // The assertions above model the process being killed. The test process
+    // itself survives, so release its open descriptor explicitly.
+    await trace.stop();
   });
 
   it('should take the export away with a discarded bundle', async () => {

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

@@ -1,3 +1,4 @@
+// feature-parity: trace.read
 import { describe, it } from 'node:test';
 import assert from 'node:assert';
 import fs from 'node:fs/promises';
@@ -16,10 +17,14 @@ import {
   TRACE_MODE,
   TRACE_OUTCOME,
 } from '../../../src/traces/schema.js';
-import { useTempTraceDirectory } from '../../helpers/trace-fixtures.js';
+import {
+  useTempTraceDirectory,
+  useTraceBundleCleanup,
+} from '../../helpers/trace-fixtures.js';
 
 describe('trace reader (issue #87)', () => {
   const directory = useTempTraceDirectory();
+  const cleanup = useTraceBundleCleanup();
 
   /**
    * Write a small bundle the tests can read back.
@@ -29,9 +34,11 @@ describe('trace reader (issue #87)', () => {
    * @returns {Promise<Object>} The bundle writer
    */
   const writeBundle = async ({ close = true } = {}) => {
-    const bundle = await openTraceBundle({
-      output: path.join(directory.path, 'run'),
-    });
+    const bundle = cleanup(
+      await openTraceBundle({
+        output: path.join(directory.path, 'run'),
+      })
+    );
     await bundle.appendEvent({
       kind: TRACE_EVENT.TRACE_START,
       mode: TRACE_MODE.CHECKPOINTS,

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

@@ -1,3 +1,4 @@
+// feature-parity: trace.record
 import { describe, it } from 'node:test';
 import assert from 'node:assert';
 import { setImmediate as yieldToEngine } from 'node:timers/promises';
@@ -172,6 +173,7 @@ describe('trace recorder (issue #87)', () => {
       await trace.checkpoint('start');
 
       assert.strictEqual(page.state.screenshots, 0);
+      await trace.stop();
     });
 
     it('should take a screenshot only on failure when asked', async () => {
@@ -182,6 +184,7 @@ describe('trace recorder (issue #87)', () => {
 
       await trace.checkpoint('the end', { reason: 'failure' });
       assert.strictEqual(page.state.screenshots, 1);
+      await trace.stop();
     });
 
     it('should keep a gap rather than fail when the page has closed', async () => {
@@ -237,6 +240,7 @@ describe('trace recorder (issue #87)', () => {
       // Once at the start, and once after each of the two checkpoints - the
       // base one the recorder takes itself and the one named above.
       assert.strictEqual(installs.length, 3);
+      await trace.stop();
     });
   });
 

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

@@ -282,6 +282,10 @@ describe('offline trace viewer (issue #87)', () => {
 
       assert.match(body, /outcome truncated/);
       assert.match(body, /the last thing it did|1 checkpoints/);
+
+      // The assertions model an interrupted process; this test process keeps
+      // running, so explicitly release the descriptor afterwards.
+      await trace.stop();
     });
 
     it('should refuse a directory that is not a bundle', async () => {

package/tests/unit/utilities/command-stream-only.test.js

@@ -0,0 +1,28 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+import { readdirSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+
+import { repoPath } from '../../helpers/repo.js';
+
+const SOURCE_ROOT = repoPath('js', 'src');
+const DIRECT_SUBPROCESS = /from\s+['"](?:node:)?child_process['"]/u;
+
+function listSourceFiles(directory) {
+  return readdirSync(directory, { withFileTypes: true }).flatMap((entry) => {
+    const entryPath = path.join(directory, entry.name);
+    if (entry.isDirectory()) {
+      return listSourceFiles(entryPath);
+    }
+    return /\.[cm]?js$/u.test(entry.name) ? [entryPath] : [];
+  });
+}
+
+describe('subprocesses go through command-stream (issue #104)', () => {
+  it('no library module imports node:child_process directly', () => {
+    const offenders = listSourceFiles(SOURCE_ROOT)
+      .filter((file) => DIRECT_SUBPROCESS.test(readFileSync(file, 'utf8')))
+      .map((file) => path.relative(SOURCE_ROOT, file));
+    assert.deepEqual(offenders, []);
+  });
+});