browser-commander 0.17.2 → 0.19.0

package/tests/unit/downloads/staging.test.js

@@ -0,0 +1,117 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+import {
+  DEFAULT_STAGING_POLL_INTERVAL,
+  DEFAULT_STAGING_TIMEOUT,
+  describeStagingTimeout,
+  STAGING_IN_PROGRESS_SUFFIXES,
+  waitForStagedFile,
+} from '../../../src/downloads/staging.js';
+import { useTempDownloadDirectory } from '../../helpers/download-fixtures.js';
+
+describe('waiting for staged bytes (issue #92)', () => {
+  const directory = useTempDownloadDirectory();
+
+  it('should report a file that is already complete', async () => {
+    const staged = path.join(directory.path, 'guid-ready');
+    await fs.writeFile(staged, 'complete body');
+
+    const settled = await waitForStagedFile({ path: staged, timeout: 1000 });
+
+    assert.strictEqual(settled.ready, true);
+    assert.strictEqual(settled.bytes, 'complete body'.length);
+    assert.strictEqual(settled.reason, null);
+  });
+
+  it('should wait for a file that appears after the completion event', async () => {
+    // This is issue #92 exactly: the browser says "completed" and the rename
+    // Chromium does behind it has not become visible yet.
+    const staged = path.join(directory.path, 'guid-late');
+    const appear = setTimeout(() => {
+      fs.writeFile(staged, 'late body').catch(() => {});
+    }, 60);
+
+    const settled = await waitForStagedFile({
+      path: staged,
+      timeout: 5000,
+      interval: 5,
+    });
+    clearTimeout(appear);
+
+    assert.strictEqual(settled.ready, true, settled.reason ?? '');
+    assert.strictEqual(settled.bytes, 'late body'.length);
+  });
+
+  it('should keep waiting while the file is still growing', async () => {
+    const staged = path.join(directory.path, 'guid-growing');
+    await fs.writeFile(staged, 'a');
+    const grow = setInterval(() => {
+      fs.appendFile(staged, 'a').catch(() => {});
+    }, 5);
+    setTimeout(() => clearInterval(grow), 80);
+
+    const settled = await waitForStagedFile({
+      path: staged,
+      timeout: 5000,
+      interval: 5,
+    });
+    clearInterval(grow);
+
+    assert.strictEqual(settled.ready, true, settled.reason ?? '');
+    // Two equal readings are what ends the wait, so the file had stopped
+    // growing before it was declared ready.
+    assert.strictEqual(settled.bytes, (await fs.stat(staged)).size);
+  });
+
+  it('should not claim a file whose partial sibling is still being written', async () => {
+    const staged = path.join(directory.path, 'guid-partial');
+    await fs.writeFile(staged, 'looks done');
+    await fs.writeFile(`${staged}.crdownload`, 'still writing');
+
+    const settled = await waitForStagedFile({
+      path: staged,
+      timeout: 60,
+      interval: 5,
+    });
+
+    assert.strictEqual(settled.ready, false);
+    assert.match(settled.reason, /\.crdownload file is still being written/);
+  });
+
+  it('should fail explicitly when the bytes never arrive', async () => {
+    const staged = path.join(directory.path, 'guid-missing');
+
+    const settled = await waitForStagedFile({
+      path: staged,
+      timeout: 60,
+      interval: 5,
+    });
+
+    assert.strictEqual(settled.ready, false);
+    assert.strictEqual(settled.bytes, null);
+    assert.match(settled.reason, /has not appeared/);
+  });
+
+  it('should name the file, the budget and what it last saw', () => {
+    const message = describeStagingTimeout({
+      path: '/tmp/root/.browser-commander-staging/guid',
+      timeout: 250,
+      reason: 'the file has not appeared yet',
+    });
+
+    assert.match(message, /reported the download as completed/);
+    assert.match(message, /guid/);
+    assert.match(message, /250ms/);
+    assert.match(message, /has not appeared yet/);
+  });
+
+  it('should ship defaults a download can actually finish within', () => {
+    assert.ok(DEFAULT_STAGING_TIMEOUT >= 1000);
+    assert.ok(DEFAULT_STAGING_POLL_INTERVAL > 0);
+    assert.ok(DEFAULT_STAGING_POLL_INTERVAL < DEFAULT_STAGING_TIMEOUT);
+    assert.ok(STAGING_IN_PROGRESS_SUFFIXES.includes('.crdownload'));
+  });
+});

package/tests/unit/downloads/store.test.js

@@ -0,0 +1,215 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+import { createHash } from 'node:crypto';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { Readable } from 'node:stream';
+
+import {
+  cleanPartials,
+  DOWNLOAD_CONFLICT,
+  saveDownload,
+} from '../../../src/downloads/store.js';
+import { useTempDownloadDirectory } from '../../helpers/download-fixtures.js';
+import { assertMode } from '../../helpers/file-modes.js';
+
+/**
+ * A download source made of literal bytes.
+ *
+ * @param {string|Buffer} body - File contents
+ * @returns {Object} Source accepted by `saveDownload`
+ */
+const bytes = (body) => ({ stream: Readable.from([Buffer.from(body)]) });
+
+describe('download store (issue #88)', () => {
+  const directory = useTempDownloadDirectory();
+
+  /**
+   * List the files currently in the download root.
+   *
+   * @returns {Promise<string[]>} Sorted entry names
+   */
+  const listing = async () => (await fs.readdir(directory.path)).sort();
+
+  /**
+   * Save two downloads that suggest the same name.
+   *
+   * @param {string} [conflict] - Conflict policy for the second one
+   * @returns {Promise<Object>} What the second save reported
+   */
+  const saveTwice = async (conflict) => {
+    await saveDownload({
+      root: directory.path,
+      source: bytes('first'),
+      suggestedFilename: 'report.pdf',
+    });
+    return saveDownload({
+      root: directory.path,
+      source: bytes('second'),
+      suggestedFilename: 'report.pdf',
+      conflict,
+    });
+  };
+
+  it('should save a download under its suggested name', async () => {
+    const saved = await saveDownload({
+      root: directory.path,
+      source: bytes('report body'),
+      suggestedFilename: 'report.pdf',
+    });
+
+    assert.strictEqual(saved.path, path.join(directory.path, 'report.pdf'));
+    assert.strictEqual(saved.bytes, 11);
+    assert.strictEqual(
+      saved.checksum,
+      createHash('sha256').update('report body').digest('hex')
+    );
+    assert.strictEqual(await fs.readFile(saved.path, 'utf8'), 'report body');
+  });
+
+  it('should write the file with owner-only permissions', async () => {
+    const saved = await saveDownload({
+      root: directory.path,
+      source: bytes('secret'),
+      suggestedFilename: 'secret.txt',
+    });
+
+    await assertMode(saved.path, 0o600);
+  });
+
+  it('should number a colliding name instead of replacing the file', async () => {
+    const second = await saveTwice();
+
+    assert.strictEqual(path.basename(second.path), 'report (2).pdf');
+    assert.deepStrictEqual(await listing(), ['report (2).pdf', 'report.pdf']);
+    assert.strictEqual(
+      await fs.readFile(path.join(directory.path, 'report.pdf'), 'utf8'),
+      'first'
+    );
+  });
+
+  it('should replace the file when the caller asked for overwrite', async () => {
+    const second = await saveTwice(DOWNLOAD_CONFLICT.OVERWRITE);
+
+    assert.deepStrictEqual(await listing(), ['report.pdf']);
+    assert.strictEqual(await fs.readFile(second.path, 'utf8'), 'second');
+  });
+
+  it('should refuse a collision when the caller asked for error', async () => {
+    await assert.rejects(
+      saveTwice(DOWNLOAD_CONFLICT.ERROR),
+      /refusing to replace/
+    );
+    assert.deepStrictEqual(await listing(), ['report.pdf']);
+  });
+
+  it('should keep a traversal attempt inside the download root', async () => {
+    // A naming callback expresses a preference, not a grant of write access:
+    // the path part is dropped and only the leaf name survives.
+    const saved = await saveDownload({
+      root: directory.path,
+      source: bytes('payload'),
+      suggestedFilename: 'safe.txt',
+      filename: () => '../../escaped.txt',
+    });
+
+    assert.strictEqual(saved.path, path.join(directory.path, 'escaped.txt'));
+    const parent = await fs.readdir(path.dirname(directory.path));
+    assert.ok(!parent.includes('escaped.txt'));
+  });
+
+  it('should refuse a page-suggested name that points outside the root', async () => {
+    const saved = await saveDownload({
+      root: directory.path,
+      source: bytes('payload'),
+      suggestedFilename: '../../../etc/passwd',
+    });
+
+    assert.strictEqual(saved.path, path.join(directory.path, 'passwd'));
+  });
+
+  // Issue #88: "a half-written or invalid artifact must never appear under
+  // the final name". A validator rejects either by throwing or by answering
+  // `false`, and neither may leave anything behind.
+  const rejections = [
+    {
+      title: 'validation throws',
+      expected: /expected a PDF/,
+      validate: ({ bytes: size }) => {
+        if (size < 1000) {
+          throw new Error('expected a PDF, got a login page');
+        }
+      },
+    },
+    {
+      title: 'validation answers false',
+      expected: /rejected by the caller/,
+      validate: ({ mimeType }) => mimeType === 'application/pdf',
+    },
+  ];
+
+  for (const { title, expected, validate } of rejections) {
+    it(`should leave no file behind when ${title}`, async () => {
+      await assert.rejects(
+        saveDownload({
+          root: directory.path,
+          source: bytes('<html>login page</html>'),
+          suggestedFilename: 'invoice.pdf',
+          mimeType: 'text/html',
+          validate,
+        }),
+        expected
+      );
+
+      assert.deepStrictEqual(await listing(), []);
+    });
+  }
+
+  it('should hand validation the real bytes before publishing them', async () => {
+    const seen = [];
+    await saveDownload({
+      root: directory.path,
+      source: bytes('%PDF-1.7 body'),
+      suggestedFilename: 'invoice',
+      mimeType: 'application/pdf',
+      validate: async (details) => {
+        seen.push({
+          ...details,
+          head: (await fs.readFile(details.path)).subarray(0, 4).toString(),
+        });
+      },
+    });
+
+    assert.strictEqual(seen.length, 1);
+    assert.strictEqual(seen[0].head, '%PDF');
+    assert.strictEqual(seen[0].bytes, 13);
+    // Validation sees the partial file, never the published name.
+    assert.ok(seen[0].path.endsWith('.partial'));
+    assert.deepStrictEqual(await listing(), ['invoice.pdf']);
+  });
+
+  it('should let a caller name the file without losing the safety rules', async () => {
+    const saved = await saveDownload({
+      root: directory.path,
+      source: bytes('payload'),
+      suggestedFilename: '8d0f9e2c-4a11-4b22-9f00-1d2e3f405162',
+      mimeType: 'application/pdf',
+      filename: ({ suggestedFilename }) => `invoice-${suggestedFilename}`,
+    });
+
+    assert.strictEqual(
+      path.basename(saved.path),
+      'invoice-8d0f9e2c-4a11-4b22-9f00-1d2e3f405162.pdf'
+    );
+  });
+
+  it('should clean up partial files left by an interrupted run', async () => {
+    const stale = path.join(directory.path, 'report.pdf.1234.partial');
+    await fs.writeFile(stale, 'half');
+
+    const removed = await cleanPartials(directory.path);
+
+    assert.deepStrictEqual(removed, [stale]);
+    assert.deepStrictEqual(await listing(), []);
+  });
+});

package/tests/unit/interactions/click-activation.test.js

@@ -0,0 +1,283 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+import {
+  CLICK_ACTIVATION,
+  CLICK_SCROLL,
+  CLICK_ACTIONABILITY,
+  ScrollConstraintError,
+  resolveActivationOptions,
+  measureClickPoint,
+  readScrollPosition,
+  restoreScrollPosition,
+  dispatchClick,
+} from '../../../src/interactions/click-activation.js';
+import { createMockLogger } from '../../helpers/mocks.js';
+import {
+  IN_VIEWPORT_POINT,
+  createScrollModel,
+} from '../../helpers/click-fixtures.js';
+
+/**
+ * Adapter stub that records what the engine was asked to do and models a
+ * scroll position the engine may move.
+ *
+ * @param {Object} [options] - Stub configuration
+ * @param {Object} [options.point] - Geometry returned by the click-point probe
+ * @param {number} [options.scrollOnClick] - Scroll position the engine click lands on
+ * @param {boolean} [options.hasEvaluateOnPage] - Whether the adapter exposes `evaluateOnPage`
+ * @returns {Object} Adapter stub
+ */
+function createAdapter(options = {}) {
+  const {
+    point = IN_VIEWPORT_POINT,
+    scrollOnClick = 0,
+    hasEvaluateOnPage = true,
+  } = options;
+
+  const calls = { click: [], domClick: 0 };
+  const scroll = createScrollModel();
+
+  const adapter = {
+    calls,
+    click: async (el, opts) => {
+      calls.click.push(opts);
+      scroll.set(scrollOnClick);
+    },
+    evaluateOnElement: async (el, fn) => {
+      if (typeof fn === 'function' && fn.length === 1) {
+        // The DOM-activation path passes `el => el.click()`.
+        const source = fn.toString();
+        if (source.includes('.click()')) {
+          calls.domClick += 1;
+          return undefined;
+        }
+      }
+      return { ...point, scroll: { x: 0, y: scroll.current() } };
+    },
+  };
+
+  if (hasEvaluateOnPage) {
+    adapter.evaluateOnPage = scroll.evaluateOnPage;
+  }
+
+  adapter.currentScrollY = scroll.current;
+  return adapter;
+}
+
+/**
+ * Page stub that records real pointer clicks.
+ *
+ * @returns {Object} Page stub
+ */
+function createPage() {
+  const clicks = [];
+  return { clicks, mouse: { click: async (x, y) => clicks.push({ x, y }) } };
+}
+
+/**
+ * Build the page/adapter pair and a `dispatchClick` invoker for one scenario.
+ *
+ * @param {Object} [options] - Scenario configuration
+ * @param {Object} [options.adapter] - Options forwarded to {@link createAdapter}
+ * @param {Object} [options.activation] - Options forwarded to `resolveActivationOptions`
+ * @returns {{page: Object, adapter: Object, dispatch: Function}} Scenario handle
+ */
+function scenario(options = {}) {
+  const page = createPage();
+  const adapter = createAdapter(options.adapter);
+
+  const dispatch = () =>
+    dispatchClick({
+      page,
+      adapter,
+      locatorOrElement: {},
+      activationOptions: resolveActivationOptions(options.activation),
+    });
+
+  return { page, adapter, dispatch };
+}
+
+describe('click activation', () => {
+  describe('resolveActivationOptions', () => {
+    it('should default to a pointer click that may scroll', () => {
+      const resolved = resolveActivationOptions();
+      assert.strictEqual(resolved.activation, CLICK_ACTIVATION.POINTER);
+      assert.strictEqual(resolved.scroll, CLICK_SCROLL.AUTO);
+      assert.strictEqual(resolved.actionability, CLICK_ACTIONABILITY.NORMAL);
+      assert.deepStrictEqual(resolved.deprecations, []);
+    });
+
+    it('should map the deprecated noAutoScroll onto scroll semantics', () => {
+      // Regression test for issue #89: noAutoScroll used to mean
+      // `{ force: true }`, which is an actionability flag, not a scroll flag.
+      const on = resolveActivationOptions({ noAutoScroll: true });
+      assert.strictEqual(on.scroll, CLICK_SCROLL.NONE);
+      assert.strictEqual(on.actionability, CLICK_ACTIONABILITY.NORMAL);
+      assert.strictEqual(on.deprecations.length, 1);
+      assert.ok(on.deprecations[0].includes('noAutoScroll is deprecated'));
+
+      const off = resolveActivationOptions({ noAutoScroll: false });
+      assert.strictEqual(off.scroll, CLICK_SCROLL.AUTO);
+    });
+
+    it('should let an explicit scroll option win over noAutoScroll', () => {
+      const resolved = resolveActivationOptions({
+        noAutoScroll: true,
+        scroll: CLICK_SCROLL.PRESERVE,
+      });
+      assert.strictEqual(resolved.scroll, CLICK_SCROLL.PRESERVE);
+    });
+
+    it('should log the deprecation notice when a logger is supplied', () => {
+      const log = createMockLogger({ collectLogs: true });
+      resolveActivationOptions({ noAutoScroll: true, log });
+      const messages = log.getLogs().map((entry) => entry.message);
+      assert.ok(messages.some((message) => message.includes('deprecated')));
+    });
+
+    it('should reject unknown values on every axis', () => {
+      assert.throws(
+        () => resolveActivationOptions({ activation: 'telepathy' }),
+        /activation must be one of/u
+      );
+      assert.throws(
+        () => resolveActivationOptions({ scroll: 'maybe' }),
+        /scroll must be one of/u
+      );
+      assert.throws(
+        () => resolveActivationOptions({ actionability: 'hard' }),
+        /actionability must be one of/u
+      );
+    });
+  });
+
+  describe('measureClickPoint', () => {
+    it('should report the element centre and hit-test result', async () => {
+      const adapter = createAdapter();
+      const point = await measureClickPoint({
+        adapter,
+        locatorOrElement: {},
+      });
+      assert.strictEqual(point.x, 50);
+      assert.strictEqual(point.y, 60);
+      assert.strictEqual(point.inViewport, true);
+      assert.strictEqual(point.hitsTarget, true);
+    });
+  });
+
+  describe('scroll position helpers', () => {
+    it('should tolerate an adapter without evaluateOnPage', async () => {
+      const adapter = createAdapter({ hasEvaluateOnPage: false });
+      assert.strictEqual(await readScrollPosition(adapter), null);
+      await restoreScrollPosition(adapter, { x: 0, y: 10 });
+    });
+
+    it('should tolerate an adapter that throws', async () => {
+      const adapter = {
+        evaluateOnPage: async () => {
+          throw new Error('context destroyed');
+        },
+      };
+      assert.strictEqual(await readScrollPosition(adapter), null);
+    });
+
+    it('should do nothing when there is no position to restore', async () => {
+      const adapter = createAdapter();
+      await restoreScrollPosition(adapter, null);
+      assert.strictEqual(adapter.currentScrollY(), 0);
+    });
+  });
+
+  describe('dispatchClick', () => {
+    it('should send force to the engine only for actionability: force', async () => {
+      const normal = scenario();
+      await normal.dispatch();
+      assert.deepStrictEqual(normal.adapter.calls.click, [{}]);
+
+      const forced = scenario({
+        activation: { actionability: CLICK_ACTIONABILITY.FORCE },
+      });
+      await forced.dispatch();
+      assert.deepStrictEqual(forced.adapter.calls.click, [{ force: true }]);
+    });
+
+    it('should restore the scroll position for scroll: preserve', async () => {
+      // The engine is free to scroll; the caller asked for the viewport to end
+      // up where it started.
+      const { adapter, dispatch } = scenario({
+        adapter: { scrollOnClick: 3911 },
+        activation: { scroll: CLICK_SCROLL.PRESERVE },
+      });
+
+      const detail = await dispatch();
+
+      assert.strictEqual(adapter.currentScrollY(), 0);
+      assert.strictEqual(detail.scrollAfter.y, 0);
+    });
+
+    it('should use a real pointer at the element point for scroll: none', async () => {
+      // Regression test for issue #89: `{ force: true }` still scrolled
+      // (scrollY 0 -> 3911 in the live repro). A mouse click at the measured
+      // point cannot scroll at all.
+      const { page, adapter, dispatch } = scenario({
+        adapter: { scrollOnClick: 3911 },
+        activation: { scroll: CLICK_SCROLL.NONE },
+      });
+
+      const detail = await dispatch();
+
+      assert.deepStrictEqual(page.clicks, [{ x: 50, y: 60 }]);
+      assert.deepStrictEqual(adapter.calls.click, []);
+      assert.strictEqual(adapter.currentScrollY(), 0);
+      assert.strictEqual(detail.scrollBefore.y, detail.scrollAfter.y);
+    });
+
+    it('should refuse scroll: none when the element is off-screen', async () => {
+      const { page, dispatch } = scenario({
+        adapter: {
+          point: {
+            ...IN_VIEWPORT_POINT,
+            y: 4000,
+            top: 3980,
+            inViewport: false,
+            hitsTarget: false,
+          },
+        },
+        activation: { scroll: CLICK_SCROLL.NONE },
+      });
+
+      await assert.rejects(dispatch, (error) => {
+        assert.ok(error instanceof ScrollConstraintError);
+        assert.ok(error.message.includes('outside the viewport'));
+        assert.ok(error.message.includes('scroll: "preserve"'));
+        assert.strictEqual(error.detail.inViewport, false);
+        return true;
+      });
+      assert.deepStrictEqual(page.clicks, []);
+    });
+
+    it('should refuse scroll: none when another element covers the target', async () => {
+      const { page, dispatch } = scenario({
+        adapter: { point: { ...IN_VIEWPORT_POINT, hitsTarget: false } },
+        activation: { scroll: CLICK_SCROLL.NONE },
+      });
+
+      await assert.rejects(dispatch, /covers the target/u);
+      assert.deepStrictEqual(page.clicks, []);
+    });
+
+    it('should dispatch an untrusted DOM click for activation: dom', async () => {
+      const { page, adapter, dispatch } = scenario({
+        activation: { activation: CLICK_ACTIVATION.DOM },
+      });
+
+      const detail = await dispatch();
+
+      assert.strictEqual(adapter.calls.domClick, 1);
+      assert.deepStrictEqual(adapter.calls.click, []);
+      assert.deepStrictEqual(page.clicks, []);
+      assert.strictEqual(detail.mode, CLICK_ACTIVATION.DOM);
+      assert.strictEqual(detail.point, null);
+    });
+  });
+});

package/tests/unit/interactions/click-result.test.js

@@ -0,0 +1,90 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+import {
+  CLICK_STATUS,
+  CLICK_EFFECT,
+  evidence,
+  makeClickResult,
+  nextActionId,
+} from '../../../src/interactions/click-result.js';
+
+describe('click result model', () => {
+  it('should expose the documented status and effect vocabularies', () => {
+    assert.deepStrictEqual(Object.values(CLICK_STATUS).sort(), [
+      'failed',
+      'interrupted',
+      'succeeded',
+      'timed_out',
+      'unverified',
+    ]);
+    assert.deepStrictEqual(Object.values(CLICK_EFFECT).sort(), [
+      'confirmed',
+      'contradicted',
+      'not-observed',
+    ]);
+  });
+
+  it('should build evidence entries with a type and detail', () => {
+    const entry = evidence('navigation', { urlChanged: true });
+    assert.deepStrictEqual(entry, {
+      type: 'navigation',
+      detail: { urlChanged: true },
+    });
+    assert.deepStrictEqual(evidence('element-state').detail, {});
+  });
+
+  it('should derive verified only from confirmed effect', () => {
+    // Regression test for issue #89: `verified` must never be true unless an
+    // effect was actually observed.
+    const confirmed = makeClickResult({
+      status: CLICK_STATUS.SUCCEEDED,
+      dispatched: true,
+      effect: CLICK_EFFECT.CONFIRMED,
+    });
+    assert.strictEqual(confirmed.verified, true);
+
+    for (const effect of [
+      CLICK_EFFECT.NOT_OBSERVED,
+      CLICK_EFFECT.CONTRADICTED,
+    ]) {
+      const result = makeClickResult({
+        status: CLICK_STATUS.UNVERIFIED,
+        dispatched: true,
+        effect,
+      });
+      assert.strictEqual(result.verified, false, effect);
+    }
+  });
+
+  it('should derive clicked from dispatched', () => {
+    assert.strictEqual(makeClickResult({ dispatched: true }).clicked, true);
+    assert.strictEqual(makeClickResult({ dispatched: false }).clicked, false);
+    assert.strictEqual(makeClickResult({}).clicked, false);
+  });
+
+  it('should default to a conservative not-observed effect', () => {
+    const result = makeClickResult({ status: CLICK_STATUS.UNVERIFIED });
+    assert.strictEqual(result.effect, CLICK_EFFECT.NOT_OBSERVED);
+    assert.strictEqual(result.verified, false);
+    assert.strictEqual(result.navigated, false);
+    assert.deepStrictEqual(result.evidence, []);
+    assert.strictEqual(result.elapsedMs, 0);
+  });
+
+  it('should omit actionId unless one was supplied', () => {
+    assert.ok(!('actionId' in makeClickResult({})));
+    assert.strictEqual(makeClickResult({ actionId: 'a1' }).actionId, 'a1');
+  });
+
+  it('should carry extra fields through untouched', () => {
+    const result = makeClickResult({ selector: '#go', ready: false });
+    assert.strictEqual(result.selector, '#go');
+    assert.strictEqual(result.ready, false);
+  });
+
+  it('should mint unique action ids for navigation correlation', () => {
+    const ids = new Set(Array.from({ length: 200 }, () => nextActionId()));
+    assert.strictEqual(ids.size, 200);
+    assert.ok([...ids].every((id) => id.startsWith('click-')));
+  });
+});