@zerotal/testing 1.4.0 → 1.5.1

package/CHANGELOG.md

@@ -8,6 +8,51 @@ follows the Zerotal monorepo's unified versioning.
 
 ## [Unreleased]
 
+## [1.5.0] — 2026-08-15
+
+### Added
+
+- **`FlowBrowser` — drive a real page against a real server, inside `bun test`.**
+  `FlowTest` mounts a component and runs its server-side lifecycle; it never opens a
+  socket, so it renders the full markup every time and every assertion passes. That is
+  the problem: every silent failure Flow has shipped has one shape — the HTML is fine
+  and the transport is dead — and no server-side test can see it by construction.
+
+  `FlowBrowser.serve(bootstrap)` boots the app through `createTestApp` on an
+  OS-assigned port, `visit(path)` opens a headless page, and the page can be read
+  (`text`, `count`, `attribute`, `connection`), driven (`click`, `type`, `press`) and
+  waited on. Lives behind `@zerotal/testing/browser` so the vast majority of tests
+  never pay to find out whether a browser is present.
+
+  **`waitForPatch()` is the primitive, and it is not a sleep.** The harness reads the
+  WebSocket through the DevTools Protocol, so the received-frame count is captured when
+  an action is dispatched and the wait is for it to rise. A harness whose assertions
+  race the transport produces flaky tests, and a flaky browser suite gets deleted.
+
+  `transport()` reports what the browser saw on the wire — sockets created, handshakes
+  that answered `101`, every frame's payload — which the page cannot lie about. Assert
+  that a `101` was **seen**, never that a status was not `403`: a refused upgrade does
+  not arrive as a handshake response at all, so the negative form passes vacuously.
+
+  **No new dependency.** `Bun.WebView` covers driving the page and reading the
+  transport, so the argument for a browser-automation library is not made.
+
+  Two limits, documented rather than discovered: the harness talks to the app's own
+  origin, so it **cannot** catch a misconfigured `allowedOrigins` (`bun zt doctor --url`
+  is the tool for that); and Bun cannot spawn Chrome on Windows today, so connect-mode
+  via `ZT_BROWSER_CDP_URL` is a first-class path rather than a fallback.
+
+### Fixed
+
+- **`createTestApp()` no longer un-adopts the app it just adopted.** The shared-app
+  path called `adoptAsCurrent()` and then `resetTestState()`, which calls
+  `Application._resetInstance()` — precisely what the adoption existed to undo. The
+  second test file in a process was handed an app whose scope had been torn down, and
+  the first facade it touched threw `E_FACADE_BEFORE_BOOT`. What made it expensive is
+  that each file passed _in isolation_, so the failure attached to whichever file
+  happened to sort second and read as a bug in that file. Reset, then adopt — the same
+  order the fresh-app path already used.
+
 ## [1.1.0] — 2026-08-08
 
 ### Fixed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zerotal/testing",
-  "version": "1.4.0",
+  "version": "1.5.1",
   "license": "MIT",
   "maturity": "stable",
   "private": false,
@@ -9,7 +9,8 @@
   "types": "./src/index.ts",
   "exports": {
     ".": "./src/index.ts",
-    "./preload": "./src/preload.ts"
+    "./preload": "./src/preload.ts",
+    "./browser": "./src/browser.ts"
   },
   "files": [
     "CHANGELOG.md",
@@ -30,14 +31,14 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@zerotal/core": "1.4.0",
-    "@zerotal/orm": "1.4.0",
-    "@zerotal/queue": "1.4.0",
-    "@zerotal/notifications": "1.4.0"
+    "@zerotal/core": "1.5.1",
+    "@zerotal/orm": "1.5.1",
+    "@zerotal/queue": "1.5.1",
+    "@zerotal/notifications": "1.5.1"
   },
   "devDependencies": {
     "typescript": "^5.8.0",
-    "@zerotal/session": "1.4.0"
+    "@zerotal/session": "1.5.1"
   },
   "description": "Testing utilities for Zerotal — an in-process test app, HTTP helpers, and database refresh.",
   "keywords": [

package/src/TestApp.ts

@@ -1,4 +1,4 @@
-import { Application, type ExceptionHandler } from "@zerotal/core";
+import { Application } from "@zerotal/core";
 import { TestResponse, type SessionDecoder } from "./TestResponse.ts";
 import { TestExceptionHandler } from "./TestExceptionHandler.ts";
 import { resetTestState } from "./resetTestState.ts";
@@ -590,19 +590,30 @@ export async function createTestApp(
   // already-started server is not idempotent — so those callers always get a fresh
   // app and own its teardown, exactly as before.
   //
-  // Only probe once an app exists: on the first call `bootstrap()` has real side
-  // effects (Application.create + provider registration) and must run after the
-  // reset below, not before it.
+  // Reset BEFORE probing, not after. `bootstrap()` may be evaluating its module for
+  // the first time, and the scaffolded bootstrap builds its Application at module
+  // scope — so probing first calls `Application.create()` while the previous file's
+  // app is still installed, and it throws "An application already exists in this
+  // process" before sharing is ever considered. Whether an app is still installed
+  // depends on which file happened to run before this one, which is why this passed
+  // on one machine and failed on the CI runner with the same code.
+  //
+  // Resetting first is safe on both paths: `resetTestState()` calls
+  // `Application._resetInstance()`, and every path below re-adopts — the shared one
+  // here, the fresh one after its own reset. Adopting before the reset is what is
+  // unsafe: it hands back an app whose scope has just been torn down, and the first
+  // facade to touch it throws E_FACADE_BEFORE_BOOT.
   if (!setup && _sharedApps.size > 0) {
+    resetTestState();
     const booted = await bootstrap();
     const existing = _sharedApps.get(booted);
     if (existing) {
-      // Re-adopt: an earlier file's close() reset the app scope even though the app
-      // itself is still running, so facades need pointing back at it.
       booted.adoptAsCurrent();
-      resetTestState();
       return existing;
     }
+    // Not a shared app after all. Fall through — the module is cached now, so the
+    // bootstrap below returns this same instance rather than creating a second one,
+    // and the `adoptAsCurrent()` there reinstalls the scope this reset tore down.
   }
 
   resetTestState();

package/src/browser/FlowBrowser.ts

@@ -0,0 +1,406 @@
+import { createTestApp, type TestApp } from "../TestApp.ts";
+import { backendOption, browserAvailability } from "./chrome.ts";
+import type { Application } from "@zerotal/core";
+
+/**
+ * Read a CDP event's params.
+ *
+ * `Bun.WebView` delivers each event as an `Event` carrying the CDP params on
+ * `data`, but neither `addEventListener` overload types that usefully here:
+ * the generic one resolves `MessageEvent` to its *constructor* once lib.dom is
+ * in scope, and the plain one wants a bare `EventListener`. A predicate keeps
+ * the listener assignable and states the assumption in one place instead of
+ * casting at every call site.
+ */
+function cdpParams<T>(event: Event): event is Event & { readonly data: T } {
+  return "data" in event;
+}
+
+/** A WebSocket frame the page sent or received, as CDP reported it. */
+export interface ObservedFrame {
+  direction: "sent" | "received";
+  payload: string;
+}
+
+/** What the transport did, from outside the page. */
+export interface TransportReport {
+  /** Sockets the page opened. */
+  created: number;
+  /** Handshakes that answered `101`. Zero means the socket never opened. */
+  upgraded: number;
+  /** Status of each handshake response that arrived. */
+  statuses: number[];
+  /** True when Chrome reported a frame-level failure. */
+  errored: boolean;
+  frames: ObservedFrame[];
+}
+
+/** Options for {@link FlowBrowser.serve}. */
+export interface FlowBrowserOptions {
+  /** Milliseconds any `waitFor*` will wait before giving up. */
+  timeout?: number;
+  /**
+   * Register routes, before the server starts.
+   *
+   * Passed straight to `createTestApp`, which runs it after the state reset and
+   * before `start()` so the routes are compiled into the server. A suite that
+   * needs a fixture page — one deliberately built to reproduce a bug — registers
+   * it here instead of adding it to the application under test.
+   */
+  setup?: () => void;
+}
+
+const DEFAULT_TIMEOUT = 5_000;
+/** Gap between polls of an in-page condition. Not a sleep the assertions depend on. */
+const POLL_MS = 25;
+
+/**
+ * A real page, driven against a real server.
+ *
+ * Obtained from {@link FlowBrowser.visit}. Every method that acts on the page
+ * records the transport frame count first, so {@link waitForPatch} can wait for
+ * a frame that arrived *after* the action rather than one already in flight.
+ */
+export class BrowserPage {
+  private readonly _view: Bun.WebView;
+  private readonly _report: TransportReport;
+  private readonly _timeout: number;
+  private _framesAtAction = 0;
+  private _closed = false;
+
+  /** @internal Constructed by {@link FlowBrowser.visit}. */
+  constructor(view: Bun.WebView, report: TransportReport, timeout: number) {
+    this._view = view;
+    this._report = report;
+    this._timeout = timeout;
+  }
+
+  // ── Reading the page ────────────────────────────────────────────────────────
+
+  /**
+   * Evaluate an expression in the page.
+   *
+   * `Bun.WebView` allows only one evaluation in flight per view, so every read
+   * here is serial by construction — never wrap these in `Promise.all`.
+   */
+  async evaluate<T = unknown>(expression: string): Promise<T> {
+    this._assertOpen();
+    return this._view.evaluate<T>(expression);
+  }
+
+  /** `textContent` of the first match, trimmed. `null` when nothing matches. */
+  async text(selector: string): Promise<string | null> {
+    return this.evaluate<string | null>(
+      `(() => { const el = document.querySelector(${quote(selector)});
+                return el ? el.textContent.trim() : null; })()`,
+    );
+  }
+
+  /** `innerHTML` of the first match. `null` when nothing matches. */
+  async html(selector: string): Promise<string | null> {
+    return this.evaluate<string | null>(
+      `(() => { const el = document.querySelector(${quote(selector)});
+                return el ? el.innerHTML : null; })()`,
+    );
+  }
+
+  /** How many elements match. The assertion the keyless-child bug needed. */
+  async count(selector: string): Promise<number> {
+    return this.evaluate<number>(`document.querySelectorAll(${quote(selector)}).length`);
+  }
+
+  /** An attribute of the first match, or `null`. */
+  async attribute(selector: string, name: string): Promise<string | null> {
+    return this.evaluate<string | null>(
+      `(() => { const el = document.querySelector(${quote(selector)});
+                return el ? el.getAttribute(${quote(name)}) : null; })()`,
+    );
+  }
+
+  /**
+   * The connection state the bridge stamped on `<body>`.
+   *
+   * This is the single most valuable thing the harness can read: it is the
+   * difference between "the app is broken" and "the app is fine" in every
+   * failure this harness exists to catch. `"online"`, `"offline"`, or `null`
+   * before the bridge has run.
+   */
+  async connection(): Promise<string | null> {
+    return this.evaluate<string | null>("document.body.dataset.flowConnection ?? null");
+  }
+
+  /** The page's current URL — for asserting a redirect actually happened. */
+  async url(): Promise<string> {
+    return this.evaluate<string>("location.pathname + location.search");
+  }
+
+  // ── Acting on the page ──────────────────────────────────────────────────────
+
+  /** Click the first element matching `selector`, as a real trusted click. */
+  async click(selector: string): Promise<this> {
+    this._assertOpen();
+    this._markAction();
+    await this._view.click(selector);
+    return this;
+  }
+
+  /**
+   * Click the match to focus it, then type into it.
+   *
+   * `WebView.type()` types into whatever holds focus, so the click is what
+   * chooses the field — the same two steps a person performs.
+   */
+  async type(selector: string, text: string): Promise<this> {
+    this._assertOpen();
+    this._markAction();
+    await this._view.click(selector);
+    await this._view.type(text);
+    return this;
+  }
+
+  /** Press a key, with the page's current focus. */
+  async press(key: string): Promise<this> {
+    this._assertOpen();
+    this._markAction();
+    await this._view.press(key);
+    return this;
+  }
+
+  // ── Waiting ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Wait until the page has received a WebSocket frame caused by the last action.
+   *
+   * This is the primitive, and it is deliberately not a sleep: the frame count is
+   * captured when the action is dispatched, and this waits for it to rise. A
+   * harness whose assertions race the transport produces flaky tests, and a flaky
+   * browser suite gets deleted.
+   *
+   * Throws on timeout rather than returning false, so a test that meant to observe
+   * a patch fails where the patch did not arrive instead of three assertions later.
+   */
+  async waitForPatch(timeout = this._timeout): Promise<this> {
+    const before = this._framesAtAction;
+    const deadline = Date.now() + timeout;
+    while (Date.now() < deadline) {
+      if (this._receivedCount() > before) return this;
+      await Bun.sleep(POLL_MS);
+    }
+    throw new Error(
+      `[FlowBrowser] No patch arrived within ${timeout}ms. ` +
+        `Connection is "${await this.connection()}"; ` +
+        `${this._report.upgraded} socket(s) upgraded, ` +
+        `${this._receivedCount()} frame(s) received in total.`,
+    );
+  }
+
+  /** Wait until an expression in the page is truthy. */
+  async waitFor(expression: string, timeout = this._timeout): Promise<this> {
+    const deadline = Date.now() + timeout;
+    let last: unknown;
+    while (Date.now() < deadline) {
+      last = await this.evaluate(expression);
+      if (last) return this;
+      await Bun.sleep(POLL_MS);
+    }
+    throw new Error(
+      `[FlowBrowser] Timed out after ${timeout}ms waiting for: ${expression}\n` +
+        `  last value: ${JSON.stringify(last)}; connection is "${await this.connection()}".`,
+    );
+  }
+
+  /** Wait until the bridge reports `online`. */
+  async waitForConnection(timeout = this._timeout): Promise<this> {
+    return this.waitFor(`document.body.dataset.flowConnection === "online"`, timeout);
+  }
+
+  /** Wait until `selector` matches at least `n` elements. */
+  async waitForCount(selector: string, n: number, timeout = this._timeout): Promise<this> {
+    return this.waitFor(
+      `document.querySelectorAll(${quote(selector)}).length >= ${String(n)}`,
+      timeout,
+    );
+  }
+
+  // ── The transport, from outside the page ────────────────────────────────────
+
+  /**
+   * What Chrome saw on the wire.
+   *
+   * The page cannot lie about this: a client that silently degraded and called
+   * itself fine still shows zero upgraded sockets here.
+   */
+  transport(): TransportReport {
+    return {
+      ...this._report,
+      statuses: [...this._report.statuses],
+      frames: [...this._report.frames],
+    };
+  }
+
+  /**
+   * Whether a WebSocket handshake answered `101`.
+   *
+   * Asserted as "a 101 was observed", never as "the status was not 403": a
+   * refused upgrade does not arrive as a handshake response at all — Chrome
+   * reports a frame error instead — so a test asserting on the status of that
+   * event would pass vacuously.
+   */
+  socketUpgraded(): boolean {
+    return this._report.upgraded > 0;
+  }
+
+  /** Close the page. Its server is not affected. */
+  close(): void {
+    if (this._closed) return;
+    this._closed = true;
+    this._view.close();
+  }
+
+  private _receivedCount(): number {
+    return this._report.frames.filter((f) => f.direction === "received").length;
+  }
+
+  private _markAction(): void {
+    this._framesAtAction = this._receivedCount();
+  }
+
+  private _assertOpen(): void {
+    if (this._closed) throw new Error("[FlowBrowser] This page is closed.");
+  }
+}
+
+/**
+ * Drives a real browser against a real server, so the WebSocket bridge has a
+ * regression net.
+ *
+ * Every silent failure Flow has shipped shares one shape — the HTML is fine and
+ * the transport is dead — and `FlowTest` cannot exercise the bridge at all: SSR
+ * renders, snapshot assertions pass, the suite is green, and the app does
+ * nothing. This is the harness that can see that.
+ *
+ * @example
+ * ```ts
+ * const browser = await FlowBrowser.serve(bootstrap);
+ * const page = await browser.visit("/settings");
+ * await page.waitForConnection();
+ * await page.click('[flow\\:click="save"]');
+ * await page.waitForPatch();
+ * expect(await page.text("#status")).toBe("Saved");
+ * ```
+ */
+export class FlowBrowser {
+  private readonly _app: TestApp;
+  private readonly _timeout: number;
+  private readonly _pages: BrowserPage[] = [];
+
+  private constructor(app: TestApp, timeout: number) {
+    this._app = app;
+    this._timeout = timeout;
+  }
+
+  /** Whether a browser can be reached, and how. Cached per process. */
+  static availability = browserAvailability;
+
+  /**
+   * Boot the app on an OS-assigned port and return a harness.
+   *
+   * Reuses `createTestApp()`, so the app under test is configured exactly the way
+   * the rest of the suite configures it rather than through a second bootstrap
+   * that can drift.
+   */
+  static async serve(
+    bootstrap: () => Application | Promise<Application>,
+    options: FlowBrowserOptions = {},
+  ): Promise<FlowBrowser> {
+    const availability = await browserAvailability();
+    if (!availability.available) throw new Error(`[FlowBrowser] ${availability.reason}`);
+
+    // Boot inside the bootstrap callback, so `setup` can use route macros.
+    //
+    // `createTestApp` runs `setup` between `bootstrap()` and `start()`, and a
+    // provider registers its macros in `onRegister()` — which runs during
+    // `boot()`, inside `start()`. So a `setup` that calls `Router.flow(...)`
+    // would find it undefined. `boot()` is idempotent and `start()` skips it
+    // when already booted, so pulling it forward changes only the ordering.
+    const app = await createTestApp(async () => {
+      const application = await bootstrap();
+      application.adoptAsCurrent();
+      await application.boot();
+      return application;
+    }, options.setup);
+    return new FlowBrowser(app, options.timeout ?? DEFAULT_TIMEOUT);
+  }
+
+  /** The server's base URL, e.g. `http://localhost:53211`. */
+  get url(): string {
+    return this._app.baseUrl;
+  }
+
+  /** The port the server bound. */
+  get port(): number {
+    return this._app.port;
+  }
+
+  /**
+   * Open `path` in a fresh page and wait for it to load.
+   *
+   * One page per test, torn down by {@link stop} — shared browser state across
+   * tests is the other way a browser suite becomes untrustworthy.
+   */
+  async visit(path: string): Promise<BrowserPage> {
+    const view = new Bun.WebView({ backend: backendOption() });
+    const report: TransportReport = {
+      created: 0,
+      upgraded: 0,
+      statuses: [],
+      errored: false,
+      frames: [],
+    };
+
+    // Network tracking has to be enabled before the page opens its socket, and
+    // CDP needs one navigation before it has a session — so land on a blank page
+    // first, subscribe, and only then navigate to the app.
+    await view.navigate("about:blank");
+    await view.cdp("Network.enable");
+
+    view.addEventListener("Network.webSocketCreated", () => {
+      report.created++;
+    });
+    view.addEventListener("Network.webSocketHandshakeResponseReceived", (event: Event) => {
+      if (!cdpParams<{ response: { status: number } }>(event)) return;
+      const status = event.data.response.status;
+      report.statuses.push(status);
+      if (status === 101) report.upgraded++;
+    });
+    view.addEventListener("Network.webSocketFrameReceived", (event: Event) => {
+      if (!cdpParams<{ response: { payloadData: string } }>(event)) return;
+      report.frames.push({ direction: "received", payload: event.data.response.payloadData });
+    });
+    view.addEventListener("Network.webSocketFrameSent", (event: Event) => {
+      if (!cdpParams<{ response: { payloadData: string } }>(event)) return;
+      report.frames.push({ direction: "sent", payload: event.data.response.payloadData });
+    });
+    view.addEventListener("Network.webSocketFrameError", () => {
+      report.errored = true;
+    });
+
+    await view.navigate(new URL(path, this._app.baseUrl).href);
+
+    const page = new BrowserPage(view, report, this._timeout);
+    this._pages.push(page);
+    return page;
+  }
+
+  /** Close every page this harness opened, then stop the server. */
+  async stop(): Promise<void> {
+    for (const page of this._pages) page.close();
+    this._pages.length = 0;
+    await this._app.close();
+  }
+}
+
+/** JSON-quote a value for embedding in an evaluated expression. */
+function quote(value: string): string {
+  return JSON.stringify(value);
+}

package/src/browser/chrome.ts

@@ -0,0 +1,90 @@
+/**
+ * Getting a headless browser, and saying clearly why you could not.
+ *
+ * `Bun.WebView` reaches Chrome two ways, and both are first-class here:
+ *
+ * - **spawn** — `backend: "chrome"`, which launches its own headless instance
+ *   over `--remote-debugging-pipe`. Nothing to set up.
+ * - **connect** — `backend: { type: "chrome", url }`, against a browser already
+ *   running with `--remote-debugging-port`.
+ *
+ * Connect is not a fallback for tidiness. On Windows, Bun 1.3.14 cannot spawn
+ * Chrome at all — it throws `Failed to spawn Chrome` even with `BUN_CHROME_PATH`
+ * set and the binary verified present — so connect is the only path a Windows
+ * developer has. Set `ZT_BROWSER_CDP_URL` and the harness uses it.
+ */
+
+/** How the harness reached a browser, or why it did not. */
+export interface BrowserAvailability {
+  available: boolean;
+  /** `spawn` launched its own; `connect` attached to a running one. */
+  mode: "spawn" | "connect" | "none";
+  /** Human-facing explanation — printed when a suite skips. */
+  reason: string;
+}
+
+/** Env var carrying a CDP WebSocket URL, for connect-mode. */
+export const CDP_URL_ENV = "ZT_BROWSER_CDP_URL";
+
+let _cached: BrowserAvailability | null = null;
+
+function connectUrl(): string | undefined {
+  const url = Bun.env[CDP_URL_ENV];
+  return url && url.length > 0 ? url : undefined;
+}
+
+/** The backend descriptor for a new view, honouring connect-mode when configured. */
+export function backendOption(): "chrome" | { type: "chrome"; url: string } {
+  const url = connectUrl();
+  return url ? { type: "chrome", url } : "chrome";
+}
+
+/**
+ * Whether a browser can be reached, cached for the process.
+ *
+ * Probes by actually opening a view and navigating — a Chrome binary that exists
+ * but cannot start is the failure mode worth catching, and it is invisible to a
+ * `which chrome`.
+ */
+export async function browserAvailability(): Promise<BrowserAvailability> {
+  if (_cached) return _cached;
+
+  const url = connectUrl();
+  try {
+    const view = new Bun.WebView({ backend: backendOption() });
+    try {
+      await view.navigate("about:blank");
+      await view.evaluate("1");
+    } finally {
+      view.close();
+    }
+    _cached = {
+      available: true,
+      mode: url ? "connect" : "spawn",
+      reason: url ? `connected to ${url}` : "spawned a headless Chrome",
+    };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    _cached = {
+      available: false,
+      mode: "none",
+      reason:
+        `no headless browser: ${message}\n` +
+        `  Install Chrome or Chromium, or start one with --remote-debugging-port ` +
+        `and set ${CDP_URL_ENV} to its webSocketDebuggerUrl ` +
+        `(read it from http://127.0.0.1:<port>/json/version).`,
+    };
+  }
+  return _cached;
+}
+
+/**
+ * True when a skipped browser suite is not acceptable.
+ *
+ * A browser suite that goes quietly green in CI is precisely the failure this
+ * harness exists to prevent, so CI treats "no browser" as a failure while a
+ * developer's machine treats it as a skip.
+ */
+export function browserRequired(): boolean {
+  return Bun.env["CI"] !== undefined && Bun.env["CI"] !== "" && Bun.env["CI"] !== "false";
+}

package/src/browser.ts

@@ -0,0 +1,40 @@
+/**
+ * `@zerotal/testing/browser` — drive a real page against a real server.
+ *
+ * Separate from the main entry point on purpose: this one reaches for a headless
+ * browser, and the overwhelming majority of tests neither need one nor should pay
+ * to find out whether it is there.
+ *
+ * `FlowTest` mounts a component and drives its server-side lifecycle. It cannot
+ * open the WebSocket bridge, which is where every silent failure Flow has shipped
+ * has lived: SSR renders, snapshot assertions pass, the suite is green, and the
+ * app does nothing in a browser. `FlowBrowser` is the harness that sees that.
+ *
+ * @example
+ * ```ts
+ * import { FlowBrowser } from "@zerotal/testing/browser";
+ *
+ * const availability = await FlowBrowser.availability();
+ *
+ * describe.skipIf(!availability.available)("settings", () => {
+ *   let browser: FlowBrowser;
+ *   beforeAll(async () => { browser = await FlowBrowser.serve(bootstrap); });
+ *   afterAll(async () => { await browser.stop(); });
+ *
+ *   it("saves", async () => {
+ *     const page = await browser.visit("/settings");
+ *     await page.waitForConnection();
+ *     await page.click('[flow\\:click="save"]');
+ *     await page.waitForPatch();
+ *     expect(await page.text("#status")).toBe("Saved");
+ *   });
+ * });
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+export { FlowBrowser, BrowserPage } from "./browser/FlowBrowser.ts";
+export type { FlowBrowserOptions, ObservedFrame, TransportReport } from "./browser/FlowBrowser.ts";
+export { browserAvailability, browserRequired, CDP_URL_ENV } from "./browser/chrome.ts";
+export type { BrowserAvailability } from "./browser/chrome.ts";