@jterrazz/test 12.1.0 → 13.0.0

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+import { Scalar } from "yaml";
 import { DeepMockProxy } from "vitest-mock-extended";
 //#region src/core/matching/match.d.ts
 /**
@@ -390,9 +391,20 @@ type CliEnv = Record<string, null | string>;
  * Abstract command interface for specification runners.
  * Implement this to plug in your command execution strategy.
  */
+/**
+ * What one invocation is handed beyond its arguments — the two per-run inputs a
+ * spec document may state. Both are absent by default: the child gets an
+ * immediately-closed stdin (never a TTY) and the adapter's own timeout.
+ */
+interface CliInput {
+  /** Written to the child's stdin, which is then closed. */
+  stdin?: string;
+  /** Milliseconds after which the run is killed (exit code 124). */
+  timeout?: number;
+}
 interface CliPort {
   /** Execute a command with the given arguments in the given working directory. */
-  exec: (args: string, cwd: string, env?: CliEnv) => Promise<CliOutput>;
+  exec: (args: string, cwd: string, env?: CliEnv, input?: CliInput) => Promise<CliOutput>;
   /** Run a long-running process and wait for a pattern or timeout. */
   watch: (args: string, cwd: string, options: ExecOptions, env?: CliEnv) => Promise<CliOutput>;
 }
@@ -926,6 +938,49 @@ declare class HttpResult extends BaseResult {
   get status(): number;
 }
 //#endregion
+//#region src/core/specification/cli/literate.d.ts
+/**
+ * Running a `<case>.spec.yaml` document: one scenario, one working directory,
+ * one set of servers, every run executed and asserted.
+ *
+ * The engine composes pieces that already exist rather than adding a second of
+ * anything — {@link copyPlan} for `fixture:`, the runner's own command adapter
+ * for each run, {@link ServeAdapter} for `serve:`, the `{{token}}` engine for
+ * every comparison, and {@link mergeTextPreservingPlaceholders} for the
+ * rewrite. What is new here is only the ORCHESTRATION the chain cannot express:
+ * several commands sharing one working directory, each asserted, none stopping
+ * the run.
+ */
+/**
+ * A server a document may start by name (`serve: mcp`), registered once per app
+ * in the `serve` option of `specification.cli()`.
+ */
+interface LiterateServeRegistration {
+  /** Shell command that starts the server, run from the project root. */
+  command: string;
+  /** The variable the resolved URL is bound to in every run's child env. */
+  env: string;
+  /**
+   * Matched against the server's output; the FIRST capture group is the port
+   * it chose — named (`(?<port>\d+)`) or not, it is group 1 either way.
+   */
+  ready: RegExp;
+  /** Builds the URL bound to {@link env} from the announced port. */
+  url: (port: number) => string;
+}
+/** Per-call options for {@link runSpecDocument} / `cli.run()`. */
+interface LiterateRunFlags {
+  /**
+   * Opt this document OUT of the update-mode rewrite. A frozen document is
+   * NEVER written under `TEST_UPDATE=1`: its mismatch still throws its diff.
+   * That is what makes a DELIBERATELY-WRONG `.spec.yaml` — one whose failure
+   * rendering is the subject of a negative test — survive an update run
+   * instead of being silently corrected into a passing file. The document's
+   * mirror of `toMatch(name, { frozen: true })`.
+   */
+  frozen?: boolean;
+}
+//#endregion
 //#region src/core/specification/mobile/result.d.ts
 /** Result from a `.open()` action — the screen as the device saw it, final state. */
 declare class ScreenResult extends BaseResult {
@@ -1135,13 +1190,25 @@ interface SpecificationConfig {
    * facet factories auto-populate this when `dockerConfig` is present.
    */
   dockerTestRunId?: string;
+  /**
+   * Named environment SETS a spec document may name by bare word
+   * (`env: frozen`). Declared once per app in `specification.cli()`.
+   */
+  envSets?: Record<string, CliEnv>;
   /**
    * When set, `.intercept()` is unavailable on this runner and throws this
    * reason immediately (compose mode — MSW is in-process, CONVENTIONS I3).
    */
   interceptDisabledReason?: string;
   jobs?: JobHandle[];
+  /** The project root — the working directory a document's `serve:` command runs from. */
+  root?: string;
   server?: ServerPort;
+  /**
+   * Named servers a spec document may start (`serve: [mcp]`). Declared once
+   * per app in `specification.cli()`.
+   */
+  serveRegistry?: Record<string, LiterateServeRegistration>;
   /**
    * The declared services record. In cli mode, drives the automatic
    * connection-URL injection into the child env (CONVENTIONS B6):
@@ -1230,6 +1297,14 @@ interface CliSpecification<DatabaseKey extends string = string> {
    * timeout.
    */
   exec: (args?: string | string[], options?: ExecOptions) => Promise<CliResult>;
+  /**
+   * Run a `<case>.spec.yaml` document — its ground (fixtures, env sets,
+   * servers) and every run, each asserted — and resolve with the LAST run's
+   * result, so a `.test.ts` can add an assertion the document cannot express
+   * (a directory golden, a grep). The path is relative to the test file's own
+   * directory, where the document lives.
+   */
+  run: (file: string, options?: LiterateRunFlags) => Promise<CliResult>;
 }
 /**
  * The `website` facet — page chain entry handed out by
@@ -1561,6 +1636,20 @@ interface CliSpecificationOptions<Services extends ServiceRecord = ServiceRecord
    * containers get force-removed at scope exit (CONVENTIONS B5).
    */
   docker?: DockerSpecConfig;
+  /**
+   * Named environment SETS for literate `.cli` specs. A header line
+   * `env: frozen` applies the whole `frozen` record; `$WORKDIR` expands and
+   * `null` unsets, exactly as in `.env()`. Declared once per app so a
+   * scenario file states WHICH ground it stands on, not how to build it.
+   */
+  env?: Record<string, CliEnv>;
+  /**
+   * Named servers a literate `.cli` header may start (`serve: mcp KEY=value`).
+   * Each entry names the shell `command`, the `ready` regex whose capture
+   * group holds the port the server announces, the `url(port)` builder, and
+   * the `env` variable that URL is bound to in every block's child.
+   */
+  serve?: Record<string, LiterateServeRegistration>;
   /**
    * Project-root override (CONVENTIONS A9) — the single meaning of `root`:
    * it anchors compose detection and local-bin resolution for the tested
@@ -1699,14 +1788,24 @@ interface MobileHandle {
 declare function startMobile(options: MobileSpecificationOptions): Promise<MobileHandle>;
 //#endregion
 //#region src/core/specification/website/serve.adapter.d.ts
-/** Options for the local server started by `specification.website()`. */
+/** Options for a local server started by the framework. */
 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;
+  /**
+   * How readiness is observed. Two forms:
+   *
+   * - a **path** (or nothing) — the framework picks the port, injects it as
+   *   `PORT`, and polls `<baseUrl><path>` until it answers any HTTP status
+   *   (default `/`). This is `specification.website()`'s form.
+   * - a **regex over the child's output** with ONE capture group holding the
+   *   port the server chose itself. Nothing is injected as `PORT`: the server
+   *   announces its port and the framework reads it from the banner. This is
+   *   the form a literate `serve:` registration uses.
+   */
+  ready?: RegExp | string;
   /** Readiness budget in milliseconds. Default 30 000. */
   timeout?: number;
 }
@@ -1840,6 +1939,86 @@ declare const specification: {
   website: typeof startWebsite;
 };
 //#endregion
+//#region src/core/literate/spec-document.d.ts
+/**
+ * The facets a document may describe. `cli` is the only one implemented; the
+ * key exists so a second facet can arrive without a second grammar.
+ */
+declare const SPEC_KINDS: readonly ["cli"];
+type SpecKind = (typeof SPEC_KINDS)[number];
+/** One `env:` entry — a bare word naming a registered set, or a `KEY=value` pair. */
+type SpecEnvToken = {
+  key: string;
+  kind: 'pair';
+  line: number;
+  value: string;
+} | {
+  kind: 'set';
+  line: number;
+  name: string;
+};
+/** One `serve:` entry — a registered server plus the extra env it is started with. */
+interface SpecServeEntry {
+  env: Record<string, string>;
+  line: number;
+  name: string;
+}
+/** One `fixture:` entry — a path with the line it was declared on. */
+interface SpecFixture {
+  line: number;
+  path: string;
+}
+/** An expected stream: its text, and the first line of that text in the file. */
+interface SpecStream {
+  /** 1-based line the scalar's content starts on — where a token defect is reported. */
+  line: number;
+  text: string;
+}
+/** One `files:` assertion, keyed by a workdir-relative path. */
+type SpecFileAssertion = {
+  contains: SpecStream[];
+  equals: null | SpecStream;
+  kind: 'content';
+  line: number;
+  path: string;
+} | {
+  kind: 'absent';
+  line: number;
+  path: string;
+} | {
+  kind: 'exists';
+  line: number;
+  path: string;
+};
+/** One run: a command, what it must exit with, and what it must have produced. */
+interface SpecRun {
+  command: string;
+  /** 1-based line of the `command:` key — the frame a failure points at. */
+  commandLine: number;
+  exitCode: number;
+  files: SpecFileAssertion[];
+  /** `null` when the key is absent, which asserts an empty stream. */
+  stderr: null | SpecStream;
+  /** Written to the child then closed; `null` keeps the empty-pipe EOF. */
+  stdin: null | string;
+  stdout: null | SpecStream;
+  timeout: null | number;
+  /** Only ever on the LAST run — a long-running command ends the session. */
+  waitFor: null | string;
+}
+/** A parsed `<case>.spec.yaml`. */
+interface SpecDocument {
+  /** The vitest test title. */
+  description: string;
+  /** 1-based line of the `description:` key. */
+  descriptionLine: number;
+  env: SpecEnvToken[];
+  fixtures: SpecFixture[];
+  kind: SpecKind;
+  runs: SpecRun[];
+  serve: SpecServeEntry[];
+}
+//#endregion
 //#region src/integrations/docker/docker-lookup.d.ts
 /** Return all container IDs (running or stopped) that carry `key=value`. */
 declare function findContainersByLabel(key: string, value: string): string[];
@@ -2262,7 +2441,7 @@ declare const mockOfDate: MockDatePort;
 //#endregion
 //#region src/index.d.ts
 declare module 'vitest' {
-  interface Matchers<T = any> {
+  interface Assertion<T = any> {
     /**
      * Assert the subject is empty — zero rows for a table (async), an
      * empty stream for a text accessor (console, errors, stdout).
@@ -2272,17 +2451,6 @@ declare module 'vitest' {
     } ? () => Promise<void> : never;
     /** Assert the container is running. Async — docker-backed subject. */
     toBeRunning: T extends ContainerAccessor ? () => Promise<void> : never;
-    /**
-     * Assert the table contains exactly the given rows for the given
-     * columns. Cells accept `match.*` dynamic-value matchers. Async —
-     * queries the database.
-     */
-    toMatchRows: T extends TableAccessor ? (expected: {
-      columns: string[];
-      rows: readonly (readonly unknown[])[];
-    }) => Promise<void> : never;
-  }
-  interface Assertion<T = any> {
     /**
      * On `@jterrazz/test` accessors: assert the subject matches a fixture
      * file under `expected/<name>` (flat — a slash creates a subfolder;
@@ -2297,7 +2465,16 @@ declare module 'vitest' {
      * the behaviour under test.
      */
     toMatch: T extends DirectoryAccessor | FilesystemAccessor ? (name: RegExp | string, options?: MatchFixtureOptions) => Promise<void> : T extends JsonAccessor | ResponseAccessor | TextAccessor ? (name: RegExp | string, options?: MatchFixtureOptions) => void : (expected: RegExp | string, options?: MatchFixtureOptions) => void;
+    /**
+     * Assert the table contains exactly the given rows for the given
+     * columns. Cells accept `match.*` dynamic-value matchers. Async —
+     * queries the database.
+     */
+    toMatchRows: T extends TableAccessor ? (expected: {
+      columns: string[];
+      rows: readonly (readonly unknown[])[];
+    }) => Promise<void> : never;
   }
 }
 //#endregion
-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 Contract, type ContractInput, type ContractRequest, type ContractResponder, type ContractResponse, type ContractResponseValue, type Contracts, type DatabaseKeys, type DatabasePort, type DeviceOpenOptions, type DevicePort, type DeviceScreen, DirectoryAccessor, type DockerSpecConfig, type ElementKind, type ElementMatch, type ElementOptions, type ElementRef, type ExecOptions, FetchResult, type FileAccessor, FilesystemAccessor, type HonoApp, type HttpContractFilter, type HttpResponseInit, HttpResult, type IsolationStrategy, type JobHandle, type JobsHandle, type JobsSpecification, type JobsSpecificationOptions, JsonAccessor, type LandmarkKind, type MatchFixtureOptions, type MatchableRequest, Matcher, type MatcherKind, type MobileBackendOptions, type MobileElementKind, type MobileElementMatch, type MobileElementRef, type MobileHandle, type MobileScenario, type MobileSpecification, type MobileSpecificationOptions, type MobileVisitor, type MockDatePort, type MockPort, Orchestrator, PageResult, type PostgresOptions, type RedisOptions, ResponseAccessor, type ScreenNode, ScreenResult, type ServeOptions, type ServerPort, type ServerResponse, type ServiceHandle, type ServiceRecord, type SpecificationConfig, type SpecificationMode, type SqliteOptions, TableAccessor, TextAccessor, type TextFilter, type VisitScenario, type Visitor, type WebsiteBackendOptions, type WebsiteHandle, type WebsiteSpecification, type WebsiteSpecificationOptions, anthropic, banner, button, complementary, content, contentinfo, defineContract, defineContracts, field, findContainersByLabel, form, heading, http, inspectContainer, link, main, match, mockOf, mockOfDate, navigation, openai, postgres, redis, region, removeContainers, search, specification, sqlite, testId, text, within };
+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 CliInput, type CliOutput, type CliPort, CliResult, type CliSpecification, type CliSpecificationOptions, ContainerAccessor, type ContainerPort, type Contract, type ContractInput, type ContractRequest, type ContractResponder, type ContractResponse, type ContractResponseValue, type Contracts, type DatabaseKeys, type DatabasePort, type DeviceOpenOptions, type DevicePort, type DeviceScreen, DirectoryAccessor, type DockerSpecConfig, type ElementKind, type ElementMatch, type ElementOptions, type ElementRef, type ExecOptions, FetchResult, type FileAccessor, FilesystemAccessor, type HonoApp, type HttpContractFilter, type HttpResponseInit, HttpResult, type IsolationStrategy, type JobHandle, type JobsHandle, type JobsSpecification, type JobsSpecificationOptions, JsonAccessor, type LandmarkKind, type LiterateRunFlags, type LiterateServeRegistration, type MatchFixtureOptions, type MatchableRequest, Matcher, type MatcherKind, type MobileBackendOptions, type MobileElementKind, type MobileElementMatch, type MobileElementRef, type MobileHandle, type MobileScenario, type MobileSpecification, type MobileSpecificationOptions, type MobileVisitor, type MockDatePort, type MockPort, Orchestrator, PageResult, type PostgresOptions, type RedisOptions, ResponseAccessor, type ScreenNode, ScreenResult, type ServeOptions, type ServerPort, type ServerResponse, type ServiceHandle, type ServiceRecord, type SpecDocument, type SpecEnvToken, type SpecFileAssertion, type SpecFixture, type SpecKind, type SpecRun, type SpecServeEntry, type SpecStream, type SpecificationConfig, type SpecificationMode, type SqliteOptions, TableAccessor, TextAccessor, type TextFilter, type VisitScenario, type Visitor, type WebsiteBackendOptions, type WebsiteHandle, type WebsiteSpecification, type WebsiteSpecificationOptions, anthropic, banner, button, complementary, content, contentinfo, defineContract, defineContracts, field, findContainersByLabel, form, heading, http, inspectContainer, link, main, match, mockOf, mockOfDate, navigation, openai, postgres, redis, region, removeContainers, search, specification, sqlite, testId, text, within };