browser-commander 0.20.0 → 0.21.1

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

@@ -0,0 +1,327 @@
+/**
+ * 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
+    .split(/[\s,]+/u)
+    .filter(Boolean)
+    .map((id) => `${id}@native-typed`)
+    .join(' ')}\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;
+}
+
+function inspectFixture(options, assertion) {
+  const root = fixture(options);
+  try {
+    assertion(generate(root));
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+}
+
+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@native-typed',
+      'c-d@native-typed',
+    ]);
+    assert.deepEqual(parseTags(tag('  #', 'a.b,c.d')), [
+      'a.b@native-typed',
+      'c.d@native-typed',
+    ]);
+    assert.deepEqual(parseTags(`const s = '${tag('//', 'a.b').trim()}';`), []);
+    assert.deepEqual(parseTags(tag('//', 'a.b').replaceAll('\n', '\r\n')), [
+      'a.b@native-typed',
+    ]);
+  });
+
+  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 +\| \[Native typed\]\(\.\.\/js\/tests\/unit\/launch\.test\.js\) +\| \[Native typed\]\(\.\.\/python\/tests\/unit\/test_launch\.py\) +\| \[Native typed\]\(\.\.\/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 a claim without an API tier', () => {
+    inspectFixture(
+      {
+        tests: {
+          ...ALL_LANGUAGES,
+          'js/tests/unit/legacy.test.js': `// ${TAG} launch.real\n`,
+        },
+      },
+      ({ errors }) => {
+        assert.ok(errors.some((error) => /has no valid API tier/u.test(error)));
+      }
+    );
+  });
+
+  it('requires a technical reason for untyped CLI access', () => {
+    inspectFixture(
+      {
+        tests: {
+          ...ALL_LANGUAGES,
+          'rust/src/launch.rs': `// ${TAG} launch.real@untyped-via-cli launch.attach@native-typed\n`,
+        },
+      },
+      ({ errors }) => {
+        assert.ok(
+          errors.some((error) => /below typed via bridge/u.test(error))
+        );
+      }
+    );
+  });
+
+  it('renders typed bridge access and a documented CLI exception', () => {
+    inspectFixture(
+      {
+        tests: {
+          ...ALL_LANGUAGES,
+          'python/tests/unit/test_launch.py': `# ${TAG} launch.real@typed-via-bridge launch.attach@native-typed\n`,
+          'rust/src/launch.rs': `// ${TAG} launch.real@untyped-via-cli launch.attach@native-typed\n`,
+        },
+        limitations: [
+          {
+            id: 'dynamic-launch',
+            features: ['launch.real'],
+            languages: ['rust'],
+            tier: 'untyped-via-cli',
+            reason: 'This command accepts a dynamic JSON script.',
+          },
+        ],
+      },
+      ({ errors, next }) => {
+        assert.deepEqual(errors, []);
+        assert.match(
+          next,
+          /\[Typed via bridge\]\(\.\.\/python\/tests\/unit\/test_launch\.py\)/u
+        );
+        assert.match(
+          next,
+          /\[Untyped via CLI\]\(\.\.\/rust\/src\/launch\.rs\) \(\[reason\]\(#dynamic-launch\)\)/u
+        );
+      }
+    );
+  });
+
+  it('rejects a stale CLI exception that has no claim', () => {
+    inspectFixture(
+      {
+        tests: {
+          ...ALL_LANGUAGES,
+          'rust/src/launch.rs': tag('//', 'launch.attach'),
+        },
+        limitations: [
+          {
+            id: 'stale-cli-exception',
+            features: ['launch.real'],
+            languages: ['rust'],
+            tier: 'untyped-via-cli',
+            reason: 'Dynamic JSON input.',
+          },
+        ],
+      },
+      ({ errors }) => {
+        assert.ok(
+          errors.some((error) => /expects untyped CLI access/u.test(error))
+        );
+      }
+    );
+  });
+
+  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/conformance.test.js

@@ -0,0 +1,92 @@
+/**
+ * Trace conformance across languages (issue #108).
+ *
+ * Python and Rust record traces natively and must write what JavaScript
+ * writes. They compare their output with two committed sets of files, and
+ * these tests keep both in step with the JavaScript sources:
+ *
+ * - `assets.json` in each package holds the in-page capture functions and
+ *   the viewer's style and script (`scripts/generate-trace-assets.mjs`);
+ * - `tests/fixtures/traces/conformance/expected/` is the bundle, Links
+ *   Notation export and redaction corpus the JavaScript recorder produces
+ *   for `scenario.json` (`scripts/generate-trace-conformance.mjs`).
+ */
+
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+import { formatTraceLinks, traceLinks } from '../../../src/traces/links.js';
+import { repoPath } from '../../helpers/repo.js';
+
+const { generateTraceAssets } = await import(
+  pathToFileURL(repoPath('scripts/generate-trace-assets.mjs'))
+);
+const {
+  EXPECTED_DIR,
+  generateTraceConformance,
+  readScenario,
+  recordConformanceScenario,
+} = await import(
+  pathToFileURL(repoPath('scripts/generate-trace-conformance.mjs'))
+);
+
+describe('trace conformance', () => {
+  it('keeps the Python and Rust trace assets in sync', async () => {
+    assert.deepEqual(
+      await generateTraceAssets({ check: true }),
+      [],
+      'run node scripts/generate-trace-assets.mjs and commit the result'
+    );
+  });
+
+  it('keeps the golden conformance bundle in sync', async () => {
+    assert.deepEqual(
+      await generateTraceConformance({ check: true }),
+      [],
+      'run node scripts/generate-trace-conformance.mjs and commit the result'
+    );
+  });
+
+  it('streams the same Links Notation the bundle exports afterwards', async () => {
+    const output = fs.mkdtempSync(path.join(os.tmpdir(), 'bc-conformance-'));
+    try {
+      await recordConformanceScenario(readScenario(), output);
+      assert.equal(
+        formatTraceLinks(await traceLinks(path.join(output, 'bundle'))),
+        fs.readFileSync(path.join(output, 'trace.lino'), 'utf8')
+      );
+    } finally {
+      fs.rmSync(output, { recursive: true, force: true });
+    }
+  });
+
+  it('covers every kind of timeline event in the golden bundle', () => {
+    const kinds = new Set(
+      fs
+        .readFileSync(path.join(EXPECTED_DIR, 'bundle/events.ndjson'), 'utf8')
+        .trim()
+        .split('\n')
+        .map((line) => JSON.parse(line).kind)
+    );
+    for (const kind of [
+      'trace.start',
+      'checkpoint',
+      'navigation',
+      'console',
+      'pageerror',
+      'requestfailed',
+      'dialog',
+      'download',
+      'interaction',
+      'dropped',
+      'mutations',
+      'trace.stop',
+    ]) {
+      assert.ok(kinds.has(kind), `the scenario never records ${kind}`);
+    }
+  });
+});

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

@@ -1,3 +1,4 @@
+// feature-parity: trace.read@native-typed
 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@native-typed
 import { describe, it } from 'node:test';
 import assert from 'node:assert';
 import { setImmediate as yieldToEngine } from 'node:timers/promises';

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

@@ -2,12 +2,14 @@ import { describe, it } from 'node:test';
 import assert from 'node:assert';
 import fs from 'node:fs/promises';
 import path from 'node:path';
+import vm from 'node:vm';
 
 import { readTrace } from '../../../src/traces/reader.js';
 import { startTrace } from '../../../src/traces/recorder.js';
 import { TRACE_FILES, TRACE_MODE } from '../../../src/traces/schema.js';
 import {
   DEFAULT_MAX_INLINE_BYTES,
+  VIEWER_SCRIPT,
   renderTraceViewer,
   writeTraceViewer,
 } from '../../../src/traces/viewer.js';
@@ -82,6 +84,42 @@ describe('offline trace viewer (issue #87)', () => {
       )[1]
     );
 
+  /**
+   * Run the viewer's own script against a minimal stand-in for its document.
+   *
+   * @param {string} viewer - The rendered viewer document
+   * @returns {Object} The stand-in elements, by id
+   */
+  const runViewerScript = (viewer) => {
+    const element = () => {
+      const node = {
+        innerHTML: '',
+        textContent: '',
+        children: [],
+        listeners: {},
+        parts: {},
+        classList: { add() {}, remove() {} },
+        addEventListener: (type, listener) => {
+          node.listeners[type] = listener;
+        },
+        append: (child) => node.children.push(child),
+        querySelector: (selector) => (node.parts[selector] ??= element()),
+      };
+      return node;
+    };
+    const elements = { 'trace-data': element() };
+    elements['trace-data'].textContent = viewer.match(
+      /<script id="trace-data" type="application\/json">([\s\S]*?)<\/script>/
+    )[1];
+    const document = {
+      getElementById: (id) => (elements[id] ??= element()),
+      createElement: () => element(),
+    };
+    assert.ok(viewer.includes(VIEWER_SCRIPT));
+    vm.runInNewContext(VIEWER_SCRIPT, { document, JSON, String, Object });
+    return elements;
+  };
+
   /**
    * Render the viewer for a bundle recorded from one snapshot.
    *
@@ -151,6 +189,46 @@ describe('offline trace viewer (issue #87)', () => {
       assert.ok(viewer.includes('\\u003cimg src=x onerror=alert(1)\\u003e'));
     });
 
+    it('should show recorded text as text, never as the viewer’s own markup', async () => {
+      // The URL, the title, a control's value and an error message are all
+      // whatever the recorded page made them. The viewer's policy allows
+      // inline handlers for its own script, so markup reaching innerHTML
+      // would run in the reviewer's viewer.
+      const payload = '<img src=x onerror=alert(1)>';
+      const { trace, page } = await beginTrace('hostile', {
+        pageOptions: {
+          snapshot: makeSnapshot({ state: { url: payload, title: payload } }),
+        },
+      });
+      await trace.checkpoint('before');
+      page.setSnapshot(
+        makeSnapshot({
+          state: {
+            url: payload,
+            title: payload,
+            controls: [{ path: payload, tag: 'input', value: payload }],
+          },
+        })
+      );
+      await trace.checkpoint('after');
+      const stopped = await trace.stop({ error: new Error(payload) });
+
+      const ui = runViewerScript(
+        await renderTraceViewer(await readTrace(stopped.path))
+      );
+      const shown = [];
+      for (const li of ui.timeline.children) {
+        li.listeners.click();
+        shown.push(ui.details.innerHTML, ui.diff.innerHTML);
+      }
+
+      for (const html of shown) {
+        assert.ok(!html.includes('<img'), `markup reached the viewer: ${html}`);
+      }
+      // The text is still shown, escaped, so a reviewer can read it.
+      assert.ok(shown.some((html) => html.includes('&#60;img src=x')));
+    });
+
     it('should escape the line separators a JavaScript parser treats as newlines', async () => {
       const page = createFakePage({
         snapshot: makeSnapshot({ html: '<p>one
two
three</p>' }),

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