@jterrazz/test 9.1.0 → 9.2.1

package/README.md

@@ -1,6 +1,6 @@
 # @jterrazz/test
 
-Declarative testing framework for APIs, jobs, and CLIs. Three constructors — `specification.api()`, `specification.jobs()`, `specification.cli()` — and specs that read as sentences: given → action → assertions. The vitest test name is the spec's description; all assertions go through `expect()` with auto-registered, subject-typed matchers.
+Declarative testing framework for APIs, jobs, CLIs, and websites. Four constructors — `specification.api()`, `specification.jobs()`, `specification.cli()`, `specification.website()` — and specs that read as sentences: given → action → assertions. The vitest test name is the spec's description; all assertions go through `expect()` with auto-registered, subject-typed matchers.
 
 ```bash
 npm install -D @jterrazz/test vitest
@@ -76,9 +76,38 @@ test('builds the project', async () => {
 });
 ```
 
-Actions are **terminal**: `.request()`, `.get()`, `.trigger()`, `.exec()` execute the spec and resolve to a precisely typed result. There is no `.run()`, no label, and no `.spawn()`.
+### Website testing (browser)
 
-## The three constructors
+```typescript
+// specs/website/website.specification.ts
+import { specification } from '@jterrazz/test';
+import { afterAll } from 'vitest';
+
+export const { cleanup, website } = await specification.website({
+    server: { command: 'node specs/fixtures/website-app/server.mjs', ready: '/' },
+});
+
+afterAll(cleanup);
+```
+
+```typescript
+// specs/website/visit/head.test.ts
+import { expect, test } from 'vitest';
+import { website } from '../website.specification.js';
+
+test('captures the full head surface of a rendered page', async () => {
+    // Given - the fixture homepage
+    const result = await website.visit('/');
+
+    // Then - one golden covers title, canonical, alternates, and metas
+    expect(result.status).toBe(200);
+    expect(result.head).toMatch('home.head.json');
+});
+```
+
+Actions are **terminal**: `.request()`, `.get()`, `.trigger()`, `.exec()`, `.fetch()`, `.visit()` execute the spec and resolve to a precisely typed result. There is no `.run()`, no label, and no `.spawn()`.
+
+## The four constructors
 
 One constructor per tested interface, each returning a record destructured with its canonical name:
 
@@ -87,6 +116,7 @@ One constructor per tested interface, each returning a record destructured with
 | `specification.api(options)`      | `{ api, cleanup, docker, orchestrator }` | `.request(file)`, `.get()`, `.post()`, `.put()`, `.delete()` |
 | `specification.jobs(options)`     | `{ jobs, cleanup, orchestrator }`        | `.trigger(name)`                                             |
 | `specification.cli(bin, options)` | `{ cli, cleanup, docker, orchestrator }` | `.exec(args, { waitFor?, timeout? }?)`                       |
+| `specification.website(options)`  | `{ website, cleanup, url }`              | `.fetch(path)`, `.visit(path, scenario?)`                    |
 
 ### `specification.api({ services, server, mode?, root? })`
 
@@ -146,35 +176,57 @@ export const { cli, cleanup } = await specification.cli('my-migrate-tool', {
 const result = await cli.seed('legacy-schema.sql').exec('up');
 ```
 
+### `specification.website({ server?, url?, external?, root? })`
+
+Tests a rendered website: `.fetch(path)` for a raw HTTP exchange (redirects never followed), `.visit(path, scenario?)` for a page rendered in a real chromium. Exactly one of `server` (start the site locally — a free port injected as `PORT`, polled on `ready`) or `url` (target a running site) is required.
+
+```typescript
+export const { website, cleanup } = await specification.website({
+    server: { command: 'node specs/fixtures/website-app/server.mjs', ready: '/' },
+});
+
+// Raw exchange — status + headers, redirects surface as 3xx
+const redirect = await website.fetch('/old');
+
+// Rendered page, optionally driven by a scenario (the When)
+const page = await website.visit('/', async (visitor) => {
+    await visitor.click(link('Articles'));
+});
+```
+
+The handle destructures to `{ website, cleanup, url }` — no `docker`, no `orchestrator`. `.visit()` needs playwright (`npm install -D playwright && npx playwright install chromium`) — an optional peer dependency, only loaded when a spec actually renders a page. Full reference: [docs/11-website.md](docs/11-website.md).
+
 ### Root auto-discovery
 
-When `root` is absent, the framework walks up from the specification file to the first directory containing `docker/compose.test.yaml`, else the first containing `package.json`. Pass `root` only when the convention does not fit. `root` is strictly the **project root** (compose detection + local-bin resolution) — it is not a fixtures root; `.fixture()` resolves its own paths.
+When `root` is absent, the framework walks up from the specification file to the first directory containing `docker/compose.test.yaml`, else the first containing `package.json`. Pass `root` only when the convention does not fit. `root` is strictly the **project root** (compose detection + local-bin resolution, or the cwd of a `specification.website()` server command) — it is not a fixtures root; `.fixture()` resolves its own paths.
 
 ## Builder API
 
 ### Setup (chainable)
 
-| Method                                  | Facets    | Description                                                                                            |
-| --------------------------------------- | --------- | ------------------------------------------------------------------------------------------------------ |
-| `.seed("file.sql", { database? })`      | all       | Load SQL from `seeds/` — `database` is the record key (mandatory with ≥ 2 databases, forbidden with 1) |
-| `.fixture("file")`                      | cli       | Copy the feature-local `fixtures/file` into the working directory                                      |
-| `.fixture("$FIXTURES/name/")`           | cli       | Spread the shared `specs/fixtures/name/` project into the cwd (trailing `/` = contents; layers)        |
-| `.env({ KEY: "value" })`                | cli       | Set env vars on the child (`null` unsets, `$WORKDIR` expands, calls merge)                             |
-| `.headers({ "Accept-Language": "fr" })` | api       | Set HTTP request headers (merge on top of `.http` file headers)                                        |
-| `.intercept(contract)`                  | api, jobs | Intercept an outgoing HTTP call with a declared contract                                               |
-| `.intercept(trigger, response)`         | api, jobs | Inline intercept for one-off cases                                                                     |
+| Method                                  | Facets       | Description                                                                                            |
+| --------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------ |
+| `.seed("file.sql", { database? })`      | all          | Load SQL from `seeds/` — `database` is the record key (mandatory with ≥ 2 databases, forbidden with 1) |
+| `.fixture("file")`                      | cli          | Copy the feature-local `fixtures/file` into the working directory                                      |
+| `.fixture("$FIXTURES/name/")`           | cli          | Spread the shared `specs/fixtures/name/` project into the cwd (trailing `/` = contents; layers)        |
+| `.env({ KEY: "value" })`                | cli          | Set env vars on the child (`null` unsets, `$WORKDIR` expands, calls merge)                             |
+| `.headers({ "Accept-Language": "fr" })` | api, website | Set HTTP request headers (merge on top of `.http` file headers, or on the browser context)             |
+| `.intercept(contract)`                  | api, jobs    | Intercept an outgoing HTTP call with a declared contract                                               |
+| `.intercept(trigger, response)`         | api, jobs    | Inline intercept for one-off cases                                                                     |
 
 ### Actions (terminal)
 
-| Method                                     | Facet | Resolves to  | Description                                                                        |
-| ------------------------------------------ | ----- | ------------ | ---------------------------------------------------------------------------------- |
-| `.request("create-user.http")`             | api   | `HttpResult` | Send the COMPLETE request from `requests/<file>` (method, path, headers, raw body) |
-| `.get(path)` / `.delete(path)`             | api   | `HttpResult` | Inline requests for simple cases                                                   |
-| `.post(path, body?)` / `.put(path, body?)` | api   | `HttpResult` | Inline body: plain object, JSON-serialized                                         |
-| `.trigger("name")`                         | jobs  | `BaseResult` | Execute a registered job                                                           |
-| `.exec("args")`                            | cli   | `CliResult`  | Run the command                                                                    |
-| `.exec(["build", "start"])`                | cli   | `CliResult`  | Sequence in the same cwd; stops on first non-zero exit                             |
-| `.exec("dev", { waitFor, timeout? })`      | cli   | `CliResult`  | Long-running: resolves at the pattern, killed at `timeout` (default 10 s)          |
+| Method                                     | Facet   | Resolves to   | Description                                                                           |
+| ------------------------------------------ | ------- | ------------- | ------------------------------------------------------------------------------------- |
+| `.request("create-user.http")`             | api     | `HttpResult`  | Send the COMPLETE request from `requests/<file>` (method, path, headers, raw body)    |
+| `.get(path)` / `.delete(path)`             | api     | `HttpResult`  | Inline requests for simple cases                                                      |
+| `.post(path, body?)` / `.put(path, body?)` | api     | `HttpResult`  | Inline body: plain object, JSON-serialized                                            |
+| `.trigger("name")`                         | jobs    | `BaseResult`  | Execute a registered job                                                              |
+| `.exec("args")`                            | cli     | `CliResult`   | Run the command                                                                       |
+| `.exec(["build", "start"])`                | cli     | `CliResult`   | Sequence in the same cwd; stops on first non-zero exit                                |
+| `.exec("dev", { waitFor, timeout? })`      | cli     | `CliResult`   | Long-running: resolves at the pattern, killed at `timeout` (default 10 s)             |
+| `.fetch(path)`                             | website | `FetchResult` | One raw HTTP exchange — redirects surface as 3xx, never followed                      |
+| `.visit(path, scenario?)`                  | website | `PageResult`  | Render the page in a shared chromium; with a scenario, the capture is the final state |
 
 One chain = one terminal action; databases reset at the start of every chain. Every cli spec runs in a fresh, empty temp directory.
 
@@ -322,13 +374,14 @@ These conventions are not just prose: the package ships an oxlint plugin (`@jter
 
 ## Requirements
 
-- **Docker** - testcontainers for node mode, docker compose for compose mode; not needed for `sqlite()` or plain cli specs
+- **Docker** - testcontainers for node mode, docker compose for compose mode; not needed for `sqlite()`, plain cli specs, or website specs
 - **vitest** - peer dependency
+- **playwright** - optional peer dependency, only needed for `.visit()`: `npm install -D playwright && npx playwright install chromium`
 - **msw** - bundled as a direct dependency (powers `.intercept()`); no separate install
 - **hono** (or any web framework) - supplied by your project for in-process apps; the adapter only needs an object with a `request()` method, so it is not a peer
 
 ## Docs
 
-- Guide (chapters): [docs/README.md](docs/README.md) — getting started, API/jobs/CLI specs, assertions, tokens, contracts, services, conventions, linting
+- Guide (chapters): [docs/README.md](docs/README.md) — getting started, API/jobs/CLI/website specs, assertions, tokens, contracts, services, conventions, linting
 - API reference: committed under [docs/reference/](docs/reference/) — compiled from source by `npm run docs`
 - Agent skill: [skills/jterrazz-test/](skills/jterrazz-test/) — mental model, per-facet references, generated rule reference

package/dist/index.d.ts

@@ -496,6 +496,116 @@ interface InterceptContract {
  */
 declare function defineContract(contract: InterceptContract): InterceptContract;
 //#endregion
+//#region src/core/ports/browser.port.d.ts
+/**
+ * A user-facing element descriptor — pure data, built by the element
+ * vocabulary (`button()`, `link()`, `field()`, …) and translated into
+ * concrete locators by the browser integration. CSS/XPath selectors are
+ * deliberately not expressible: user-facing elements are the only surface.
+ */
+interface ElementRef {
+  kind: 'button' | 'field' | 'heading' | 'link' | 'testId' | 'text';
+  name: string;
+}
+/** A `<link>` element captured from the rendered document's head. */
+interface BrowserLinkElement {
+  href: string;
+  hreflang?: string;
+  rel: string;
+  type?: string;
+}
+/** A `<meta>` element captured from the rendered document's head. */
+interface BrowserMetaElement {
+  content: string;
+  name?: string;
+  property?: string;
+}
+/** A console message emitted while the page loaded or the scenario ran. */
+interface BrowserConsoleMessage {
+  text: string;
+  type: string;
+}
+/**
+ * The visitor — the interaction vocabulary handed to a visit scenario.
+ * Every action auto-waits (playwright actionability); `see()` is the single
+ * synchronization primitive: it retries until the element is visible and
+ * fails at the timeout. There is no sleep and no conditional helper.
+ */
+interface Visitor {
+  /** Check a checkbox or radio. */
+  check: (element: ElementRef) => Promise<void>;
+  /** Click the element. */
+  click: (element: ElementRef) => Promise<void>;
+  /** Fill a form field with a value. */
+  fill: (element: ElementRef, value: string) => Promise<void>;
+  /** Navigate to a path of the site under test. */
+  goto: (path: string) => Promise<void>;
+  /** Hover the element. */
+  hover: (element: ElementRef) => Promise<void>;
+  /** Press a key (e.g. `Enter`). */
+  press: (key: string) => Promise<void>;
+  /** Wait until the element is visible — the only synchronization primitive. */
+  see: (element: ElementRef) => Promise<void>;
+  /** Select an option in a select field. */
+  select: (element: ElementRef, option: string) => Promise<void>;
+}
+/** The behavior of a visit — the When of the spec; assertions stay in the Then. */
+type VisitScenario = (visitor: Visitor) => Promise<void>;
+/** Per-visit options forwarded to the browser context. */
+interface BrowserOpenOptions {
+  /**
+   * Base URL of the site under test — the origin `goto()` resolves against
+   * and the boundary of the `external` policy.
+   */
+  baseUrl: string;
+  /**
+   * Cross-origin request policy. `'block'` aborts every request leaving
+   * the site under test (analytics, CDNs) — the browser-side analog of
+   * strict intercepts. `'allow'` lets them through (deployed-site mode).
+   */
+  external: 'allow' | 'block';
+  /** Extra HTTP headers sent with every request of the visit (incl. User-Agent overrides). */
+  headers?: Record<string, string>;
+  /** The interaction scenario to run after load; the capture reflects the final state. */
+  scenario?: VisitScenario;
+}
+/**
+ * The rendered page captured by a browser visit — the FINAL state when a
+ * scenario ran. Extraction happens in-page (the browser IS the HTML
+ * parser); interpretation of the raw elements belongs to core.
+ */
+interface BrowserPage {
+  /** Console messages emitted while loading and interacting, in order. */
+  consoleMessages: BrowserConsoleMessage[];
+  /** Serialized DOM after rendering (`document.documentElement.outerHTML`). */
+  html: string;
+  /** Raw text content of every `application/ld+json` script, in DOM order. */
+  jsonLdBlocks: string[];
+  /** `<link>` elements of the head, in DOM order. */
+  links: BrowserLinkElement[];
+  /** `<meta>` elements of the head, in DOM order. */
+  metas: BrowserMetaElement[];
+  /** HTTP status of the main document response (0 when unavailable). */
+  status: number;
+  /** Rendered `document.body.innerText`. */
+  text: string;
+  /** `document.title` after rendering. */
+  title: string;
+  /** Final URL after redirects and scenario navigation. */
+  url: string;
+}
+/**
+ * Abstract browser interface for the website specification runner.
+ * One implementation lives in `integrations/playwright/` — a single shared
+ * browser instance per runner; each `open()` gets a fresh, isolated context.
+ */
+interface BrowserPort {
+  /** Close the shared browser instance (idempotent). */
+  close: () => Promise<void>;
+  /** Load `url` in a fresh context, run the scenario, capture the final page. */
+  open: (url: string, options: BrowserOpenOptions) => Promise<BrowserPage>;
+}
+//#endregion
 //#region src/core/ports/isolation.port.d.ts
 /**
  * Strategy for isolating service state across parallel test workers.
@@ -623,6 +733,83 @@ declare class HttpResult extends BaseResult {
   get status(): number;
 }
 //#endregion
+//#region src/core/specification/website/result.d.ts
+/** A raw HTTP exchange captured by `.fetch()` — redirects are NOT followed. */
+interface FetchExchange {
+  body: string;
+  headers: Record<string, string>;
+  status: number;
+}
+/** Result from a raw `.fetch()` action (robots.txt, sitemaps, redirects). */
+declare class FetchResult extends BaseResult {
+  private readonly exchange;
+  constructor(options: {
+    config: SpecificationConfig;
+    exchange: FetchExchange;
+    testDir: string;
+  });
+  /** The response body as a text accessor (`toMatch('robots.txt')`, `.grep()`). */
+  get body(): TextAccessor;
+  /** Response headers as a flat, lower-cased key-value map. */
+  get headers(): Record<string, string>;
+  /** The response body parsed as JSON. */
+  get json(): JsonAccessor;
+  /** The `location` header of a redirect response, or undefined. */
+  get location(): string | undefined;
+  /** The HTTP response status code — redirects surface as 3xx, never followed. */
+  get status(): number;
+}
+/** Result from a rendered `.visit()` action — the page as a browser saw it. */
+declare class PageResult extends BaseResult {
+  private readonly page;
+  constructor(options: {
+    config: SpecificationConfig;
+    page: BrowserPage;
+    testDir: string;
+  });
+  /** Hreflang alternates declared in the head, keyed by language code. */
+  get alternates(): Record<string, string>;
+  /** The canonical URL declared in the head, or null. */
+  get canonical(): null | string;
+  /**
+   * The browser console as a stream — one message per line, prefixed by
+   * its type — same shape as `stdout` on a cli result. Assert emptiness
+   * with `toBeEmpty()`, or snapshot with `toMatch('home.console.txt')`.
+   */
+  get console(): TextAccessor;
+  /**
+   * Console messages of type `error` only — the stream you usually want
+   * empty: `expect(result.errors).toBeEmpty()`. Same shape as `stderr` on
+   * a cli result.
+   */
+  get errors(): TextAccessor;
+  /**
+   * The document-head projection as a JSON accessor — title, canonical,
+   * hreflang alternates, and named metas — for one golden per page:
+   * `expect(result.head).toMatch('home.head.json')`.
+   */
+  get head(): JsonAccessor;
+  /** The rendered DOM serialization as a text accessor. */
+  get html(): TextAccessor;
+  /**
+   * Every `application/ld+json` block of the page, parsed, as one JSON
+   * array — `expect(result.jsonLd).toMatch('article.jsonld.json')`.
+   */
+  get jsonLd(): JsonAccessor;
+  /** `<link>` elements of the head, in DOM order. */
+  get links(): BrowserLinkElement[];
+  /** The content of a named meta — `meta('description')`, `meta('og:image')`. */
+  meta(name: string): string | undefined;
+  /** HTTP status of the main document response. */
+  get status(): number;
+  /** Rendered body text as a text accessor. */
+  get content(): TextAccessor;
+  /** The document title as a text accessor. */
+  get title(): TextAccessor;
+  /** Final URL after redirects. */
+  get url(): string;
+}
+//#endregion
 //#region src/core/specification/shared/builder.d.ts
 /** A named job that can be triggered via jobs.trigger(). */
 interface JobHandle {
@@ -642,6 +829,20 @@ interface DockerSpecConfig {
 }
 /** Adapter configuration passed to the specification facets at setup time. */
 interface SpecificationConfig {
+  /** Base URL of the website under test (website facet only). */
+  baseUrl?: string;
+  /**
+   * Lazy browser accessor (website facet only). The first `.visit()`
+   * launches the shared browser instance; `.fetch()`-only spec files never
+   * pay the browser cost.
+   */
+  browser?: () => Promise<BrowserPort>;
+  /**
+   * Cross-origin request policy for visits (website facet only): `'block'`
+   * aborts requests leaving the site under test — the browser-side analog
+   * of strict intercepts.
+   */
+  external?: 'allow' | 'block';
   command?: CliPort;
   database?: DatabasePort;
   /**
@@ -750,6 +951,24 @@ interface CliSpecification<DatabaseKey extends string = string> {
    */
   exec: (args?: string | string[], options?: ExecOptions) => Promise<CliResult>;
 }
+/**
+ * The `website` facet — page chain entry handed out by
+ * `specification.website()`. Setup methods chain; action methods are
+ * terminal. `.visit()` renders the page in the shared browser; `.fetch()`
+ * performs one raw HTTP exchange and never follows redirects.
+ */
+interface WebsiteSpecification {
+  /** Set HTTP headers for the exchange (incl. User-Agent overrides). Multiple calls merge. */
+  headers: (headers: Record<string, string>) => WebsiteSpecification;
+  /** Perform one raw HTTP GET — redirects surface as 3xx results, never followed. */
+  fetch: (path: string) => Promise<FetchResult>;
+  /**
+   * Render the page in the shared browser and resolve with the captured
+   * document. With a scenario, the visitor interacts first (the When) and
+   * the capture reflects the FINAL page state.
+   */
+  visit: (path: string, scenario?: VisitScenario) => Promise<PageResult>;
+}
 //#endregion
 //#region src/core/specification/cli/result.d.ts
 /**
@@ -1101,6 +1320,65 @@ interface JobsHandle<DatabaseKey extends string = string> {
 }
 declare function startJobs<Services extends ServiceRecord>(options: JobsSpecificationOptions<Services>): Promise<JobsHandle<DatabaseKeys<Services>>>;
 //#endregion
+//#region src/core/specification/website/serve.adapter.d.ts
+/** Options for the local server started by `specification.website()`. */
+interface ServeOptions {
+  /** Shell command that starts the site. Receives the chosen port as `PORT`. */
+  command: string;
+  /** Fixed port. Default: an OS-assigned free port, injected as `PORT`. */
+  port?: number;
+  /** Path polled until it answers with any HTTP status. Default `/`. */
+  ready?: string;
+  /** Readiness budget in milliseconds. Default 30 000. */
+  timeout?: number;
+}
+//#endregion
+//#region src/core/specification/website/start-website.d.ts
+/**
+ * Options for {@link startWebsite | specification.website}. `server` (start
+ * the site locally) and `url` (target a running site) are mutually
+ * exclusive BY TYPE — the union makes the invalid combinations
+ * inexpressible rather than runtime-checked.
+ */
+type WebsiteSpecificationOptions = {
+  /**
+   * Cross-origin request policy for visits. Default: `'block'` with a
+   * local `server` (deterministic — analytics and CDNs never leave the
+   * machine), `'allow'` with a deployed `url`.
+   */
+  external?: 'allow' | 'block';
+  /**
+   * Project-root override (CONVENTIONS A9): the working directory of the
+   * `server` command. Auto-discovered from the calling file when absent.
+   */
+  root?: string;
+} & ({
+  /**
+   * Start the site locally: a shell command receiving a free port
+   * as `PORT`, polled on `ready` (default `/`) until it answers.
+   */
+  server: ServeOptions;
+  url?: never;
+} | {
+  server?: never;
+  /** Target an already-running site (a deployed or preview URL). */
+  url: string;
+});
+/**
+ * The record returned by {@link startWebsite | specification.website}.
+ * Destructure with the canonical names (CONVENTIONS A3):
+ *
+ *     const { website, cleanup } = await specification.website(…);
+ */
+interface WebsiteHandle {
+  /** Stop the server process and the shared browser instance. */
+  cleanup: () => Promise<void>;
+  /** The base URL the specs run against. */
+  url: string;
+  website: WebsiteSpecification;
+}
+declare function startWebsite(options: WebsiteSpecificationOptions): Promise<WebsiteHandle>;
+//#endregion
 //#region src/core/specification/shared/specification.d.ts
 /**
  * The three specification constructors (CONVENTIONS A2) — created in a
@@ -1146,6 +1424,14 @@ declare const specification: {
    * server, no mode. `.trigger(name)` is the terminal action.
    */
   jobs: typeof startJobs;
+  /**
+   * Test a deployed or locally-served website. `server` starts the site
+   * (a shell command receiving `PORT`); `url` targets a running one.
+   * `.visit(path)` renders the page in a single shared browser instance;
+   * `.fetch(path)` performs one raw HTTP exchange (redirects never
+   * followed).
+   */
+  website: typeof startWebsite;
 };
 //#endregion
 //#region src/integrations/docker/docker-lookup.d.ts
@@ -1176,6 +1462,26 @@ interface ContainerPort {
   getLogs: () => Promise<string>;
 }
 //#endregion
+//#region src/core/specification/website/elements.d.ts
+/**
+ * The element vocabulary — user-facing descriptors for visit scenarios.
+ * Reads like English (`click(link('Articles'))`), translates to
+ * accessibility-first locators in the browser integration. CSS/XPath is
+ * deliberately not expressible; `testId()` is the single escape hatch.
+ */
+/** A button (or element with the button role), by accessible name. */
+declare const button: (name: string) => ElementRef;
+/** A form field, by label. */
+declare const field: (label: string) => ElementRef;
+/** A heading, by accessible name. */
+declare const heading: (name: string) => ElementRef;
+/** A link, by accessible name. */
+declare const link: (name: string) => ElementRef;
+/** An element containing the given text. */
+declare const content: (value: string) => ElementRef;
+/** The escape hatch: an element by `data-testid`. Prefer user-facing elements. */
+declare const testId: (id: string) => ElementRef;
+//#endregion
 //#region src/integrations/postgres/postgres.d.ts
 interface PostgresOptions {
   /**
@@ -1466,8 +1772,13 @@ declare const mockOfDate: MockDatePort;
 //#region src/index.d.ts
 declare module 'vitest' {
   interface Matchers<T = any> {
-    /** Assert the table has zero rows. Async — queries the database. */
-    toBeEmpty: T extends TableAccessor ? () => Promise<void> : never;
+    /**
+     * Assert the subject is empty — zero rows for a table (async), an
+     * empty stream for a text accessor (console, errors, stdout).
+     */
+    toBeEmpty: T extends TableAccessor ? () => Promise<void> : T extends {
+      readonly comparableText: string;
+    } ? () => Promise<void> : never;
     /** Assert the container is running. Async — docker-backed subject. */
     toBeRunning: T extends ContainerAccessor ? () => Promise<void> : never;
     /**
@@ -1498,4 +1809,4 @@ declare module 'vitest' {
   }
 }
 //#endregion
-export { type ApiHandle, type ApiSpecification, type ApiSpecificationOptions, BaseResult, type CaptureScope, type CliEnv, type CliHandle, type CliOutput, type CliPort, CliResult, type CliSpecification, type CliSpecificationOptions, ContainerAccessor, type ContainerPort, type DatabaseKeys, type DatabasePort, DirectoryAccessor, type DockerSpecConfig, type ExecOptions, type FileAccessor, FilesystemAccessor, type HonoApp, HttpResult, type InterceptContract, type InterceptEntry, type InterceptResponder, type InterceptResponse, type InterceptResponseValue, type InterceptTrigger, type IsolationStrategy, type JobHandle, type JobsHandle, type JobsSpecification, type JobsSpecificationOptions, JsonAccessor, type MatchFixtureOptions, type MatchableRequest, Matcher, type MatcherKind, type MockDatePort, type MockPort, Orchestrator, type PostgresOptions, type RedisOptions, ResponseAccessor, type ServerPort, type ServerResponse, type ServiceHandle, type ServiceRecord, type SpecificationConfig, type SpecificationMode, type SqliteOptions, TableAccessor, TextAccessor, anthropic, defineContract, findContainersByLabel, http, inspectContainer, match, mockOf, mockOfDate, openai, postgres, redis, removeContainers, specification, sqlite, text };
+export { type ApiHandle, type ApiSpecification, type ApiSpecificationOptions, BaseResult, type BrowserConsoleMessage, type BrowserLinkElement, type BrowserMetaElement, type BrowserOpenOptions, type BrowserPage, type BrowserPort, type CaptureScope, type CliEnv, type CliHandle, type CliOutput, type CliPort, CliResult, type CliSpecification, type CliSpecificationOptions, ContainerAccessor, type ContainerPort, type DatabaseKeys, type DatabasePort, DirectoryAccessor, type DockerSpecConfig, type ElementRef, type ExecOptions, FetchResult, type FileAccessor, FilesystemAccessor, type HonoApp, HttpResult, type InterceptContract, type InterceptEntry, type InterceptResponder, type InterceptResponse, type InterceptResponseValue, type InterceptTrigger, type IsolationStrategy, type JobHandle, type JobsHandle, type JobsSpecification, type JobsSpecificationOptions, JsonAccessor, type MatchFixtureOptions, type MatchableRequest, Matcher, type MatcherKind, type MockDatePort, type MockPort, Orchestrator, PageResult, type PostgresOptions, type RedisOptions, ResponseAccessor, type ServeOptions, type ServerPort, type ServerResponse, type ServiceHandle, type ServiceRecord, type SpecificationConfig, type SpecificationMode, type SqliteOptions, TableAccessor, TextAccessor, type VisitScenario, type Visitor, type WebsiteHandle, type WebsiteSpecification, type WebsiteSpecificationOptions, anthropic, button, content, defineContract, field, findContainersByLabel, heading, http, inspectContainer, link, match, mockOf, mockOfDate, openai, postgres, redis, removeContainers, specification, sqlite, testId, text };