browser-commander 0.31.1 → 0.31.2

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.31.2
+
+### Patch Changes
+
+- 9f486af: Preserve native Playwright text selectors and CSS sibling positions. Resolve nonnative text matches to unique ancestor paths so interactions keep their intended target across Playwright, Puppeteer, and Selenium.
+
+  Retain sanitized engine failures alongside Chrome stderr in launch error messages. Identify attachment stages and optionally log their timing with verbose mode; wait for actual child exit before profile cleanup, and verify readiness, cleanup ownership, and fresh-profile startup on macOS in CI.
+
 ## 0.31.1
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "browser-commander",
-  "version": "0.31.1",
+  "version": "0.31.2",
   "description": "Universal browser automation library that supports Playwright, Puppeteer, and Selenium with a unified API",
   "main": "src/index.js",
   "bin": {

package/src/browser/connection-stage.js

@@ -0,0 +1,23 @@
+/** Identify attachment failures; optional logs contain stage names and timings. */
+export async function connectionStage(options, stage, work) {
+  const start = performance.now();
+  const report = (state) => {
+    if (options.verbose) {
+      console.log(
+        `Browser attachment ${stage} ${state} after ${Math.round(performance.now() - start)}ms`
+      );
+    }
+  };
+  report('started');
+  try {
+    const result = await work();
+    report('completed');
+    return result;
+  } catch (error) {
+    if (error && typeof error === 'object' && Object.isExtensible(error)) {
+      error.attachmentStage ??= stage;
+    }
+    report('failed');
+    throw error;
+  }
+}

package/src/browser/connector.js

@@ -1,4 +1,5 @@
 import { attachDownloads } from '../downloads/attach.js';
+import { connectionStage } from './connection-stage.js';
 import { connectWebDriver, launchWebDriver } from './webdriver.js';
 import {
   loadStorageState,
@@ -282,7 +283,9 @@ async function connectPlaywright({ options, loadPlaywright, storageState }) {
   const settings = buildPlaywrightConnectOptions(options);
   let browser;
   try {
-    browser = await chromium.connectOverCDP(endpoint, settings);
+    browser = await connectionStage(options, 'engine-connect', () =>
+      chromium.connectOverCDP(endpoint, settings)
+    );
   } catch (error) {
     if (
       settings.noDefaults !== undefined ||
@@ -291,21 +294,26 @@ async function connectPlaywright({ options, loadPlaywright, storageState }) {
     ) {
       throw error;
     }
-    browser = await chromium.connectOverCDP(endpoint, {
-      ...settings,
-      noDefaults: true,
-    });
+    browser = await connectionStage(options, 'engine-connect', () =>
+      chromium.connectOverCDP(endpoint, { ...settings, noDefaults: true })
+    );
   }
   try {
     const context = browser.contexts()[0];
     if (!context) {
       throw new Error('Connected Playwright browser has no default context');
     }
-    const page =
-      (await pickForegroundPage(context.pages(), options)) ??
-      (await context.newPage());
+    const page = await connectionStage(
+      options,
+      'page-selection',
+      async () =>
+        (await pickForegroundPage(context.pages(), options)) ??
+        (await context.newPage())
+    );
 
-    await restorePlaywrightStorageState({ context, storageState });
+    await connectionStage(options, 'storage-restore', () =>
+      restorePlaywrightStorageState({ context, storageState })
+    );
     return { browser, page, detach: browser.close?.bind(browser) };
   } catch (error) {
     await ignoreCleanup(() => browser.close?.());
@@ -316,15 +324,21 @@ async function connectPlaywright({ options, loadPlaywright, storageState }) {
 async function connectPuppeteer({ options, loadPuppeteer, storageState }) {
   const puppeteerModule = await loadPuppeteer();
   const puppeteer = puppeteerModule.default ?? puppeteerModule;
-  const browser = await puppeteer.connect(
-    buildPuppeteerConnectOptions(options)
+  const browser = await connectionStage(options, 'engine-connect', () =>
+    puppeteer.connect(buildPuppeteerConnectOptions(options))
   );
   try {
-    const page =
-      (await pickForegroundPage(await browser.pages(), options)) ??
-      (await browser.newPage());
+    const page = await connectionStage(
+      options,
+      'page-selection',
+      async () =>
+        (await pickForegroundPage(await browser.pages(), options)) ??
+        (await browser.newPage())
+    );
 
-    await restorePuppeteerStorageState({ page, storageState });
+    await connectionStage(options, 'storage-restore', () =>
+      restorePuppeteerStorageState({ page, storageState })
+    );
     return { browser, page, detach: browser.disconnect?.bind(browser) };
   } catch (error) {
     await ignoreCleanup(() => browser.disconnect?.());

package/src/browser/launch-diagnostics.js

@@ -7,10 +7,11 @@ export class BrowserLaunchError extends Error {
     exitCode = null,
     signal = null,
     stderrTail = '',
+    attachmentStage,
     cause,
   }) {
     super(
-      `Browser launch failed (${phase}: ${category}): ${stderrTail || cause?.message || ''}`,
+      `Browser launch failed (${phase}: ${category}): ${cause?.message || ''}${stderrTail ? `\nBrowser stderr:\n${stderrTail}` : ''}`,
       { cause }
     );
     this.name = 'BrowserLaunchError';
@@ -21,6 +22,7 @@ export class BrowserLaunchError extends Error {
       exitCode,
       signal,
       stderrTail,
+      ...(attachmentStage ? { attachmentStage } : {}),
     });
   }
 }
@@ -98,5 +100,6 @@ export function launchFailure(
     signal: browserProcess?.signalCode ?? null,
     stderrTail: scrub(browserProcess?.stderrTail ?? cause?.stderrTail ?? ''),
     cause: safeCause,
+    attachmentStage: cause?.attachmentStage,
   });
 }

package/src/core/engine-adapter.js

@@ -284,13 +284,6 @@ export class PlaywrightAdapter extends EngineAdapter {
   // ============================================================================
 
   createLocator(selector) {
-    // Handle :nth-of-type() pseudo-selectors which don't work in Playwright locators
-    const nthOfTypeMatch = selector.match(/^(.+):nth-of-type\((\d+)\)$/);
-    if (nthOfTypeMatch) {
-      const baseSelector = nthOfTypeMatch[1];
-      const index = parseInt(nthOfTypeMatch[2], 10) - 1; // Convert to 0-based
-      return this.page.locator(baseSelector).nth(index);
-    }
     return this.page.locator(selector);
   }
 

package/src/elements/locators.js

@@ -6,7 +6,7 @@ import {
 
 /**
  * Helper to create Playwright locator from selector string
- * Handles :nth-of-type() pseudo-selectors which don't work in Playwright locators
+ * Preserves native CSS and text selector semantics.
  * @param {Object} options - Configuration options
  * @param {Object} options.page - Browser page object
  * @param {string} options.selector - CSS selector
@@ -22,15 +22,6 @@ export function createPlaywrightLocator(options = {}) {
   const { page, selector } = options;
 
   requireSelector(selector);
-  // Check if selector has :nth-of-type(n) pattern
-  const nthOfTypeMatch = selector.match(/^(.+):nth-of-type\((\d+)\)$/);
-
-  if (nthOfTypeMatch) {
-    const baseSelector = nthOfTypeMatch[1];
-    const index = parseInt(nthOfTypeMatch[2], 10) - 1; // Convert to 0-based index
-    return page.locator(baseSelector).nth(index);
-  }
-
   return page.locator(selector);
 }
 

package/src/elements/selectors.js

@@ -4,6 +4,7 @@ import {
   recoverWaitError,
 } from '../core/navigation-safety.js';
 import { createPlaywrightLocator, requireSelector } from './locators.js';
+import { textSelectorInPage } from './text-selector.js';
 
 /**
  * Query single element
@@ -80,75 +81,18 @@ export async function findByText(options = {}) {
   }
 }
 
-/**
- * Check if a selector is a Playwright-specific text selector
- * @param {string} selector - The selector to check
- * @returns {boolean} - True if selector contains Playwright text pseudo-selectors
- */
-function isPlaywrightTextSelector(selector) {
-  if (typeof selector !== 'string') {
-    return false;
-  }
-  return selector.includes(':has-text(') || selector.includes(':text-is(');
-}
-
-/**
- * Split `base:<pseudo>("text")` into its base selector and text.
- *
- * String operations rather than a regular expression: the former
- * /^(.+?):has-text\("(.+?)"\)$/ backtracked quadratically on long selectors
- * that do not match (CodeQL js/polynomial-redos). The base is everything before
- * the first `:<pseudo>("`, as the lazy `(.+?)` made it; base and text must be
- * non-empty.
- * @param {string} selector - Selector to split
- * @param {string} pseudo - Pseudo-class name, e.g. 'has-text'
- * @returns {{baseSelector: string, text: string}|null} - Parts, or null
- */
-function splitTextPseudo(selector, pseudo) {
-  const open = `:${pseudo}("`;
-  const start = selector.indexOf(open, 1);
-  if (start === -1 || !selector.endsWith('")')) {
-    return null;
-  }
-  const text = selector.slice(start + open.length, -2);
-  if (!text) {
-    return null;
-  }
-  return { baseSelector: selector.slice(0, start), text };
-}
-
-/**
- * Parse a Playwright text selector to extract base selector and text
- * @param {string} selector - Playwright text selector like 'a:has-text("text")'
- * @returns {Object|null} - { baseSelector, text, exact } or null if not parseable
- */
-function parsePlaywrightTextSelector(selector) {
-  // Match patterns like 'a:has-text("text")' or 'button:text-is("exact text")'
-  const hasText = splitTextPseudo(selector, 'has-text');
-  if (hasText) {
-    return { ...hasText, exact: false };
-  }
-
-  const textIs = splitTextPseudo(selector, 'text-is');
-  if (textIs) {
-    return { ...textIs, exact: true };
-  }
-
-  return null;
-}
-
 /**
  * Normalize selector to handle both Puppeteer and Playwright text selectors
- * Converts engine-specific text selectors to valid CSS selectors for browser context
+ * Preserves native Playwright strings; resolves text objects to unique CSS paths.
  *
  * @param {Object} options - Configuration 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 text selector object
- * @returns {Promise<string|null>} - Valid CSS selector or null if not found
+ * @returns {Promise<string|null>} - Native selector, unique CSS path, or null
  */
 export async function normalizeSelector(options = {}) {
-  const { page, engine, selector } = options;
+  const { page, selector } = options;
 
   requireSelector(selector);
 
@@ -171,59 +115,6 @@ export async function normalizeSelector(options = {}) {
     return null;
   }
 
-  // Handle Playwright text selectors (strings containing :has-text or :text-is)
-  // These are valid for Playwright's locator API but NOT for document.querySelectorAll
-  if (
-    typeof selector === 'string' &&
-    engine === 'playwright' &&
-    isPlaywrightTextSelector(selector)
-  ) {
-    const parsed = parsePlaywrightTextSelector(selector);
-    if (!parsed) {
-      // Could not parse, return as-is and hope for the best
-      return selector;
-    }
-
-    try {
-      // Use page.evaluate to find matching element and generate a valid CSS selector
-      const result = await page.evaluate(({ baseSelector, text, exact }) => {
-        const elements = Array.from(document.querySelectorAll(baseSelector));
-        const matchingElement = elements.find((el) => {
-          const elementText = el.textContent.trim();
-          return exact ? elementText === text : elementText.includes(text);
-        });
-
-        if (!matchingElement) {
-          return null;
-        }
-
-        // Generate a unique selector using data-qa or nth-of-type
-        const dataQa = matchingElement.getAttribute('data-qa');
-        if (dataQa) {
-          return `[data-qa="${dataQa}"]`;
-        }
-
-        // Use nth-of-type as fallback
-        const tagName = matchingElement.tagName.toLowerCase();
-        const siblings = Array.from(
-          matchingElement.parentElement.children
-        ).filter((el) => el.tagName.toLowerCase() === tagName);
-        const index = siblings.indexOf(matchingElement);
-        return `${tagName}:nth-of-type(${index + 1})`;
-      }, parsed);
-
-      return result;
-    } catch (error) {
-      if (isNavigationError(error)) {
-        console.log(
-          '⚠️  Navigation detected during normalizeSelector (Playwright), returning null'
-        );
-        return null;
-      }
-      throw error;
-    }
-  }
-
   // Plain string selector - return as-is
   if (typeof selector === 'string') {
     return selector;
@@ -233,36 +124,11 @@ export async function normalizeSelector(options = {}) {
   if (selector._isPuppeteerTextSelector) {
     try {
       // Find element by text and generate a unique selector
-      const result = await page.evaluate(
-        (baseSelector, text, exact) => {
-          const elements = Array.from(document.querySelectorAll(baseSelector));
-          const matchingElement = elements.find((el) => {
-            const elementText = el.textContent.trim();
-            return exact ? elementText === text : elementText.includes(text);
-          });
-
-          if (!matchingElement) {
-            return null;
-          }
-
-          // Generate a unique selector using data-qa or nth-of-type
-          const dataQa = matchingElement.getAttribute('data-qa');
-          if (dataQa) {
-            return `[data-qa="${dataQa}"]`;
-          }
-
-          // Use nth-of-type as fallback
-          const tagName = matchingElement.tagName.toLowerCase();
-          const siblings = Array.from(
-            matchingElement.parentElement.children
-          ).filter((el) => el.tagName.toLowerCase() === tagName);
-          const index = siblings.indexOf(matchingElement);
-          return `${tagName}:nth-of-type(${index + 1})`;
-        },
-        selector.baseSelector,
-        selector.text,
-        selector.exact
-      );
+      const result = await page.evaluate(textSelectorInPage, {
+        baseSelector: selector.baseSelector,
+        text: selector.text,
+        exact: selector.exact,
+      });
 
       return result;
     } catch (error) {
@@ -296,6 +162,7 @@ export function withTextSelectorSupport(fn, engine, page) {
     // selenium)
     if (
       engine !== 'playwright' &&
+      selector &&
       typeof selector === 'object' &&
       selector._isPuppeteerTextSelector
     ) {
@@ -305,18 +172,6 @@ export function withTextSelectorSupport(fn, engine, page) {
       }
     }
 
-    // Normalize Playwright text selectors (string format with :has-text or :text-is)
-    if (
-      engine === 'playwright' &&
-      typeof selector === 'string' &&
-      isPlaywrightTextSelector(selector)
-    ) {
-      selector = await normalizeSelector({ page, engine, selector });
-      if (!selector) {
-        throw new Error('Element with specified text not found');
-      }
-    }
-
     return fn({ ...options, selector });
   };
 }

package/src/elements/text-selector.js

@@ -0,0 +1,23 @@
+/** Resolve a text match to an unambiguous CSS path without changing the DOM. */
+export function textSelectorInPage({ baseSelector, text, exact }) {
+  const matching = Array.from(document.querySelectorAll(baseSelector)).find(
+    (element) => {
+      const content = element.textContent.trim();
+      return exact ? content === text : content.includes(text);
+    }
+  );
+  if (!matching) {
+    return null;
+  }
+  const steps = [];
+  for (let node = matching; node; node = node.parentElement) {
+    const siblings = Array.from(node.parentElement?.children ?? []).filter(
+      (sibling) => sibling.localName === node.localName
+    );
+    const index = siblings.indexOf(node) + 1;
+    steps.unshift(
+      `${window.CSS.escape(node.localName)}:nth-of-type(${Math.max(1, index)})`
+    );
+  }
+  return steps.join(' > ');
+}

package/src/utilities/subprocess.js

@@ -177,6 +177,7 @@ export class ManagedProcess {
     this.stdout = new OutputChannel();
     this.stderr = new OutputChannel();
     this.exitListeners = new Set();
+    this.termination = null;
     runner.on('stdout', (chunk) => {
       if (forwardOutput) {
         process.stdout.write(chunk);
@@ -196,7 +197,15 @@ export class ManagedProcess {
         this.spawnError = error;
         return { code: error?.code ?? 1 };
       })
-      .then((result) => {
+      .then(async (result) => {
+        const actualExit = await this.termination;
+        if (actualExit) {
+          result = {
+            ...result,
+            code: actualExit.code ?? result.code,
+            signal: actualExit.signal,
+          };
+        }
         this.exitCode = typeof result.code === 'number' ? result.code : 1;
         this.signalCode = result.signal ?? null;
         for (const listener of this.exitListeners) {
@@ -233,10 +242,36 @@ export class ManagedProcess {
    * @returns {boolean} Whether a running process was signalled
    */
   kill(signal) {
-    if (this.exitCode !== null) {
+    if (this.exitCode !== null || this.termination) {
       return false;
     }
+    // command-stream resolves cancellation immediately and removes the child's
+    // listeners. Retain its handle and observe the real exit after signalling,
+    // so launchers cannot delete profiles while Chrome still writes to them.
+    const child = this.runner.child;
+    let resolveExit;
+    if (child?.pid) {
+      this.termination = new Promise((resolve) => {
+        resolveExit = resolve;
+      });
+    }
     this.runner.kill(signal);
+    if (resolveExit) {
+      if (child.exited) {
+        child.exited.then((code) =>
+          resolveExit({ code, signal: child.signalCode ?? null })
+        );
+      } else if (
+        Number.isInteger(child.exitCode) ||
+        typeof child.signalCode === 'string'
+      ) {
+        resolveExit({ code: child.exitCode, signal: child.signalCode });
+      } else {
+        child.once('exit', (code, exitSignal) =>
+          resolveExit({ code, signal: exitSignal })
+        );
+      }
+    }
     return true;
   }
 }

package/tests/e2e/selector-identity.e2e.test.js

@@ -0,0 +1,104 @@
+import assert from 'node:assert/strict';
+import { it } from 'node:test';
+import { makeBrowserCommander } from '../../src/factory.js';
+import { createEngineAdapter } from '../../src/core/engine-adapter.js';
+import { launchE2EBrowser } from '../helpers/e2e-browser.js';
+
+for (const engine of ['playwright', 'puppeteer', 'selenium']) {
+  it(
+    `${engine} keeps scoped text selectors on the intended element`,
+    { skip: process.env.RUN_E2E !== 'true', timeout: 60000 },
+    async () => {
+      const session = await launchE2EBrowser({ engine });
+      const commander = makeBrowserCommander({
+        page: session.page,
+        verbose: false,
+        debug: false,
+        enableNetworkTracking: false,
+        enableNavigationManager: false,
+      });
+      try {
+        await session.page.setContent(`
+          <nav><button>A</button><button data-qa='duplicate'
+            onclick="window.clicked='nav-2'">B</button></nav>
+          <div class="parent"><section><button>A</button>
+            <button data-qa='duplicate' data-target='B'
+              onclick="window.clicked='B'; this.setAttribute('aria-pressed','true')">B</button>
+            <textarea>Edit</textarea>
+          </section></div>`);
+        for (const exact of [false, true]) {
+          const selector = await commander.findByText({
+            selector: '.parent button',
+            text: 'B',
+            exact,
+          });
+          assert.equal(
+            await commander.getAttribute({
+              selector,
+              attribute: 'data-target',
+            }),
+            'B'
+          );
+          assert.equal(await commander.textContent({ selector }), 'B');
+          assert.equal(await commander.isVisible({ selector }), true);
+          assert.equal(await commander.isEnabled({ selector }), true);
+          await commander.clickButton({ selector, verify: false });
+          assert.equal(await session.page.evaluate(() => window.clicked), 'B');
+        }
+        const editable = await commander.findByText({
+          selector: '.parent textarea',
+          text: 'Edit',
+          exact: true,
+        });
+        await commander.fillTextArea({
+          selector: editable,
+          text: 'Changed',
+          checkEmpty: false,
+          simulateTyping: false,
+        });
+        assert.equal(
+          await session.page.evaluate(
+            () => document.querySelector('.parent textarea').value
+          ),
+          'Changed'
+        );
+      } finally {
+        await commander.destroy();
+        await session.cleanup();
+      }
+    }
+  );
+}
+
+it(
+  'Playwright preserves CSS sibling position across multiple parents',
+  { skip: process.env.RUN_E2E !== 'true', timeout: 60000 },
+  async () => {
+    const session = await launchE2EBrowser({ engine: 'playwright' });
+    const commander = makeBrowserCommander({
+      page: session.page,
+      debug: false,
+      enableNetworkTracking: false,
+      enableNavigationManager: false,
+    });
+    try {
+      await session.page.setContent(
+        '<section><span></span><button>A</button></section><section><button>B</button><button>C</button></section>'
+      );
+      const matches = await commander.querySelectorAll({
+        selector: 'section button:nth-of-type(2)',
+      });
+      assert.equal(matches.length, 1);
+      assert.equal(await matches[0].textContent(), 'C');
+      const adapter = createEngineAdapter(session.page, 'playwright');
+      const adapterMatches = await adapter.querySelectorAll(
+        'section button:nth-of-type(2)'
+      );
+      assert.equal(adapterMatches.length, 1);
+      assert.equal(await adapterMatches[0].textContent(), 'C');
+    } finally {
+      await commander.destroy();
+      await session.cleanup();
+    }
+  }
+);

package/tests/e2e/startup-readiness.e2e.test.js

@@ -0,0 +1,95 @@
+import assert from 'node:assert/strict';
+import { it } from 'node:test';
+import { access, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { launchBrowser } from '../../src/browser/launcher.js';
+import { launchAndConnectRealBrowserWithDependencies } from '../../src/browser/real-browser.js';
+import { startProcess } from '../../src/utilities/subprocess.js';
+import { CHROME_LAUNCH_OPTIONS } from '../helpers/e2e-browser.js';
+
+it(
+  'fresh-profile Chrome starts repeatedly with session persistence',
+  { skip: process.env.RUN_E2E !== 'true', timeout: 90000 },
+  async () => {
+    const root = await mkdtemp(path.join(os.tmpdir(), 'bc-startup-smoke-'));
+    try {
+      for (let attempt = 0; attempt < 3; attempt++) {
+        const userDataDir = path.join(root, `profile-${attempt}`);
+        const session = await launchBrowser({
+          debug: false,
+          channel: 'chrome',
+          headless: true,
+          userDataDir,
+          persistSessionCookies: true,
+          ...CHROME_LAUNCH_OPTIONS,
+        });
+        try {
+          assert.equal(await session.page.evaluate(() => 2 + 2), 4);
+        } finally {
+          await session.close();
+        }
+        assert.notEqual(session.browserProcess.exitCode, null);
+        await access(userDataDir);
+      }
+    } finally {
+      await rm(root, { recursive: true, force: true });
+    }
+  }
+);
+
+it(
+  'failure after real DevTools readiness leaves another Chrome and caller profile intact',
+  { skip: process.env.RUN_E2E !== 'true', timeout: 90000 },
+  async () => {
+    const sibling = await launchBrowser({
+      debug: false,
+      headless: true,
+      ...CHROME_LAUNCH_OPTIONS,
+    });
+    const root = await mkdtemp(path.join(os.tmpdir(), 'bc-owned-startup-'));
+    const marker = path.join(root, 'keep.txt');
+    await writeFile(marker, 'caller profile');
+    try {
+      for (const suppliedProfile of [false, true]) {
+        let child, profile;
+        await assert.rejects(
+          () =>
+            launchAndConnectRealBrowserWithDependencies(
+              {
+                debug: false,
+                headless: true,
+                persistSessionCookies: suppliedProfile,
+                ...(suppliedProfile ? { userDataDir: root } : {}),
+                ...CHROME_LAUNCH_OPTIONS,
+              },
+              {
+                spawnBrowser: (file, args, options) => {
+                  profile = args
+                    .find((arg) => arg.startsWith('--user-data-dir='))
+                    .slice('--user-data-dir='.length);
+                  child = startProcess(file, args, { env: options.env });
+                  return child;
+                },
+                connect: async () => {
+                  throw new Error(
+                    'Injected attachment timeout after endpoint readiness'
+                  );
+                },
+              }
+            ),
+          /Injected attachment timeout/
+        );
+        assert.notEqual(child.exitCode, null);
+        assert.equal(await sibling.page.evaluate(() => 2 + 2), 4);
+        assert.equal(await readFile(marker, 'utf8'), 'caller profile');
+        if (!suppliedProfile) {
+          await assert.rejects(() => access(profile), /ENOENT/);
+        }
+      }
+    } finally {
+      await sibling.close();
+      await rm(root, { recursive: true, force: true });
+    }
+  }
+);

package/tests/unit/browser/connection-stage.test.js

@@ -0,0 +1,74 @@
+import assert from 'node:assert/strict';
+import { it } from 'node:test';
+import { connectBrowserWithDependencies } from '../../../src/browser/connector.js';
+
+it('identifies an engine attachment failure and logs stage timing only when verbose', async (t) => {
+  const logs = [];
+  t.mock.method(console, 'log', (message) => logs.push(message));
+  for (const verbose of [false, true]) {
+    logs.length = 0;
+    await assert.rejects(
+      () =>
+        connectBrowserWithDependencies(
+          { cdpEndpoint: 'http://127.0.0.1:9222', verbose, timeout: 123 },
+          {
+            loadPlaywright: async () => ({
+              chromium: {
+                connectOverCDP: async (_endpoint, options) => {
+                  assert.equal(options.timeout, 123);
+                  throw new Error('connectOverCDP: Timeout 123ms exceeded');
+                },
+              },
+            }),
+          }
+        ),
+      (error) => {
+        assert.equal(error.attachmentStage, 'engine-connect');
+        return true;
+      }
+    );
+    if (verbose) {
+      assert.ok(logs.some((message) => /engine-connect started/.test(message)));
+      assert.ok(
+        logs.some((message) =>
+          /engine-connect failed after \d+ms/.test(message)
+        )
+      );
+    } else {
+      assert.deepEqual(logs, []);
+    }
+  }
+});
+
+it('distinguishes page selection from engine connection and detaches on failure', async () => {
+  let detached = 0;
+  const browser = {
+    contexts: () => [
+      {
+        pages: () => [],
+        newPage: async () => {
+          throw new Error('newPage timeout');
+        },
+      },
+    ],
+    close: async () => {
+      detached++;
+    },
+  };
+  await assert.rejects(
+    () =>
+      connectBrowserWithDependencies(
+        { cdpEndpoint: 'http://127.0.0.1:9222' },
+        {
+          loadPlaywright: async () => ({
+            chromium: { connectOverCDP: async () => browser },
+          }),
+        }
+      ),
+    (error) => {
+      assert.equal(error.attachmentStage, 'page-selection');
+      return true;
+    }
+  );
+  assert.equal(detached, 1);
+});

package/tests/unit/browser/launch-diagnostics.test.js

@@ -1,6 +1,28 @@
 // feature-parity: launch.diagnostics@native-typed
 import { it } from 'node:test';
-import { redactLaunchEvidence } from '../../../src/browser/launch-diagnostics.js';
+import {
+  launchFailure,
+  redactLaunchEvidence,
+} from '../../../src/browser/launch-diagnostics.js';
+
+it('retains the attachment timeout alongside incidental Chrome stderr', () => {
+  const error = launchFailure(
+    new Error(
+      'connectOverCDP: Timeout 30000ms exceeded; <ws connected> ws://127.0.0.1:9222/devtools/browser/private'
+    ),
+    {
+      phase: 'connect',
+      browserProcess: {
+        exitCode: null,
+        stderrTail:
+          'DevTools listening on ws://127.0.0.1:9222/devtools/browser/private\nCVDisplayLinkCreateWithCGDisplay failed',
+      },
+    }
+  );
+  assert.match(error.message, /connectOverCDP: Timeout 30000ms exceeded/);
+  assert.match(error.message, /CVDisplayLinkCreateWithCGDisplay failed/);
+  assert.doesNotMatch(error.message, /devtools|private|127\.0\.0\.1/);
+});
 
 it('diagnostics scrub URL credentials and queries and bound multibyte evidence', () => {
   const redacted = redactLaunchEvidence(

package/tests/unit/browser/startup-readiness.test.js

@@ -0,0 +1,129 @@
+import assert from 'node:assert/strict';
+import { PassThrough } from 'node:stream';
+import * as fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { it } from 'node:test';
+import {
+  launchAndConnectRealBrowserWithDependencies,
+  waitForCdpEndpoint,
+} from '../../../src/browser/real-browser.js';
+
+it(
+  'waits for HTTP readiness after DevTools is announced, despite incidental warnings',
+  { timeout: 5000 },
+  async () => {
+    const stderr = new PassThrough();
+    stderr.write(
+      'DevTools listening on ws://127.0.0.1:9777/devtools/browser/ours\nCVDisplayLinkCreateWithCGDisplay failed\n'
+    );
+    let probes = 0;
+    const endpoint = await waitForCdpEndpoint({
+      remoteDebuggingPort: 9777,
+      userDataDir: '/nonexistent',
+      browserProcess: { exitCode: null, stderr },
+      timeout: 2000,
+      fetchImplementation: async () => {
+        probes++;
+        if (probes === 1) {
+          throw new Error('ECONNREFUSED');
+        }
+        if (probes === 2) {
+          return { ok: false };
+        }
+        return {
+          ok: true,
+          json: async () => ({
+            webSocketDebuggerUrl: 'ws://127.0.0.1:9777/devtools/browser/ours',
+          }),
+        };
+      },
+    });
+    assert.equal(endpoint, 'http://127.0.0.1:9777');
+    assert.equal(probes, 3);
+  }
+);
+
+for (const suppliedProfile of [false, true]) {
+  it(
+    `attachment timeout cleans only owned state (supplied profile: ${suppliedProfile})`,
+    { timeout: 5000 },
+    async () => {
+      const root = await fs.mkdtemp(path.join(os.tmpdir(), 'bc-startup-test-'));
+      const marker = path.join(root, 'keep.txt');
+      await fs.writeFile(marker, 'caller owned');
+      let profile;
+      let kills = 0;
+      let launches = 0;
+      const child = {
+        exitCode: null,
+        stderrTail:
+          'DevTools listening on ws://127.0.0.1:9777/devtools/browser/ours\nCVDisplayLinkCreateWithCGDisplay failed',
+        kill: () => {
+          kills++;
+          child.exitCode = 143;
+        },
+      };
+      try {
+        await assert.rejects(
+          () =>
+            launchAndConnectRealBrowserWithDependencies(
+              {
+                ...(suppliedProfile ? { userDataDir: root } : {}),
+                debug: false,
+                headless: true,
+                persistSessionCookies: suppliedProfile,
+                timeout: 123,
+                closeTimeout: 50,
+              },
+              {
+                resolveExecutable: async () => '/opt/google/chrome',
+                reservePort: async () => 9777,
+                spawnBrowser: (_file, args) => {
+                  launches++;
+                  profile = args
+                    .find((arg) => arg.startsWith('--user-data-dir='))
+                    .slice('--user-data-dir='.length);
+                  return child;
+                },
+                waitForEndpoint: async () => 'http://127.0.0.1:9777',
+                connect: async (options) => {
+                  assert.equal(options.timeout, 123);
+                  const error = new Error(
+                    'connectOverCDP: Timeout 123ms exceeded'
+                  );
+                  error.attachmentStage = 'engine-connect';
+                  throw error;
+                },
+              }
+            ),
+          (error) => {
+            assert.equal(error.phase, 'connect');
+            assert.equal(error.category, 'startup_timeout');
+            assert.equal(error.attachmentStage, 'engine-connect');
+            assert.match(
+              error.message,
+              /connectOverCDP: Timeout 123ms exceeded/
+            );
+            assert.match(error.message, /CVDisplayLink/);
+            return true;
+          }
+        );
+        assert.equal(kills, 1);
+        assert.equal(launches, 1);
+        assert.equal(await fs.readFile(marker, 'utf8'), 'caller owned');
+        if (!suppliedProfile) {
+          await assert.rejects(
+            () => fs.readFile(path.join(profile, 'First Run')),
+            /ENOENT/
+          );
+        }
+      } finally {
+        await fs.rm(root, { recursive: true, force: true });
+        if (!suppliedProfile && profile) {
+          await fs.rm(profile, { recursive: true, force: true });
+        }
+      }
+    }
+  );
+}

package/tests/unit/elements/selector-identity.test.js

@@ -0,0 +1,50 @@
+import assert from 'node:assert/strict';
+import { it } from 'node:test';
+import {
+  normalizeSelector,
+  withTextSelectorSupport,
+} from '../../../src/elements/selectors.js';
+import { createPlaywrightLocator } from '../../../src/elements/locators.js';
+import { PlaywrightAdapter } from '../../../src/core/engine-adapter.js';
+
+it('keeps native Playwright text selectors without an eager DOM lookup', async () => {
+  const selector = '.parent button:has-text("B")';
+  const page = {
+    evaluate: () => {
+      throw new Error('unexpected DOM lookup');
+    },
+  };
+  assert.equal(
+    await normalizeSelector({ page, engine: 'playwright', selector }),
+    selector
+  );
+  const wrapped = withTextSelectorSupport(
+    async ({ selector }) => selector,
+    'playwright',
+    page
+  );
+  assert.equal(await wrapped({ selector }), selector);
+});
+
+for (const [name, create] of [
+  [
+    'locator helper',
+    (page, selector) => createPlaywrightLocator({ page, selector }),
+  ],
+  [
+    'shared adapter',
+    (page, selector) => new PlaywrightAdapter(page).createLocator(selector),
+  ],
+]) {
+  it(`preserves CSS sibling semantics in the Playwright ${name}`, () => {
+    const selector = 'section button:nth-of-type(2)';
+    const expected = {};
+    const page = {
+      locator: (received) => {
+        assert.equal(received, selector);
+        return expected;
+      },
+    };
+    assert.equal(create(page, selector), expected);
+  });
+}

package/tests/unit/elements/selectors.test.js

@@ -205,32 +205,18 @@ describe('selectors', () => {
       return page;
     }
 
-    it('splits :has-text into base selector and text', async () => {
-      const page = capturingPage();
-      await normalizeSelector({
-        page,
-        engine: 'playwright',
-        selector: 'nav a:has-text("Sign in")',
-      });
-      assert.deepStrictEqual(page.parsed, {
-        baseSelector: 'nav a',
-        text: 'Sign in',
-        exact: false,
-      });
-    });
-
-    it('splits :text-is into base selector and exact text', async () => {
-      const page = capturingPage();
-      await normalizeSelector({
-        page,
-        engine: 'playwright',
-        selector: 'button:text-is("Submit")',
-      });
-      assert.deepStrictEqual(page.parsed, {
-        baseSelector: 'button',
-        text: 'Submit',
-        exact: true,
-      });
+    it('preserves native text selectors without an eager lookup', async () => {
+      for (const selector of [
+        'nav a:has-text("Sign in")',
+        'button:text-is("Submit")',
+      ]) {
+        const page = capturingPage();
+        assert.equal(
+          await normalizeSelector({ page, engine: 'playwright', selector }),
+          selector
+        );
+        assert.equal(page.parsed, null);
+      }
     });
 
     it('returns an unparseable selector unchanged', async () => {

package/tests/unit/scripts/ci-timeout-budgets.test.js

@@ -196,6 +196,7 @@ describe('CI execution budgets', () => {
     assert.deepEqual(budgeted, [
       'docs.yml build-docs Rust API docs',
       'js.yml test Node.js test suite',
+      'js.yml test macOS Chrome startup regression',
       'parity.yml cli CLI and API coverage suites',
       'parity.yml cli Cross-language CLI contract',
       'parity.yml cli Rust CLI build',

package/tests/unit/utilities/subprocess.test.js

@@ -97,6 +97,39 @@ describe('startProcess', { timeout: 10000 }, () => {
     const exitCode = await child.exited;
     assert.notEqual(exitCode, 0);
   });
+
+  it(
+    'reports exit only after a signalled child finishes its profile writes',
+    { skip: process.platform === 'win32' && 'Windows termination is forceful' },
+    async (t) => {
+      const directory = await fs.mkdtemp(
+        path.join(tmpdir(), 'bc-shutdown-172-')
+      );
+      const marker = path.join(directory, 'flushed');
+      const child = startProcess(
+        node,
+        [repoPath('experiments', 'issue-172', 'delayed-shutdown.mjs'), marker],
+        { killGrace: 1000 }
+      );
+      const processHandle = child.runner.child;
+      t.after(async () => {
+        if (
+          processHandle.exitCode === null &&
+          processHandle.signalCode === null
+        ) {
+          processHandle.kill('SIGKILL');
+          await new Promise((resolve) => processHandle.once('exit', resolve));
+        }
+        await fs.rm(directory, { recursive: true, force: true });
+      });
+      await new Promise((resolve) => child.stdout.on('data', resolve));
+      child.kill();
+      await child.exited;
+      assert.equal(await fs.readFile(marker, 'utf8'), 'flushed');
+      assert.equal(processHandle.exitCode, 0);
+      assert.equal(child.exitCode, 0);
+    }
+  );
 });
 
 describe(