browser-commander 0.21.0 → 0.21.1

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/unit/browser/attach/extension-relay.test.js

@@ -1,4 +1,4 @@
-// feature-parity: attach.extension
+// feature-parity: attach.extension@native-typed
 import assert from 'node:assert';
 import { once } from 'node:events';
 import { access } from 'node:fs/promises';

package/tests/unit/browser/attach/snapshot-launch.test.js

@@ -1,5 +1,5 @@
 import assert from 'node:assert';
-import { access, mkdir, writeFile } from 'node:fs/promises';
+import { access, mkdir, readFile, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { describe, it } from 'node:test';
 
@@ -192,6 +192,15 @@ describe('snapshot attach launch option', () => {
     ]);
 
     await access(result.userDataDir);
+    assert.equal(
+      JSON.parse(
+        await readFile(
+          path.join(result.userDataDir, 'Profile 1', 'Preferences'),
+          'utf8'
+        )
+      ).browser.check_default_browser,
+      false
+    );
     browserProcess.exit(0);
     await new Promise((resolve) => setTimeout(resolve, 50));
     await assert.rejects(access(result.userDataDir), { code: 'ENOENT' });

package/tests/unit/browser/attach/snapshot.test.js

@@ -1,4 +1,4 @@
-// feature-parity: attach.snapshot
+// feature-parity: attach.snapshot@native-typed
 import assert from 'node:assert';
 import { createHash } from 'node:crypto';
 import {
@@ -151,9 +151,16 @@ describe('snapshotUserDataDir', () => {
     assert.equal(report.target, to);
     assert.deepEqual(report.warnings, []);
     assert.equal(report.copied.databases, 1);
+    const localState = JSON.parse(
+      await readFile(path.join(to, 'Local State'), 'utf8')
+    );
+    assert.deepEqual(localState.os_crypt, { key: 'k' });
+    assert.equal(localState.browser.default_browser_infobar_declined_count, 5);
+    assert.equal(localState.browser.default_browser_declined_count, 5);
     assert.equal(
-      await readFile(path.join(to, 'Local State'), 'utf8'),
-      JSON.stringify({ os_crypt: { key: 'k' } })
+      (await readProfileJson(path.join(to, 'Default'), 'Preferences')).browser
+        .check_default_browser,
+      false
     );
     assert.deepEqual(
       await readProfileJson(path.join(to, 'Default'), 'Bookmarks'),
@@ -258,7 +265,10 @@ describe('snapshotUserDataDir', () => {
 
         const copy = path.join(to, 'Default', 'History');
         // One self-contained file: the committed WAL content is folded in.
-        assert.deepEqual(await readdir(path.join(to, 'Default')), ['History']);
+        assert.deepEqual(await readdir(path.join(to, 'Default')), [
+          'History',
+          'Preferences',
+        ]);
         assert.equal(report.copied.databases, 1);
         assert.equal(countRows(copy), 6);
         const database = new BetterSqlite3(copy, { readonly: true });
@@ -335,6 +345,15 @@ describe('snapshotUserDataDir', () => {
     try {
       assert.equal(report.source.profile, 'Profile 1');
       await stat(path.join(report.target, 'Profile 1', 'Preferences'));
+      assert.equal(
+        (
+          await readProfileJson(
+            path.join(report.target, 'Profile 1'),
+            'Preferences'
+          )
+        ).browser.check_default_browser,
+        false
+      );
       await assert.rejects(stat(path.join(report.target, 'Default')), {
         code: 'ENOENT',
       });

package/tests/unit/browser/browser-cookie-lock.test.js

@@ -0,0 +1,102 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs/promises';
+import { syncBuiltinESMExports } from 'node:module';
+import os from 'node:os';
+import path from 'node:path';
+import { test } from 'node:test';
+
+import {
+  clearBrowserCookieMemoryCache,
+  getCachedCredential,
+} from '../../../src/browser/browser-cookie-cache.js';
+
+async function cleanup(t, directory) {
+  t.mock.restoreAll();
+  syncBuiltinESMExports();
+  clearBrowserCookieMemoryCache();
+  await fs.rm(directory, { recursive: true, force: true });
+}
+
+test('retries a Windows delete-pending credential lock without rereading the credential', async (t) => {
+  const directory = await fs.mkdtemp(path.join(os.tmpdir(), 'bc-cookie-lock-'));
+  const realOpen = fs.open;
+  let attempted = false;
+  let reads = 0;
+  // Model the observed Windows exclusive-open EPERM while the previous
+  // reader's lock is pending deletion. Other file operations stay real.
+  t.mock.method(fs, 'open', async (filename, ...args) => {
+    if (filename.endsWith('.lock') && !attempted) {
+      attempted = true;
+      throw Object.assign(new Error('lock pending deletion'), {
+        code: 'EPERM',
+      });
+    }
+    return realOpen(filename, ...args);
+  });
+  syncBuiltinESMExports();
+  try {
+    const options = {
+      cache: { enabled: true, dir: directory, ttlSeconds: 60 },
+      identity: 'windows-lock-contention',
+      refresh: false,
+      metadata: {},
+      platform: 'win32',
+      create: async () => {
+        reads += 1;
+        return Buffer.from('credential');
+      },
+    };
+    assert.deepEqual(
+      await getCachedCredential(options),
+      Buffer.from('credential')
+    );
+    clearBrowserCookieMemoryCache();
+    assert.deepEqual(
+      await getCachedCredential(options),
+      Buffer.from('credential')
+    );
+    assert.equal(reads, 1);
+    assert.ok(attempted);
+  } finally {
+    await cleanup(t, directory);
+  }
+});
+
+test('does not retry permanent permission errors or Unix EPERM', async (t) => {
+  const directory = await fs.mkdtemp(
+    path.join(os.tmpdir(), 'bc-cookie-denied-')
+  );
+  const realOpen = fs.open;
+  try {
+    for (const [platform, code] of [
+      ['win32', 'EACCES'],
+      ['linux', 'EPERM'],
+    ]) {
+      const error = Object.assign(new Error('access denied'), { code });
+      t.mock.method(fs, 'open', async (filename, ...args) => {
+        if (filename.endsWith('.lock')) {
+          throw error;
+        }
+        return realOpen(filename, ...args);
+      });
+      syncBuiltinESMExports();
+      await assert.rejects(
+        getCachedCredential({
+          cache: { enabled: true, dir: directory, ttlSeconds: 60 },
+          identity: platform,
+          refresh: false,
+          metadata: {},
+          platform,
+          create: async () => {
+            throw new Error('must not read credentials');
+          },
+        }),
+        (received) => received === error
+      );
+      t.mock.restoreAll();
+      syncBuiltinESMExports();
+    }
+  } finally {
+    await cleanup(t, directory);
+  }
+});

package/tests/unit/browser/launch-building-blocks.test.js

@@ -6,6 +6,7 @@ import path from 'node:path';
 import { PassThrough } from 'node:stream';
 import {
   access,
+  mkdir,
   mkdtemp,
   readFile,
   rm,
@@ -22,8 +23,10 @@ import {
   FIRST_RUN_SENTINEL,
   INITIAL_LOCAL_STATE,
   LOCAL_STATE_FILE,
+  PREFERENCES_FILE,
   TEMPORARY_PROFILE_PREFIX,
   createTemporaryUserDataDir,
+  configureUserDataDir,
   prepareUserDataDir,
   removeUserDataDir,
 } from '../../../src/browser/profile-directory.js';
@@ -106,6 +109,11 @@ describe('launch restrictions', () => {
 });
 
 describe('profile directory', () => {
+  const readPreferences = async (directory) =>
+    JSON.parse(
+      await readFile(path.join(directory, 'Default', 'Preferences'), 'utf8')
+    );
+
   it('creates a fresh profile with the First Run sentinel', async () => {
     const dir = await createTemporaryUserDataDir();
     try {
@@ -113,15 +121,25 @@ describe('profile directory', () => {
       await access(path.join(dir, FIRST_RUN_SENTINEL));
       assert.deepEqual(
         JSON.parse(await readFile(path.join(dir, LOCAL_STATE_FILE), 'utf8')),
-        INITIAL_LOCAL_STATE
+        {
+          browser: {
+            ...INITIAL_LOCAL_STATE.browser,
+            default_browser_infobar_declined_count: 5,
+            default_browser_declined_count: 5,
+          },
+          fre: INITIAL_LOCAL_STATE.fre,
+        }
       );
+      assert.deepEqual(await readPreferences(dir), {
+        browser: { check_default_browser: false },
+      });
     } finally {
       await removeUserDataDir(dir);
     }
     await assert.rejects(() => access(dir), /ENOENT/);
   });
 
-  it('never overwrites Local State that Chrome already wrote', async () => {
+  it('preserves other Local State values that Chrome already wrote', async () => {
     const dir = await mkdtemp(path.join(os.tmpdir(), 'bc-profile-test-'));
     try {
       const localState = path.join(dir, LOCAL_STATE_FILE);
@@ -130,9 +148,61 @@ describe('profile directory', () => {
         '{"browser":{"enabled_labs_experiments":[]}}'
       );
       await prepareUserDataDir(dir);
+      assert.deepEqual(JSON.parse(await readFile(localState, 'utf8')), {
+        browser: {
+          enabled_labs_experiments: [],
+          default_browser_infobar_declined_count: 5,
+          default_browser_declined_count: 5,
+        },
+      });
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+
+  it('deep-merges settings and lets the named default-browser option override a copied preference', async () => {
+    const dir = await mkdtemp(path.join(os.tmpdir(), 'bc-profile-test-'));
+    try {
+      await prepareUserDataDir(dir);
+      await writeFile(
+        path.join(dir, 'Default', 'Preferences'),
+        JSON.stringify({
+          browser: { check_default_browser: true, show_home_button: false },
+          intl: { accept_languages: 'en' },
+        })
+      );
+      await prepareUserDataDir(dir, {
+        defaultBrowserCheck: false,
+        preferences: { browser: { show_home_button: true } },
+        localState: { browser: { extra: 1 } },
+      });
+      assert.deepEqual(await readPreferences(dir), {
+        browser: { check_default_browser: false, show_home_button: true },
+        intl: { accept_languages: 'en' },
+      });
+      assert.deepEqual(
+        JSON.parse(await readFile(path.join(dir, LOCAL_STATE_FILE), 'utf8')),
+        {
+          browser: {
+            last_whats_new_version: 9999,
+            default_browser_infobar_declined_count: 5,
+            default_browser_declined_count: 5,
+            extra: 1,
+          },
+          fre: { has_user_seen_fre: true },
+        }
+      );
+      await prepareUserDataDir(dir, { defaultBrowserCheck: true });
       assert.equal(
-        await readFile(localState, 'utf8'),
-        '{"browser":{"enabled_labs_experiments":[]}}'
+        JSON.parse(
+          await readFile(path.join(dir, 'Default', 'Preferences'), 'utf8')
+        ).browser.check_default_browser,
+        true
+      );
+      assert.equal(
+        JSON.parse(await readFile(path.join(dir, LOCAL_STATE_FILE), 'utf8'))
+          .browser.default_browser_declined_count,
+        0
       );
     } finally {
       await rm(dir, { recursive: true, force: true });
@@ -153,6 +223,59 @@ describe('profile directory', () => {
       await rm(parent, { recursive: true, force: true });
     }
   });
+
+  it('allows an explicit first-run flow in a new profile', async () => {
+    const dir = await mkdtemp(path.join(os.tmpdir(), 'bc-profile-test-'));
+    try {
+      await prepareUserDataDir(dir, { firstRun: true });
+      await assert.rejects(
+        () => access(path.join(dir, FIRST_RUN_SENTINEL)),
+        /ENOENT/
+      );
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+
+  it('rejects malformed profile settings before writing them', async () => {
+    const dir = await mkdtemp(path.join(os.tmpdir(), 'bc-profile-test-'));
+    try {
+      await assert.rejects(
+        prepareUserDataDir(dir, { preferences: { browser: false } }),
+        /preferences.browser/u
+      );
+      await assert.rejects(
+        prepareUserDataDir(dir, { preferences: JSON.parse('{"__proto__":1}') }),
+        /profile setting key/u
+      );
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+
+  it('configures a selected snapshot profile instead of Default', async () => {
+    const dir = await mkdtemp(path.join(os.tmpdir(), 'bc-profile-test-'));
+    try {
+      const selected = path.join(dir, 'Profile 1');
+      await mkdir(selected);
+      await writeFile(
+        path.join(selected, 'Preferences'),
+        '{"browser":{"check_default_browser":true}}'
+      );
+      await configureUserDataDir(dir, { profileDirectory: 'Profile 1' });
+      assert.equal(
+        JSON.parse(await readFile(path.join(selected, 'Preferences'), 'utf8'))
+          .browser.check_default_browser,
+        false
+      );
+      await assert.rejects(
+        () => access(path.join(dir, PREFERENCES_FILE)),
+        /ENOENT/
+      );
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
 });
 
 describe('debugging port', () => {

package/tests/unit/browser/migration/index.test.js

@@ -1,4 +1,4 @@
-// feature-parity: migration.profile
+// feature-parity: migration.profile@native-typed
 import assert from 'node:assert';
 import { readFile } from 'node:fs/promises';
 import path from 'node:path';

package/tests/unit/browser/open-in-user-browser.test.js

@@ -1,4 +1,4 @@
-// feature-parity: attach.open
+// feature-parity: attach.open@native-typed
 import assert from 'node:assert';
 import { describe, it } from 'node:test';
 

package/tests/unit/browser/parity.test.js

@@ -1,4 +1,4 @@
-// feature-parity: parity.measure
+// feature-parity: parity.measure@native-typed
 import assert from 'node:assert';
 import { describe, it } from 'node:test';
 

package/tests/unit/browser/real-browser.test.js

@@ -1,4 +1,4 @@
-// feature-parity: migration.launch
+// feature-parity: migration.launch@native-typed
 import assert from 'node:assert';
 import { access, mkdtemp, rm } from 'node:fs/promises';
 import os from 'node:os';

package/tests/unit/browser/storage-state.test.js

@@ -146,3 +146,5 @@ describe('browser storage state', () => {
     assert.deepEqual(JSON.parse(await readFile(filePath, 'utf8')), state);
   });
 });
+
+// feature-parity: storage.portable@native-typed