browser-commander 0.20.0 → 0.21.1

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

@@ -1,3 +1,4 @@
+// feature-parity: engine.puppeteer@native-typed
 /**
  * E2E tests for browser-commander using Puppeteer engine
  *
@@ -12,6 +13,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 +218,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}}`,
+    })),
+  });
+}

package/tests/fixtures/traces/conformance/expected/bundle/checkpoints/0001.html

@@ -0,0 +1,2 @@
+<!DOCTYPE html>
+<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>

package/tests/fixtures/traces/conformance/expected/bundle/checkpoints/0001.png

@@ -0,0 +1 @@
+fake-png

package/tests/fixtures/traces/conformance/expected/bundle/checkpoints/0001.state.json

@@ -0,0 +1,54 @@
+{
+  "url": "https://[redacted]:[redacted]@example.com/start?ticket=[redacted]&lang=en#access_token=[redacted]&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": [],
+  "name": "initial",
+  "actor": "recorder",
+  "reason": "initial"
+}

package/tests/fixtures/traces/conformance/expected/bundle/checkpoints/0002.html

@@ -0,0 +1,2 @@
+<!DOCTYPE html>
+<html><body><form><input name="user" value="bob"><textarea>sk-zzz9 note</textarea></form></body></html>

package/tests/fixtures/traces/conformance/expected/bundle/checkpoints/0002.png

@@ -0,0 +1 @@
+fake-png

package/tests/fixtures/traces/conformance/expected/bundle/checkpoints/0002.state.json

@@ -0,0 +1,60 @@
+{
+  "url": "https://example.com/next?token=[redacted]",
+  "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": "[redacted] note",
+      "scroll": {
+        "x": 0,
+        "y": 3
+      },
+      "redacted": false
+    }
+  ],
+  "frames": [
+    {
+      "url": "https://ads.example.com/frame",
+      "crossOrigin": true
+    }
+  ],
+  "name": "after click",
+  "actor": "automation",
+  "reason": "checkpoint"
+}

package/tests/fixtures/traces/conformance/expected/bundle/checkpoints/0003.html

@@ -0,0 +1,2 @@
+<!DOCTYPE html>
+<html><body><form><input name="user" value="bob"><textarea>sk-zzz9 note</textarea></form></body></html>

package/tests/fixtures/traces/conformance/expected/bundle/checkpoints/0003.png

@@ -0,0 +1 @@
+fake-png