browser-commander 0.31.1 → 0.32.0

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/interruption.test.js

@@ -0,0 +1,182 @@
+import * as fs from 'node:fs/promises';
+import path from 'node:path';
+import { tmpdir } from 'node:os';
+import assert from 'node:assert';
+import { describe, it } from 'node:test';
+import {
+  interruptionMode,
+  startProcess,
+} from '../../../src/utilities/subprocess.js';
+import { repoPath } from '../../helpers/repo.js';
+import { waitForFileText } from '../../helpers/temp-directory.js';
+
+// feature-parity: process.interruption@native-typed
+
+const node = process.execPath;
+const delayedShutdown = repoPath(
+  'experiments',
+  'issue-172',
+  'delayed-shutdown.mjs'
+);
+const unixOnly = {
+  timeout: 15000,
+  skip:
+    process.platform === 'win32' &&
+    'Command Stream only creates separate process groups on Unix',
+};
+
+function isAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    if (error.code === 'ESRCH') {
+      return false;
+    }
+    throw error;
+  }
+}
+
+function forceKill(pid) {
+  if (pid && isAlive(pid)) {
+    process.kill(pid, 'SIGKILL');
+  }
+}
+
+async function tempDirectory(t, prefix) {
+  const directory = await fs.mkdtemp(path.join(tmpdir(), prefix));
+  t.after(() => fs.rm(directory, { recursive: true, force: true }));
+  return directory;
+}
+
+/**
+ * Run an embedding supervisor that interrupts itself, keeps its child from
+ * its own SIGINT handler, and exits. Returns whether the child survived.
+ */
+async function childSurvivesSupervisorInterrupt(t, mode) {
+  const directory = await tempDirectory(t, 'bc-interrupt-174-');
+  const pidFile = path.join(directory, 'pid');
+  const supervisor = startProcess(node, [
+    repoPath('experiments', 'issue-174', 'sigint-supervisor.mjs'),
+    mode,
+    pidFile,
+  ]);
+  assert.equal(await supervisor.exited, 130, supervisor.stderrTail);
+  const pid = Number(await fs.readFile(pidFile, 'utf8'));
+  t.after(() => forceKill(pid));
+  assert.ok(pid > 0);
+  await new Promise((resolve) => setTimeout(resolve, 300));
+  return isAlive(pid);
+}
+
+describe('interruption ownership (issue #174)', unixOnly, () => {
+  it('forwards SIGINT to the child by default, before the embedder can keep it', async (t) => {
+    assert.equal(await childSurvivesSupervisorInterrupt(t, 'managed'), false);
+    assert.equal(
+      await childSurvivesSupervisorInterrupt(t, 'detach-in-handler'),
+      false
+    );
+  });
+
+  it("leaves SIGINT to the embedder's handler with interruption: 'caller'", async (t) => {
+    assert.equal(await childSurvivesSupervisorInterrupt(t, 'caller'), true);
+  });
+
+  it('keeps streaming output and reporting the exit code for a caller-owned child', async () => {
+    const child = startProcess(
+      node,
+      [
+        '-e',
+        'setTimeout(()=>{process.stderr.write("hello\\n");process.exit(4)},100)',
+      ],
+      { interruption: 'caller' }
+    );
+    assert.equal(child.interruption, 'caller');
+    let stderr = '';
+    child.stderr.on('data', (chunk) => {
+      stderr += chunk;
+    });
+    assert.equal(await child.exited, 4);
+    assert.equal(stderr, 'hello\n');
+    assert.equal(child.kill(), false);
+  });
+
+  it('kill() still awaits the actual exit of a caller-owned child', async (t) => {
+    const directory = await tempDirectory(t, 'bc-caller-kill-174-');
+    const marker = path.join(directory, 'flushed');
+    const child = startProcess(node, [delayedShutdown, marker], {
+      interruption: 'caller',
+      killGrace: 1000,
+    });
+    t.after(() => forceKill(child.pid));
+    await new Promise((resolve) => child.stdout.on('data', resolve));
+    assert.equal(child.kill(), true);
+    assert.equal(await child.exited, 0);
+    assert.equal(await fs.readFile(marker, 'utf8'), 'flushed');
+    assert.equal(isAlive(child.pid), false);
+  });
+
+  it('escalates to SIGKILL when a caller-owned child ignores SIGTERM', async (t) => {
+    const child = startProcess(
+      node,
+      [
+        '-e',
+        'process.on("SIGTERM",()=>{});process.stdout.write("ready");setInterval(()=>{},1000)',
+      ],
+      { interruption: 'caller', killGrace: 200 }
+    );
+    t.after(() => forceKill(child.pid));
+    await new Promise((resolve) => child.stdout.on('data', resolve));
+    child.kill();
+    assert.equal(await child.exited, 128 + 9);
+    assert.equal(child.signalCode, 'SIGKILL');
+  });
+
+  it('detach() lets the supervisor end while the exact child keeps running', async (t) => {
+    const directory = await tempDirectory(t, 'bc-detach-174-');
+    const marker = path.join(directory, 'survived');
+    const launcher = startProcess(node, [
+      repoPath('experiments', 'issue-174', 'detach-launcher.mjs'),
+      marker,
+    ]);
+    let output = '';
+    launcher.stdout.on('data', (chunk) => {
+      output += chunk;
+    });
+    assert.equal(await launcher.exited, 0, launcher.stderrTail);
+    const { pid, detached } = JSON.parse(output);
+    t.after(() => forceKill(pid));
+    assert.equal(detached, true);
+    assert.equal(isAlive(pid), true);
+    assert.equal(
+      await waitForFileText(marker, 'survived'),
+      true,
+      'detached child did not outlive its supervisor'
+    );
+  });
+
+  it('detach() is idempotent and a detached child can still be stopped', async () => {
+    const child = startProcess(node, ['-e', 'setInterval(()=>{},1000)'], {
+      killGrace: 200,
+    });
+    await new Promise((resolve) => setTimeout(resolve, 100));
+    assert.equal(child.detach(), true);
+    assert.equal(child.detach(), true);
+    assert.equal(child.detached, true);
+    assert.equal(child.kill(), true);
+    assert.equal(await child.exited, 128 + 15);
+    assert.equal(child.detach(), false);
+  });
+});
+
+describe('interruptionMode', () => {
+  it('defaults to managed and rejects unknown modes', () => {
+    assert.equal(interruptionMode(), 'managed');
+    assert.equal(interruptionMode('caller'), 'caller');
+    assert.throws(() => interruptionMode('detached'), TypeError);
+    assert.throws(
+      () => startProcess(node, [], { interruption: 'none' }),
+      /interruption must be one of managed, caller/
+    );
+  });
+});

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

@@ -9,6 +9,7 @@ import {
   startProcess,
 } from '../../../src/utilities/subprocess.js';
 import { repoPath } from '../../helpers/repo.js';
+import { waitForFileText } from '../../helpers/temp-directory.js';
 
 const node = process.execPath;
 
@@ -97,6 +98,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(
@@ -140,19 +174,11 @@ describe(
       assert.equal(await launcher.exited, 0, launcher.stderrTail);
       assert.ok(pid > 0);
       await assert.rejects(fs.readFile(marker), { code: 'ENOENT' });
-      const deadline = Date.now() + 5000;
-      while (Date.now() < deadline) {
-        try {
-          assert.equal(await fs.readFile(marker, 'utf8'), 'survived');
-          return;
-        } catch (error) {
-          if (error.code !== 'ENOENT') {
-            throw error;
-          }
-          await new Promise((resolve) => setTimeout(resolve, 50));
-        }
-      }
-      assert.fail('detached child did not survive the launcher exit');
+      assert.equal(
+        await waitForFileText(marker, 'survived'),
+        true,
+        'detached child did not survive the launcher exit'
+      );
     });
   }
 );