browser-commander 0.27.0 → 0.28.0

package/src/interactions/click.js

@@ -31,6 +31,25 @@ function isInterrupted(error) {
   return isNavigationError(error) || isActionStoppedError(error);
 }
 
+function waitInterruptedByNavigation({
+  error,
+  page,
+  navigationManager,
+  startUrl,
+  startSessionId,
+  preparationFinished,
+}) {
+  const timedOut =
+    error.name === 'TimeoutError' ||
+    error.name === 'NavigationInterruptedError' ||
+    /timeout|timed out/i.test(error.message);
+  const navigationChanged =
+    page.url() !== startUrl ||
+    (startSessionId !== undefined &&
+      navigationManager?.getSessionId?.() !== startSessionId);
+  return timedOut && navigationChanged && !preparationFinished;
+}
+
 /**
  * Read the target element's observable state under the click's own budget.
  *
@@ -975,6 +994,7 @@ export async function clickButton(options = {}) {
 
   const startUrl = page.url();
   const startSessionId = navigationManager?.getSessionId?.();
+  let preparationFinished = false;
 
   try {
     const prepareResult = await prepareElement({
@@ -1012,6 +1032,7 @@ export async function clickButton(options = {}) {
       });
     }
 
+    preparationFinished = true;
     const clickResult = await clickElement({
       page,
       engine,
@@ -1055,6 +1076,29 @@ export async function clickButton(options = {}) {
       actionId,
     });
   } catch (error) {
+    if (
+      waitInterruptedByNavigation({
+        error,
+        page,
+        navigationManager,
+        startUrl,
+        startSessionId,
+        preparationFinished,
+      })
+    ) {
+      return makeClickResult({
+        status: CLICK_STATUS.INTERRUPTED,
+        dispatched: false,
+        effect: CLICK_EFFECT.NOT_OBSERVED,
+        navigated: true,
+        reason: 'navigation interrupted the element wait before the click',
+        evidence: [
+          evidence('interrupted', { message: error.message, phase: 'prepare' }),
+        ],
+        elapsedMs: elapsed(),
+        actionId,
+      });
+    }
     if (isInterrupted(error)) {
       log.debug(
         () =>

package/src/interactions/overlays.js

@@ -0,0 +1,28 @@
+import { isVisible } from '../elements/visibility.js';
+
+/** Dismiss only overlays explicitly named by the caller. No page markers. */
+export async function dismissOverlays({ page, engine, overlays = [] }) {
+  if (!Array.isArray(overlays)) {
+    throw new TypeError('overlays must be an array');
+  }
+  for (const item of overlays) {
+    const options = typeof item === 'string' ? { selector: item } : item;
+    if (!options?.selector) {
+      throw new TypeError('overlay requires selector');
+    }
+    if (engine === 'playwright') {
+      const target = page.locator(options.selector).first();
+      if (await target.isVisible()) {
+        await target.click({ timeout: options.timeout ?? 1000 });
+      }
+    } else {
+      const target = await page.$(options.selector);
+      if (
+        target &&
+        (await isVisible({ page, engine, selector: options.selector }))
+      ) {
+        await target.click();
+      }
+    }
+  }
+}

package/src/traces/bundle.js

@@ -181,10 +181,17 @@ export async function openTraceBundle(options = {}) {
    * @param {string|Buffer} contents - What to write
    * @returns {Promise<Object|null>} `{member, bytes}` or null when dropped
    */
-  async function writeMember(member, contents) {
+  async function writeMember(member, contents, { append = false } = {}) {
     const data = Buffer.isBuffer(contents) ? contents : Buffer.from(contents);
+    const target = path.join(root, member);
+    const previous = append
+      ? await fs.stat(target).then(
+          (value) => value.size,
+          () => 0
+        )
+      : 0;
 
-    if (!fits(data.length)) {
+    if (!fits(data.length) || previous + data.length > maxResourceBytes) {
       await drop({
         reason: TRACE_DROP_REASON.SIZE_LIMIT,
         member,
@@ -193,13 +200,15 @@ export async function openTraceBundle(options = {}) {
       return null;
     }
 
-    const target = path.join(root, member);
     try {
       await fs.mkdir(path.dirname(target), {
         recursive: true,
         mode: TRACE_DIRECTORY_MODE,
       });
-      await fs.writeFile(target, data, { mode: TRACE_FILE_MODE });
+      await fs.writeFile(target, data, {
+        mode: TRACE_FILE_MODE,
+        flag: append ? 'a' : 'w',
+      });
       written += data.length;
       return { member, bytes: data.length };
     } catch (error) {
@@ -267,7 +276,7 @@ export async function openTraceBundle(options = {}) {
     }
     const member = `${TRACE_FILES.MUTATIONS_DIR}/${sequenceName(index)}.ndjson`;
     const body = `${batches.map((batch) => JSON.stringify(batch)).join('\n')}\n`;
-    const result = await writeMember(member, body);
+    const result = await writeMember(member, body, { append: true });
     if (result) {
       counts.mutationBatches += batches.length;
     }

package/src/traces/checkpoints.js

@@ -0,0 +1,99 @@
+import { captureSnapshotInPage } from './page-capture.js';
+import { withDeadline } from './deadline.js';
+import { redactValue, redactUrl, REDACTED } from './redaction.js';
+import { TRACE_EVENT, TRACE_DROP_REASON } from './schema.js';
+export function createCheckpointRecorder({
+  isStopped,
+  captureState,
+  mutations,
+  evaluateInPage,
+  privacyOptions,
+  domOptions,
+  links,
+  limits,
+  captureTimeoutMs,
+  bundle,
+  screenshot,
+  checkpoints,
+  record,
+}) {
+  /**
+   * Capture a named checkpoint.
+   *
+   * @param {string} name - What this moment is
+   * @param {Object} [checkpointOptions] - `{actor, reason, screenshots}`
+   * @returns {Promise<Object|null>} `{index, name, members}`
+   */
+  async function checkpoint(name, checkpointOptions = {}) {
+    if (isStopped()) {
+      throw new Error('this trace has already been stopped');
+    }
+
+    const { actor = 'automation', reason = 'checkpoint' } = checkpointOptions;
+    const index = ++captureState.index;
+
+    // Mutations are drained first so the batches belong to the interval that
+    // ended here, not to the one that starts now.
+    await mutations.drain(index - 1 > 0 ? index - 1 : 0);
+
+    let captured = null;
+    try {
+      captured = await withDeadline(
+        evaluateInPage(captureSnapshotInPage, {
+          redactSelectors: privacyOptions.redactSelectors,
+          redactAttributes: privacyOptions.redactAttributes,
+          redacted: REDACTED,
+          html: domOptions.html,
+          liveControlState: domOptions.liveControlState,
+          openShadowRoots: domOptions.openShadowRoots,
+          ignoreSelectors: domOptions.ignoreSelectors ?? [],
+          captureText: links?.dom === 'text',
+          maxHtmlBytes: limits.maxHtmlBytes ?? 0,
+        }),
+        captureTimeoutMs,
+        'trace checkpoint capture'
+      );
+    } catch (error) {
+      await bundle.drop({
+        reason: /closed/i.test(error.message)
+          ? TRACE_DROP_REASON.PAGE_CLOSED
+          : TRACE_DROP_REASON.CAPTURE_FAILED,
+        member: `checkpoints/${index}`,
+        detail: error.message,
+      });
+    }
+
+    const shot = await screenshot(reason);
+    const state = captured?.state
+      ? redactValue(captured.state, privacyOptions)
+      : null;
+
+    const members = await bundle.writeCheckpoint({
+      index,
+      html: captured?.html ?? undefined,
+      state: state ? { ...state, name, actor, reason } : undefined,
+      screenshot: shot ?? undefined,
+    });
+
+    const entry = {
+      index,
+      name,
+      actor,
+      reason,
+      url: state ? redactUrl(state.url, privacyOptions) : null,
+      truncated: Boolean(captured?.truncated),
+      members,
+    };
+    checkpoints.push(entry);
+    await record(TRACE_EVENT.CHECKPOINT, entry);
+
+    // The init script covers every document created from here on; this covers
+    // a frame that was attached without one, which is cheap because installing
+    // over a recorder that is already observing does nothing.
+    await mutations.install();
+
+    return entry;
+  }
+
+  return checkpoint;
+}

package/src/traces/links.js

@@ -429,6 +429,7 @@ export async function traceLinks(trace, options = {}) {
   if (sections.has('control-diffs')) {
     links.push(...(await controlDiffLinks(opened)));
   }
+  links.push(...(await domLinks(opened, options.dom)));
 
   if (sections.has('trace')) {
     links.push(
@@ -470,6 +471,63 @@ async function controlDiffLinks(opened) {
   return links;
 }
 
+/** Self-contained DOM and mutation records in Links Notation. */
+async function domLinks(opened, dom, seen = new Set()) {
+  if (!dom) {
+    return [];
+  }
+  const links = [];
+  for (const checkpoint of opened.checkpoints) {
+    if (dom === 'text') {
+      const state = await opened.state(checkpoint.index);
+      if (state?.text) {
+        links.push(
+          new Link('dom-text', [
+            field('checkpoint', checkpoint.index),
+            field('text', state.text),
+          ])
+        );
+      }
+    } else {
+      links.push(
+        new Link('dom-snapshot', [
+          field('checkpoint', checkpoint.index),
+          field('html', await opened.html(checkpoint.index)),
+        ])
+      );
+    }
+  }
+  for (const event of opened.events.filter(
+    (event) => event.kind === 'mutations'
+  )) {
+    const batches = (await opened.mutations(event.checkpoint)).filter(
+      (batch) => {
+        const key = `${event.member}:${batch.frameId}:${batch.sequence}:${batch.at}`;
+        if (seen.has(key)) {
+          return false;
+        }
+        seen.add(key);
+        return true;
+      }
+    );
+    for (const batch of batches) {
+      for (const record of batch.records ?? []) {
+        if (dom !== 'text') {
+          links.push(
+            new Link('dom-mutation', [
+              field('at', batch.at),
+              field('record', JSON.stringify(record)),
+            ])
+          );
+        } else {
+          links.push(...textMutationLinks(record, batch));
+        }
+      }
+    }
+  }
+  return links;
+}
+
 /**
  * Resolve where an export should be written.
  *
@@ -521,10 +579,11 @@ export async function writeTraceLinks(trace, output, options = {}) {
  * @returns {Promise<Object>} The sink
  */
 export async function openTraceLinks(options = {}) {
-  const { output, include, bundlePath, ...about } = options;
+  const { output, include, dom, bundlePath, ...about } = options;
   const file = await resolveOutput(output);
   const sections = chosenSections(include);
   const problems = [];
+  const seenDom = new Set();
 
   await fs.mkdir(path.dirname(file), { recursive: true });
   const handle = await fs.open(file, 'w', 0o600);
@@ -572,6 +631,24 @@ export async function openTraceLinks(options = {}) {
         return;
       }
       await append(linksForEvent(event, sections));
+      if (
+        dom &&
+        bundlePath &&
+        [TRACE_EVENT.CHECKPOINT, TRACE_EVENT.MUTATIONS].includes(event.kind)
+      ) {
+        const opened = await readTrace(bundlePath);
+        await append(
+          await domLinks(
+            {
+              ...opened,
+              checkpoints: event.kind === TRACE_EVENT.CHECKPOINT ? [event] : [],
+              events: event.kind === TRACE_EVENT.MUTATIONS ? [event] : [],
+            },
+            dom,
+            seenDom
+          )
+        );
+      }
     },
     /**
      * Finish the export.
@@ -593,6 +670,7 @@ export async function openTraceLinks(options = {}) {
           problems.push({ member: file, detail: error.message });
         }
       }
+
       if (sections.has('trace')) {
         links.push(
           traceResultLink(closing.manifest, {
@@ -621,3 +699,41 @@ export async function openTraceLinks(options = {}) {
     },
   };
 }
+
+function textMutationLinks(record, batch) {
+  if (record.target?.visible === false) {
+    return [];
+  }
+  const links = [];
+  const target = record.target?.path ?? '';
+  if (record.kind === 'attributes' || record.kind === 'characterData') {
+    links.push(
+      new Link(
+        record.kind === 'attributes' ? 'attribute-changed' : 'text-changed',
+        [
+          field('at', batch.at),
+          field('path', target),
+          field('attribute', record.attribute ?? null),
+          field('before', record.before),
+          field('after', record.after),
+        ]
+      )
+    );
+  }
+  if (record.kind === 'childList') {
+    for (const change of ['added', 'removed']) {
+      for (const node of record[change] ?? []) {
+        if (node.visible !== false && node.text) {
+          links.push(
+            new Link(`text-${change}`, [
+              field('at', batch.at),
+              field('path', node.path ?? target),
+              field('text', node.text),
+            ])
+          );
+        }
+      }
+    }
+  }
+  return links;
+}

package/src/traces/mutation-stream.js

@@ -63,6 +63,7 @@ export function createMutationStream(options) {
     globalName: RECORDER_GLOBAL,
     redactSelectors: privacyOptions.redactSelectors,
     redacted: REDACTED,
+    ignoreSelectors: domOptions.ignoreSelectors ?? [],
     maxQueued: limits.maxQueuedMutations ?? DEFAULT_MAX_QUEUED_MUTATIONS,
     liveState: domOptions.liveState !== false,
   };

package/src/traces/network.js

@@ -0,0 +1,257 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { withDeadline } from './deadline.js';
+
+const PRIVATE_HEADERS = new Set([
+  'cookie',
+  'authorization',
+  'proxy-authorization',
+  'set-cookie',
+]);
+export function redactHeaders(headers = {}) {
+  return Object.fromEntries(
+    Object.entries(headers).map(([key, value]) => [
+      key.toLowerCase(),
+      PRIVATE_HEADERS.has(key.toLowerCase()) ? '[redacted]' : value,
+    ])
+  );
+}
+
+function matches(url, pattern) {
+  if (pattern === undefined) {
+    return true;
+  }
+  if (typeof pattern === 'function') {
+    return Boolean(pattern(url));
+  }
+  if (pattern instanceof RegExp) {
+    pattern.lastIndex = 0;
+    return pattern.test(url);
+  }
+  return url.includes(String(pattern));
+}
+
+export function networkHar(events) {
+  const requests = new Map(
+    events
+      .filter((event) => event.kind === 'network.request')
+      .map((event) => [event.requestId, event])
+  );
+  const headers = (value) =>
+    Object.entries(value ?? {}).map(([name, value]) => ({
+      name,
+      value: String(value),
+    }));
+  const entries = events
+    .filter((event) => event.kind === 'network.response')
+    .map((response) => {
+      const request = requests.get(response.requestId) ?? response;
+      const timing = response.timing ?? request.timing ?? {};
+      return {
+        startedDateTime: request.at ?? new Date().toISOString(),
+        time: Math.max(0, timing.responseEnd ?? 0),
+        request: {
+          method: request.method,
+          url: request.url,
+          httpVersion: 'HTTP/1.1',
+          headers: headers(request.headers),
+          cookies: [],
+          queryString: [],
+          headersSize: -1,
+          bodySize: -1,
+          ...(request.postData !== undefined
+            ? {
+                postData: {
+                  mimeType: request.headers?.['content-type'] ?? '',
+                  text: request.postData,
+                  _truncated: request.postDataTruncated,
+                },
+              }
+            : {}),
+        },
+        response: {
+          status: response.status,
+          statusText: response.statusText ?? '',
+          httpVersion: 'HTTP/1.1',
+          headers: headers(response.headers),
+          cookies: [],
+          redirectURL: response.headers?.location ?? '',
+          headersSize: -1,
+          bodySize: response.body?.size ?? -1,
+          content: {
+            size: response.body?.size ?? 0,
+            mimeType: response.contentType ?? '',
+            ...(response.body
+              ? {
+                  text: response.body.data,
+                  encoding: 'base64',
+                  _truncated: response.body.truncated,
+                }
+              : {}),
+          },
+        },
+        cache: {},
+        timings: {
+          send: 0,
+          wait: Math.max(
+            0,
+            (timing.responseStart ?? 0) - (timing.requestStart ?? 0)
+          ),
+          receive: Math.max(
+            0,
+            (timing.responseEnd ?? 0) - (timing.responseStart ?? 0)
+          ),
+        },
+        _resourceType: response.resourceType,
+      };
+    });
+  return {
+    log: {
+      version: '1.2',
+      creator: { name: 'browser-commander', version: '1' },
+      entries,
+    },
+  };
+}
+
+/** Observe without fetching again, and drain responses before closing the bundle. */
+export function validateNetworkOptions(network) {
+  if (!network) {
+    return;
+  }
+  const options = network === true ? {} : network;
+  if (
+    typeof options !== 'object' ||
+    !Number.isSafeInteger(options.maxBodyBytes ?? 1024 * 1024) ||
+    (options.maxBodyBytes ?? 0) < 0 ||
+    (options.maxBodyBytes ?? 0) > 16 * 1024 * 1024
+  ) {
+    throw new RangeError(
+      'network.maxBodyBytes must be an integer between 0 and 16 MiB'
+    );
+  }
+}
+export function attachNetwork({ page, network, record, note }) {
+  validateNetworkOptions(network);
+  if (!network) {
+    return async () => {};
+  }
+  const options = network === true ? {} : network;
+  const maxBodyBytes = options.maxBodyBytes ?? 1024 * 1024;
+  if (!Number.isSafeInteger(maxBodyBytes) || maxBodyBytes < 0) {
+    throw new RangeError('network.maxBodyBytes must be a nonnegative integer');
+  }
+  const ids = new WeakMap();
+  const pending = new Set();
+  let sequence = 0;
+  const details = (request) => ({
+    requestId: ids.get(request),
+    method: request.method(),
+    url: request.url(),
+    resourceType: request.resourceType?.() ?? 'other',
+    timing: request.timing?.() ?? null,
+  });
+  const allowed = (request) =>
+    (!options.resourceTypes ||
+      options.resourceTypes.includes(request.resourceType?.())) &&
+    matches(request.url(), options.urlPattern ?? options.url);
+  const track = (promise) => {
+    pending.add(promise);
+    promise.finally(() => pending.delete(promise)).catch(() => {});
+  };
+  const request = (request) => {
+    if (!allowed(request)) {
+      return;
+    }
+    ids.set(request, ++sequence);
+    track(
+      record('network.request', {
+        ...details(request),
+        headers: redactHeaders(request.headers?.()),
+        ...(options.bodies &&
+        ['document', 'xhr', 'fetch'].includes(request.resourceType?.()) &&
+        request.postData?.()
+          ? {
+              postData: Buffer.from(request.postData())
+                .subarray(0, maxBodyBytes)
+                .toString('utf8'),
+              postDataTruncated:
+                Buffer.byteLength(request.postData()) > maxBodyBytes,
+            }
+          : {}),
+      })
+    );
+  };
+  const response = (response) => {
+    const request = response.request();
+    if (!ids.has(request)) {
+      return;
+    }
+    const saturated = pending.size >= 32;
+    track(
+      (async () => {
+        const headers = redactHeaders(
+          await withDeadline(
+            Promise.resolve(response.allHeaders?.() ?? response.headers()),
+            5000,
+            'network headers'
+          )
+        );
+        const payload = {
+          ...details(request),
+          status: response.status(),
+          statusText: response.statusText?.() ?? '',
+          headers,
+          contentType: headers['content-type'] ?? null,
+        };
+        const resourceType = payload.resourceType;
+        if (
+          !saturated &&
+          options.bodies &&
+          ['document', 'xhr', 'fetch'].includes(resourceType)
+        ) {
+          const length = Number(headers['content-length']);
+          if (Number.isFinite(length) && length > maxBodyBytes) {
+            payload.body = { size: length, truncated: true, data: '' };
+          } else {
+            try {
+              const data = Buffer.from(
+                await withDeadline(
+                  response.body?.() ?? response.buffer(),
+                  5000,
+                  'network body'
+                )
+              );
+              payload.body = {
+                size: data.length,
+                truncated: data.length > maxBodyBytes,
+                data: data.subarray(0, maxBodyBytes).toString('base64'),
+              };
+            } catch (error) {
+              payload.bodyError = error.message;
+            }
+          }
+        }
+        if (saturated && options.bodies) {
+          payload.bodyError = 'body capture concurrency limit';
+        }
+        await record('network.response', payload);
+      })().catch((error) => note(`network capture: ${error.message}`))
+    );
+  };
+  page.on('request', request);
+  page.on('response', response);
+  return async () => {
+    page.off('request', request);
+    page.off('response', response);
+    await Promise.allSettled([...pending]);
+  };
+}
+
+export async function writeHar(opened, output) {
+  await fs.writeFile(
+    output ?? path.join(opened.path, 'network.har'),
+    JSON.stringify(networkHar(opened.events), null, 2),
+    { mode: 0o600 }
+  );
+}