browser-commander 0.26.2 → 0.27.0

package/src/elements/reusable.js

@@ -0,0 +1,92 @@
+import { count, isVisible } from './visibility.js';
+import { getLocatorOrElement } from './locators.js';
+import { clickButton } from '../interactions/click.js';
+import { evaluate } from '../utilities/wait.js';
+
+/** Return the first selector in caller order with a match (optionally visible). */
+export async function findFirst({
+  selectors,
+  visible = false,
+  ...options
+} = {}) {
+  if (!Array.isArray(selectors)) {
+    throw new TypeError('selectors must be an array');
+  }
+  for (const selector of selectors) {
+    if (
+      (await count({ ...options, selector })) > 0 &&
+      (!visible || (await isVisible({ ...options, selector })))
+    ) {
+      return selector;
+    }
+  }
+  return null;
+}
+
+/** Match any phrase in body text; Unicode whitespace includes nonbreaking spaces. */
+export function hasText({
+  texts,
+  normalizeWhitespace = false,
+  ...options
+} = {}) {
+  if (!Array.isArray(texts) || texts.some((text) => typeof text !== 'string')) {
+    throw new TypeError('texts must be strings');
+  }
+  return evaluate({
+    ...options,
+    fn: (phrases, normalize) => {
+      const clean = (text) =>
+        normalize ? text.replace(/\s+/gu, ' ').trim() : text;
+      const body = clean(document.body?.textContent ?? '');
+      return phrases.some((text) => body.includes(clean(text)));
+    },
+    args: [texts, normalizeWhitespace],
+  });
+}
+
+/** Observe checked state of the selected checkbox or radio. */
+export async function isChecked(options = {}) {
+  const element = await getLocatorOrElement(options);
+  if (!element) {
+    return false;
+  }
+  const probe = (el) => Boolean(el.checked);
+  return options.engine === 'playwright'
+    ? element.evaluate(probe)
+    : options.page.evaluate(probe, element);
+}
+
+/** Idempotently set a checkbox or radio and verify the resulting state. */
+export async function check({ checked = true, ...options } = {}) {
+  const element = await getLocatorOrElement(options);
+  if (!element) {
+    return { checked: false, changed: false, verified: false };
+  }
+  const type =
+    options.engine === 'playwright'
+      ? await element.evaluate((el) => el.type)
+      : await options.page.evaluate((el) => el.type, element);
+  if (!['checkbox', 'radio'].includes(type)) {
+    throw new TypeError('check requires a checkbox or radio');
+  }
+  if (type === 'radio' && !checked) {
+    throw new TypeError('A radio cannot be unchecked by clicking');
+  }
+  const before = await isChecked({ ...options, selector: element });
+  if (before === checked) {
+    return { checked: before, changed: false, verified: true };
+  }
+  await clickButton({
+    ...options,
+    selector: element,
+    verify: false,
+    waitAfterClick: 0,
+    waitForNavigation: false,
+  });
+  const after = await isChecked({ ...options, selector: element });
+  return {
+    checked: after,
+    changed: before !== after,
+    verified: after === checked,
+  };
+}

package/src/elements/visibility.js

@@ -19,7 +19,7 @@ export async function isVisible(options = {}) {
 
   try {
     if (engine === 'playwright') {
-      const locator = await getLocatorOrElement({ page, engine, selector });
+      const locator = await getLocatorOrElement(options);
       try {
         await locator.waitFor({
           state: 'visible',
@@ -30,7 +30,7 @@ export async function isVisible(options = {}) {
         return false;
       }
     } else {
-      const element = await getLocatorOrElement({ page, engine, selector });
+      const element = await getLocatorOrElement(options);
       if (!element) {
         return false;
       }
@@ -56,16 +56,11 @@ export async function isVisible(options = {}) {
  * @param {Object} options.page - Browser page object
  * @param {string} options.engine - Engine type ('playwright' or 'puppeteer')
  * @param {string|Object} options.selector - CSS selector or locator
- * @param {Array<string>} options.disabledClasses - Additional CSS classes that indicate disabled state (default: ['magritte-button_loading'])
+ * @param {Array<string>} options.disabledClasses - Additional CSS classes that indicate disabled state (default: ['disabled'])
  * @returns {Promise<boolean>} - True if enabled
  */
 export async function isEnabled(options = {}) {
-  const {
-    page,
-    engine,
-    selector,
-    disabledClasses = ['magritte-button_loading'],
-  } = options;
+  const { page, engine, selector, disabledClasses = ['disabled'] } = options;
 
   if (!selector) {
     throw new Error('selector is required in options');
@@ -76,7 +71,7 @@ export async function isEnabled(options = {}) {
       // For Playwright, use locator API
       const locator =
         typeof selector === 'string'
-          ? page.locator(selector).first()
+          ? (await getLocatorOrElement(options)).first()
           : selector;
       return await locator.evaluate((el, classes) => {
         const isDisabled =
@@ -87,7 +82,7 @@ export async function isEnabled(options = {}) {
       }, disabledClasses);
     } else {
       // For Puppeteer (selector should already be normalized by withTextSelectorSupport wrapper)
-      const element = await getLocatorOrElement({ page, engine, selector });
+      const element = await getLocatorOrElement(options);
       if (!element) {
         return false;
       }

package/src/exports.js

@@ -328,3 +328,17 @@ export {
   SafariUnsupportedError,
   openSafariSettings,
 } from './browser/safari-support.js';
+
+export { BrowserLaunchError } from './browser/launch-diagnostics.js';
+
+export { findFirst, hasText, isChecked, check } from './elements/reusable.js';
+export { setCookies, clearCookies } from './browser/session-cookies.js';
+export {
+  readFlag,
+  uninstallClickListener,
+} from './high-level/universal-logic.js';
+
+export {
+  findSiteSessions,
+  readBrowserCookieSession,
+} from './browser/browser-cookie-session.js';

package/src/factory.js

@@ -215,16 +215,16 @@ export function makeBrowserCommander(options = {}) {
     // Subscribe to navigation events (legacy API)
     onNavigationStart: navigationManager
       ? (fn) => navigationManager.on('onNavigationStart', fn)
-      : () => {},
+      : () => () => {},
     onNavigationComplete: navigationManager
       ? (fn) => navigationManager.on('onNavigationComplete', fn)
-      : () => {},
+      : () => () => {},
     onUrlChange: navigationManager
       ? (fn) => navigationManager.on('onUrlChange', fn)
-      : () => {},
+      : () => () => {},
     onPageReady: navigationManager
       ? (fn) => navigationManager.on('onPageReady', fn)
-      : () => {},
+      : () => () => {},
 
     // Abort handling - check these to stop operations when navigation occurs
     shouldAbort: navigationManager

package/src/high-level/universal-logic.js

@@ -101,26 +101,29 @@ export async function installClickListener(options = {}) {
 
   const result = await safeEvaluate({
     fn: (text, key) => {
-      document.addEventListener(
-        'click',
-        (event) => {
-          let element = event.target;
-          while (element && element !== document.body) {
-            const elementText = element.textContent?.trim() || '';
-            if (
-              elementText === text ||
-              ((element.tagName === 'A' || element.tagName === 'BUTTON') &&
-                elementText.includes(text))
-            ) {
-              console.log(`[Click Listener] Detected click on ${text} button!`);
-              window.sessionStorage.setItem(key, 'true');
-              break;
-            }
-            element = element.parentElement;
+      window.__browserCommanderClickListeners ??= new Map();
+      const previous = window.__browserCommanderClickListeners.get(key);
+      if (previous) {
+        document.removeEventListener('click', previous, true);
+      }
+      const listener = (event) => {
+        let element = event.target;
+        while (element && element !== document.body) {
+          const elementText = element.textContent?.trim() || '';
+          if (
+            elementText === text ||
+            ((element.tagName === 'A' || element.tagName === 'BUTTON') &&
+              elementText.includes(text))
+          ) {
+            console.log(`[Click Listener] Detected click on ${text} button!`);
+            window.sessionStorage.setItem(key, 'true');
+            break;
           }
-        },
-        true
-      );
+          element = element.parentElement;
+        }
+      };
+      window.__browserCommanderClickListeners.set(key, listener);
+      document.addEventListener('click', listener, true);
     },
     args: [buttonText, storageKey],
   });
@@ -176,6 +179,7 @@ export async function findToggleButton(options = {}) {
     findByText,
     dataQaSelectors = [],
     textToFind,
+    texts = textToFind ? [textToFind] : [],
     elementTypes = ['button', 'a', 'span'],
   } = options;
 
@@ -188,10 +192,10 @@ export async function findToggleButton(options = {}) {
   }
 
   // Fallback to text search
-  if (textToFind) {
+  for (const text of texts) {
     for (const elementType of elementTypes) {
       const selector = await findByText({
-        text: textToFind,
+        text,
         selector: elementType,
       });
       const elemCount = await count({ selector });
@@ -203,3 +207,35 @@ export async function findToggleButton(options = {}) {
 
   return null;
 }
+
+/** Read without clearing; interruption is distinct from an unset flag. */
+export async function readFlag({ evaluate, storageKey } = {}) {
+  try {
+    const set = await evaluate({
+      fn: (key) => window.sessionStorage.getItem(key) === 'true',
+      args: [storageKey],
+    });
+    return { status: 'observed', set };
+  } catch (error) {
+    if (isNavigationError(error)) {
+      return { status: 'interrupted', set: null };
+    }
+    throw error;
+  }
+}
+
+/** Uninstall only the click listener installed for this storage key. */
+export function uninstallClickListener({ evaluate, storageKey } = {}) {
+  return evaluate({
+    fn: (key) => {
+      const listener = window.__browserCommanderClickListeners?.get(key);
+      if (!listener) {
+        return false;
+      }
+      document.removeEventListener('click', listener, true);
+      window.__browserCommanderClickListeners.delete(key);
+      return true;
+    },
+    args: [storageKey],
+  });
+}

package/src/interactions/click.js

@@ -709,6 +709,7 @@ async function prepareElement(options = {}) {
     log,
     verbose = false,
     selector,
+    index,
     scrollIntoView: shouldScroll = true,
     waitAfterScroll,
     smoothScroll = true,
@@ -719,6 +720,7 @@ async function prepareElement(options = {}) {
     page,
     engine,
     selector,
+    index,
     timeout,
   });
 
@@ -982,6 +984,7 @@ export async function clickButton(options = {}) {
       log,
       verbose,
       selector,
+      index: options.index,
       scrollIntoView: activationOptions.scroll === CLICK_SCROLL.AUTO,
       waitAfterScroll,
       smoothScroll,

package/src/interactions/scroll.js

@@ -1,3 +1,4 @@
+import { getLocatorOrElement } from '../elements/locators.js';
 import { TIMING } from '../core/constants.js';
 import { isNavigationError } from '../core/navigation-safety.js';
 import { isActionStoppedError } from '../core/page-trigger-manager.js';
@@ -146,7 +147,7 @@ export async function scrollIntoView(options = {}) {
   const {
     page,
     engine,
-    locatorOrElement,
+    locatorOrElement: suppliedElement,
     behavior = 'smooth',
     verify = true,
     verifyFn,
@@ -154,8 +155,13 @@ export async function scrollIntoView(options = {}) {
     log = { debug: () => {} },
   } = options;
 
+  const locatorOrElement =
+    suppliedElement ??
+    (options.selector ? await getLocatorOrElement(options) : null);
   if (!locatorOrElement) {
-    throw new Error('locatorOrElement is required in options');
+    throw new Error(
+      'locatorOrElement is required (or provide selector) in options'
+    );
   }
 
   try {

package/src/utilities/subprocess.js

@@ -14,12 +14,16 @@ import { ProcessRunner } from 'command-stream/process-runner';
  * optional PTY and terminal-rendering modules are never loaded.
  */
 
-function runnerFor(file, args, { env, cwd, stdin = 'ignore', killGrace }) {
+function runnerFor(
+  file,
+  args,
+  { env, cwd, stdin = 'ignore', killGrace, capture = true }
+) {
   return new ProcessRunner(
     { mode: 'exec', file, args },
     {
       mirror: false,
-      capture: true,
+      capture,
       stdin,
       ...(env ? { env } : {}),
       ...(cwd ? { cwd } : {}),
@@ -102,7 +106,7 @@ export async function runCommand(file, args = [], options = {}) {
  */
 export function startProcess(file, args = [], options = {}) {
   const { env, cwd, forwardOutput = false, killGrace = 2000 } = options;
-  const runner = runnerFor(file, args, { env, cwd, killGrace });
+  const runner = runnerFor(file, args, { env, cwd, killGrace, capture: false });
   return new ManagedProcess(runner, { forwardOutput });
 }
 
@@ -136,6 +140,8 @@ export class ManagedProcess {
     this.runner = runner;
     this.exitCode = null;
     this.signalCode = null;
+    this.stderrTail = '';
+    this.spawnError = null;
     this.stdout = new OutputChannel();
     this.stderr = new OutputChannel();
     this.exitListeners = new Set();
@@ -146,6 +152,7 @@ export class ManagedProcess {
       this.stdout.emit(chunk);
     });
     runner.on('stderr', (chunk) => {
+      this.stderrTail = (this.stderrTail + String(chunk)).slice(-8192);
       if (forwardOutput) {
         process.stderr.write(chunk);
       }
@@ -153,9 +160,13 @@ export class ManagedProcess {
     });
     runner.start();
     this.exited = Promise.resolve(runner)
-      .catch((error) => ({ code: error?.code ?? 1 }))
+      .catch((error) => {
+        this.spawnError = error;
+        return { code: error?.code ?? 1 };
+      })
       .then((result) => {
         this.exitCode = typeof result.code === 'number' ? result.code : 1;
+        this.signalCode = result.signal ?? null;
         for (const listener of this.exitListeners) {
           listener(this.exitCode);
         }

package/tests/e2e/navigation-budget.e2e.test.js

@@ -0,0 +1,132 @@
+import { describe, it, before, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { CHROME_LAUNCH_OPTIONS } from '../helpers/e2e-browser.js';
+import { createCommander, predicate } from '../../src/index.js';
+import { sendHtml, startFixtureHost } from '../helpers/fixture-server.js';
+
+// Authored local fixtures only. Each deliberately stalled connection is closed
+// by server teardown; browser actions and suites have finite budgets.
+for (const engine of ['playwright', 'puppeteer']) {
+  describe(
+    `navigation budgets: ${engine}`,
+    { skip: !process.env.RUN_E2E, timeout: 60000 },
+    () => {
+      let browser;
+      let page;
+      let commander;
+      let server;
+      before(async () => {
+        server = await startFixtureHost((route, _req, res) => {
+          if (route === '/stall' || route === '/pending') {
+            return;
+          }
+          if (route === '/redirect') {
+            res.writeHead(302, { location: '/ready' });
+            res.end();
+            return;
+          }
+          if (route === '/continuous') {
+            sendHtml(
+              res,
+              '<h1>Continuous requests</h1><script>setInterval(() => fetch("/pending"), 60);</script>'
+            );
+            return;
+          }
+          sendHtml(res, '<h1 id="ready">Ready</h1>');
+        });
+        const { chromium } = await import('playwright');
+        const launchOptions = { headless: true, ...CHROME_LAUNCH_OPTIONS };
+        if (engine === 'playwright') {
+          browser = await chromium.launch(launchOptions);
+          page = await browser.newPage();
+        } else {
+          const { default: puppeteer } = await import('puppeteer');
+          browser = await puppeteer.launch({
+            ...launchOptions,
+            executablePath:
+              CHROME_LAUNCH_OPTIONS.executablePath ?? chromium.executablePath(),
+          });
+          page = await browser.newPage();
+        }
+        commander = createCommander({ page, engine });
+      });
+      after(async () => {
+        await commander?.destroy();
+        await browser?.close();
+        await server?.close();
+      });
+      const navigate = async (url, options = {}) => {
+        const start = performance.now();
+        const result = await commander.goto({
+          url,
+          timeout: 800,
+          verify: false,
+          waitForStableUrlBefore: false,
+          waitForStableUrlAfter: false,
+          waitForNetworkIdle: false,
+          ...options,
+        });
+        assert.ok(
+          performance.now() - start < 1600,
+          'end-to-end budget must bound elapsed time'
+        );
+        return result;
+      };
+      it('loads a data page quickly with tracking enabled', async () => {
+        assert.equal(
+          (await navigate('data:text/html,<h1>Authored fixture</h1>')).status,
+          'ready'
+        );
+        assert.ok(commander.networkTracker);
+        assert.ok(page.listenerCount?.('request') > 0);
+      });
+      it('follows redirects under the same deadline', async () => {
+        const result = await navigate(`${server.baseUrl}/redirect`);
+        assert.equal(result.status, 'ready');
+        assert.equal(page.url(), `${server.baseUrl}/ready`);
+      });
+      it('times out continuous network activity and cleans navigation state', async () => {
+        const result = await navigate(`${server.baseUrl}/continuous`, {
+          waitForNetworkIdle: true,
+        });
+        assert.equal(result.status, 'timed_out');
+        assert.equal(commander.navigationManager.isNavigating(), false);
+      });
+      it('bounds a stalled engine navigation', async () => {
+        assert.equal(
+          (await navigate(`${server.baseUrl}/stall`)).status,
+          'timed_out'
+        );
+      });
+      it('observes a positive selector check', async () => {
+        const ready = predicate({
+          name: 'selector_ready',
+          fn: async () =>
+            page.evaluate(() => Boolean(document.querySelector('#ready'))),
+        });
+        assert.equal(
+          (await navigate(`${server.baseUrl}/ready`, { checks: [ready] }))
+            .status,
+          'ready'
+        );
+      });
+      it('cancels a stalled call and preserves only the session listeners', async () => {
+        const abort = new AbortController();
+        const event =
+          engine === 'playwright' ? 'framenavigated' : 'framenavigated';
+        const count = page.listenerCount?.(event);
+        const timer = setTimeout(() => abort.abort(), 80);
+        try {
+          const result = await navigate(`${server.baseUrl}/stall`, {
+            signal: abort.signal,
+          });
+          assert.equal(result.status, 'interrupted');
+          assert.equal(commander.navigationManager.isNavigating(), false);
+          assert.equal(page.listenerCount?.(event), count);
+        } finally {
+          clearTimeout(timer);
+        }
+      });
+    }
+  );
+}