browser-commander 0.21.0 → 0.21.1

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

@@ -35,7 +35,11 @@ const {
 const TAG = ['feature', 'parity:'].join('-');
 
 function tag(comment, ids) {
-  return `${comment} ${TAG} ${ids}\n`;
+  return `${comment} ${TAG} ${ids
+    .split(/[\s,]+/u)
+    .filter(Boolean)
+    .map((id) => `${id}@native-typed`)
+    .join(' ')}\n`;
 }
 
 function fixture({ tests, limitations = [] }) {
@@ -73,6 +77,15 @@ function fixture({ tests, limitations = [] }) {
   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'),
@@ -81,11 +94,17 @@ const ALL_LANGUAGES = {
 
 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(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',
+      'a.b@native-typed',
     ]);
   });
 
@@ -126,7 +145,7 @@ describe('feature parity generator', () => {
       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
+        /\| 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);
@@ -179,6 +198,93 @@ describe('feature parity generator', () => {
     }
   });
 
+  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,

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,4 +1,4 @@
-// feature-parity: trace.read
+// 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,4 +1,4 @@
-// feature-parity: trace.record
+// 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>' }),