@jterrazz/test 12.2.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>;
 }
@@ -928,24 +940,25 @@ declare class HttpResult extends BaseResult {
 //#endregion
 //#region src/core/specification/cli/literate.d.ts
 /**
- * Running a literate `<case>.cli` spec: one scenario, one workdir, one set of
- * servers, every `$` block executed and asserted.
+ * 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 block, {@link ServeAdapter} for `serve:`, the `{{token}}` engine for
- * the 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.
+ * 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 literate header may start by name (`serve: mcp KEY=value`),
- * registered once per app in the `serve` option of `specification.cli()`.
+ * 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 block's child env. */
+  /** 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
@@ -955,15 +968,15 @@ interface LiterateServeRegistration {
   /** Builds the URL bound to {@link env} from the announced port. */
   url: (port: number) => string;
 }
-/** Per-call options for {@link runLiterateSpec} / `cli.run()`. */
+/** Per-call options for {@link runSpecDocument} / `cli.run()`. */
 interface LiterateRunFlags {
   /**
-   * Opt this file OUT of the update-mode rewrite. A frozen file is NEVER
-   * written under `TEST_UPDATE=1`: its mismatch still throws its diff. That
-   * is what makes a DELIBERATELY-WRONG `.cli` — 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 `.cli` mirror of
-   * `toMatch(name, { frozen: true })`.
+   * 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;
 }
@@ -1178,7 +1191,7 @@ interface SpecificationConfig {
    */
   dockerTestRunId?: string;
   /**
-   * Named environment SETS a literate `.cli` header may name by bare word
+   * Named environment SETS a spec document may name by bare word
    * (`env: frozen`). Declared once per app in `specification.cli()`.
    */
   envSets?: Record<string, CliEnv>;
@@ -1188,12 +1201,12 @@ interface SpecificationConfig {
    */
   interceptDisabledReason?: string;
   jobs?: JobHandle[];
-  /** The project root — the working directory a literate `serve:` command runs from. */
+  /** The project root — the working directory a document's `serve:` command runs from. */
   root?: string;
   server?: ServerPort;
   /**
-   * Named servers a literate `.cli` header may start (`serve: mcp KEY=value`).
-   * Declared once per app in `specification.cli()`.
+   * Named servers a spec document may start (`serve: [mcp]`). Declared once
+   * per app in `specification.cli()`.
    */
   serveRegistry?: Record<string, LiterateServeRegistration>;
   /**
@@ -1285,11 +1298,11 @@ interface CliSpecification<DatabaseKey extends string = string> {
    */
   exec: (args?: string | string[], options?: ExecOptions) => Promise<CliResult>;
   /**
-   * Run a literate `<case>.cli` spec — its header (fixtures, env sets,
-   * servers) and every `$` block, each asserted — and resolve with the LAST
-   * block's result, so a `.test.ts` can add an assertion the file cannot
-   * express (a directory golden, a grep). The path is relative to the test
-   * file's own directory, where the `.cli` lives.
+   * 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>;
 }
@@ -1926,83 +1939,84 @@ declare const specification: {
   website: typeof startWebsite;
 };
 //#endregion
-//#region src/core/literate/literate-file.d.ts
+//#region src/core/literate/spec-document.d.ts
 /**
- * Parser / serializer for `<case>.cli` literate spec files.
- *
- * A literate spec is ONE scenario in one file: a header of `key: value` lines
- * (the narrative and the ground the run stands on), a blank line, then one or
- * more `$ <argv>` blocks holding the expected exit code and streams.
- *
- *     test: refuses to guess when it is run outside the checkout
- *     given: a workdir with no home/ + apps/ pair anywhere above it
- *     then: the error names where the command has to be run
- *     fixture: $FIXTURES/repositories-stub/
- *     env: frozen TERRA_ORIGIN=http://127.0.0.1:9
- *     serve: mcp MCP_STUB_WITHHOLD=get-article
- *
- *     $ terra git repositories
- *     exit: 1
- *     --- stderr
- *     Error: no directory with home/ and apps/ above the current directory
- *
- * The shape mirrors the `.http` grammar (a start section, then a body split at
- * the first blank line) so a reader who knows one knows the other. The parser
- * is pure text: it resolves nothing, runs nothing, and knows no filesystem.
+ * 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.
  */
-/** One `KEY=value` (or a bare word naming a registered env set) from an `env:` line. */
-type LiterateEnvToken = {
+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:` line — a registered server name plus the extra env it is started with. */
-interface LiterateServeEntry {
+/** One `serve:` entry — a registered server plus the extra env it is started with. */
+interface SpecServeEntry {
   env: Record<string, string>;
   line: number;
   name: string;
 }
-/**
- * The header of a literate spec — everything before the first blank line.
- *
- * The field names ARE the grammar keys, `then:` included: a reader must be able
- * to move between the file and this type without a translation table. The
- * thenable hazard the linter guards is not reachable here — a header is data
- * read out of a `LiterateSpec`, never a value the framework awaits.
- */
-interface LiterateHeader {
-  /** `env:` lines, flattened to their tokens in declaration order. */
-  env: LiterateEnvToken[];
-  /** `fixture:` paths, in declaration order (they layer). */
-  fixtures: string[];
-  given: string;
-  /** `serve:` lines, in declaration order. */
-  serve: LiterateServeEntry[];
-  /** The vitest test title. */
-  test: string;
-  then: string;
+/** One `fixture:` entry — a path with the line it was declared on. */
+interface SpecFixture {
+  line: number;
+  path: string;
 }
-/** One `$ <argv>` block: the command, its exit code, and both streams verbatim. */
-interface LiterateBlock {
-  /** The command line, exactly as written after `$ ` (may be empty). */
-  argv: string;
-  exitCode: number;
-  /** 1-based line of the `$ ` line in the source file. */
+/** 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;
-  /** Expected stderr; `null` when the block declares no `--- stderr` section. */
-  stderr: null | string;
-  /** Expected stdout, verbatim (no trailing newline). */
-  stdout: string;
+  text: string;
 }
-/** A parsed `<case>.cli` file. */
-interface LiterateSpec {
-  blocks: LiterateBlock[];
-  header: LiterateHeader;
-  /** The header text verbatim, including its trailing blank line — never rewritten. */
-  headerText: 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
@@ -2463,4 +2477,4 @@ declare module 'vitest' {
   }
 }
 //#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 LiterateBlock, type LiterateHeader, type LiterateRunFlags, type LiterateServeRegistration, type LiterateSpec, 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 };

package/dist/index.js

@@ -1,5 +1,5 @@
-import { i as match, n as Matcher, t as CaptureScope } from "./match.js";
-import { A as mergeTextPreservingPlaceholders, C as formatDirectoryDiff, D as formatTableDiff, E as formatStdoutDiff, F as textEquals, M as renderExpected, N as structuralEquals, P as structuralSubset, S as walkDirectory, T as formatStartupReport, _ as text, a as UPDATE_HINT, b as DirectoryAccessor, c as CliResult, d as findContainersByLabel, f as inspectContainer, g as TextAccessor, h as JsonAccessor, i as copyPlan, k as mergePreservingPlaceholders, l as BaseResult, m as TableAccessor, n as runLiterateSpec, o as shouldUpdateSnapshots, p as removeContainers, r as ServeAdapter, s as ContainerAccessor, u as validateDatabaseOption, v as getCallerDir, w as formatResponseDiff, x as diffDirectories, y as FilesystemAccessor } from "./literate.js";
+import { a as copyPlan, i as match, n as Matcher, t as CaptureScope } from "./match.js";
+import { C as formatResponseDiff, E as formatTableDiff, M as structuralEquals, N as structuralSubset, O as mergePreservingPlaceholders, P as textEquals, S as formatDirectoryDiff, T as formatStdoutDiff, _ as getCallerDir, a as shouldUpdateSnapshots, b as diffDirectories, c as BaseResult, d as inspectContainer, f as removeContainers, g as text, h as TextAccessor, i as UPDATE_HINT, j as renderExpected, k as mergeTextPreservingPlaceholders, l as validateDatabaseOption, m as JsonAccessor, o as ContainerAccessor, p as TableAccessor, r as ServeAdapter, s as CliResult, t as runSpecDocument, u as findContainersByLabel, v as FilesystemAccessor, w as formatStartupReport, x as walkDirectory, y as DirectoryAccessor } from "./literate.js";
 import { a as isContract, i as defineContracts, n as contractsOf, o as isContracts, r as defineContract, t as ContractQueue } from "./queue.js";
 import { closeSync, copyFileSync, cpSync, existsSync, mkdirSync, mkdtempSync, openSync, readFileSync, readSync, readdirSync, rmSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { dirname, isAbsolute, join, relative, resolve } from "node:path";
@@ -1222,18 +1222,18 @@ var SpecificationBuilder = class {
 		});
 	}
 	/**
-	* Run a literate `<case>.cli` spec and resolve with the LAST block's
-	* result. The whole file runs in ONE working directory with ONE set of
-	* servers, and every block is asserted — unlike `.exec([...])`, a non-zero
+	* Run a `<case>.spec.yaml` document and resolve with the LAST run's
+	* result. The whole file executes in ONE working directory with ONE set of
+	* servers, and every run is asserted — unlike `.exec([...])`, a non-zero
 	* exit does not stop the sequence, because here each exit code is part of
-	* what the file states.
+	* what the document states.
 	*
-	* Setup chained BEFORE the call layers underneath the file's own header: a
-	* chained `.fixture()` is copied first, the header's `fixture:` lines over
-	* it, and the header's `env:` wins over a chained `.env()`.
+	* Setup chained BEFORE the call layers underneath the document's own
+	* ground: a chained `.fixture()` is copied first, the document's `fixture:`
+	* entries over it, and its `env:` wins over a chained `.env()`.
 	*
 	* @example
-	*   const result = await cli.run('no-estate.cli');
+	*   const result = await cli.run('no-estate.spec.yaml');
 	*   await expect(result.directory('out')).toMatch('scaffold');
 	*/
 	run(file, options) {
@@ -1492,7 +1492,7 @@ var SpecificationBuilder = class {
 	}
 	runLiterateAction(workDir, file, options) {
 		const filePath = resolve(this.testDir, file);
-		return runLiterateSpec({
+		return runSpecDocument({
 			baseEnv: this.childEnv(workDir),
 			frozen: options?.frozen,
 			config: this.config,
@@ -2206,21 +2206,23 @@ var ExecAdapter = class {
 	constructor(command) {
 		this.command = command;
 	}
-	async exec(args, cwd, extraEnv) {
+	async exec(args, cwd, extraEnv, input) {
 		const env = buildEnv(extraEnv);
 		const result = spawnSync(`${this.command} ${args}`, [], {
 			cwd,
 			encoding: "utf8",
 			env,
+			input: input?.stdin,
 			shell: true,
 			stdio: [
 				"pipe",
 				"pipe",
 				"pipe"
-			]
+			],
+			timeout: input?.timeout
 		});
 		return {
-			exitCode: result.status ?? 1,
+			exitCode: result.error?.code === "ETIMEDOUT" ? 124 : result.status ?? 1,
 			stderr: result.stderr ?? "",
 			stdout: result.stdout ?? ""
 		};