browser-commander 0.20.0 → 0.21.0

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/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/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';

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';

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, []);
+  });
+});

package/tests/unit/utilities/subprocess.test.js

@@ -0,0 +1,80 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+import {
+  CommandError,
+  runCommand,
+  startProcess,
+} from '../../../src/utilities/subprocess.js';
+
+const node = process.execPath;
+
+describe('runCommand', () => {
+  it('passes arguments without a shell and captures output', async () => {
+    const result = await runCommand(node, [
+      '-e',
+      'process.stdout.write(JSON.stringify(process.argv.slice(1)))',
+      'a b',
+      '$HOME',
+      '"q"',
+    ]);
+    assert.equal(result.code, 0);
+    assert.deepEqual(JSON.parse(result.stdout), ['a b', '$HOME', '"q"']);
+  });
+
+  it('writes input to stdin and sets the child environment only', async () => {
+    const result = await runCommand(
+      node,
+      [
+        '-e',
+        'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>process.stdout.write(s+process.env.BC_TEST_ONLY))',
+      ],
+      { input: 'in:', env: { ...process.env, BC_TEST_ONLY: 'child' } }
+    );
+    assert.equal(result.stdout, 'in:child');
+    assert.equal(process.env.BC_TEST_ONLY, undefined);
+  });
+
+  it('throws CommandError on a non-zero exit unless check is false', async () => {
+    const args = ['-e', 'process.stderr.write("boom");process.exit(3)'];
+    await assert.rejects(
+      () => runCommand(node, args),
+      (error) =>
+        error instanceof CommandError &&
+        error.code === 3 &&
+        error.stderr === 'boom'
+    );
+    const result = await runCommand(node, args, { check: false });
+    assert.equal(result.code, 3);
+  });
+});
+
+describe('startProcess', () => {
+  it('streams output and reports the exit code', async () => {
+    const child = startProcess(node, [
+      '-e',
+      'process.stderr.write("hello\\n");process.exit(4)',
+    ]);
+    let stderr = '';
+    child.stderr.on('data', (chunk) => {
+      stderr += chunk;
+    });
+    const exitCode = await new Promise((resolve) =>
+      child.once('exit', resolve)
+    );
+    assert.equal(exitCode, 4);
+    assert.equal(stderr, 'hello\n');
+    assert.equal(await child.exited, 4);
+    assert.equal(child.kill(), false);
+  });
+
+  it('kills a running process', async () => {
+    const child = startProcess(node, ['-e', 'setInterval(() => {}, 1000)'], {
+      killGrace: 200,
+    });
+    await new Promise((resolve) => setTimeout(resolve, 100));
+    assert.ok(child.pid > 0);
+    assert.equal(child.kill(), true);
+    const exitCode = await child.exited;
+    assert.notEqual(exitCode, 0);
+  });
+});