browser-commander 0.20.0 → 0.21.0

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

package/tests/unit/browser/attach/extension-relay.test.js

@@ -0,0 +1,360 @@
+// feature-parity: attach.extension
+import assert from 'node:assert';
+import { once } from 'node:events';
+import { access } from 'node:fs/promises';
+import path from 'node:path';
+import { describe, it } from 'node:test';
+
+import {
+  attachViaExtension,
+  checkRelayUpgrade,
+  EXTENSION_DIRECTORY,
+  extensionIdFromOrigin,
+  RELAY_PATH,
+} from '../../../../src/browser/attach/extension-relay.js';
+import { connectWebSocket } from '../../../../src/browser/attach/websocket.js';
+import { createRelayClient } from '../../../../extension/relay-handler.js';
+import {
+  createExtensionWebSocket,
+  createFakeChrome,
+} from '../../../helpers/fake-chrome.js';
+
+const TABS = [
+  { id: 1, url: 'https://mail.test/', title: 'Inbox', active: true },
+  { id: 2, url: 'https://docs.test/', title: 'Docs', active: false },
+];
+
+/**
+ * A fake extension that speaks the protocol by hand, so the test controls
+ * every message.
+ */
+async function connectFakeExtension(url, origin = 'chrome-extension://abc') {
+  const connection = await connectWebSocket(url, {
+    headers: { Origin: origin },
+  });
+  const requests = [];
+  connection.on('message', (text) => {
+    const request = JSON.parse(text);
+    requests.push(request);
+    connection.emit('request', request);
+  });
+  const post = (message) => connection.send(JSON.stringify(message));
+  return { connection, requests, post };
+}
+
+/** Start the relay on a free port with a hand-driven extension. */
+async function attachWithFakeExtension(options = {}) {
+  let extension;
+  const relay = await attachViaExtension({
+    port: 0,
+    timeoutMs: 5_000,
+    ...options,
+    onListening: async ({ url }) => {
+      extension = await connectFakeExtension(url);
+      extension.post({
+        type: 'hello',
+        extensionVersion: '1.2.3',
+        userAgent: 'Mozilla/5.0 Test',
+      });
+    },
+  });
+  return { relay, extension };
+}
+
+/** Answer the next request with `reply(request)`. */
+function answerNext(extension, reply) {
+  extension.connection.once('request', (request) =>
+    extension.post({ id: request.id, ...reply(request) })
+  );
+}
+
+async function statusOf(url, headers) {
+  try {
+    const connection = await connectWebSocket(url, { headers });
+    connection.terminate();
+    return 101;
+  } catch (error) {
+    return error.statusCode;
+  }
+}
+
+describe('checkRelayUpgrade', () => {
+  it('accepts one extension origin on the relay path only', () => {
+    const accept = { path: RELAY_PATH, origin: 'chrome-extension://abc' };
+    assert.deepEqual(checkRelayUpgrade(accept), {
+      accept: true,
+      extensionId: 'abc',
+    });
+    assert.equal(
+      checkRelayUpgrade({ ...accept, path: `${RELAY_PATH}?x=1` }).accept,
+      true
+    );
+    const status = (request) => checkRelayUpgrade(request).status;
+    assert.equal(status({ ...accept, path: '/' }), 404);
+    assert.equal(status({ ...accept, origin: 'http://evil.example' }), 403);
+    assert.equal(status({ ...accept, origin: undefined }), 403);
+    assert.equal(status({ ...accept, origin: 'null' }), 403);
+    assert.equal(
+      status({ ...accept, origin: 'chrome-extension://abc.evil.example' }),
+      403
+    );
+    assert.equal(status({ ...accept, allowedExtensionIds: ['xyz'] }), 403);
+    assert.equal(status({ ...accept, connected: true }), 409);
+    assert.equal(extensionIdFromOrigin('chrome-extension://abc'), 'abc');
+    assert.equal(extensionIdFromOrigin('moz-extension://abc'), null);
+  });
+
+  it('points at the unpacked extension', async () => {
+    await access(path.join(EXTENSION_DIRECTORY, 'manifest.json'));
+    await access(path.join(EXTENSION_DIRECTORY, 'background.js'));
+  });
+});
+
+describe('attachViaExtension', () => {
+  it('lists tabs, drives a debugger session and forwards its events', async () => {
+    const { relay, extension } = await attachWithFakeExtension();
+    try {
+      assert.equal(relay.mode, 'extension');
+      assert.deepEqual(relay.extension, {
+        id: 'abc',
+        version: '1.2.3',
+        userAgent: 'Mozilla/5.0 Test',
+      });
+      assert.equal(relay.connected(), true);
+      assert.ok(
+        relay.differences.some(({ aspect }) => aspect === 'debugger-infobar')
+      );
+
+      answerNext(extension, () => ({ result: [{ tabId: 1, url: 'u' }] }));
+      assert.deepEqual(await relay.tabs(), [{ tabId: 1, url: 'u' }]);
+
+      answerNext(extension, () => ({ result: { attached: true } }));
+      const session = await relay.session(1);
+      // Attaching again is idempotent and hands back the same session.
+      answerNext(extension, () => ({ result: { attached: true } }));
+      assert.equal(await relay.session(1), session);
+
+      answerNext(extension, ({ params }) => ({
+        result: { echoed: params },
+      }));
+      assert.deepEqual(
+        await session.send('Runtime.evaluate', { expression: '1+1' }),
+        {
+          echoed: {
+            tabId: 1,
+            method: 'Runtime.evaluate',
+            params: { expression: '1+1' },
+          },
+        }
+      );
+
+      answerNext(extension, () => ({ error: { message: 'no such method' } }));
+      await assert.rejects(session.send('Bad.method'), /no such method/u);
+
+      const event = once(session, 'Page.loadEventFired');
+      extension.post({
+        type: 'event',
+        tabId: 1,
+        method: 'Page.loadEventFired',
+        params: { timestamp: 7 },
+      });
+      assert.deepEqual(await event, [{ timestamp: 7 }]);
+
+      const detached = new Promise((resolve) =>
+        session.once('detached', resolve)
+      );
+      extension.post({
+        type: 'detached',
+        tabId: 1,
+        reason: 'canceled_by_user',
+      });
+      assert.deepEqual(await detached, {
+        tabId: 1,
+        reason: 'canceled_by_user',
+      });
+      await assert.rejects(session.send('Page.reload'), /detached/u);
+
+      assert.deepEqual(
+        extension.requests.map(({ method }) => method),
+        [
+          'tabs.list',
+          'debugger.attach',
+          'debugger.attach',
+          'cdp.send',
+          'cdp.send',
+        ]
+      );
+    } finally {
+      await relay.close();
+    }
+  });
+
+  it('refuses web origins with 403 and a second extension with 409', async () => {
+    const { relay } = await attachWithFakeExtension();
+    try {
+      const url = `ws://127.0.0.1:${relay.port}${RELAY_PATH}`;
+      assert.equal(await statusOf(url, { Origin: 'http://evil.example' }), 403);
+      assert.equal(await statusOf(url, {}), 403);
+      assert.equal(
+        await statusOf(url, { Origin: 'chrome-extension://other' }),
+        409
+      );
+      assert.equal(
+        await statusOf(`ws://127.0.0.1:${relay.port}/`, {
+          Origin: 'chrome-extension://abc',
+        }),
+        404
+      );
+      assert.equal(relay.connected(), true);
+    } finally {
+      await relay.close();
+    }
+    await assert.rejects(
+      connectWebSocket(relay.url, {
+        headers: { Origin: 'chrome-extension://abc' },
+      }),
+      { code: 'ECONNREFUSED' }
+    );
+  });
+
+  it('rejects pending requests and detaches sessions when the extension leaves', async () => {
+    const { relay, extension } = await attachWithFakeExtension();
+    try {
+      answerNext(extension, () => ({ result: { attached: true } }));
+      const session = await relay.session(2);
+      const detached = new Promise((resolve) =>
+        session.once('detached', resolve)
+      );
+      const pending = relay.tabs();
+      extension.connection.terminate();
+
+      await assert.rejects(pending, /disconnected/u);
+      assert.equal((await detached).tabId, 2);
+      assert.equal(relay.connected(), false);
+      await assert.rejects(relay.tabs(), /not connected/u);
+    } finally {
+      await relay.close();
+    }
+  });
+
+  it('closes the extension connection with 1001 on close()', async () => {
+    const { relay, extension } = await attachWithFakeExtension();
+    const closed = once(extension.connection, 'close');
+    await relay.close();
+    await relay.close();
+    assert.equal((await closed)[0].code, 1001);
+  });
+
+  it('accepts only allowedExtensionIds', async () => {
+    let refused;
+    await assert.rejects(
+      attachViaExtension({
+        port: 0,
+        timeoutMs: 300,
+        allowedExtensionIds: ['xyz'],
+        onListening: ({ url }) => {
+          refused = statusOf(url, { Origin: 'chrome-extension://abc' });
+        },
+      }),
+      /Load unpacked/u
+    );
+    assert.equal(await refused, 403);
+  });
+
+  it('times out with install instructions and frees the port', async () => {
+    let url;
+    await assert.rejects(
+      attachViaExtension({
+        port: 0,
+        timeoutMs: 100,
+        onListening: (listening) => {
+          url = listening.url;
+        },
+      }),
+      (error) =>
+        error.message.includes(EXTENSION_DIRECTORY) &&
+        error.message.includes('Load unpacked')
+    );
+    await assert.rejects(
+      connectWebSocket(url, { headers: { Origin: 'chrome-extension://abc' } }),
+      { code: 'ECONNREFUSED' }
+    );
+  });
+
+  it('listens on loopback only and validates its options', async () => {
+    for (const options of [
+      { host: '0.0.0.0' },
+      { host: '192.168.1.2' },
+      { port: 70_000 },
+      { timeoutMs: 0 },
+      { allowedExtensionIds: 'abc' },
+    ]) {
+      await assert.rejects(attachViaExtension(options), TypeError);
+    }
+  });
+
+  it('drives the real extension service worker code end to end', async () => {
+    const chrome = createFakeChrome({ tabs: TABS.map((tab) => ({ ...tab })) });
+    let client;
+    const relay = await attachViaExtension({
+      port: 0,
+      timeoutMs: 5_000,
+      onListening: ({ port }) => {
+        chrome.storage.local.get = async () => ({ port });
+        client = createRelayClient({
+          chrome,
+          WebSocket: createExtensionWebSocket(),
+          userAgent: 'Mozilla/5.0 Extension',
+        });
+        client.start();
+      },
+    });
+    try {
+      assert.deepEqual(relay.extension, {
+        id: 'abc',
+        version: '1.2.3',
+        userAgent: 'Mozilla/5.0 Extension',
+      });
+      assert.deepEqual(await relay.tabs(), [
+        { tabId: 1, url: 'https://mail.test/', title: 'Inbox', active: true },
+        { tabId: 2, url: 'https://docs.test/', title: 'Docs', active: false },
+      ]);
+      assert.deepEqual(await relay.newTab('https://new.test/'), {
+        tabId: 100,
+      });
+
+      const session = await relay.session(1);
+      assert.deepEqual(
+        await session.send('Runtime.evaluate', { expression: '1+1' }),
+        { result: { type: 'number', value: 2 } }
+      );
+      await assert.rejects(session.send('Bad.method'), /wasn't found/u);
+
+      const event = once(session, 'Network.requestWillBeSent');
+      chrome.debugger.onEvent.fire({ tabId: 2 }, 'Ignored.event', {});
+      chrome.debugger.onEvent.fire({ tabId: 1 }, 'Network.requestWillBeSent', {
+        requestId: 'r1',
+      });
+      assert.deepEqual(await event, [{ requestId: 'r1' }]);
+
+      await session.detach();
+      assert.deepEqual(
+        chrome.calls.filter(([name]) => name.startsWith('debugger.')),
+        [
+          ['debugger.attach', 1, '1.3'],
+          [
+            'debugger.sendCommand',
+            1,
+            'Runtime.evaluate',
+            { expression: '1+1' },
+          ],
+          ['debugger.sendCommand', 1, 'Bad.method', {}],
+          ['debugger.detach', 1],
+        ]
+      );
+    } finally {
+      client?.stop();
+      await relay.close();
+    }
+  });
+});