browser-commander 0.19.0 → 0.21.0

package/tests/e2e/measure-parity.e2e.test.js

@@ -0,0 +1,118 @@
+/**
+ * E2E: `measureParity()` against every installed Chrome-family browser.
+ *
+ * The default real launch must be `ok` - no difference from the same binary
+ * started by hand, neither in the command line chrome://version reports nor in
+ * anything the environment probe reads - headful and headless, through either
+ * engine. The engine launch is `ok` only because every one of its extra
+ * switches is tied to the `engine-launch-switches` catalogue entry.
+ *
+ * Google Chrome is required. Chromium, Edge and Brave are measured when they
+ * are installed; a browser that is not installed defines no test rather than
+ * a skipped one, so the parity workflow's "no SKIP" gate still holds.
+ *
+ *     RUN_E2E=true xvfb-run -a --server-args="-screen 0 1920x1080x24" \
+ *       npm run test:e2e:parity
+ */
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+
+import { measureParity } from '../../src/browser/parity.js';
+import { resolveSystemBrowserExecutable } from '../../src/browser/system-browser.js';
+import {
+  PARITY_CHROME as CHROME,
+  paritySkipReason,
+} from '../helpers/e2e-browser.js';
+
+const TEST_TIMEOUT = 180000;
+
+async function installedBrowsers() {
+  const browsers = [{ name: 'chrome', executablePath: CHROME }];
+  for (const channel of ['chromium', 'msedge', 'brave']) {
+    const executablePath = await resolveSystemBrowserExecutable({
+      channel,
+    }).catch(() => null);
+    if (executablePath) {
+      browsers.push({ name: channel, executablePath });
+    }
+  }
+  return browsers;
+}
+
+function describeUnlisted(report) {
+  return JSON.stringify(
+    report.unlisted.map(({ path, expected, actual }) => ({
+      path,
+      expected,
+      actual,
+    }))
+  );
+}
+
+// Every browser is measured headful too, so a display is required.
+const skip = paritySkipReason();
+const browsers = skip ? [] : await installedBrowsers();
+
+describe('E2E Tests - measureParity', { skip }, () => {
+  for (const { name, executablePath } of browsers) {
+    for (const headless of [false, true]) {
+      const mode = headless ? 'headless' : 'headful';
+
+      for (const engine of ['playwright', 'puppeteer']) {
+        it(
+          `${name} ${mode}: the real launch through ${engine} matches a hand-started browser`,
+          { timeout: TEST_TIMEOUT },
+          async () => {
+            const report = await measureParity({
+              engine,
+              executablePath,
+              headless,
+            });
+            assert.equal(report.browser.launch, 'real');
+            assert.deepEqual(report.commandLine.extra, []);
+            assert.deepEqual(report.commandLine.missing, []);
+            assert.equal(report.commandLine.attachment.length, 1);
+            assert.equal(report.ok, true, describeUnlisted(report));
+            assert.deepEqual(report.differences, []);
+          }
+        );
+      }
+    }
+
+    it(
+      `${name}: an engine launch is explained by the catalogue`,
+      { timeout: TEST_TIMEOUT },
+      async () => {
+        const report = await measureParity({
+          engine: 'playwright',
+          executablePath,
+          launch: 'engine',
+        });
+        assert.ok(report.commandLine.extra.length > 0);
+        assert.equal(report.ok, true, describeUnlisted(report));
+        assert.ok(
+          report.differences.every(
+            (entry) => entry.limitation === 'engine-launch-switches'
+          )
+        );
+      }
+    );
+  }
+
+  it(
+    'reports an opt-in restriction as requested, not as a leak',
+    { timeout: TEST_TIMEOUT },
+    async () => {
+      const report = await measureParity({
+        executablePath: CHROME,
+        restrictions: ['no-sync'],
+      });
+      assert.deepEqual(report.commandLine.extra, ['--disable-sync']);
+      assert.equal(report.ok, true, describeUnlisted(report));
+      assert.deepEqual(
+        report.differences.map(({ path, requested }) => ({ path, requested })),
+        [{ path: 'commandLine.extra.--disable-sync', requested: true }]
+      );
+    }
+  );
+});

package/tests/e2e/playwright.e2e.test.js

@@ -12,6 +12,7 @@ import assert from 'node:assert';
 // Dynamic import for playwright since it may not be installed
 let playwright;
 let createCommander;
+const TOGGLE_SLIDER = '[data-testid="toggle-switch"] + .toggle-slider';
 
 describe(
   'E2E Tests - Playwright Engine',
@@ -124,12 +125,11 @@ describe(
         }
 
         await commander.click({ selector: '[data-testid="radio-male"]' });
-        const checked = await commander.getAttribute({
-          selector: '[data-testid="radio-male"]',
-          attribute: 'checked',
-        });
-        // Playwright returns empty string for checked attribute when true
-        assert.ok(checked !== null);
+        // React controls the live property without adding a checked attribute.
+        assert.strictEqual(
+          await page.locator('[data-testid="radio-male"]').isChecked(),
+          true
+        );
       });
 
       it('should check checkbox', async () => {
@@ -237,7 +237,7 @@ describe(
         const initialStatus = await commander.textContent({
           selector: '[data-testid="toggle-status"]',
         });
-        await commander.click({ selector: '[data-testid="toggle-switch"]' });
+        await commander.click({ selector: TOGGLE_SLIDER });
         await commander.wait({ ms: 50 });
         const newStatus = await commander.textContent({
           selector: '[data-testid="toggle-status"]',
@@ -337,7 +337,10 @@ describe(
         }
 
         // Scroll to target item (item 15)
-        await commander.scroll({ selector: '[data-testid="scroll-item-15"]' });
+        await commander.scrollIntoView({
+          locatorOrElement: page.locator('[data-testid="scroll-item-15"]'),
+          behavior: 'instant',
+        });
         await commander.wait({ ms: 500 });
 
         // Element should now be visible
@@ -354,17 +357,22 @@ describe(
 
         // Use click which auto-scrolls
         let alertHandled = false;
-        page.on('dialog', async (dialog) => {
+        const onDialog = async (dialog) => {
           alertHandled = true;
           await dialog.accept();
-        });
-
-        await commander.click({
-          selector: '[data-testid="scroll-target-button"]',
-        });
-        await commander.wait({ ms: 100 });
-
-        assert.strictEqual(alertHandled, true);
+        };
+        commander.onDialog(onDialog);
+
+        try {
+          await commander.click({
+            selector: '[data-testid="scroll-target-button"]',
+          });
+          await commander.wait({ ms: 100 });
+
+          assert.strictEqual(alertHandled, true);
+        } finally {
+          commander.offDialog(onDialog);
+        }
       });
     });
 

package/tests/e2e/puppeteer.e2e.test.js

@@ -12,6 +12,7 @@ import assert from 'node:assert';
 // Dynamic import for puppeteer since it may not be installed
 let puppeteer;
 let createCommander;
+const TOGGLE_SLIDER = '[data-testid="toggle-switch"] + .toggle-slider';
 
 describe('E2E Tests - Puppeteer Engine', { skip: !process.env.RUN_E2E }, () => {
   let browser;
@@ -216,30 +217,23 @@ describe('E2E Tests - Puppeteer Engine', { skip: !process.env.RUN_E2E }, () => {
         return;
       }
 
-      // Get initial state
-      const initialStatus = await commander.textContent({
-        selector: '[data-testid="toggle-status"]',
-      });
-
-      // Toggle
-      await commander.click({ selector: '[data-testid="toggle-switch"]' });
-      await commander.wait({ ms: 50 });
-
-      // Verify changed
-      const newStatus = await commander.textContent({
-        selector: '[data-testid="toggle-status"]',
-      });
-      assert.notStrictEqual(initialStatus.trim(), newStatus.trim());
-
-      // Toggle back
-      await commander.click({ selector: '[data-testid="toggle-switch"]' });
-      await commander.wait({ ms: 50 });
+      const initialChecked = await page.$eval(
+        '[data-testid="toggle-switch"]',
+        (input) => input.checked
+      );
+      await commander.click({ selector: TOGGLE_SLIDER });
+      const changedChecked = await page.$eval(
+        '[data-testid="toggle-switch"]',
+        (input) => input.checked
+      );
+      assert.notStrictEqual(changedChecked, initialChecked);
 
-      // Verify back to original
-      const finalStatus = await commander.textContent({
-        selector: '[data-testid="toggle-status"]',
-      });
-      assert.strictEqual(initialStatus.trim(), finalStatus.trim());
+      await commander.click({ selector: TOGGLE_SLIDER });
+      const finalChecked = await page.$eval(
+        '[data-testid="toggle-switch"]',
+        (input) => input.checked
+      );
+      assert.strictEqual(finalChecked, initialChecked);
     });
 
     it('should interact with custom dropdown', async () => {

package/tests/e2e/webdriver.e2e.test.js

@@ -0,0 +1,239 @@
+/**
+ * E2E tests for the selenium (WebDriver) engine (issue #104).
+ *
+ * launchWebDriver() starts chromedriver itself (found through driverPath,
+ * PATH or Selenium Manager), so the suite needs only Chrome and the
+ * selenium-webdriver dev dependency:
+ *
+ *   RUN_E2E=true CHROME_PATH=/usr/bin/google-chrome \
+ *     xvfb-run -a node scripts/run-tests.mjs tests/e2e/webdriver.e2e.test.js
+ *
+ * The Firefox suite runs only when a firefox executable is on PATH (or
+ * FIREFOX_PATH names one); geckodriver comes from PATH or Selenium Manager.
+ */
+
+import { describe, it, before, after } from 'node:test';
+import assert from 'node:assert';
+import { accessSync, constants } from 'node:fs';
+import { createServer } from 'node:http';
+import path from 'node:path';
+import { launchWebDriver } from '../../src/browser/webdriver.js';
+import { makeBrowserCommander } from '../../src/factory.js';
+import { CHROME_LAUNCH_OPTIONS } from '../helpers/e2e-browser.js';
+
+const PAGE = `<!doctype html>
+<title>WebDriver e2e</title>
+<h1 data-testid="heading">Hello WebDriver</h1>
+<input data-testid="name" value="">
+<button data-testid="greet"
+  onclick="document.querySelector('[data-testid=out]').textContent =
+    'Hi ' + document.querySelector('[data-testid=name]').value;
+    console.log('greeted', document.querySelector('[data-testid=name]').value)">
+  Greet
+</button>
+<p data-testid="out"></p>`;
+
+/** Serve PAGE on a loopback port; cookies need an http origin. */
+async function startPageServer() {
+  const server = createServer((request, response) => {
+    response.writeHead(200, { 'content-type': 'text/html; charset=utf-8' });
+    response.end(PAGE);
+  });
+  await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
+  return {
+    url: `http://127.0.0.1:${server.address().port}/`,
+    close: () => new Promise((resolve) => server.close(resolve)),
+  };
+}
+
+/** The firefox executable this machine has, or null. */
+function findFirefox() {
+  const candidates = process.env.FIREFOX_PATH
+    ? [process.env.FIREFOX_PATH]
+    : (process.env.PATH ?? '')
+        .split(path.delimiter)
+        .filter(Boolean)
+        .map((directory) => path.join(directory, 'firefox'));
+  return (
+    candidates.find((candidate) => {
+      try {
+        accessSync(candidate, constants.X_OK);
+        return true;
+      } catch {
+        return false;
+      }
+    }) ?? null
+  );
+}
+
+const headless = process.env.HEADLESS !== 'false';
+
+describe(
+  'E2E Tests - Selenium (WebDriver) engine',
+  {
+    skip: !process.env.RUN_E2E,
+  },
+  () => {
+    let server;
+    let session;
+    let commander;
+
+    before(async () => {
+      server = await startPageServer();
+      session = await launchWebDriver({
+        browser: 'chrome',
+        headless,
+        bidi: true,
+        ...CHROME_LAUNCH_OPTIONS,
+      });
+      commander = makeBrowserCommander({ page: session.page });
+    });
+
+    after(async () => {
+      await commander?.destroy?.();
+      await session?.close();
+      await server?.close();
+    });
+
+    it('detects the selenium engine', () => {
+      assert.equal(commander.engine, 'selenium');
+      assert.equal(session.bidi, true);
+    });
+
+    it('navigates', async () => {
+      await commander.goto({ url: server.url });
+      assert.equal(commander.getUrl(), server.url);
+      assert.equal(await session.page.title(), 'WebDriver e2e');
+    });
+
+    it('finds elements and reads their text', async () => {
+      assert.equal(await commander.count({ selector: 'input' }), 1);
+      assert.equal(
+        (
+          await commander.textContent({ selector: '[data-testid="heading"]' })
+        ).trim(),
+        'Hello WebDriver'
+      );
+      assert.equal(
+        await commander.isVisible({ selector: '[data-testid="greet"]' }),
+        true
+      );
+    });
+
+    it('types, clicks and receives the page console message over BiDi', async () => {
+      const messages = [];
+      const onConsole = (message) => messages.push(message.text());
+      session.page.on('console', onConsole);
+      await session.page.eventsReady();
+
+      await commander.fill({ selector: '[data-testid="name"]', text: 'Ada' });
+      assert.equal(
+        await commander.inputValue({ selector: '[data-testid="name"]' }),
+        'Ada'
+      );
+      await commander.click({ selector: '[data-testid="greet"]' });
+      assert.equal(
+        await commander.textContent({ selector: '[data-testid="out"]' }),
+        'Hi Ada'
+      );
+
+      const deadline = Date.now() + 5000;
+      while (
+        !messages.some((text) => text.includes('greeted')) &&
+        Date.now() < deadline
+      ) {
+        await new Promise((resolve) => setTimeout(resolve, 50));
+      }
+      session.page.off('console', onConsole);
+      assert.ok(
+        messages.some((text) => text.includes('greeted Ada')),
+        `console messages: ${JSON.stringify(messages)}`
+      );
+    });
+
+    it('executes scripts with arguments', async () => {
+      const product = await commander.evaluate({
+        fn: (left, right) => `${left}x${right}`,
+        args: ['6', '7'],
+      });
+      assert.equal(product, '6x7');
+    });
+
+    it('keeps navigator.webdriver false under chromedriver', async () => {
+      assert.equal(
+        await commander.evaluate({ fn: () => navigator.webdriver }),
+        false
+      );
+    });
+
+    it('takes a PNG screenshot', async () => {
+      const png = await session.page.screenshot();
+      assert.ok(Buffer.isBuffer(png));
+      assert.equal(png.subarray(1, 4).toString('latin1'), 'PNG');
+    });
+
+    it('sets, reads and deletes cookies', async () => {
+      await session.page.setCookie({ name: 'e2e', value: 'webdriver' });
+      const cookie = (await session.page.cookies()).find(
+        (candidate) => candidate.name === 'e2e'
+      );
+      assert.equal(cookie?.value, 'webdriver');
+      assert.equal(
+        await commander.evaluate({ fn: () => document.cookie }),
+        'e2e=webdriver'
+      );
+      await session.page.deleteCookie({ name: 'e2e' });
+      assert.equal(
+        (await session.page.cookies()).some((c) => c.name === 'e2e'),
+        false
+      );
+    });
+
+    it('prints the page to PDF', async () => {
+      const pdf = await session.page.pdf({ format: 'A4' });
+      assert.equal(pdf.subarray(0, 5).toString('latin1'), '%PDF-');
+    });
+  }
+);
+
+const firefox = findFirefox();
+
+describe(
+  'E2E Tests - Selenium (WebDriver) engine on Firefox',
+  {
+    skip: !process.env.RUN_E2E
+      ? true
+      : !firefox && 'firefox is not installed (set FIREFOX_PATH)',
+  },
+  () => {
+    let server;
+    let session;
+
+    before(async () => {
+      server = await startPageServer();
+      session = await launchWebDriver({
+        browser: 'firefox',
+        executablePath: firefox,
+        headless,
+        bidi: true,
+      });
+    });
+
+    after(async () => {
+      await session?.close();
+      await server?.close();
+    });
+
+    it('navigates, types and reads the result', async () => {
+      const commander = makeBrowserCommander({ page: session.page });
+      await commander.goto({ url: server.url });
+      await commander.fill({ selector: '[data-testid="name"]', text: 'Grace' });
+      await commander.click({ selector: '[data-testid="greet"]' });
+      assert.equal(
+        await commander.textContent({ selector: '[data-testid="out"]' }),
+        'Hi Grace'
+      );
+      await commander.destroy?.();
+    });
+  }
+);

package/tests/fixtures/firefox-nss-fixtures.mjs

@@ -0,0 +1,211 @@
+import {
+  createCipheriv,
+  createHash,
+  pbkdf2Sync,
+  randomBytes,
+} from 'node:crypto';
+
+import path from 'node:path';
+import BetterSqlite3 from 'better-sqlite3';
+
+/**
+ * Build the `key4.db` and `logins.json` fixtures a Firefox login-decryption
+ * test needs, using the exact NSS structures (PBES2-wrapped keys, DER-wrapped
+ * 3DES login fields) the production decryptor parses. Both the encryptor here
+ * and the decryptor under test share the same algorithm, so a green test proves
+ * the parser and the crypto agree.
+ */
+
+const OID_BYTES = Object.freeze({
+  PBES2: [0x2a, 0x86, 0x48, 0x86, 0xf7, 0x0d, 0x01, 0x05, 0x0d],
+  PBKDF2: [0x2a, 0x86, 0x48, 0x86, 0xf7, 0x0d, 0x01, 0x05, 0x0c],
+  HMAC_SHA256: [0x2a, 0x86, 0x48, 0x86, 0xf7, 0x0d, 0x02, 0x09],
+  AES_256_CBC: [0x60, 0x86, 0x48, 0x01, 0x65, 0x03, 0x04, 0x01, 0x2a],
+  DES_EDE3_CBC: [0x2a, 0x86, 0x48, 0x86, 0xf7, 0x0d, 0x03, 0x07],
+});
+
+function derLength(length) {
+  if (length < 0x80) {
+    return Buffer.from([length]);
+  }
+  const bytes = [];
+  let value = length;
+  while (value > 0) {
+    bytes.unshift(value & 0xff);
+    value = Math.floor(value / 256);
+  }
+  return Buffer.from([0x80 | bytes.length, ...bytes]);
+}
+
+function derElement(tag, content) {
+  return Buffer.concat([
+    Buffer.from([tag]),
+    derLength(content.length),
+    content,
+  ]);
+}
+
+function derSequence(...parts) {
+  return derElement(0x30, Buffer.concat(parts));
+}
+
+function derOctet(buffer) {
+  return derElement(0x04, buffer);
+}
+
+function derOid(bytes) {
+  return derElement(0x06, Buffer.from(bytes));
+}
+
+function derInteger(number) {
+  let bytes = [];
+  if (number === 0) {
+    bytes = [0];
+  } else {
+    let value = number;
+    while (value > 0) {
+      bytes.unshift(value & 0xff);
+      value = Math.floor(value / 256);
+    }
+    if (bytes[0] & 0x80) {
+      bytes.unshift(0);
+    }
+  }
+  return derElement(0x02, Buffer.from(bytes));
+}
+
+// Mirrors the NSS key4.db scheme so fixtures decrypt like a real profile.
+function pbes2Key(globalSalt, entrySalt, iterations, primaryPassword) {
+  const passwordHash = createHash('sha1')
+    .update(Buffer.concat([globalSalt, primaryPassword]))
+    .digest();
+  return pbkdf2Sync(passwordHash, entrySalt, iterations, 32, 'sha256');
+}
+
+function encodePbes2Blob({
+  globalSalt,
+  entrySalt,
+  iterations,
+  iv14,
+  plaintext,
+  primaryPassword,
+}) {
+  const key = pbes2Key(globalSalt, entrySalt, iterations, primaryPassword);
+  const fullIv = Buffer.concat([Buffer.from([0x04, 0x0e]), iv14]);
+  const cipher = createCipheriv('aes-256-cbc', key, fullIv);
+  const ciphertext = Buffer.concat([cipher.update(plaintext), cipher.final()]);
+  const kdf = derSequence(
+    derOid(OID_BYTES.PBKDF2),
+    derSequence(
+      derOctet(entrySalt),
+      derInteger(iterations),
+      derInteger(32),
+      derSequence(derOid(OID_BYTES.HMAC_SHA256))
+    )
+  );
+  const enc = derSequence(derOid(OID_BYTES.AES_256_CBC), derOctet(iv14));
+  const algorithmId = derSequence(
+    derOid(OID_BYTES.PBES2),
+    derSequence(kdf, enc)
+  );
+  return derSequence(algorithmId, derOctet(ciphertext));
+}
+
+function pkcs7Pad(buffer, blockSize) {
+  const padLength = blockSize - (buffer.length % blockSize);
+  return Buffer.concat([buffer, Buffer.alloc(padLength, padLength)]);
+}
+
+/**
+ * Build a Firefox key4.db with a PBES2-wrapped 3DES login key.
+ *
+ * @param {Object} [options]
+ * @returns {{key4Path: string, loginKey: Buffer, primaryPassword: Buffer}}
+ */
+export function buildKey4Database({
+  dir,
+  primaryPassword = Buffer.alloc(0),
+  iterations = 100,
+} = {}) {
+  const globalSalt = randomBytes(16);
+  const loginKey = randomBytes(24);
+
+  const checkBlob = encodePbes2Blob({
+    globalSalt,
+    entrySalt: randomBytes(16),
+    iterations,
+    iv14: randomBytes(14),
+    plaintext: Buffer.from('password-check\u0002\u0002', 'latin1'),
+    primaryPassword,
+  });
+  const keyBlob = encodePbes2Blob({
+    globalSalt,
+    entrySalt: randomBytes(16),
+    iterations,
+    iv14: randomBytes(14),
+    plaintext: loginKey,
+    primaryPassword,
+  });
+
+  const key4Path = path.join(dir, 'key4.db');
+  const db = new BetterSqlite3(key4Path);
+  db.exec(
+    'CREATE TABLE metadata (id TEXT PRIMARY KEY, item1 BLOB, item2 BLOB);' +
+      'CREATE TABLE nssPrivate (a11 BLOB, a102 BLOB);'
+  );
+  db.prepare('INSERT INTO metadata (id, item1, item2) VALUES (?, ?, ?)').run(
+    'password',
+    globalSalt,
+    checkBlob
+  );
+  db.prepare('INSERT INTO nssPrivate (a11, a102) VALUES (?, ?)').run(
+    keyBlob,
+    Buffer.from('f8000000000000000000000000000001', 'hex')
+  );
+  db.close();
+  return { key4Path, loginKey, primaryPassword };
+}
+
+/**
+ * Encode one NSS login field (username/password) as base64, exactly like
+ * `logins.json` stores it.
+ *
+ * @param {Object} options
+ * @param {Buffer} options.key - The 24-byte 3DES key
+ * @param {string} options.plaintext
+ * @returns {string}
+ */
+export function encodeLoginField({ key, plaintext }) {
+  const iv = randomBytes(8);
+  const cipher = createCipheriv('des-ede3-cbc', key, iv);
+  cipher.setAutoPadding(false);
+  const padded = pkcs7Pad(Buffer.from(plaintext, 'utf8'), 8);
+  const ciphertext = Buffer.concat([cipher.update(padded), cipher.final()]);
+  const ckaId = Buffer.from('f8000000000000000000000000000001', 'hex');
+  return derSequence(
+    derOctet(ckaId),
+    derSequence(derOid(OID_BYTES.DES_EDE3_CBC), derOctet(iv)),
+    derOctet(ciphertext)
+  ).toString('base64');
+}
+
+/**
+ * Build a `logins.json` document from plaintext credentials.
+ *
+ * @param {Object} options
+ * @param {Buffer} options.key
+ * @param {Array<{hostname: string, username: string, password: string}>} options.entries
+ * @returns {string} JSON text
+ */
+export function buildLoginsJson({ key, entries }) {
+  return JSON.stringify({
+    nextId: entries.length + 1,
+    logins: entries.map((entry, index) => ({
+      id: index + 1,
+      hostname: entry.hostname,
+      encryptedUsername: encodeLoginField({ key, plaintext: entry.username }),
+      encryptedPassword: encodeLoginField({ key, plaintext: entry.password }),
+      guid: `{fixture-${index}}`,
+    })),
+  });
+}