browser-commander 0.28.0 → 0.30.0

package/src/traces/user-actions.js

@@ -0,0 +1,405 @@
+import { withDeadline } from './deadline.js';
+import { framesOf, installInitScript } from './init-script.js';
+import { TRACE_EVENT, TRACE_DROP_REASON } from './schema.js';
+
+const bindings = new WeakMap();
+const USER_ACTION_BINDING = '__browserCommanderUserActionsEmit__';
+
+async function attachBinding(page, route, emit) {
+  if (!page.exposeFunction) {
+    return null;
+  }
+  let binding = bindings.get(page);
+  if (!binding) {
+    const callbacks = new Map();
+    binding = {
+      callbacks,
+      ready: page.exposeFunction(USER_ACTION_BINDING, (id, payload) =>
+        callbacks.get(id)?.(payload)
+      ),
+    };
+    bindings.set(page, binding);
+  }
+  await binding.ready;
+  binding.callbacks.set(route, emit);
+  return () => binding.callbacks.delete(route);
+}
+
+/** Runs in each document. Event descriptions never read control values. */
+export function installUserActionRecorderInPage(options) {
+  const {
+    globalName,
+    binding,
+    maxQueued,
+    redactSelectors,
+    ignoreSelectors,
+    redacted,
+  } = options;
+  if (window[globalName]?.observing) {
+    return;
+  }
+  const state = {
+    observing: true,
+    queue: [],
+    dropped: 0,
+    frameId: `frame-${Math.random().toString(36).slice(2, 10)}`,
+  };
+  const matches = (node, selectors) => {
+    for (let at = node; at; at = at.getRootNode?.()?.host) {
+      if (
+        selectors.some((selector) => {
+          try {
+            return Boolean(at.closest?.(selector));
+          } catch {
+            return false;
+          }
+        })
+      ) {
+        return true;
+      }
+    }
+    return false;
+  };
+  const privateNode = (node) => matches(node, redactSelectors);
+  const pathOf = (node) => {
+    const steps = [];
+    let separator = '';
+    for (let at = node; at?.nodeType === 1 && steps.length < 20;) {
+      const siblings = [...(at.parentElement?.children ?? [])].filter(
+        (child) => child.localName === at.localName
+      );
+      const step = at.id
+        ? `#${window.CSS.escape(at.id)}`
+        : `${at.localName}${siblings.length > 1 ? `:nth-of-type(${siblings.indexOf(at) + 1})` : ''}`;
+      steps.unshift(`${step}${separator}`);
+      if (at.id) {
+        break;
+      }
+      separator = at.parentElement ? ' > ' : ' >>> ';
+      at = at.parentElement ?? at.getRootNode()?.host;
+    }
+    return steps.join('');
+  };
+  const visibleText = (node, depth = 0, budget = { remaining: 500 }) => {
+    if (
+      !node ||
+      depth >= 20 ||
+      --budget.remaining < 0 ||
+      matches(node.nodeType === 1 ? node : node.parentElement, [
+        'input',
+        'textarea',
+        'select',
+        '[contenteditable]',
+        ...ignoreSelectors,
+      ])
+    ) {
+      return '';
+    }
+    if (privateNode(node.nodeType === 1 ? node : node.parentElement)) {
+      return redacted;
+    }
+    if (node.nodeType === 3) {
+      return node.nodeValue ?? '';
+    }
+    if (
+      node.nodeType === 1 &&
+      (!node.getClientRects().length ||
+        window.getComputedStyle(node).visibility === 'hidden')
+    ) {
+      return '';
+    }
+    let text = '';
+    for (const child of node.childNodes ?? []) {
+      text += visibleText(child, depth + 1, budget);
+      if (text.length >= 500) {
+        break;
+      }
+    }
+    return text.slice(0, 500);
+  };
+  const describe = (target) => {
+    const secret = privateNode(target);
+    const text = secret ? redacted : visibleText(target).trim();
+    const labelled = (target.getAttribute('aria-labelledby') ?? '')
+      .split(/\s+/)
+      .filter(Boolean)
+      .map((id) => visibleText(target.getRootNode().getElementById?.(id)))
+      .join(' ')
+      .trim();
+    const label = [...(target.labels ?? [])]
+      .slice(0, 20)
+      .map((node) => visibleText(node))
+      .join(' ')
+      .trim();
+    const roles = {
+      button: 'button',
+      a: 'link',
+      textarea: 'textbox',
+      select: 'combobox',
+      form: 'form',
+    };
+    const inputRole =
+      target.type === 'checkbox'
+        ? 'checkbox'
+        : target.type === 'radio'
+          ? 'radio'
+          : ['submit', 'button', 'reset'].includes(target.type)
+            ? 'button'
+            : 'textbox';
+    return {
+      path: pathOf(target),
+      role:
+        target.getAttribute('role') ??
+        (target.localName === 'input'
+          ? inputRole
+          : (roles[target.localName] ?? null)),
+      name: secret
+        ? redacted
+        : (
+            labelled ||
+            target.getAttribute('aria-label') ||
+            label ||
+            target.getAttribute('alt') ||
+            target.getAttribute('title') ||
+            text
+          ).slice(0, 500),
+      text,
+    };
+  };
+  const nonTextKeys =
+    /^(?:Enter|Escape|Tab|Backspace|Delete|Insert|Home|End|PageUp|PageDown|Arrow(?:Up|Down|Left|Right)|F(?:[1-9]|1\d|2[0-4]))$/;
+  const listener = (event) => {
+    if (
+      !event.isTrusted ||
+      (event.type === 'keydown' &&
+        (!nonTextKeys.test(event.key) || event.isComposing))
+    ) {
+      return;
+    }
+    const nodes = event.composedPath?.() ?? [event.target];
+    let target = nodes.find((node) => node?.nodeType === 1);
+    if (!target || matches(target, ignoreSelectors)) {
+      return;
+    }
+    // Only suppress engine input aimed at the commander's current target.
+    // A person using another control while an automation call waits is still
+    // recorded. Trusted input outside commander methods is always user input.
+    const commanderInput = (window.__browserCommanderActions__ ?? []).some(
+      (action) => {
+        if (!action.types.includes(event.type)) {
+          return false;
+        }
+        if (action.element) {
+          return (
+            action.element === target ||
+            action.element.contains(target) ||
+            (event.type === 'click' &&
+              event.detail === 0 &&
+              action.types.includes('keydown') &&
+              action.element.form &&
+              action.element.form === target.form) ||
+            (event.type === 'submit' && target.contains(action.element))
+          );
+        }
+        if (!action.selector) {
+          return event.type === 'keydown';
+        }
+        try {
+          return (
+            Boolean(target.closest(action.selector)) ||
+            (event.type === 'submit' &&
+              Boolean(target.querySelector(action.selector)))
+          );
+        } catch {
+          return false;
+        }
+      }
+    );
+    if (commanderInput) {
+      return;
+    }
+    if (event.type !== 'keydown') {
+      target =
+        target.closest(
+          'button, a, input, select, textarea, form, [role], [contenteditable]'
+        ) ?? target;
+    }
+    const payload = {
+      source: 'user',
+      actor: 'user',
+      action: event.type,
+      target: describe(target),
+      at: new Date().toISOString(),
+      url: location.href,
+      frameId: state.frameId,
+      mainFrame: window.top === window,
+      ...(event.type === 'keydown'
+        ? {
+            key: event.key,
+            altKey: event.altKey,
+            ctrlKey: event.ctrlKey,
+            metaKey: event.metaKey,
+            shiftKey: event.shiftKey,
+          }
+        : {}),
+    };
+    const enqueue = () => {
+      if (!state.observing) {
+        return;
+      }
+      if (state.queue.length < maxQueued) {
+        state.queue.push(payload);
+      } else {
+        state.dropped += 1;
+      }
+    };
+    if (binding && typeof window[binding] === 'function') {
+      // Bindings deliver the action before the app's request/response callbacks;
+      // engines without bindings use the bounded polling queue instead.
+      Promise.resolve(window[binding](globalName, payload)).catch(enqueue);
+    } else {
+      enqueue();
+    }
+  };
+  const types = ['click', 'pointerdown', 'keydown', 'submit', 'contextmenu'];
+  for (const type of types) {
+    document.addEventListener(type, listener, true);
+  }
+  state.stop = () => {
+    state.observing = false;
+    for (const type of types) {
+      document.removeEventListener(type, listener, true);
+    }
+  };
+  window[globalName] = state;
+}
+
+function drainUserActionsInPage(globalName) {
+  const state = window[globalName];
+  if (!state) {
+    return { actions: [], dropped: 0 };
+  }
+  const result = { actions: state.queue.splice(0), dropped: state.dropped };
+  state.dropped = 0;
+  return result;
+}
+
+function stopUserActionsInPage(globalName) {
+  window[globalName]?.stop();
+}
+
+/** Host half, shared by raw launched pages and commander traces. */
+export function createUserActionStream(options) {
+  const {
+    page,
+    enabled,
+    record,
+    identity,
+    note,
+    privacyOptions,
+    limits,
+    evaluateInPage,
+    captureTimeoutMs,
+  } = options;
+  const globalName = `__browserCommanderUserActions_${identity.traceId}`;
+  let active = true,
+    detachInit,
+    detachBinding;
+  const pending = new Set();
+  const emit = (payload) => {
+    if (!active) {
+      return Promise.resolve();
+    }
+    if (pending.size >= (limits.maxQueuedUserActions ?? 5000)) {
+      return Promise.reject(new Error('user action writer busy'));
+    }
+    const promise = record(TRACE_EVENT.INTERACTION, {
+      ...payload,
+      actionId: identity.nextActionId(),
+    });
+    pending.add(promise);
+    promise.finally(() => pending.delete(promise)).catch(() => {});
+    return promise;
+  };
+  const evaluate = async (fn, arg) => {
+    const frames = framesOf(page);
+    return await withDeadline(
+      frames.length
+        ? Promise.all(
+            frames.map((frame) => frame.evaluate(fn, arg).catch(() => null))
+          )
+        : Promise.resolve(evaluateInPage(fn, arg)).then((result) => [result]),
+      captureTimeoutMs,
+      'trace user actions'
+    );
+  };
+  async function install() {
+    if (!enabled) {
+      return;
+    }
+    try {
+      detachBinding = await attachBinding(page, globalName, emit).catch(
+        (error) => {
+          note(`using queued user actions: ${error.message}`);
+          return null;
+        }
+      );
+      const config = {
+        globalName,
+        binding: detachBinding ? USER_ACTION_BINDING : null,
+        maxQueued: limits.maxQueuedUserActions ?? 5000,
+        redactSelectors: privacyOptions.redactSelectors,
+        ignoreSelectors: options.ignoreSelectors ?? [],
+        redacted: '[redacted]',
+      };
+      detachInit = await installInitScript({
+        page,
+        fn: installUserActionRecorderInPage,
+        arg: config,
+        note,
+      });
+      await evaluate(installUserActionRecorderInPage, config);
+    } catch (error) {
+      note(`could not install user action recorder: ${error.message}`);
+      await record(TRACE_EVENT.DROPPED, {
+        reason: TRACE_DROP_REASON.CAPTURE_FAILED,
+        member: 'user-actions',
+        detail: error.message,
+      });
+    }
+  }
+  async function drain() {
+    if (!enabled) {
+      return;
+    }
+    try {
+      for (const result of await evaluate(drainUserActionsInPage, globalName)) {
+        for (const action of result?.actions ?? []) {
+          await emit(action);
+        }
+        if (result?.dropped) {
+          await record(TRACE_EVENT.DROPPED, {
+            reason: TRACE_DROP_REASON.SIZE_LIMIT,
+            member: 'user-actions',
+            detail: `${result.dropped} user actions over the queue limit`,
+          });
+        }
+      }
+      await Promise.all([...pending]);
+    } catch (error) {
+      note(`could not drain user actions: ${error.message}`);
+    }
+  }
+  async function stop() {
+    active = false;
+    await evaluate(stopUserActionsInPage, globalName).catch((error) =>
+      note(error.message)
+    );
+    try {
+      await detachInit?.();
+    } finally {
+      detachBinding?.();
+    }
+  }
+  return { install, drain, stop };
+}

package/tests/e2e/issue-160.e2e.test.js

@@ -0,0 +1,291 @@
+import { it } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import net from 'node:net';
+import {
+  startTrace,
+  readTrace,
+  connectOrLaunch,
+  connectBrowser,
+} from '../../src/index.js';
+import { isNavigationError } from '../../src/core/navigation-safety.js';
+import { startProcess } from '../../src/utilities/subprocess.js';
+import {
+  closeOwnedSession,
+  closeRemoteBrowser,
+  SESSION_METADATA,
+  probeSession,
+} from '../../src/browser/persistent-session.js';
+import {
+  launchE2EBrowser,
+  CHROME_LAUNCH_OPTIONS,
+  PARITY_CHROME,
+} from '../helpers/e2e-browser.js';
+import { sendHtml, startFixtureHost } from '../helpers/fixture-server.js';
+
+const options = { skip: !process.env.RUN_E2E, timeout: 60000 };
+async function removeProfile(userDataDir) {
+  await fs.rm(userDataDir, {
+    recursive: true,
+    force: true,
+    maxRetries: 10,
+    retryDelay: 100,
+  });
+}
+async function port() {
+  const server = net.createServer();
+  await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
+  const number = server.address().port;
+  await new Promise((resolve) => server.close(resolve));
+  return number;
+}
+async function until(predicate) {
+  for (let attempt = 0; attempt < 100; attempt++) {
+    if (await predicate()) {
+      return;
+    }
+    await new Promise((resolve) => setTimeout(resolve, 50));
+  }
+  throw new Error('browser condition did not settle');
+}
+
+for (const engine of ['playwright', 'puppeteer']) {
+  it(
+    `records bounded, private mutations and interrupted goto: ${engine}`,
+    options,
+    async () => {
+      const output = await fs.mkdtemp(path.join(os.tmpdir(), 'bc-160-e2e-'));
+      const launched = await launchE2EBrowser({ engine });
+      let trace;
+      let slowStarted;
+      const started = new Promise((resolve) => {
+        slowStarted = resolve;
+      });
+      const server = await startFixtureHost((route, req, res) => {
+        if (route === '/private') {
+          res.setHeader('content-type', 'application/json');
+          res.setHeader('X-Xsrftoken', 'PRIVATE_HEADER');
+          res.end(
+            JSON.stringify({ token: 'PRIVATE_RESPONSE', public: 'visible' })
+          );
+        } else if (route === '/slow') {
+          slowStarted();
+          req.once('close', () => res.destroy());
+        } else {
+          sendHtml(
+            res,
+            '<div id="app">public</div><input type="hidden" value="PRIVATE_HIDDEN"><meta name="csrf-token" content="PRIVATE_META"><script>window.xsrfToken="PRIVATE_SCRIPT";</script>'
+          );
+        }
+      });
+      try {
+        await launched.page.goto(server.baseUrl);
+        trace = await startTrace({
+          page: launched.page,
+          engine,
+          output,
+          mode: 'continuous',
+          screenshots: false,
+          network: { bodies: true, har: true },
+          gzip: engine === 'puppeteer',
+          privacy: { redactPatterns: [/PRIVATE_DYNAMIC/g] },
+          links: { dom: 'full', output: path.join(output, 'trace.lino') },
+        });
+        await launched.page.evaluate(async () => {
+          await fetch('/private?xsrf=PRIVATE_QUERY', {
+            method: 'POST',
+            headers: {
+              'content-type': 'application/json',
+              'X-Xsrftoken': 'PRIVATE_HEADER',
+            },
+            body: JSON.stringify({
+              password: 'PRIVATE_PASSWORD',
+              _xsrf: 'PRIVATE_BODY',
+              public: 'visible',
+            }),
+          }).then((response) => response.text());
+        });
+        await launched.page.evaluate(() => {
+          const app = document.querySelector('#app');
+          app.innerHTML = `<section>${'public'.repeat(1000)}</section>`;
+          for (let i = 0; i < 50; i++) {
+            const node = document.createElement('span');
+            node.textContent = `public-${i} PRIVATE_DYNAMIC`;
+            app.appendChild(node);
+          }
+          document.querySelector('meta').content = 'PRIVATE_CHANGED';
+        });
+        await trace.checkpoint('after');
+        await trace.stop();
+        const opened = await readTrace(output);
+        const batches = await opened.mutations(opened.checkpoints[0].index);
+        const data = JSON.stringify(batches);
+        assert.ok(data.length < 60000, `mutation bytes: ${data.length}`);
+        for (const batch of batches) {
+          for (const record of batch.records ?? []) {
+            assert.equal(record.target?.html, undefined);
+          }
+        }
+        const contents = [
+          data,
+          JSON.stringify(opened.events),
+          await fs.readFile(path.join(output, 'trace.lino'), 'utf8'),
+          await fs.readFile(path.join(output, 'network.har'), 'utf8'),
+          ...(await Promise.all(
+            opened.checkpoints.map((cp) => opened.html(cp.index))
+          )),
+        ];
+        for (const text of contents) {
+          assert.doesNotMatch(text, /PRIVATE_/);
+          assert.match(text, /public|visible/);
+        }
+        const interrupted = launched.page
+          .goto(`${server.baseUrl}/slow`)
+          .catch((error) => error);
+        await started;
+        await launched.page.goto(server.baseUrl);
+        assert.equal(isNavigationError(await interrupted), true);
+      } finally {
+        await trace?.stop();
+        await launched.cleanup();
+        await server.close();
+        await fs.rm(output, { recursive: true, force: true });
+      }
+    }
+  );
+}
+
+it(
+  'adopts a verified profile, heartbeats an idle controller and closes later tabs',
+  options,
+  async () => {
+    const userDataDir = await fs.mkdtemp(
+      path.join(os.tmpdir(), 'bc-160-session-')
+    );
+    const remoteDebuggingPort = await port();
+    const settings = {
+      engine: 'playwright',
+      userDataDir,
+      remoteDebuggingPort,
+      idleTimeoutMs: 2500,
+      headless: true,
+      ...CHROME_LAUNCH_OPTIONS,
+    };
+    let session, originalOwner;
+    try {
+      session = await connectOrLaunch(settings);
+      originalOwner = JSON.parse(
+        await fs.readFile(path.join(userDataDir, SESSION_METADATA), 'utf8')
+      );
+      const originalUrl = session.page.url();
+      const preferred = await session.browser.contexts()[0].newPage();
+      await preferred.goto('data:text/html,<p>preferred tab</p>');
+      const preferredUrl = preferred.url();
+      assert.ok(
+        (await session.reusePage({
+          urlMatchers: [preferredUrl, originalUrl],
+        })) === preferred,
+        'ranked URL matchers must override the remembered target'
+      );
+      await session.detach();
+      session = await connectOrLaunch({
+        ...settings,
+        urlMatchers: [originalUrl, preferredUrl],
+      });
+      assert.equal(session.page.url(), originalUrl);
+      await session.detach();
+      await fs.rm(path.join(userDataDir, SESSION_METADATA));
+      session = await connectOrLaunch({
+        ...settings,
+        adoptExisting: true,
+        closeNewTabs: true,
+        singleTab: true,
+      });
+      assert.equal(session.adopted, true);
+      const selected = session.page;
+      await session.browser
+        .contexts()[0]
+        .newPage()
+        .catch(() => {});
+      await until(() => session.browser.contexts()[0].pages().length === 1);
+      assert.equal(session.page, selected);
+      await selected.close();
+      const replacement = await session.reusePage();
+      assert.equal(replacement.isClosed(), false);
+      await new Promise((resolve) => setTimeout(resolve, 4000));
+      assert.ok(await probeSession(`http://127.0.0.1:${remoteDebuggingPort}`));
+      await session.detach();
+      await closeOwnedSession(
+        path.join(userDataDir, SESSION_METADATA),
+        JSON.parse(
+          await fs.readFile(path.join(userDataDir, SESSION_METADATA), 'utf8')
+        )
+      );
+    } finally {
+      await session?.detach();
+      const metadataFile = path.join(userDataDir, SESSION_METADATA);
+      const metadata = await fs
+        .readFile(metadataFile, 'utf8')
+        .then(JSON.parse, () => null);
+      if (metadata) {
+        await closeOwnedSession(metadataFile, metadata);
+      } else if (originalOwner) {
+        const version = await probeSession(
+          `http://127.0.0.1:${remoteDebuggingPort}`
+        );
+        if (
+          version?.webSocketDebuggerUrl === originalOwner.webSocketDebuggerUrl
+        ) {
+          await closeRemoteBrowser(version.webSocketDebuggerUrl);
+        }
+      }
+      await removeProfile(userDataDir);
+    }
+  }
+);
+
+it(
+  'reconnects to headed Chrome with no page targets in its default context',
+  options,
+  async () => {
+    const userDataDir = await fs.mkdtemp(
+      path.join(os.tmpdir(), 'bc-160-zero-pages-')
+    );
+    const remoteDebuggingPort = await port();
+    const endpoint = `http://127.0.0.1:${remoteDebuggingPort}`;
+    const process = startProcess(PARITY_CHROME, [
+      ...(CHROME_LAUNCH_OPTIONS.args ?? []),
+      `--user-data-dir=${userDataDir}`,
+      `--remote-debugging-port=${remoteDebuggingPort}`,
+      '--no-startup-window',
+      '--keep-alive-for-test',
+      '--no-first-run',
+    ]);
+    let connection;
+    try {
+      await until(() => probeSession(endpoint));
+      const targets = await fetch(`${endpoint}/json/list`).then((response) =>
+        response.json()
+      );
+      assert.equal(
+        targets.filter((target) => target.type === 'page').length,
+        0
+      );
+      connection = await connectBrowser({
+        engine: 'playwright',
+        cdpEndpoint: endpoint,
+      });
+      assert.ok(connection.page);
+      await connection.page.goto('data:text/html,<p>public profile page</p>');
+      await connection.detach();
+      assert.ok(await probeSession(endpoint));
+    } finally {
+      await connection?.detach();
+      process.kill();
+      await process.exited;
+      await removeProfile(userDataDir);
+    }
+  }
+);