@jterrazz/test 12.1.0 → 13.0.0

package/README.md

@@ -76,6 +76,19 @@ test('builds the project', async () => {
 });
 ```
 
+A CLI session can also BE the spec file. A `<case>.spec.yaml` document states one scenario — its ground, then its runs — and executes either as a test file of its own (the `literate()` vite plugin) or through `cli.run('case.spec.yaml')`:
+
+```yaml
+description: refuses to build without a manifest
+runs:
+    - command: build
+      exit: 1
+      stderr: |
+          Error: no my-cli.yaml in the current directory
+```
+
+Same engine as the chain, same `{{token}}` grammar, same `TEST_UPDATE=1` — which rewrites each run's exit code and streams, and nothing else. A JSON Schema ships at `@jterrazz/test/schema` so an editor validates as you type. Full grammar: [docs/04-cli.md](docs/04-cli.md#spec-documents--casespecyaml).
+
 ### Website testing (browser)
 
 ```typescript
@@ -193,9 +206,9 @@ const result = await jobs.seed('pending.sql').trigger('nightly-report');
 
 A `JobHandle` is `{ name: string; execute: () => Promise<void> }`.
 
-### `specification.cli(bin, { root?, services?, docker?, transform? })`
+### `specification.cli(bin, { root?, services?, docker?, transform?, env?, serve? })`
 
-Runs a command binary against fixture projects in fresh temp directories. With `services`, connection URLs are injected into the child env automatically: `<KEY>_URL` per record key (CONSTANT_CASE at camelCase boundaries — `analyticsDb` → `ANALYTICS_DB_URL`), plus `DATABASE_URL` (exactly one SQL database) and `REDIS_URL` (exactly one redis). `.env()` overrides; `null` unsets.
+Runs a command binary against fixture projects in fresh temp directories. `env` (named environment sets) and `serve` (named servers) are the registries a [`<case>.spec.yaml`](docs/04-cli.md#spec-documents--casespecyaml) names by word. With `services`, connection URLs are injected into the child env automatically: `<KEY>_URL` per record key (CONSTANT_CASE at camelCase boundaries — `analyticsDb` → `ANALYTICS_DB_URL`), plus `DATABASE_URL` (exactly one SQL database) and `REDIS_URL` (exactly one redis). `.env()` overrides; `null` unsets.
 
 ```typescript
 export const { cli, cleanup } = await specification.cli('my-migrate-tool', {
@@ -275,6 +288,7 @@ When `root` is absent, the framework walks up from the specification file to the
 | `.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)                |
+| `.run("case.spec.yaml")`                   | cli     | `CliResult`    | Run a `<case>.spec.yaml` — its ground and EVERY run asserted; the last one returns       |
 | `.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    |
 | `.open(deepLink?, scenario?)`              | mobile  | `ScreenResult` | Relaunch the app fresh on the simulator; with a scenario, the capture is the final state |