browser-commander 0.20.0 → 0.21.1

package/src/core/webdriver-conversions.js

@@ -0,0 +1,347 @@
+/**
+ * Translations between the Puppeteer-shaped page API the rest of Browser
+ * Commander speaks and the WebDriver wire protocol (issue #104).
+ *
+ * Everything here is a pure function of its arguments, so the facade in
+ * `webdriver-page.js` stays about sequencing commands and these stay testable
+ * without a browser.
+ */
+
+/**
+ * W3C WebDriver key codes for the named keys the Playwright and Puppeteer
+ * keyboards accept (WebDriver specification, "Keyboard actions", table of
+ * normalized key values). A single character is sent as itself.
+ */
+export const WEBDRIVER_KEYS = Object.freeze({
+  Cancel: '\uE001',
+  Help: '\uE002',
+  Backspace: '\uE003',
+  Tab: '\uE004',
+  Clear: '\uE005',
+  Enter: '\uE007',
+  Shift: '\uE008',
+  ShiftLeft: '\uE008',
+  Control: '\uE009',
+  ControlLeft: '\uE009',
+  Alt: '\uE00A',
+  AltLeft: '\uE00A',
+  Pause: '\uE00B',
+  Escape: '\uE00C',
+  Space: '\uE00D',
+  PageUp: '\uE00E',
+  PageDown: '\uE00F',
+  End: '\uE010',
+  Home: '\uE011',
+  ArrowLeft: '\uE012',
+  ArrowUp: '\uE013',
+  ArrowRight: '\uE014',
+  ArrowDown: '\uE015',
+  Insert: '\uE016',
+  Delete: '\uE017',
+  F1: '\uE031',
+  F2: '\uE032',
+  F3: '\uE033',
+  F4: '\uE034',
+  F5: '\uE035',
+  F6: '\uE036',
+  F7: '\uE037',
+  F8: '\uE038',
+  F9: '\uE039',
+  F10: '\uE03A',
+  F11: '\uE03B',
+  F12: '\uE03C',
+  Meta: '\uE03D',
+  MetaLeft: '\uE03D',
+  Command: '\uE03D',
+});
+
+/**
+ * Translate one key name into the value a WebDriver key action carries.
+ *
+ * @param {string} key - A single character or a name such as 'Enter'
+ * @returns {string} The WebDriver key value
+ */
+export function toWebDriverKey(key) {
+  if (typeof key !== 'string' || key.length === 0) {
+    throw new TypeError(`A key must be a non-empty string, got ${key}`);
+  }
+  if ([...key].length === 1) {
+    return key;
+  }
+  const value = WEBDRIVER_KEYS[key];
+  if (value === undefined) {
+    throw new Error(
+      `Unknown key "${key}" for WebDriver. Use a single character or one of: ${Object.keys(WEBDRIVER_KEYS).join(', ')}`
+    );
+  }
+  return value;
+}
+
+/**
+ * Split a Playwright-style chord such as 'Control+A' into the keys held
+ * together. A lone '+' is the plus key, not a separator.
+ *
+ * @param {string} key
+ * @returns {string[]} WebDriver key values, modifiers first
+ */
+export function toWebDriverChord(key) {
+  const parts =
+    key.length > 1 && key.includes('+')
+      ? key.split('+').map((part, index, all) =>
+          // 'Control++' holds Control and presses '+'.
+          part === '' && index === all.length - 1 ? '+' : part
+        )
+      : [key];
+  return parts.filter((part) => part !== '').map(toWebDriverKey);
+}
+
+/** Paper sizes Puppeteer and Playwright accept, in inches (width, height). */
+const PAPER_FORMATS_IN = Object.freeze({
+  letter: [8.5, 11],
+  legal: [8.5, 14],
+  tabloid: [11, 17],
+  ledger: [17, 11],
+  a0: [33.1102, 46.811],
+  a1: [23.3858, 33.1102],
+  a2: [16.5354, 23.3858],
+  a3: [11.6929, 16.5354],
+  a4: [8.2677, 11.6929],
+  a5: [5.8268, 8.2677],
+  a6: [4.1339, 5.8268],
+});
+
+const CM_PER_UNIT = Object.freeze({
+  px: 2.54 / 96,
+  in: 2.54,
+  cm: 1,
+  mm: 0.1,
+});
+
+/**
+ * Convert a Puppeteer length (a number of CSS pixels, or a string with a
+ * px/in/cm/mm unit) into the centimetres WebDriver's Print Page expects.
+ *
+ * @param {number|string} value
+ * @returns {number}
+ */
+export function toCentimetres(value) {
+  if (typeof value === 'number') {
+    return value * CM_PER_UNIT.px;
+  }
+  const match = /^(-?\d+(?:\.\d+)?)\s*(px|in|cm|mm)?$/i.exec(
+    String(value).trim()
+  );
+  if (!match) {
+    throw new Error(`Cannot convert "${value}" to a print length`);
+  }
+  const unit = (match[2] ?? 'px').toLowerCase();
+  return Number(match[1]) * CM_PER_UNIT[unit];
+}
+
+/**
+ * PDF options that have no WebDriver Print Page equivalent. They are refused
+ * rather than dropped, because a PDF without the header a caller asked for is
+ * a silently wrong result (limitation `webdriver-print-options`).
+ */
+export const UNSUPPORTED_PRINT_OPTIONS = Object.freeze([
+  'displayHeaderFooter',
+  'headerTemplate',
+  'footerTemplate',
+  'preferCSSPageSize',
+  'tagged',
+  'outline',
+  'omitBackground',
+]);
+
+/**
+ * Translate Puppeteer/Playwright `page.pdf()` options into the parameters of
+ * selenium-webdriver's `driver.printPage()`.
+ *
+ * @param {Object} [options]
+ * @returns {Object} printPage options (lengths in centimetres)
+ */
+export function toPrintOptions(options = {}) {
+  const unsupported = UNSUPPORTED_PRINT_OPTIONS.filter((name) => options[name]);
+  if (unsupported.length > 0) {
+    throw new Error(
+      `WebDriver Print Page does not support ${unsupported.join(', ')} ` +
+        '(see the webdriver-print-options limitation)'
+    );
+  }
+
+  const print = {};
+  if (options.landscape) {
+    print.orientation = 'landscape';
+  }
+  if (options.printBackground !== undefined) {
+    print.background = Boolean(options.printBackground);
+  }
+  if (options.scale !== undefined) {
+    print.scale = options.scale;
+  }
+  if (options.pageRanges) {
+    print.pageRanges = String(options.pageRanges)
+      .split(',')
+      .map((range) => range.trim())
+      .filter(Boolean);
+  }
+
+  if (options.format) {
+    const size = PAPER_FORMATS_IN[String(options.format).toLowerCase()];
+    if (!size) {
+      throw new Error(`Unknown paper format: ${options.format}`);
+    }
+    print.width = size[0] * CM_PER_UNIT.in;
+    print.height = size[1] * CM_PER_UNIT.in;
+  }
+  if (options.width !== undefined) {
+    print.width = toCentimetres(options.width);
+  }
+  if (options.height !== undefined) {
+    print.height = toCentimetres(options.height);
+  }
+
+  for (const side of ['top', 'right', 'bottom', 'left']) {
+    if (options.margin?.[side] !== undefined) {
+      print[side] = toCentimetres(options.margin[side]);
+    }
+  }
+  return print;
+}
+
+/**
+ * A WebDriver cookie in the shape `page.cookies()` returns in Puppeteer.
+ *
+ * @param {Object} cookie - WebDriver cookie
+ * @returns {Object}
+ */
+export function fromWebDriverCookie(cookie) {
+  const session = cookie.expiry === undefined || cookie.expiry === null;
+  return {
+    name: cookie.name,
+    value: cookie.value,
+    domain: cookie.domain,
+    path: cookie.path ?? '/',
+    expires: session ? -1 : Number(cookie.expiry),
+    size: `${cookie.name}${cookie.value}`.length,
+    httpOnly: Boolean(cookie.httpOnly),
+    secure: Boolean(cookie.secure),
+    session,
+    ...(cookie.sameSite ? { sameSite: cookie.sameSite } : {}),
+  };
+}
+
+/**
+ * A Puppeteer `setCookie()` argument as a WebDriver cookie.
+ *
+ * WebDriver can only add a cookie for the document that is loaded, so a
+ * cookie's `url` is not a way to target another site here; the domain of the
+ * current document applies unless `domain` names a parent of it.
+ *
+ * @param {Object} cookie - Puppeteer cookie parameter
+ * @returns {Object}
+ */
+export function toWebDriverCookie(cookie) {
+  const result = { name: cookie.name, value: cookie.value };
+  for (const field of ['path', 'domain', 'secure', 'httpOnly', 'sameSite']) {
+    if (cookie[field] !== undefined) {
+      result[field] = cookie[field];
+    }
+  }
+  if (typeof cookie.expires === 'number' && cookie.expires > 0) {
+    result.expiry = Math.floor(cookie.expires);
+  }
+  return result;
+}
+
+/**
+ * The page-side script that runs a function (or evaluates an expression) and
+ * reports the document URL in the same round trip.
+ *
+ * The function source is part of the script body instead of being passed as an
+ * argument and compiled in the page: WebDriver compiles the body outside the
+ * page's Content-Security-Policy, whereas `new Function()` in the page is
+ * refused on any site that forbids `unsafe-eval`.
+ *
+ * @param {Function|string} pageFunction
+ * @returns {string} Script for `driver.executeScript`
+ */
+export function buildEvaluateScript(pageFunction) {
+  const call =
+    typeof pageFunction === 'function'
+      ? `(${pageFunction.toString()}).apply(null, args)`
+      : `(${pageFunction})`;
+  return [
+    'const args = Array.prototype.slice.call(arguments);',
+    `return (async () => [await ${call}, location.href])();`,
+  ].join('\n');
+}
+
+const SCRIPT_UNSAFE_CHARACTERS = {
+  '<': '\\u003C',
+  '>': '\\u003E',
+  '/': '\\u002F',
+  '\u2028': '\\u2028',
+  '\u2029': '\\u2029',
+};
+
+/**
+ * A JSON value as a JavaScript literal that is safe to splice into script
+ * source: `JSON.stringify` alone leaves `</script>`, U+2028 and U+2029, which
+ * end or break the surrounding code.
+ *
+ * @param {*} value - JSON-serialisable value
+ * @returns {string}
+ */
+export function toScriptLiteral(value) {
+  return JSON.stringify(value).replace(
+    /[<>/\u2028\u2029]/gu,
+    (character) => SCRIPT_UNSAFE_CHARACTERS[character]
+  );
+}
+
+/**
+ * A BiDi `log.entryAdded` entry as a Puppeteer ConsoleMessage.
+ *
+ * @param {Object} params
+ * @returns {Object}
+ */
+export function toConsoleMessage(params) {
+  const type = params.method ?? params.level ?? 'log';
+  return {
+    type: () => (type === 'warn' ? 'warning' : type),
+    text: () => params.text ?? '',
+    args: () => params.args ?? [],
+    location: () => ({
+      url: params.source?.url ?? params.stackTrace?.callFrames?.[0]?.url,
+    }),
+    level: params.level,
+  };
+}
+
+/**
+ * A BiDi network event as a Puppeteer HTTPRequest.
+ *
+ * @param {Object} params - BiDi network event parameters
+ * @returns {Object}
+ */
+export function toNetworkRequest(params) {
+  const request = params.request ?? {};
+  const headers = Object.fromEntries(
+    (request.headers ?? []).map(({ name, value }) => [
+      name.toLowerCase(),
+      value?.value ?? value,
+    ])
+  );
+  return {
+    id: request.request,
+    url: () => request.url,
+    method: () => request.method,
+    headers: () => headers,
+    isNavigationRequest: () => Boolean(params.navigation),
+    failure: () =>
+      params.errorText ? { errorText: params.errorText } : undefined,
+    response: () =>
+      params.response ? { status: () => params.response.status } : null,
+  };
+}

package/src/core/webdriver-events.js

@@ -0,0 +1,229 @@
+/**
+ * WebDriver BiDi events as the page events the rest of Browser Commander
+ * listens to (issue #104).
+ *
+ * Classic WebDriver is request/response only: nothing tells the client that a
+ * console message was logged, a dialog opened or a request went out. BiDi
+ * does, so when the session has a BiDi connection the page facade subscribes
+ * to the matching BiDi event the first time something listens for a page
+ * event, and re-emits it in the Puppeteer shape:
+ *
+ * | page event        | BiDi event                                        |
+ * | ----------------- | ------------------------------------------------- |
+ * | `console`         | `log.entryAdded` (console entries)                |
+ * | `pageerror`       | `log.entryAdded` (type `javascript`)              |
+ * | `framenavigated`  | `browsingContext.navigationCommitted` (or         |
+ * |                   | `domContentLoaded`), `fragmentNavigated`,         |
+ * |                   | `historyUpdated`                                  |
+ * | `domcontentloaded`| `browsingContext.domContentLoaded`                |
+ * | `load`            | `browsingContext.load`                            |
+ * | `dialog`          | `browsingContext.userPromptOpened`                |
+ * | `request`         | `network.beforeRequestSent`                       |
+ * | `requestfinished` | `network.responseCompleted`                       |
+ * | `response`        | `network.responseCompleted`                       |
+ * | `requestfailed`   | `network.fetchError`                              |
+ *
+ * Without BiDi the events stay silent, which is limitation
+ * `webdriver-classic-has-no-events`.
+ */
+
+import { toConsoleMessage, toNetworkRequest } from './webdriver-conversions.js';
+
+/**
+ * The BiDi events each page event needs. Where a list has alternatives
+ * (`oneOf`), the first one the driver accepts is used: older drivers do not
+ * know `browsingContext.navigationCommitted`, and `domContentLoaded` is the
+ * closest event every driver has.
+ */
+export const PAGE_EVENT_SOURCES = Object.freeze({
+  console: [['log.entryAdded']],
+  pageerror: [['log.entryAdded']],
+  framenavigated: [
+    ['browsingContext.navigationCommitted', 'browsingContext.domContentLoaded'],
+    ['browsingContext.fragmentNavigated'],
+    ['browsingContext.historyUpdated'],
+  ],
+  domcontentloaded: [['browsingContext.domContentLoaded']],
+  load: [['browsingContext.load']],
+  dialog: [['browsingContext.userPromptOpened']],
+  request: [['network.beforeRequestSent']],
+  requestfinished: [['network.responseCompleted']],
+  response: [['network.responseCompleted']],
+  requestfailed: [['network.fetchError']],
+});
+
+const NAVIGATION_EVENTS = new Set([
+  'browsingContext.navigationCommitted',
+  'browsingContext.fragmentNavigated',
+  'browsingContext.historyUpdated',
+]);
+
+/**
+ * A BiDi user prompt as a Puppeteer Dialog.
+ *
+ * @param {Object} page - The WebDriverPage the prompt belongs to
+ * @param {Object} params - `browsingContext.userPromptOpened` parameters
+ * @returns {Object}
+ */
+function toDialog(page, params) {
+  const handle = (accept, userText) =>
+    page.bidiCommand('browsingContext.handleUserPrompt', {
+      context: params.context,
+      accept,
+      ...(userText !== undefined ? { userText: String(userText) } : {}),
+    });
+  return {
+    type: () => params.type,
+    message: () => params.message ?? '',
+    defaultValue: () => params.defaultValue ?? '',
+    accept: (promptText) => handle(true, promptText),
+    dismiss: () => handle(false),
+  };
+}
+
+/**
+ * Bridge BiDi events onto a WebDriverPage.
+ *
+ * @param {Object} page - The WebDriverPage (an EventEmitter with `bidi()`)
+ * @returns {{subscribe: function(string): Promise<void>, ready: function(): Promise<void>, dispose: function(): Promise<void>}}
+ */
+export function createWebDriverEventBridge(page) {
+  const subscribed = new Map(); // page event -> Promise
+  const handles = [];
+  // Which BiDi method was chosen for the navigation alternative; the
+  // domContentLoaded fallback also counts as a navigation then.
+  let navigationSource = null;
+
+  const isTop = (context) =>
+    context === undefined || context === page.contextIdSync();
+
+  function dispatch(method, params) {
+    switch (method) {
+      case 'log.entryAdded': {
+        if (!isTop(params.source?.context)) {
+          return;
+        }
+        if (params.type === 'javascript') {
+          const error = new Error(params.text ?? 'Uncaught error');
+          error.stackTrace = params.stackTrace;
+          page.emit('pageerror', error);
+        } else {
+          page.emit('console', toConsoleMessage(params));
+        }
+        return;
+      }
+      case 'browsingContext.userPromptOpened':
+        if (isTop(params.context)) {
+          page.emit('dialog', toDialog(page, params));
+        }
+        return;
+      case 'network.beforeRequestSent':
+        page.emit('request', toNetworkRequest(params));
+        return;
+      case 'network.responseCompleted': {
+        const request = toNetworkRequest(params);
+        page.emit('response', request.response());
+        page.emit('requestfinished', request);
+        return;
+      }
+      case 'network.fetchError':
+        page.emit('requestfailed', toNetworkRequest(params));
+        return;
+      default:
+        break;
+    }
+
+    if (!isTop(params.context)) {
+      return;
+    }
+    if (NAVIGATION_EVENTS.has(method) || method === navigationSource) {
+      page.recordNavigation(params.url);
+    }
+    if (method === 'browsingContext.domContentLoaded') {
+      page.emit('domcontentloaded');
+    } else if (method === 'browsingContext.load') {
+      page.emit('load');
+    }
+  }
+
+  const methodHandles = new Map(); // BiDi method -> Promise<handle>
+
+  function listen(method) {
+    if (!methodHandles.has(method)) {
+      methodHandles.set(
+        method,
+        page.subscribeBidi(method, (params) => dispatch(method, params))
+      );
+    }
+    return methodHandles.get(method);
+  }
+
+  async function listenToFirstSupported(alternatives) {
+    let lastError = null;
+    for (const method of alternatives) {
+      try {
+        const handle = await listen(method);
+        handles.push(handle);
+        if (alternatives.length > 1) {
+          navigationSource = method;
+        }
+        return;
+      } catch (error) {
+        methodHandles.delete(method);
+        lastError = error;
+      }
+    }
+    throw lastError;
+  }
+
+  async function subscribeSources(eventName) {
+    const bidi = await page.bidi();
+    if (!bidi) {
+      return;
+    }
+    // Events are filtered to the page's own browsing context, so its id has
+    // to be known before the first one arrives.
+    await page.contextId();
+    for (const alternatives of PAGE_EVENT_SOURCES[eventName]) {
+      await listenToFirstSupported(alternatives);
+    }
+  }
+
+  return {
+    /**
+     * Make sure the BiDi events behind a page event are subscribed.
+     * Unknown event names and classic sessions are a no-op.
+     *
+     * @param {string} eventName
+     * @returns {Promise<void>}
+     */
+    subscribe(eventName) {
+      if (!PAGE_EVENT_SOURCES[eventName]) {
+        return Promise.resolve();
+      }
+      if (!subscribed.has(eventName)) {
+        const pending = subscribeSources(eventName).catch((error) => {
+          page.recordBridgeError(eventName, error);
+        });
+        subscribed.set(eventName, pending);
+      }
+      return subscribed.get(eventName);
+    },
+
+    /** Resolves once every subscription requested so far is in place. */
+    async ready() {
+      await Promise.all(subscribed.values());
+    },
+
+    /** Remove every BiDi subscription the bridge made. */
+    async dispose() {
+      const all = [...new Set(handles)];
+      handles.length = 0;
+      subscribed.clear();
+      methodHandles.clear();
+      await Promise.all(
+        all.map((handle) => Promise.resolve(handle?.unsubscribe?.()))
+      ).catch(() => {});
+    },
+  };
+}