browser-commander 0.20.0 → 0.21.0

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();
     },
   };
 }

package/tests/helpers/fake-chrome.js

@@ -0,0 +1,124 @@
+/**
+ * A fake `chrome` namespace and browser `WebSocket` for the companion
+ * extension tests (issue #102, addendum, mode 2).
+ *
+ * The extension code in js/extension only touches the handful of APIs below,
+ * so the relay handler and its service-worker client run unchanged in Node.
+ */
+import { connectWebSocket } from '../../src/browser/attach/websocket.js';
+
+/** A `chrome.*.onSomething` event whose listeners the test can fire. */
+function fakeEvent() {
+  const listeners = [];
+  return {
+    listeners,
+    addListener: (listener) => listeners.push(listener),
+    fire: (...args) => listeners.forEach((listener) => listener(...args)),
+  };
+}
+
+/**
+ * @param {Object} [options]
+ * @param {Array<Object>} [options.tabs] - `chrome.tabs.Tab`-like objects
+ * @param {Object} [options.storage] - `chrome.storage.local` contents
+ * @returns {Object} The fake namespace; `calls` records every API call
+ */
+export function createFakeChrome({ tabs = [], storage = {} } = {}) {
+  const calls = [];
+  let nextTabId = 100;
+  const chrome = {
+    calls,
+    tabs: {
+      query: async (query) => {
+        calls.push(['tabs.query', query]);
+        return tabs;
+      },
+      create: async (properties) => {
+        calls.push(['tabs.create', properties]);
+        const tab = { id: nextTabId++, pendingUrl: properties.url };
+        tabs.push(tab);
+        return tab;
+      },
+    },
+    debugger: {
+      attach: async (target, version) => {
+        calls.push(['debugger.attach', target.tabId, version]);
+      },
+      detach: async (target) => {
+        calls.push(['debugger.detach', target.tabId]);
+      },
+      sendCommand: async (target, method, params) => {
+        calls.push(['debugger.sendCommand', target.tabId, method, params]);
+        if (method === 'Bad.method') {
+          throw new Error("'Bad.method' wasn't found");
+        }
+        return method === 'Runtime.evaluate'
+          ? { result: { type: 'number', value: 2 } }
+          : undefined;
+      },
+      onEvent: fakeEvent(),
+      onDetach: fakeEvent(),
+    },
+    alarms: {
+      create: (name, info) => calls.push(['alarms.create', name, info]),
+      onAlarm: fakeEvent(),
+    },
+    storage: {
+      local: { get: async (key) => ({ [key]: storage[key] }) },
+      onChanged: fakeEvent(),
+    },
+    runtime: {
+      getManifest: () => ({ version: '1.2.3' }),
+      onStartup: fakeEvent(),
+      onInstalled: fakeEvent(),
+    },
+  };
+  return chrome;
+}
+
+/**
+ * The browser `WebSocket` API on top of {@link connectWebSocket}, sending the
+ * `Origin` an extension service worker sends.
+ */
+export function createExtensionWebSocket(origin = 'chrome-extension://abc') {
+  return class ExtensionWebSocket {
+    static CONNECTING = 0;
+    static OPEN = 1;
+    static CLOSED = 3;
+
+    constructor(url) {
+      this.url = url;
+      this.readyState = ExtensionWebSocket.CONNECTING;
+      connectWebSocket(url, { headers: { Origin: origin } }).then(
+        (connection) => {
+          this.connection = connection;
+          this.readyState = ExtensionWebSocket.OPEN;
+          connection.on('message', (data) => this.onmessage?.({ data }));
+          connection.on('error', () => {});
+          connection.once('close', () => this.closed());
+          this.onopen?.();
+        },
+        (error) => {
+          this.error = error;
+          this.onerror?.(error);
+          this.closed();
+        }
+      );
+    }
+
+    send(text) {
+      this.connection.send(text);
+    }
+
+    close() {
+      this.connection?.close();
+    }
+
+    closed() {
+      if (this.readyState !== ExtensionWebSocket.CLOSED) {
+        this.readyState = ExtensionWebSocket.CLOSED;
+        this.onclose?.();
+      }
+    }
+  };
+}

package/tests/helpers/migration-fixtures.js

@@ -0,0 +1,242 @@
+/**
+ * Profile fixtures for the migration tests.
+ *
+ * Every migration suite moves data from a source profile into a target one and
+ * checks the same report shape, and the Firefox suites (plus the installed
+ * browser cookie reader) need the same `cookies.sqlite`, `places.sqlite` and
+ * `logins.json` files, so they are built here once instead of per test file.
+ */
+
+import assert from 'node:assert';
+import { readFile, stat, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+
+import BetterSqlite3 from 'better-sqlite3';
+
+import { decryptChromiumCookie } from '../../src/browser/browser-cookie-crypto.js';
+import { openSqliteDatabase } from '../../src/browser/browser-cookie-database.js';
+import {
+  buildKey4Database,
+  buildLoginsJson,
+} from '../fixtures/firefox-nss-fixtures.mjs';
+
+/**
+ * Run a Chromium migration step from one profile directory into another.
+ *
+ * @param {Function} migrate - A `migrate*` data-class function
+ * @param {string} source - Source profile directory
+ * @param {string} target - Target profile directory
+ * @param {Object} [options] - Extra options for the step
+ * @returns {Promise<Object>} The step's report
+ */
+export function migrateBetween(migrate, source, target, options = {}) {
+  return migrate({
+    sourceProfileDir: source,
+    targetProfileDir: target,
+    ...options,
+  });
+}
+
+/**
+ * Assert that a step migrated nothing, and why.
+ *
+ * @param {Object} report - A data-class report
+ * @param {string} reason - The expected first skip reason
+ */
+export function assertNothingMigrated(report, reason) {
+  assert.equal(report.migrated, 0);
+  assert.equal(report.skipped[0].reason, reason);
+}
+
+/**
+ * Assert that `action` leaves a source file untouched. Migration only ever
+ * reads a snapshot of the source, so its modification time must not move.
+ *
+ * @param {string} filePath - The source file
+ * @param {() => Promise<void>} action
+ */
+export async function assertSourceUnchanged(filePath, action) {
+  const before = (await stat(filePath)).mtimeMs;
+  await action();
+  const after = (await stat(filePath)).mtimeMs;
+  assert.equal(before, after);
+}
+
+/**
+ * Write a JSON profile file such as `Bookmarks` or `Preferences`.
+ *
+ * @param {string} profileDir
+ * @param {string} name - File name relative to the profile
+ * @param {*} value - Serialised with `JSON.stringify`
+ * @returns {Promise<void>}
+ */
+export function writeProfileJson(profileDir, name, value) {
+  return writeFile(path.join(profileDir, name), JSON.stringify(value));
+}
+
+/**
+ * Read and parse a JSON profile file a migration wrote.
+ *
+ * @param {string} profileDir
+ * @param {string} name - File name relative to the profile
+ * @returns {Promise<*>}
+ */
+export async function readProfileJson(profileDir, name) {
+  return JSON.parse(await readFile(path.join(profileDir, name), 'utf8'));
+}
+
+/**
+ * Write a Chromium `History` database with `urlCount` visited URLs.
+ *
+ * @param {string} profileDir - Chromium profile directory
+ * @param {number} urlCount
+ * @returns {string} The database path
+ */
+export function writeChromiumHistory(profileDir, urlCount) {
+  const historyPath = path.join(profileDir, 'History');
+  const db = new BetterSqlite3(historyPath);
+  db.exec('CREATE TABLE urls (id INTEGER PRIMARY KEY, url TEXT, title TEXT)');
+  const insert = db.prepare('INSERT INTO urls (url, title) VALUES (?, ?)');
+  for (let i = 0; i < urlCount; i += 1) {
+    insert.run(`https://example.com/${i}`, `Page ${i}`);
+  }
+  db.close();
+  return historyPath;
+}
+
+/**
+ * Write a Firefox `cookies.sqlite` holding the given rows.
+ *
+ * @param {string} profileDir - Firefox profile directory
+ * @param {Array<Object>} rows - `{name, value, host}` plus optional `path`,
+ *   `expiry`, `secure`, `httpOnly` and `sameSite`
+ * @returns {Promise<string>} The database path
+ */
+export async function writeFirefoxCookies(profileDir, rows) {
+  const cookiePath = path.join(profileDir, 'cookies.sqlite');
+  const database = await openSqliteDatabase(cookiePath);
+  database.exec(`
+    CREATE TABLE moz_cookies (
+      name TEXT,
+      value TEXT,
+      host TEXT,
+      path TEXT,
+      expiry INTEGER,
+      isSecure INTEGER,
+      isHttpOnly INTEGER,
+      sameSite INTEGER
+    );
+  `);
+  const insert = database.prepare(`
+    INSERT INTO moz_cookies
+      (name, value, host, path, expiry, isSecure, isHttpOnly, sameSite)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+  `);
+  for (const row of rows) {
+    insert.run(
+      row.name,
+      row.value,
+      row.host,
+      row.path ?? '/',
+      row.expiry ?? 0,
+      row.secure ? 1 : 0,
+      row.httpOnly ? 1 : 0,
+      row.sameSite ?? 0
+    );
+  }
+  database.close();
+  return cookiePath;
+}
+
+/**
+ * Write a Firefox `places.sqlite` with a toolbar bookmark and, unless
+ * `withMenuBookmark` is false, a bookmarks-menu one. Each bookmark has its own
+ * `moz_places` row, so the history count equals the bookmark count.
+ *
+ * @param {string} profileDir - Firefox profile directory
+ * @param {Object} [options]
+ * @param {boolean} [options.withMenuBookmark=true]
+ */
+export function writeFirefoxPlaces(
+  profileDir,
+  { withMenuBookmark = true } = {}
+) {
+  const db = new BetterSqlite3(path.join(profileDir, 'places.sqlite'));
+  db.exec(
+    `CREATE TABLE moz_places (id INTEGER PRIMARY KEY, url TEXT);
+     CREATE TABLE moz_bookmarks (id INTEGER PRIMARY KEY, type INTEGER, fk INTEGER,
+       parent INTEGER, position INTEGER, title TEXT, guid TEXT);`
+  );
+  const insertPlace = db.prepare(
+    'INSERT INTO moz_places (id, url) VALUES (?, ?)'
+  );
+  const insertBookmark = db.prepare(
+    'INSERT INTO moz_bookmarks (id, type, fk, parent, position, title, guid) VALUES (?, ?, ?, ?, ?, ?, ?)'
+  );
+  insertBookmark.run(1, 2, null, 0, 0, '', 'root________');
+  insertBookmark.run(3, 2, null, 1, 0, 'Bookmarks Toolbar', 'toolbar_____');
+  insertPlace.run(10, 'https://toolbar.example/');
+  insertBookmark.run(100, 1, 10, 3, 0, 'Toolbar Site', 'aaaaaaaaaaaa');
+  if (withMenuBookmark) {
+    insertBookmark.run(2, 2, null, 1, 1, 'Bookmarks Menu', 'menu________');
+    insertPlace.run(11, 'https://menu.example/');
+    insertBookmark.run(101, 1, 11, 2, 0, 'Menu Site', 'bbbbbbbbbbbb');
+  }
+  db.close();
+}
+
+/**
+ * Write a Firefox `key4.db` and a `logins.json` encrypted with its login key.
+ *
+ * @param {string} profileDir - Firefox profile directory
+ * @param {Object} options
+ * @param {Array<{hostname: string, username: string, password: string}>} options.entries
+ * @param {Buffer} [options.primaryPassword] - Locks the key when set
+ * @returns {Promise<{key4Path: string, loginKey: Buffer}>}
+ */
+export async function writeFirefoxLogins(
+  profileDir,
+  { entries, primaryPassword }
+) {
+  const fixture = buildKey4Database({ dir: profileDir, primaryPassword });
+  await writeFile(
+    path.join(profileDir, 'logins.json'),
+    buildLoginsJson({ key: fixture.loginKey, entries })
+  );
+  return fixture;
+}
+
+/**
+ * Read back the logins a migration wrote to a target `Login Data`, decrypting
+ * each password with the target profile's key (Linux `v10`/`v11` scheme).
+ *
+ * @param {string} targetProfileDir
+ * @param {Buffer} targetKey
+ * @returns {Array<{origin: string, username: string, password: string}>}
+ *   Sorted by origin
+ */
+export function readMigratedLogins(targetProfileDir, targetKey) {
+  const db = new BetterSqlite3(path.join(targetProfileDir, 'Login Data'), {
+    readonly: true,
+  });
+  try {
+    return db
+      .prepare(
+        'SELECT origin_url, username_value, password_value FROM logins ORDER BY origin_url'
+      )
+      .all()
+      .map((row) => ({
+        origin: row.origin_url,
+        username: row.username_value,
+        password: decryptChromiumCookie({
+          encryptedValue: row.password_value,
+          host: new URL(row.origin_url).hostname,
+          databaseVersion: 0,
+          platform: 'linux',
+          key: targetKey,
+        }),
+      }));
+  } finally {
+    db.close();
+  }
+}

package/tests/helpers/temp-directory.js

@@ -42,3 +42,27 @@ export function useTempDirectory(prefix) {
 
   return holder;
 }
+
+/**
+ * Let each test create as many directories as it needs (a source and a target
+ * profile, say), and remove all of them after the test.
+ *
+ * @param {string} [prefix] - Default name prefix for the directories
+ * @returns {(prefix?: string) => Promise<string>} Creates and tracks one more
+ *   directory, optionally with its own prefix
+ */
+export function useTempDirectories(prefix) {
+  const created = [];
+
+  afterEach(async () => {
+    while (created.length > 0) {
+      await fs.rm(created.pop(), { recursive: true, force: true });
+    }
+  });
+
+  return async (directoryPrefix = prefix) => {
+    const directory = await makeTempDirectory(directoryPrefix);
+    created.push(directory);
+    return directory;
+  };
+}