@wdio/nightwatch-devtools 1.5.1 → 1.7.0

package/README.md

@@ -8,6 +8,46 @@ npm install @wdio/nightwatch-devtools
 
 ---
 
+## Quick Start
+
+**1. Install the package** in your Nightwatch project:
+
+```bash
+npm install @wdio/nightwatch-devtools
+```
+
+**2. Wire the plugin into your Nightwatch config** via the `globals` field:
+
+```javascript
+// nightwatch.conf.cjs
+const nightwatchDevtools = require('@wdio/nightwatch-devtools').default
+
+module.exports = {
+  src_folders: ['tests'],
+
+  test_settings: {
+    default: {
+      desiredCapabilities: {
+        browserName: 'chrome',
+        // Required for network request capture
+        'goog:loggingPrefs': { performance: 'ALL' }
+      },
+      globals: nightwatchDevtools({ port: 3000 })
+    }
+  }
+}
+```
+
+**3. Run your tests as normal** — the DevTools UI opens automatically in a new browser window:
+
+```bash
+nightwatch
+```
+
+No changes to your test files are needed.
+
+---
+
 ## Setup
 
 ### Standard Nightwatch (mocha-style)
@@ -76,15 +116,9 @@ module.exports = {
 
 ---
 
-## Configuration Options
+## Configuration
 
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `port` | `number` | `3000` | Port for the DevTools backend server. Auto-incremented if already in use. |
-| `hostname` | `string` | `'localhost'` | Hostname the backend server binds to. |
-| `screencast` | `ScreencastOptions` | `{ enabled: false }` | Session video recording — live mode only (see [Screencast](#screencast)). |
-| `bidi` | `boolean` | `false` | Opt into WebDriver BiDi capture for browser console + JS exceptions + network. Requires `webSocketUrl: true` in your capabilities and a BiDi-capable chromedriver. When attached, the per-command Chrome perf-log network path is gated off so requests don't duplicate. |
-| `mode` | `'live' \| 'trace'` | `'live'` | `'live'` opens the DevTools UI window; `'trace'` skips the UI and writes a `trace-<sessionId>.zip` next to your `nightwatch.conf.cjs` at run end. See [Trace mode](../../README.md#-trace-mode-tracezip). |
+Options are passed to the plugin through the `globals` field — `globals: nightwatchDevtools({ ... })`. **All options are optional**; the plugin runs fine with `nightwatchDevtools({})`. See [Reference](#reference) for the full option table.
 
 ```javascript
 globals: nightwatchDevtools({
@@ -96,6 +130,71 @@ globals: nightwatchDevtools({
 
 ---
 
+## Live Mode
+
+In the default `mode: 'live'`, the plugin launches the DevTools dashboard in a new browser window when your tests run, streaming each test's commands, screenshots, console logs, and network activity in real time. See the [dashboard docs](https://webdriver.io/docs/devtools/dashboard) for a walkthrough of the UI.
+
+### Preserve & Rerun (Compare)
+
+Available for Nightwatch — same dashboard UI as WebdriverIO. The "compare with rerun" flow snapshots the failing run, re-launches the test with `DEVTOOLS_RERUN_LABEL` set (the plugin filters down to just that test name on the rerun), and the dashboard shows the two runs side-by-side aligned by command.
+
+---
+
+## Trace Mode
+
+Set `mode: 'trace'` to skip the DevTools UI window and instead write a portable, self-contained trace artifact at run end — for offline replay, CI artifact collection, or AI-agent diffing. The backend port-bind, the UI window, and the live-only `screencast` option are all skipped in trace mode.
+
+```javascript
+globals: nightwatchDevtools({
+  mode: 'trace',
+  traceFormat: 'ndjson-directory'  // optional; default 'zip'
+})
+```
+
+Nightwatch emits the **same normalized trace** as the WebdriverIO and Selenium adapters (all three share `@wdio/devtools-core`), so the archive format and the `show-trace` player are identical no matter which adapter produced it. A Nightwatch trace carries the full per-action capture — a screenshot, the depth-indented accessibility-tree snapshot, the interactable-element list, and the Markdown transcript — so it opens in the player with DOM/snapshot time-travel, the **A11y** and **Transcript** tabs, an **Errors** tab surfacing expect/step failures with jump-to-source, the pick-locator element overlay, and (for Cucumber) **Feature → Scenario → Step** nesting.
+
+Open a trace with the `show-trace` bin, shipped with this package (no extra dependency):
+
+```bash
+npx show-trace test-results/trace-<sessionId>.zip   # in a project that installs this adapter
+pnpm show-trace test-results/trace-<sessionId>.zip  # from the devtools monorepo
+```
+
+For the full artifact contents, the `traceGranularity` / `tracePolicy` reference, and the player walkthrough, see [Trace mode](../../README.md#-trace-mode-tracezip) and [Viewing traces](../../README.md#viewing-traces) in the root README, and the [Trace Mode docs](https://webdriver.io/docs/devtools/wdio/trace-mode).
+
+### Per-test slicing & the BDD `describe/it` caveat
+
+The per-test options — `traceGranularity: 'test'`, and the `tracePolicy`, `screenshot`, and `video` options that pair with it — need a per-test hook to cut each test's slice. The **exports-object (mocha-style)** interface and **Cucumber** (per-scenario hooks) expose one, so they get real per-test slicing. The **BDD `describe/it`** interface — the style used by this package's bundled example — is the exception: Nightwatch runs each `it()` internally and fires the plugin's per-test hook only once per module, so `traceGranularity: 'test'` collapses to a single **session-scoped** slice keyed to the first test. The artifacts manifest still lists every testcase with its correct state; only the per-test slice/artifact keying collapses. Session- and spec-granularity traces are unaffected.
+
+**Cucumber and `traceGranularity`.** Nightwatch quits the browser after every scenario. A `'session'` trace now spans that — one zip covering the whole run, every scenario, with each scenario nested under its feature. (Before, it captured only the *last* scenario, silently.) `'test'` remains the recommendation for Cucumber: one zip per scenario, in its own folder, keyed for retention and smaller to open.
+
+---
+
+## BiDi capture
+
+Enable WebDriver BiDi capture for browser console messages, JS exceptions, and network requests. Equivalent to the path selenium-devtools uses — both adapters call the same `attachBidiHandlers` in `@wdio/devtools-core`.
+
+```javascript
+globals: nightwatchDevtools({
+  port: 3000,
+  bidi: true
+})
+```
+
+You also need `webSocketUrl: true` in your capabilities so chromedriver actually exposes the BiDi channel:
+
+```javascript
+desiredCapabilities: {
+  browserName: 'chrome',
+  'webSocketUrl': true,                         // ← enables BiDi
+  'goog:chromeOptions': { /* ... */ }
+}
+```
+
+When attached, the per-command Chrome performance-log network capture path is gated off so requests don't appear twice in the dashboard. If `webSocketUrl` is missing or the chromedriver version doesn't expose BiDi, the attach silently fails and the perf-log fallback continues to work.
+
+---
+
 ## Screencast
 
 Record a continuous `.webm` video of the browser session. The recording starts on the first session the plugin sees and is finalized in Nightwatch's `after()` hook, writing `nightwatch-video-<sessionId>.webm` to the directory of the test file that just ran. Falls back to the directory containing `nightwatch.conf.*` if the test file path isn't known, and to `process.cwd()` as a last resort. Directories under `node_modules/` are skipped.
@@ -130,6 +229,28 @@ The encoded video is sent to the DevTools dashboard via the `screencast` WS scop
 
 ---
 
+## Reference
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `port` | `number` | `3000` | Port for the DevTools backend server. Auto-incremented if already in use. |
+| `hostname` | `string` | `'localhost'` | Hostname the backend server binds to. |
+| `screencast` | `ScreencastOptions` | `{ enabled: false }` | Session video recording — live mode only (see [Screencast](#screencast)). |
+| `bidi` | `boolean` | `false` | Opt into WebDriver BiDi capture for browser console + JS exceptions + network. Requires `webSocketUrl: true` in your capabilities and a BiDi-capable chromedriver. When attached, the per-command Chrome perf-log network path is gated off so requests don't duplicate. |
+| `mode` | `'live' \| 'trace'` | `'live'` | `'live'` opens the DevTools UI window; `'trace'` skips the UI and writes a `trace-<sessionId>.zip` (or directory) under a `test-results/` directory at run end (base dir resolved from the test file dir → config dir → cwd). See [Trace mode](#trace-mode). |
+| `traceFormat` | `'zip' \| 'ndjson-directory'` | `'zip'` | Trace artifact layout — `zip` writes a single archive, `ndjson-directory` unpacks the same files into `trace-<sessionId>/`. Only applies when `mode: 'trace'`. |
+| `traceGranularity` | `'session' \| 'spec' \| 'test'` | `'session'` | One trace per session / spec file / test. `'test'` is what the per-test `screenshot` / `video` artifacts attach to. Only applies when `mode: 'trace'`. **Caveat:** the BDD `describe/it` interface collapses to a single session-scoped slice (see [Per-test slicing](#per-test-slicing--the-bdd-describeit-caveat)). For Cucumber, `'session'` spans every scenario in one zip; `'test'` gives one per scenario and is the recommendation. |
+| `tracePolicy` | `'on' \| 'retain-on-failure' \| 'retain-on-first-failure' \| 'on-first-retry' \| 'on-all-retries' \| 'retain-on-failure-and-retries'` | `'on'` | Which traces to keep. Pairs with `traceGranularity: 'test'`. Only applies when `mode: 'trace'`. |
+| `filmstrip` | `boolean` | `true` | Record a dense, continuous screencast filmstrip into the trace for scrubbable playback in the trace player — not just one frame per action. Runs the screencast recorder (polling mode on Nightwatch) for the session. Only applies when `mode: 'trace'`. |
+| `screenshot` | `'off' \| 'on' \| 'only-on-failure'` | `'off'` | Per-test screenshot. Trace mode + `traceGranularity: 'test'` only. **Produce-only** — the PNG is written to the trace output dir (and listed in the artifacts manifest when `emitArtifactsManifest: true`); it is NOT attached inline to Allure (see note below). |
+| `video` | `'off' \| TraceRetentionPolicy` | `'off'` | Per-test video slice, retained per the given policy (e.g. `'retain-on-failure'`). Trace mode + `traceGranularity: 'test'` only. Setting a non-`off` policy starts the screencast recorder itself — you do **not** also need `filmstrip` or `screencast.enabled`; the recorder runs continuously for the session and each test's slice is cut from it by wall-clock window. **Produce-only** — the `.webm` is written to the trace output dir (and listed in the manifest when `emitArtifactsManifest: true`); NOT attached inline to Allure. |
+| `emitArtifactsManifest` | `boolean` | `false` | Write the `devtools-artifacts-<sessionId>.json` manifest — the generic index reporters/CI consume to discover produced artifacts — next to the trace. **Opt-in for Nightwatch**: it has no live Allure signal to auto-detect against (`nightwatch-allure` is post-hoc), so unlike WDIO/Selenium it never auto-enables. Trace mode only. |
+| `captureAssertions` | `boolean` | `true` | Capture assertions as trace action rows — `node:assert` plus native `browser.assert.*` / `browser.verify.*`, including negated `.not.*` matchers. Passing assertions render green, failing ones red with the error. Set `false` to opt out. |
+
+> **Inline Allure attachment is not supported for Nightwatch.** Its official `nightwatch-allure` reporter is post-hoc (no live attach API), and `allure-js-commons`' `attachment()` no-ops in a Nightwatch run. So `screenshot`/`video` artifacts are *produced* (files, plus the artifacts manifest when `emitArtifactsManifest: true`) in the trace output dir but not attached to an Allure test. Per-test slicing (and therefore these artifacts) is meaningful for the cucumber and exports-object interfaces; the BDD `describe/it` interface collapses to session granularity, so the gate no-ops there.
+
+---
+
 ## Examples
 
 Working examples are included in this package:
@@ -159,36 +280,11 @@ Nightwatch does not provide the same depth of framework hooks as WebdriverIO, so
 | Limited test context | `browser.currentTest` provides less metadata than the WDIO runner context; test names and file paths require additional heuristics. |
 | Flat suite nesting | Nightwatch does not natively support multiply-nested `describe` blocks; the plugin reports a maximum of two levels. |
 | Delayed result availability | Test results are only finalised in `afterEach`, not available mid-test. |
+| Per-test trace slicing (BDD `describe/it`) | The BDD interface fires the plugin's per-test hook once per module, so `traceGranularity: 'test'` collapses to one session-scoped slice. The exports-object (mocha-style) and Cucumber interfaces get real per-test slicing. See [Per-test slicing](#per-test-slicing--the-bdd-describeit-caveat). |
+| Produce-only trace artifacts | Per-test `screenshot` / `video` files are written to the trace output dir (and the manifest when `emitArtifactsManifest: true`) but not attached inline to Allure — Nightwatch has no live Allure attach API. |
 
 Overall feature parity with the WebdriverIO DevTools service is approximately **80–90%**.
 
-### Preserve & Rerun (Compare)
-
-Available for Nightwatch — same dashboard UI as WebdriverIO. The "compare with rerun" flow snapshots the failing run, re-launches the test with `DEVTOOLS_RERUN_LABEL` set (the plugin filters down to just that test name on the rerun), and the dashboard shows the two runs side-by-side aligned by command.
-
-### BiDi capture (opt-in)
-
-Enable WebDriver BiDi capture for browser console messages, JS exceptions, and network requests. Equivalent to the path selenium-devtools uses — both adapters call the same `attachBidiHandlers` in `@wdio/devtools-core`.
-
-```javascript
-globals: nightwatchDevtools({
-  port: 3000,
-  bidi: true
-})
-```
-
-You also need `webSocketUrl: true` in your capabilities so chromedriver actually exposes the BiDi channel:
-
-```javascript
-desiredCapabilities: {
-  browserName: 'chrome',
-  'webSocketUrl': true,                         // ← enables BiDi
-  'goog:chromeOptions': { /* ... */ }
-}
-```
-
-When attached, the per-command Chrome performance-log network capture path is gated off so requests don't appear twice in the dashboard. If `webSocketUrl` is missing or the chromedriver version doesn't expose BiDi, the attach silently fails and the perf-log fallback continues to work.
-
 ## :page_facing_up: License
 
 [MIT](/LICENSE)

package/dist/bidi-4GYMJUJN.js

@@ -0,0 +1,42 @@
+import {
+  attachBidiHandlers
+} from "./chunk-QYGJTYKJ.js";
+
+// src/bidi.ts
+import logger from "@wdio/logger";
+var log = logger("@wdio/nightwatch-devtools:bidi");
+async function attachBidiHandlers2(driver, sinks) {
+  return attachBidiHandlers(
+    driver,
+    sinks,
+    (level, message) => log[level](message)
+  );
+}
+function buildBidiSinks(capturer) {
+  return {
+    pushConsoleLog: (entry) => {
+      capturer.consoleLogs.push(entry);
+      capturer.sendUpstream("consoleLogs", [entry]);
+    },
+    pushNetworkRequest: (entry) => {
+      capturer.networkRequests.push(entry);
+      capturer.sendUpstream("networkRequests", [entry]);
+    },
+    replaceNetworkRequest: (id, entry) => {
+      const idx = capturer.networkRequests.findIndex(
+        (r) => r.id === id
+      );
+      if (idx !== -1) {
+        capturer.networkRequests[idx] = entry;
+      } else {
+        capturer.networkRequests.push(entry);
+      }
+      capturer.sendUpstream("networkRequests", [entry]);
+    }
+  };
+}
+export {
+  attachBidiHandlers2 as attachBidiHandlers,
+  buildBidiSinks
+};
+//# sourceMappingURL=bidi-4GYMJUJN.js.map

package/dist/bidi-4GYMJUJN.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/bidi.ts"],"sourcesContent":["import logger from '@wdio/logger'\nimport {\n  type BidiHandlerSinks,\n  attachBidiHandlers as attachBidiHandlersCore\n} from '@wdio/devtools-core'\nimport type { SessionCapturer } from './session.js'\n\nconst log = logger('@wdio/nightwatch-devtools:bidi')\n\n/**\n * Nightwatch wrapper around the core BiDi attach helper. Nightwatch ships\n * selenium-webdriver under the hood (via chromedriver), so the same\n * `selenium-webdriver/bidi` inspectors selenium-devtools uses are available\n * whenever the user has set `webSocketUrl: true` in their capabilities.\n *\n * Opt-in via the plugin's `bidi: true` option. When attached, the per-command\n * Chrome performance-log network capture is gated off to avoid duplicate\n * entries in the dashboard.\n */\nexport async function attachBidiHandlers(\n  driver: unknown,\n  sinks: BidiHandlerSinks\n): Promise<boolean> {\n  return attachBidiHandlersCore(driver, sinks, (level, message) =>\n    log[level](message)\n  )\n}\n\n/**\n * Build sinks that route BiDi events into the SessionCapturer's local arrays\n * and broadcast them upstream. Mirrors selenium-devtools' `buildBidiSinks` —\n * separate per-adapter because the SessionCapturer concrete types differ.\n */\nexport function buildBidiSinks(capturer: SessionCapturer): BidiHandlerSinks {\n  return {\n    pushConsoleLog: (entry) => {\n      capturer.consoleLogs.push(entry)\n      capturer.sendUpstream('consoleLogs', [entry])\n    },\n    pushNetworkRequest: (entry) => {\n      capturer.networkRequests.push(entry)\n      capturer.sendUpstream('networkRequests', [entry])\n    },\n    replaceNetworkRequest: (id, entry) => {\n      const idx = capturer.networkRequests.findIndex(\n        (r: { id?: string }) => r.id === id\n      )\n      if (idx !== -1) {\n        capturer.networkRequests[idx] = entry\n      } else {\n        capturer.networkRequests.push(entry)\n      }\n      capturer.sendUpstream('networkRequests', [entry])\n    }\n  }\n}\n"],"mappings":";;;;;AAAA,OAAO,YAAY;AAOnB,IAAM,MAAM,OAAO,gCAAgC;AAYnD,eAAsBA,oBACpB,QACA,OACkB;AAClB,SAAO;AAAA,IAAuB;AAAA,IAAQ;AAAA,IAAO,CAAC,OAAO,YACnD,IAAI,KAAK,EAAE,OAAO;AAAA,EACpB;AACF;AAOO,SAAS,eAAe,UAA6C;AAC1E,SAAO;AAAA,IACL,gBAAgB,CAAC,UAAU;AACzB,eAAS,YAAY,KAAK,KAAK;AAC/B,eAAS,aAAa,eAAe,CAAC,KAAK,CAAC;AAAA,IAC9C;AAAA,IACA,oBAAoB,CAAC,UAAU;AAC7B,eAAS,gBAAgB,KAAK,KAAK;AACnC,eAAS,aAAa,mBAAmB,CAAC,KAAK,CAAC;AAAA,IAClD;AAAA,IACA,uBAAuB,CAAC,IAAI,UAAU;AACpC,YAAM,MAAM,SAAS,gBAAgB;AAAA,QACnC,CAAC,MAAuB,EAAE,OAAO;AAAA,MACnC;AACA,UAAI,QAAQ,IAAI;AACd,iBAAS,gBAAgB,GAAG,IAAI;AAAA,MAClC,OAAO;AACL,iBAAS,gBAAgB,KAAK,KAAK;AAAA,MACrC;AACA,eAAS,aAAa,mBAAmB,CAAC,KAAK,CAAC;AAAA,IAClD;AAAA,EACF;AACF;","names":["attachBidiHandlers"]}

package/dist/chunk-QYGJTYKJ.js

@@ -0,0 +1,380 @@
+// ../core/src/error.ts
+function toError(value) {
+  if (value instanceof Error) {
+    return value;
+  }
+  if (value !== null && typeof value === "object" && typeof value.message === "string") {
+    const e = new Error(value.message);
+    const name = value.name;
+    if (typeof name === "string") {
+      e.name = name;
+    }
+    return e;
+  }
+  return new Error(String(value));
+}
+function errorMessage(value) {
+  if (value instanceof Error) {
+    return value.message;
+  }
+  if (typeof value === "string") {
+    return value;
+  }
+  if (value !== null && typeof value === "object" && typeof value.message === "string") {
+    return value.message;
+  }
+  if (value === void 0 || value === null) {
+    return "unknown error";
+  }
+  try {
+    return String(value);
+  } catch {
+    return "unknown error";
+  }
+}
+function serializeError(error) {
+  if (!error) {
+    return void 0;
+  }
+  return { name: error.name, message: error.message, stack: error.stack };
+}
+
+// ../core/src/bidi.ts
+import { createRequire } from "module";
+
+// ../core/src/console.ts
+var CONSOLE_METHODS = ["log", "info", "warn", "error"];
+var ANSI_REGEX = /\x1b\[[?]?[0-9;]*[A-Za-z]/g;
+function stripAnsi(text) {
+  return text.replace(ANSI_REGEX, "");
+}
+var LOG_LEVEL_PATTERNS = [
+  { level: "trace", pattern: /\btrace\b/i },
+  { level: "debug", pattern: /\bdebug\b/i },
+  { level: "info", pattern: /\binfo\b/i },
+  { level: "warn", pattern: /\bwarn(ing)?\b/i },
+  { level: "error", pattern: /\berror\b/i }
+];
+var ERROR_INDICATORS = ["\u2717", "failed", "failure"];
+var SPINNER_RE = /^[⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏]/u;
+function isInternalStreamLine(line) {
+  const t = line.trim();
+  if (t.startsWith('{"') || t.startsWith("[SESSION]")) {
+    return true;
+  }
+  if (t.includes("@wdio/devtools-backend")) {
+    return true;
+  }
+  if (/^console\.(log|info|warn|error|debug|trace)$/.test(t)) {
+    return true;
+  }
+  if (/^at\s.+:\d+:\d+\)?$/.test(t)) {
+    return true;
+  }
+  return false;
+}
+var LOG_SOURCES = {
+  BROWSER: "browser",
+  TEST: "test",
+  TERMINAL: "terminal"
+};
+function detectLogLevel(text) {
+  const normalised = stripAnsi(text).toLowerCase();
+  for (const { level, pattern } of LOG_LEVEL_PATTERNS) {
+    if (pattern.test(normalised)) {
+      return level;
+    }
+  }
+  if (ERROR_INDICATORS.some((i) => normalised.includes(i.toLowerCase()))) {
+    return "error";
+  }
+  return "log";
+}
+function createConsoleLogEntry(type, args, source = LOG_SOURCES.TEST) {
+  return { timestamp: Date.now(), type, args, source };
+}
+function mapChromeBrowserLogs(entries) {
+  return entries.map((entry) => ({
+    timestamp: entry.timestamp,
+    type: chromeLogLevelToLogLevel(
+      entry.level
+    ),
+    args: [entry.message],
+    source: LOG_SOURCES.BROWSER
+  }));
+}
+function chromeLogLevelToLogLevel(level) {
+  const levelName = (typeof level === "object" ? level?.name ?? "" : level ?? "").toUpperCase();
+  switch (levelName) {
+    case "SEVERE":
+      return "error";
+    case "WARNING":
+      return "warn";
+    case "INFO":
+      return "info";
+    case "DEBUG":
+      return "debug";
+    default:
+      return "log";
+  }
+}
+
+// ../core/src/net.ts
+import * as net from "net";
+
+// ../core/src/request-type.ts
+function getRequestType(url, mimeType) {
+  const contentType = mimeType?.toLowerCase() ?? "";
+  const urlLower = url.toLowerCase();
+  if (contentType.includes("text/html")) {
+    return "document";
+  }
+  if (contentType.includes("text/css")) {
+    return "stylesheet";
+  }
+  if (contentType.includes("javascript") || contentType.includes("ecmascript")) {
+    return "script";
+  }
+  if (contentType.includes("image/")) {
+    return "image";
+  }
+  if (contentType.includes("font/") || contentType.includes("woff")) {
+    return "font";
+  }
+  if (contentType.includes("application/json")) {
+    return "fetch";
+  }
+  if (urlLower.endsWith(".html") || urlLower.endsWith(".htm")) {
+    return "document";
+  }
+  if (urlLower.endsWith(".css")) {
+    return "stylesheet";
+  }
+  if (urlLower.endsWith(".js") || urlLower.endsWith(".mjs")) {
+    return "script";
+  }
+  if (/\.(png|jpg|jpeg|gif|svg|webp|ico)$/.test(urlLower)) {
+    return "image";
+  }
+  if (/\.(woff|woff2|ttf|eot|otf)$/.test(urlLower)) {
+    return "font";
+  }
+  return "xhr";
+}
+
+// ../core/src/net.ts
+function isPortInUse(port, hostname) {
+  return new Promise((resolve) => {
+    const server = net.createServer();
+    server.once("error", () => resolve(true));
+    server.once("listening", () => server.close(() => resolve(false)));
+    server.listen(port, hostname);
+  });
+}
+async function findFreePort(startPort, hostname) {
+  let port = startPort;
+  while (await isPortInUse(port, hostname)) {
+    port++;
+  }
+  return port;
+}
+
+// ../core/src/bidi.ts
+function loadSeleniumSubmodule(subpath) {
+  try {
+    const userRequire = createRequire(`${process.cwd()}/`);
+    return userRequire(`selenium-webdriver/${subpath}`);
+  } catch {
+    try {
+      const localRequire = createRequire(import.meta.url);
+      return localRequire(`selenium-webdriver/${subpath}`);
+    } catch {
+      return null;
+    }
+  }
+}
+function handleBidiConsoleEntry(rawEntry, sinks, log) {
+  const entry = rawEntry;
+  try {
+    const level = (entry?.level ?? entry?.type ?? "info").toString();
+    const text = entry?.text ?? entry?.message ?? "";
+    sinks.pushConsoleLog({
+      timestamp: Number(entry?.timestamp) || Date.now(),
+      type: chromeLogLevelToLogLevel(level),
+      args: [text],
+      source: LOG_SOURCES.BROWSER
+    });
+  } catch (err) {
+    log("warn", `onConsoleEntry handler threw: ${errorMessage(err)}`);
+  }
+}
+function handleBidiJsException(rawExc, sinks, log) {
+  const exception = rawExc;
+  try {
+    const text = exception?.text ?? exception?.message ?? String(rawExc);
+    const trimmed = String(text).replace(/\s+/g, " ").slice(0, 200);
+    log(
+      "warn",
+      `\u{1F41B} JS error in page: ${trimmed}${String(text).length > 200 ? "\u2026" : ""}`
+    );
+    sinks.pushConsoleLog({
+      timestamp: Date.now(),
+      type: "error",
+      args: [text],
+      source: LOG_SOURCES.BROWSER
+    });
+  } catch (err) {
+    log("warn", `onJavascriptException handler threw: ${errorMessage(err)}`);
+  }
+}
+async function attachLogInspector(driver, factory, sinks, log) {
+  try {
+    const inspector = await factory(driver);
+    await inspector.onConsoleEntry((e) => handleBidiConsoleEntry(e, sinks, log));
+    await inspector.onJavascriptException(
+      (e) => handleBidiJsException(e, sinks, log)
+    );
+    log("info", "\u2713 BiDi LogInspector attached (console + JS exceptions)");
+    return true;
+  } catch (err) {
+    log("warn", `BiDi LogInspector attach failed: ${errorMessage(err)}`);
+    return false;
+  }
+}
+var isFiniteNumber = (value) => typeof value === "number" && Number.isFinite(value);
+function bidiResponseTiming(timings, startTime, timestamp) {
+  if (timings && isFiniteNumber(timings.requestTime) && isFiniteNumber(timings.responseEnd) && timings.responseEnd > timings.requestTime) {
+    const time = Math.round(timings.responseEnd - timings.requestTime);
+    return { endTime: startTime + time, time };
+  }
+  const endTime = Number(timestamp ?? Date.now());
+  return { endTime, time: Math.max(0, endTime - startTime) };
+}
+function handleBidiRequestSent(rawEvent, pending, sinks, log) {
+  const event = rawEvent;
+  try {
+    const requestId = String(event?.request?.request ?? event?.id ?? "");
+    if (!requestId) {
+      return;
+    }
+    const entry = {
+      id: requestId,
+      url: event?.request?.url ?? "",
+      method: event?.request?.method ?? "GET",
+      requestHeaders: arrayHeadersToObject(event?.request?.headers),
+      timestamp: Date.now(),
+      startTime: Number(event?.timestamp ?? Date.now()),
+      type: getRequestType(event?.request?.url ?? "")
+    };
+    pending.set(requestId, entry);
+    sinks.pushNetworkRequest(entry);
+  } catch (err) {
+    log("warn", `beforeRequestSent threw: ${errorMessage(err)}`);
+  }
+}
+function handleBidiResponseCompleted(rawEvent, pending, sinks, log) {
+  const event = rawEvent;
+  try {
+    const requestId = String(event?.request?.request ?? event?.id ?? "");
+    const previous = pending.get(requestId);
+    if (!previous) {
+      return;
+    }
+    const { endTime, time } = bidiResponseTiming(
+      event?.request?.timings,
+      previous.startTime,
+      event?.timestamp
+    );
+    const finalized = {
+      ...previous,
+      status: Number(event?.response?.status) || previous.status,
+      statusText: event?.response?.statusText ?? previous.statusText,
+      responseHeaders: arrayHeadersToObject(event?.response?.headers),
+      type: getRequestType(previous.url, event?.response?.mimeType),
+      endTime,
+      time,
+      size: Number(event?.response?.bytesReceived) || void 0
+    };
+    pending.delete(requestId);
+    sinks.replaceNetworkRequest(requestId, finalized);
+  } catch (err) {
+    log("warn", `responseCompleted threw: ${errorMessage(err)}`);
+  }
+}
+async function attachNetworkInspector(driver, factory, sinks, log) {
+  try {
+    const inspector = await factory(driver);
+    const pending = /* @__PURE__ */ new Map();
+    await inspector.beforeRequestSent(
+      (e) => handleBidiRequestSent(e, pending, sinks, log)
+    );
+    await inspector.responseCompleted(
+      (e) => handleBidiResponseCompleted(e, pending, sinks, log)
+    );
+    log("info", "\u2713 BiDi NetworkInspector attached (request + response)");
+    return true;
+  } catch (err) {
+    log("warn", `BiDi NetworkInspector attach failed: ${errorMessage(err)}`);
+    return false;
+  }
+}
+async function attachBidiHandlers(driver, sinks, onLog) {
+  const log = (level, message) => onLog?.(level, message);
+  const logFactory = loadSeleniumSubmodule("bidi/logInspector");
+  const networkFactory = loadSeleniumSubmodule(
+    "bidi/networkInspector"
+  );
+  let attached = 0;
+  if (typeof logFactory === "function") {
+    if (await attachLogInspector(driver, logFactory, sinks, log)) {
+      attached++;
+    }
+  } else {
+    log("info", "selenium-webdriver/bidi/logInspector not available \u2014 skipping");
+  }
+  if (typeof networkFactory === "function") {
+    if (await attachNetworkInspector(driver, networkFactory, sinks, log)) {
+      attached++;
+    }
+  } else {
+    log(
+      "info",
+      "selenium-webdriver/bidi/networkInspector not available \u2014 skipping"
+    );
+  }
+  return attached > 0;
+}
+function arrayHeadersToObject(headers) {
+  if (!Array.isArray(headers)) {
+    return void 0;
+  }
+  const out = {};
+  for (const h of headers) {
+    const name = String(h?.name ?? "").toLowerCase();
+    if (!name) {
+      continue;
+    }
+    const v = h?.value;
+    out[name] = typeof v === "string" ? v : typeof v?.value === "string" ? v.value : JSON.stringify(v ?? "");
+  }
+  return out;
+}
+
+export {
+  toError,
+  errorMessage,
+  serializeError,
+  CONSOLE_METHODS,
+  stripAnsi,
+  SPINNER_RE,
+  isInternalStreamLine,
+  LOG_SOURCES,
+  detectLogLevel,
+  createConsoleLogEntry,
+  mapChromeBrowserLogs,
+  getRequestType,
+  findFreePort,
+  loadSeleniumSubmodule,
+  attachBidiHandlers
+};
+//# sourceMappingURL=chunk-QYGJTYKJ.js.map