browser-commander 0.20.0 → 0.21.1

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;
+  };
+}

package/tests/helpers/webdriver-mocks.js

@@ -0,0 +1,183 @@
+/**
+ * Stand-ins for a selenium-webdriver WebDriver, its WebElements and its BiDi
+ * connection (issue #104). Every call is recorded in `calls` so tests can
+ * assert on the WebDriver commands an operation produced.
+ */
+
+/**
+ * A mock WebElement.
+ *
+ * @param {Object} [options]
+ * @param {boolean} [options.displayed=true]
+ * @param {Array} [calls] - Shared call log
+ * @returns {Object}
+ */
+export function createMockWebElement(
+  { displayed = true, id = 'el' } = {},
+  calls = []
+) {
+  return {
+    id,
+    displayed,
+    click: async () => {
+      calls.push(['element.click', id]);
+    },
+    sendKeys: async (...keys) => {
+      calls.push(['element.sendKeys', id, ...keys]);
+    },
+    clear: async () => {
+      calls.push(['element.clear', id]);
+    },
+    async isDisplayed() {
+      return this.displayed;
+    },
+  };
+}
+
+function createMockActions(calls) {
+  const steps = [];
+  const chain = {};
+  for (const name of [
+    'move',
+    'press',
+    'release',
+    'keyDown',
+    'keyUp',
+    'sendKeys',
+    'pause',
+    'scroll',
+    'click',
+  ]) {
+    chain[name] = (...args) => {
+      steps.push([name, ...args]);
+      return chain;
+    };
+  }
+  chain.perform = async () => {
+    calls.push(['actions', steps]);
+  };
+  return chain;
+}
+
+/**
+ * A mock WebDriver.
+ *
+ * @param {Object} [options]
+ * @param {string} [options.url='about:blank']
+ * @param {Object} [options.capabilities] - e.g. {webSocketUrl: 'ws://...'}
+ * @param {Object<string, Object[]>} [options.elements] - CSS selector -> elements
+ * @param {Function} [options.script] - (script, args) => value returned by the page function
+ * @returns {Object}
+ */
+export function createMockDriver({
+  url = 'about:blank',
+  capabilities = {},
+  elements = {},
+  script = () => undefined,
+  cookies = [],
+} = {}) {
+  const calls = [];
+  const state = { url, cookies: [...cookies] };
+  const driver = {
+    calls,
+    state,
+    getCurrentUrl: async () => state.url,
+    get: async (target) => {
+      calls.push(['get', target]);
+      state.url = target;
+    },
+    getTitle: async () => 'Mock title',
+    getPageSource: async () => '<html></html>',
+    getWindowHandle: async () => 'context-1',
+    getCapabilities: async () => ({ get: (name) => capabilities[name] }),
+    findElements: async (locator) => {
+      calls.push(['findElements', locator]);
+      return elements[locator.css] ?? [];
+    },
+    executeScript: async (source, ...args) => {
+      calls.push(['executeScript', source, args]);
+      return [await script(source, args), state.url];
+    },
+    manage: () => ({
+      getCookies: async () => state.cookies,
+      addCookie: async (cookie) => {
+        calls.push(['addCookie', cookie]);
+        state.cookies.push(cookie);
+      },
+      deleteCookie: async (name) => {
+        calls.push(['deleteCookie', name]);
+        state.cookies = state.cookies.filter((c) => c.name !== name);
+      },
+      setTimeouts: async (timeouts) => {
+        calls.push(['setTimeouts', timeouts]);
+      },
+    }),
+    navigate: () => ({
+      back: async () => calls.push(['back']),
+      forward: async () => calls.push(['forward']),
+      refresh: async () => calls.push(['refresh']),
+    }),
+    switchTo: () => ({
+      window: async (handle) => calls.push(['switchTo.window', handle]),
+    }),
+    actions: (options) => {
+      calls.push(['actions.new', options]);
+      return createMockActions(calls);
+    },
+    takeScreenshot: async () => Buffer.from('png').toString('base64'),
+    printPage: async (options) => {
+      calls.push(['printPage', options]);
+      return Buffer.from('%PDF-mock').toString('base64');
+    },
+    close: async () => calls.push(['close']),
+    quit: async () => calls.push(['quit']),
+  };
+  return driver;
+}
+
+/**
+ * A mock BiDi connection: `send` answers from `responses`, `addCallback`
+ * records handlers that `fire(method, params)` invokes.
+ *
+ * @param {Object} [options]
+ * @param {Object<string, Object|Function>} [options.responses] - method -> result (or params => result)
+ * @param {string[]} [options.unsupported] - Event methods that fail to subscribe
+ * @returns {Object}
+ */
+export function createMockBidi({ responses = {}, unsupported = [] } = {}) {
+  const sent = [];
+  const callbacks = new Map();
+  const unsubscribed = [];
+  return {
+    sent,
+    callbacks,
+    unsubscribed,
+    send: async ({ method, params }) => {
+      sent.push({ method, params });
+      const response = responses[method];
+      if (response?.error) {
+        return response;
+      }
+      return {
+        type: 'success',
+        result:
+          typeof response === 'function' ? response(params) : (response ?? {}),
+      };
+    },
+    addCallback: async (method, handler) => {
+      if (unsupported.includes(method)) {
+        throw new Error(`invalid argument: ${method} is not a known event`);
+      }
+      callbacks.set(method, handler);
+      return {
+        unsubscribe: async () => {
+          unsubscribed.push(method);
+          callbacks.delete(method);
+        },
+      };
+    },
+    fire(method, params) {
+      callbacks.get(method)?.(params);
+    },
+  };
+}