browser-commander 0.20.0 → 0.21.1

package/tests/fixtures/traces/conformance/expected/trace.lino

@@ -0,0 +1,27 @@
+(trace: (format: browser-commander-trace) (links: 1) (schema: 2) (bundle: bundle) (mode: continuous) (engine: playwright) (started: '2026-01-01T00:00:00.000Z') (commander: 0.0.0-conformance))
+(timeline: (sequence: 1) (at: '2026-01-01T00:00:00.000Z') (monotonicMs: 1235) (kind: trace.start) (trace: trace-1) (context: context-1) (page: page-1) (navigation: nav-1) (actor: recorder) (outcome: recorded) (mode: continuous) (engine: playwright) (dom: '{"html":true,"liveControlState":true,"liveState":true,"mutations":true,"openShadowRoots":true}') (events: '["navigation","interaction","console","pageerror","dialog","requestfailed","download"]') (initialCheckpoint: true))
+(timeline: (sequence: 2) (at: '2026-01-01T00:00:00.000Z') (monotonicMs: 1235) (kind: checkpoint) (trace: trace-1) (context: context-1) (page: page-1) (navigation: nav-1) (actor: recorder) (target: 'https://[redacted]:[redacted]@example.com/start?ticket=[redacted]&lang=en#access_token=[redacted]&view=1') (outcome: recorded) (index: 1) (name: initial) (reason: initial) (url: 'https://[redacted]:[redacted]@example.com/start?ticket=[redacted]&lang=en#access_token=[redacted]&view=1') (truncated: false))
+(checkpoint: (index: 1) (sequence: 2) (at: '2026-01-01T00:00:00.000Z') (name: initial) (actor: recorder) (reason: initial) (page: page-1) (navigation: nav-1) (url: 'https://[redacted]:[redacted]@example.com/start?ticket=[redacted]&lang=en#access_token=[redacted]&view=1') (outcome: recorded) (html: checkpoints/0001.html) (state: checkpoints/0001.state.json) (screenshot: checkpoints/0001.png))
+(timeline: (sequence: 3) (at: '2026-01-01T00:00:00.000Z') (monotonicMs: 1235) (kind: navigation) (trace: trace-1) (context: context-1) (page: page-1) (navigation: nav-2) (actor: browser) (action: framenavigated) (target: 'https://example.com/next?token=[redacted]&q=a+b') (outcome: recorded) (phase: framenavigated) (mainFrame: true) (url: 'https://example.com/next?token=[redacted]&q=a+b'))
+(timeline: (sequence: 4) (at: '2026-01-01T00:00:00.000Z') (monotonicMs: 1235) (kind: navigation) (trace: trace-1) (context: context-1) (page: page-1) (navigation: nav-2) (actor: browser) (action: framenavigated) (target: 'https://ads.example.com/frame') (outcome: recorded) (phase: framenavigated) (mainFrame: false) (url: 'https://ads.example.com/frame'))
+(timeline: (sequence: 5) (at: '2026-01-01T00:00:00.000Z') (monotonicMs: 1235) (kind: console) (trace: trace-1) (context: context-1) (page: page-1) (navigation: nav-2) (actor: browser) (outcome: recorded) (level: log) (text: "key [redacted] loaded\n\ttab \u0022and\u0022 'quotes'"))
+(timeline: (sequence: 6) (at: '2026-01-01T00:00:00.000Z') (monotonicMs: 1235) (kind: pageerror) (trace: trace-1) (context: context-1) (page: page-1) (navigation: nav-2) (actor: browser) (outcome: recorded) (message: 'boom: (unbalanced') (stack: 'Error: boom\n    at main.js:1:2'))
+(timeline: (sequence: 7) (at: '2026-01-01T00:00:00.000Z') (monotonicMs: 1235) (kind: requestfailed) (trace: trace-1) (context: context-1) (page: page-1) (navigation: nav-2) (actor: browser) (target: 'https://api.example.com/v1?api_key=[redacted]&page=2') (outcome: failed) (url: 'https://api.example.com/v1?api_key=[redacted]&page=2') (method: POST) (failure: 'net::ERR_FAILED'))
+(timeline: (sequence: 8) (at: '2026-01-01T00:00:00.000Z') (monotonicMs: 1235) (kind: dialog) (trace: trace-1) (context: context-1) (page: page-1) (navigation: nav-2) (actor: browser) (outcome: recorded) (type: confirm) (message: 'Continue? #yes'))
+(timeline: (sequence: 9) (at: '2026-01-01T00:00:00.000Z') (monotonicMs: 1235) (kind: download) (trace: trace-1) (context: context-1) (page: page-1) (navigation: nav-2) (actor: browser) (action: completed) (target: 'https://files.example.com/r.csv?signature=[redacted]') (outcome: recorded) (phase: completed) (id: download-1) (suggestedFilename: 'report final.csv') (path: '/downloads/report final.csv') (checksum: 'sha256:00ff') (bytes: 42) (url: 'https://files.example.com/r.csv?signature=[redacted]'))
+(timeline: (sequence: 10) (at: '2026-01-01T00:00:00.000Z') (monotonicMs: 1235) (kind: interaction) (trace: trace-1) (context: context-1) (page: page-1) (navigation: nav-2) (actor: automation) (action: goto) (target: 'https://example.com/next?code=abc') (outcome: ok) (actionId: trace-1-action-1) (durationMs: 0) (ok: true))
+(timeline: (sequence: 11) (at: '2026-01-01T00:00:00.000Z') (monotonicMs: 1235) (kind: interaction) (trace: trace-1) (context: context-1) (page: page-1) (navigation: nav-2) (actor: automation) (action: clickButton) (target: '#go') (outcome: failed) (actionId: trace-1-action-2) (durationMs: 0) (ok: false) (error: 'button #go is not visible'))
+(timeline: (sequence: 12) (at: '2026-01-01T00:00:00.000Z') (monotonicMs: 1235) (kind: dropped) (actor: recorder) (target: mutations) (outcome: dropped) (reason: size-limit) (member: mutations) (detail: '2 records over the in-page queue limit'))
+(timeline: (sequence: 13) (at: '2026-01-01T00:00:00.000Z') (monotonicMs: 1235) (kind: mutations) (trace: trace-1) (context: context-1) (page: page-1) (navigation: nav-2) (actor: recorder) (target: mutations/0001.ndjson) (outcome: recorded) (member: mutations/0001.ndjson) (batches: 2) (checkpoint: 1) (frames: 1))
+(timeline: (sequence: 14) (at: '2026-01-01T00:00:00.000Z') (monotonicMs: 1235) (kind: checkpoint) (trace: trace-1) (context: context-1) (page: page-1) (navigation: nav-2) (actor: automation) (target: 'https://example.com/next?token=[redacted]') (outcome: partial) (index: 2) (name: 'after click') (reason: checkpoint) (url: 'https://example.com/next?token=[redacted]') (truncated: true))
+(checkpoint: (index: 2) (sequence: 14) (at: '2026-01-01T00:00:00.000Z') (name: 'after click') (actor: automation) (reason: checkpoint) (page: page-1) (navigation: nav-2) (url: 'https://example.com/next?token=[redacted]') (outcome: partial) (html: checkpoints/0002.html) (state: checkpoints/0002.state.json) (screenshot: checkpoints/0002.png))
+(timeline: (sequence: 15) (at: '2026-01-01T00:00:00.000Z') (monotonicMs: 1235) (kind: interaction) (trace: trace-1) (context: context-1) (page: page-1) (navigation: nav-2) (actor: caller) (action: note) (outcome: recorded) (authorization: [redacted]) (detail: 'uses [redacted]') (pageUrl: 'https://example.com/?session=[redacted]') (count: 3) (ratio: 0.25) (whole: 2) (nested: '{"list":[1,"two",null,true]}'))
+(timeline: (sequence: 16) (at: '2026-01-01T00:00:00.000Z') (monotonicMs: 1235) (kind: mutations) (trace: trace-1) (context: context-1) (page: page-1) (navigation: nav-2) (actor: recorder) (target: mutations/0002.ndjson) (outcome: recorded) (member: mutations/0002.ndjson) (batches: 1) (checkpoint: 2) (frames: 1))
+(timeline: (sequence: 17) (at: '2026-01-01T00:00:00.000Z') (monotonicMs: 1235) (kind: checkpoint) (trace: trace-1) (context: context-1) (page: page-1) (navigation: nav-2) (actor: caller) (target: 'https://example.com/next?token=[redacted]') (outcome: partial) (index: 3) (name: final) (reason: failure) (url: 'https://example.com/next?token=[redacted]') (truncated: true))
+(checkpoint: (index: 3) (sequence: 17) (at: '2026-01-01T00:00:00.000Z') (name: final) (actor: caller) (reason: failure) (page: page-1) (navigation: nav-2) (url: 'https://example.com/next?token=[redacted]') (outcome: partial) (html: checkpoints/0003.html) (state: checkpoints/0003.state.json) (screenshot: checkpoints/0003.png))
+(timeline: (sequence: 18) (at: '2026-01-01T00:00:00.000Z') (monotonicMs: 1235) (kind: trace.stop) (trace: trace-1) (context: context-1) (page: page-1) (navigation: nav-2) (actor: recorder) (outcome: recorded) (discarded: false))
+(control-diff: (checkpoint: 2) (previous: 1) (path: 'form > input:nth-of-type(1)') (change: changed) (before: alice) (after: bob) (actor: automation))
+(control-diff: (checkpoint: 2) (previous: 1) (path: 'form > input:nth-of-type(2)') (change: changed) (before: false) (after: true) (actor: automation))
+(control-diff: (checkpoint: 2) (previous: 1) (path: 'form > textarea') (change: added) (after: '[redacted] note') (actor: automation))
+(control-diff: (checkpoint: 2) (previous: 1) (path: 'form > select') (change: removed) (before: a) (actor: automation))
+(result: (outcome: partial) (stopped: '2026-01-01T00:00:00.000Z') (events: 18) (checkpoints: 3) (mutationBatches: 3) (dropped: 1) (truncated: true) (replay: checkpoints mutations childListPositions liveState identifiers))

package/tests/fixtures/traces/conformance/scenario.json

@@ -0,0 +1,249 @@
+{
+  "description": "One continuous trace recorded against a fake page by JavaScript, Python and Rust; all three must write these bytes.",
+  "clock": { "now": 1767225600000, "monotonic": 1234.5 },
+  "engine": "playwright",
+  "options": {
+    "mode": "continuous",
+    "commanderVersion": "0.0.0-conformance",
+    "privacy": {
+      "redactPatterns": ["sk-[a-z0-9]+"],
+      "redactQueryParams": ["ticket"]
+    },
+    "limits": { "maxQueuedMutations": 100 },
+    "links": true
+  },
+  "snapshot": {
+    "html": "<!DOCTYPE html>\n<html><head><title>Start</title></head><body><form><input name=\"user\" value=\"alice\"><input type=\"checkbox\" name=\"agree\"><select name=\"plan\"><option>a</option></select></form></body></html>",
+    "truncated": false,
+    "state": {
+      "url": "https://user:pw@example.com/start?ticket=t-1&lang=en#access_token=abc&view=1",
+      "title": "Start – “quoted” 'single' \\ back",
+      "readyState": "complete",
+      "scroll": { "x": 0, "y": 12.5 },
+      "viewport": { "width": 1280, "height": 720 },
+      "activeElement": null,
+      "controls": [
+        {
+          "path": "form > input:nth-of-type(1)",
+          "tag": "input",
+          "type": "text",
+          "name": "user",
+          "id": null,
+          "focused": false,
+          "value": "alice",
+          "redacted": false
+        },
+        {
+          "path": "form > input:nth-of-type(2)",
+          "tag": "input",
+          "type": "checkbox",
+          "name": "agree",
+          "id": null,
+          "focused": false,
+          "value": "on",
+          "checked": false,
+          "redacted": false
+        },
+        {
+          "path": "form > select",
+          "tag": "select",
+          "type": null,
+          "name": "plan",
+          "id": null,
+          "focused": false,
+          "value": "a",
+          "selected": [0],
+          "redacted": false
+        }
+      ],
+      "frames": []
+    }
+  },
+  "steps": [
+    {
+      "op": "queueMutations",
+      "dropped": 2,
+      "batches": [
+        {
+          "at": 1767225600200,
+          "records": [
+            {
+              "type": "attributes",
+              "target": 4,
+              "name": "class",
+              "value": "busy"
+            }
+          ]
+        },
+        {
+          "at": 1767225600100,
+          "records": [
+            {
+              "type": "live-state",
+              "target": 2,
+              "property": "value",
+              "value": "bo"
+            },
+            {
+              "type": "childList",
+              "target": 1,
+              "added": [{ "id": 9, "html": "<p>new
line</p>" }],
+              "removed": [],
+              "index": 3
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "op": "emit",
+      "event": "framenavigated",
+      "data": {
+        "url": "https://example.com/next?token=abc&q=a b",
+        "main": true
+      }
+    },
+    {
+      "op": "emit",
+      "event": "framenavigated",
+      "data": { "url": "https://ads.example.com/frame", "main": false }
+    },
+    {
+      "op": "emit",
+      "event": "console",
+      "data": {
+        "type": "log",
+        "text": "key sk-abc123 loaded\n\ttab \"and\" 'quotes'"
+      }
+    },
+    {
+      "op": "emit",
+      "event": "pageerror",
+      "data": {
+        "message": "boom: (unbalanced",
+        "stack": "Error: boom\n    at main.js:1:2"
+      }
+    },
+    {
+      "op": "emit",
+      "event": "requestfailed",
+      "data": {
+        "url": "https://api.example.com/v1?api_key=k&page=2",
+        "method": "POST",
+        "errorText": "net::ERR_FAILED"
+      }
+    },
+    {
+      "op": "dialog",
+      "data": { "type": "confirm", "message": "Continue? #yes" }
+    },
+    {
+      "op": "download",
+      "phase": "completed",
+      "artifact": {
+        "id": "download-1",
+        "suggestedFilename": "report final.csv",
+        "path": "/downloads/report final.csv",
+        "checksum": "sha256:00ff",
+        "bytes": 42,
+        "url": "https://files.example.com/r.csv?signature=s"
+      }
+    },
+    {
+      "op": "interaction",
+      "action": "goto",
+      "target": "https://example.com/next?code=abc"
+    },
+    {
+      "op": "interaction",
+      "action": "clickButton",
+      "target": "#go",
+      "fail": "button #go is not visible"
+    },
+    {
+      "op": "setSnapshot",
+      "snapshot": {
+        "html": "<!DOCTYPE html>\n<html><body><form><input name=\"user\" value=\"bob\"><textarea>sk-zzz9 note</textarea></form></body></html>",
+        "truncated": true,
+        "state": {
+          "url": "https://example.com/next?token=abc",
+          "title": "Next",
+          "readyState": "interactive",
+          "scroll": { "x": 0, "y": 0 },
+          "viewport": { "width": 1280, "height": 720 },
+          "activeElement": "form > textarea",
+          "controls": [
+            {
+              "path": "form > input:nth-of-type(1)",
+              "tag": "input",
+              "type": "text",
+              "name": "user",
+              "id": null,
+              "focused": false,
+              "value": "bob",
+              "redacted": false
+            },
+            {
+              "path": "form > input:nth-of-type(2)",
+              "tag": "input",
+              "type": "checkbox",
+              "name": "agree",
+              "id": null,
+              "focused": false,
+              "value": "on",
+              "checked": true,
+              "redacted": false
+            },
+            {
+              "path": "form > textarea",
+              "tag": "textarea",
+              "type": null,
+              "name": null,
+              "id": "note",
+              "focused": true,
+              "value": "sk-zzz9 note",
+              "scroll": { "x": 0, "y": 3 },
+              "redacted": false
+            }
+          ],
+          "frames": [
+            { "url": "https://ads.example.com/frame", "crossOrigin": true }
+          ]
+        }
+      }
+    },
+    { "op": "checkpoint", "name": "after click", "actor": "automation" },
+    {
+      "op": "queueMutations",
+      "dropped": 0,
+      "batches": [
+        {
+          "at": 1767225600300,
+          "records": [
+            { "type": "characterData", "target": 7, "value": "done ✓ 😀" }
+          ]
+        }
+      ]
+    },
+    {
+      "op": "event",
+      "name": "note",
+      "data": {
+        "authorization": "Bearer xyz",
+        "detail": "uses sk-q1w2",
+        "pageUrl": "https://example.com/?session=s1",
+        "count": 3,
+        "ratio": 0.25,
+        "whole": 2.0,
+        "nested": { "list": [1, "two", null, true] }
+      }
+    },
+    {
+      "op": "checkpoint",
+      "name": "final",
+      "actor": "caller",
+      "reason": "failure"
+    },
+    { "op": "stop" }
+  ]
+}

package/tests/helpers/cli-fakes.js

@@ -0,0 +1,214 @@
+/**
+ * Fake engine objects for the CLI and JSON-RPC dispatcher tests (issue #104).
+ *
+ * The dispatcher only calls a handful of page methods for its high-level
+ * methods, so a small in-memory page is enough to check what it sends and
+ * what it returns without a browser.
+ */
+import { EventEmitter } from 'node:events';
+import path from 'node:path';
+
+/** A page that records calls and keeps a URL, a title and field values. */
+export class FakePage extends EventEmitter {
+  constructor() {
+    super();
+    this.calls = [];
+    this.currentUrl = 'about:blank';
+    this.values = {};
+    this.cookies = [];
+  }
+
+  async goto(url) {
+    this.calls.push(['goto', url]);
+    this.currentUrl = url;
+  }
+
+  url() {
+    return this.currentUrl;
+  }
+
+  async title() {
+    return `Title of ${this.currentUrl}`;
+  }
+
+  async click(selector) {
+    this.calls.push(['click', selector]);
+  }
+
+  async fill(selector, value) {
+    this.calls.push(['fill', selector, value]);
+    this.values[selector] = value;
+  }
+
+  locator(selector) {
+    return { fill: (value) => this.fill(selector, value) };
+  }
+
+  async evaluate(expression, ...args) {
+    this.calls.push(['evaluate', expression]);
+    return typeof expression === 'function'
+      ? expression(...args)
+      : { expression };
+  }
+
+  async screenshot(options = {}) {
+    this.calls.push(['screenshot', options]);
+    return Buffer.from('png-bytes');
+  }
+
+  async pdf(options = {}) {
+    this.calls.push(['pdf', options]);
+    return Buffer.from('%PDF');
+  }
+
+  async setCookie(...cookies) {
+    this.cookies.push(...cookies);
+  }
+
+  context() {
+    return this.owner;
+  }
+}
+
+/** A Playwright-like context owning one page. */
+export class FakeContext {
+  constructor(page) {
+    this.page = page;
+    page.owner = this;
+    this.cookies = [];
+  }
+
+  pages() {
+    return [this.page];
+  }
+
+  async addCookies(cookies) {
+    if (cookies.some((cookie) => cookie.name === 'bad')) {
+      throw new Error('Invalid cookie fields');
+    }
+    this.cookies.push(...cookies);
+  }
+}
+
+/**
+ * Dependencies for `createDispatcher()` backed by fakes.
+ *
+ * @returns {{dependencies: Object, launches: Object[], connections: Object[], pages: FakePage[], relays: Object[]}}
+ */
+export function createFakeDependencies() {
+  const launches = [];
+  const connections = [];
+  const pages = [];
+  const relays = [];
+  const newPage = () => {
+    const page = new FakePage();
+    pages.push(page);
+    return page;
+  };
+  const dependencies = {
+    packageInfo: async () => ({
+      name: 'browser-commander',
+      version: '0.0.0-test',
+      language: 'js',
+    }),
+    launchBrowser: async (options) => {
+      const page = newPage();
+      const context = new FakeContext(page);
+      const record = { options, closed: false };
+      launches.push(record);
+      return {
+        browser: context,
+        page,
+        connectedBrowser: { name: 'fake-browser' },
+        cdpEndpoint: 'http://127.0.0.1:9222',
+        remoteDebuggingPort: 9222,
+        userDataDir: '/tmp/fake-profile',
+        temporaryProfile: true,
+        args: ['--user-data-dir=/tmp/fake-profile'],
+        close: async () => {
+          record.closed = true;
+        },
+      };
+    },
+    connectBrowser: async (options) => {
+      const page = newPage();
+      const context = new FakeContext(page);
+      const record = { options, closed: false, disconnected: false };
+      connections.push(record);
+      const browser = new EventEmitter();
+      browser.close = async () => {
+        record.closed = true;
+      };
+      browser.disconnect = async () => {
+        record.disconnected = true;
+      };
+      browser.defaultBrowserContext = () => context;
+      return { browser, page };
+    },
+    startTrace: async ({ output }) => ({
+      path: output,
+      stopped: false,
+      async stop() {
+        this.stopped = true;
+      },
+    }),
+    writeTraceViewer: async (bundle, output) =>
+      output ?? path.join(bundle, 'viewer.html'),
+    readBrowserCookies: async ({ domainFilter }) => [
+      { name: 'sid', value: '1', domain: `.${domainFilter}`, path: '/' },
+      { name: 'bad', value: '2', domain: `.${domainFilter}`, path: '/' },
+    ],
+    loadEngine: async (name) => ({ default: new FakeEngine(name) }),
+    openInUserBrowser: async (url) => ({ opened: url, command: ['open', url] }),
+    migrateProfile: async (options) => ({ migrated: {}, options }),
+    measureParity: async () => ({ ok: true, unlisted: [] }),
+    snapshotUserDataDir: async (options) => ({
+      source: {
+        browser: options.browser,
+        profile: options.profile ?? 'Default',
+        userDataDir: `/home/user/.config/${options.browser}`,
+      },
+      target: options.to ?? '/tmp/fake-snapshot',
+      copied: { files: 3, databases: 1 },
+      skipped: [{ item: 'SingletonLock', reason: 'lock' }],
+      warnings: [],
+    }),
+    attachUserBrowser: async (options) => {
+      const relay = {
+        options,
+        mode: 'extension',
+        extension: { id: 'abc', version: '0.20.0', userAgent: 'Chrome' },
+        differences: [{ aspect: 'debugger-infobar', description: 'infobar' }],
+        closed: false,
+        sent: [],
+        tabs: async () => [
+          { tabId: 1, url: 'https://example.com/', title: 'Example' },
+        ],
+        session: async (tabId) => ({
+          tabId,
+          send: async (method, params) => {
+            relay.sent.push({ tabId, method, params });
+            return { ok: true };
+          },
+        }),
+        close: async () => {
+          relay.closed = true;
+        },
+      };
+      relays.push(relay);
+      return relay;
+    },
+  };
+  return { dependencies, launches, connections, pages, relays };
+}
+
+/** A stand-in for the Playwright or Puppeteer entry object. */
+export class FakeEngine {
+  constructor(name) {
+    this.name = name;
+  }
+
+  launch() {
+    return `launched with ${this.name}`;
+  }
+}

package/tests/helpers/declared-api.js

@@ -0,0 +1,80 @@
+/**
+ * The public methods an engine declares in its TypeScript definitions
+ * (issue #104, API coverage).
+ *
+ * `serve --stdio` promises that the generic handle methods reach every public
+ * Playwright and Puppeteer method. The authoritative list of those methods is
+ * what each package ships for TypeScript users:
+ *
+ * - Puppeteer: `puppeteer-core/lib/types.d.ts` (`export declare class …`).
+ * - Playwright: `playwright-core/types/types.d.ts` (`export interface …`).
+ *   Playwright's wire protocol description (`protocol.yml`) is not shipped
+ *   in the npm package, so the client API declarations are used instead.
+ *
+ * Both files put every member of a class or interface on a line indented by
+ * exactly two spaces, which is all this parser relies on.
+ */
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+
+const require = createRequire(import.meta.url);
+
+const BLOCK_START =
+  /^export (?:declare )?(?:abstract )?(?:class|interface) ([A-Za-z]\w*)/u;
+const MEMBER =
+  /^ {2}(?:(?:public|abstract|async|override)\s+)*([A-Za-z$][\w$]*)\??(?:<|\()/u;
+const NOT_A_METHOD = /^ {2}(?:private|protected|static|get|set|readonly)\s/u;
+
+/**
+ * Methods declared directly on each class or interface of a `.d.ts` file.
+ * Private, protected and static members, accessors, the constructor and
+ * `_`-prefixed names are left out.
+ *
+ * @param {string} source - The declaration file contents
+ * @returns {Map<string, Set<string>>} Type name to method names
+ */
+export function parseDeclaredMethods(source) {
+  const types = new Map();
+  let current = null;
+  for (const line of source.split(/\r?\n/u)) {
+    const start = BLOCK_START.exec(line);
+    if (start) {
+      current = new Set();
+      types.set(start[1], current);
+      continue;
+    }
+    if (line === '}') {
+      current = null;
+      continue;
+    }
+    if (!current || NOT_A_METHOD.test(line)) {
+      continue;
+    }
+    const name = MEMBER.exec(line)?.[1];
+    if (name && name !== 'constructor' && !name.startsWith('_')) {
+      current.add(name);
+    }
+  }
+  return types;
+}
+
+/** The declaration file of an installed package. */
+function declarationFile(packageName, relative) {
+  const root = path.dirname(require.resolve(`${packageName}/package.json`));
+  return readFileSync(path.join(root, relative), 'utf8');
+}
+
+/** Puppeteer's declared classes and their methods. */
+export function puppeteerDeclarations() {
+  return parseDeclaredMethods(
+    declarationFile('puppeteer-core', 'lib/types.d.ts')
+  );
+}
+
+/** Playwright's declared interfaces and their methods. */
+export function playwrightDeclarations() {
+  return parseDeclaredMethods(
+    declarationFile('playwright-core', 'types/types.d.ts')
+  );
+}

package/tests/helpers/e2e-browser.js

@@ -8,12 +8,34 @@
  * read as the behaviour they check.
  */
 
-import fs from 'node:fs/promises';
-import os from 'node:os';
-import path from 'node:path';
+import { existsSync } from 'node:fs';
 
 import { launchBrowser } from '../../src/browser/launcher.js';
 
+/** The installed Chrome the parity suites compare against. */
+export const PARITY_CHROME =
+  process.env.CHROME_PATH || '/usr/bin/google-chrome';
+
+/**
+ * Why a parity suite cannot run here, or `false` when it can.
+ *
+ * @param {Object} [options]
+ * @param {boolean} [options.headless=false] - Headless suites need no display
+ * @returns {string|false}
+ */
+export function paritySkipReason({ headless = false } = {}) {
+  if (!process.env.RUN_E2E) {
+    return 'set RUN_E2E=true to run the parity tests';
+  }
+  if (!existsSync(PARITY_CHROME)) {
+    return `no Chrome binary at ${PARITY_CHROME}; set CHROME_PATH`;
+  }
+  if (!headless && process.platform === 'linux' && !process.env.DISPLAY) {
+    return 'headful parity needs a display; run under xvfb-run';
+  }
+  return false;
+}
+
 /**
  * Extra Chrome arguments for environments without a usable sandbox.
  *
@@ -24,6 +46,17 @@ import { launchBrowser } from '../../src/browser/launcher.js';
 export const SANDBOX_ARGS =
   process.env.CHROME_NO_SANDBOX === 'true' ? ['--no-sandbox'] : [];
 
+/**
+ * The sandbox arguments plus the CHROME_PATH binary, when one is set: the
+ * launch options every e2e suite shares.
+ */
+export const CHROME_LAUNCH_OPTIONS = {
+  args: SANDBOX_ARGS,
+  ...(process.env.CHROME_PATH
+    ? { executablePath: process.env.CHROME_PATH }
+    : {}),
+};
+
 /**
  * Launch a real browser for one engine, with its own profile.
  *
@@ -34,19 +67,13 @@ export const SANDBOX_ARGS =
  */
 export async function launchE2EBrowser(options = {}) {
   const { engine, downloadDirectory } = options;
-  const userDataDir = await fs.mkdtemp(
-    path.join(os.tmpdir(), 'bc-e2e-profile-')
-  );
 
+  // The default launch creates a fresh temporary profile and deletes it on
+  // close, so the helper no longer manages one itself.
   const launched = await launchBrowser({
     engine,
-    userDataDir,
     headless: process.env.HEADLESS !== 'false',
-    slowMo: 0,
-    args: SANDBOX_ARGS,
-    ...(process.env.CHROME_PATH
-      ? { executablePath: process.env.CHROME_PATH }
-      : {}),
+    ...CHROME_LAUNCH_OPTIONS,
     ...(downloadDirectory
       ? { downloads: { directory: downloadDirectory } }
       : {}),
@@ -60,8 +87,7 @@ export async function launchE2EBrowser(options = {}) {
      * @returns {Promise<void>} Resolves once both are gone
      */
     cleanup: async () => {
-      await launched.browser?.close();
-      await fs.rm(userDataDir, { recursive: true, force: true });
+      await launched.close();
     },
   };
 }