slicetest 0.1.0 → 0.3.0

package/README.md

@@ -4,7 +4,7 @@
 
 Tests that sit between unit tests and end-to-end tests, for apps written in any language or framework.
 
-slicetest starts your app as a real process, points it at a real Postgres and at stub servers for the services it calls, and lets you check all three sides in one scenario:
+slicetest starts your app as a real process, points it at a real Postgres (or MySQL) and at stub servers for the services it calls, and lets you check all three sides in one scenario:
 
 ```ts
 import { expect } from "vitest";
@@ -27,10 +27,30 @@ No browser, no mocked database, no hooks inside your app. The app only has to re
 
 - **Unit tests** mock the database and the network, so broken SQL, migrations and request payloads slip through.
 - **End-to-end tests** drive a browser against a deployed stack. They are slow and hard to make deterministic.
-- **slicetest** keeps the real HTTP server, the real SQL and the real migrations, and replaces only the things you don't own: third-party APIs.
+- **slicetest** keeps the real HTTP server, the real SQL and the real migrations, and replaces only the things you don't own: third-party APIs. With OpenAPI specs, it also checks that those replacements behave like the real thing.
 
 The database is reset between scenarios with a single `TRUNCATE ... RESTART IDENTITY CASCADE` (about 1.5 ms). The app keeps its connections, so this works with any driver or ORM. Resetting by dropping and re-creating the database takes about 130 ms, and it crashed some apps when their pooled connections were cut.
 
+## Quick start
+
+```sh
+npx slicetest init   # detects your stack, writes slicetest.config.yaml and a first scenario
+npx slicetest        # starts Postgres, migrates, starts your app, runs scenarios/*.scenario.yaml
+```
+
+`init` recognises Node (`npm start`), Django, FastAPI, Flask, Rails, Go and Rust apps; Atlas, Prisma, Alembic, Django, Rails, Drizzle, Knex and plain SQL migrations; and an `openapi.yaml`. If there's a `compose.yaml` / `docker-compose.yml`, its database service sets `db.image` (and `db.engine: mysql` for MySQL or MariaDB), and Redis, Valkey, Mongo, Elasticsearch, MinIO, RabbitMQ and other services with a port become [`containers`](#containers-redis-search-s3-and-other-dependencies), with a reset command where one is known and the usual variable (`REDIS_URL`, `S3_ENDPOINT`, …) passed to the app. It lists every guess as a comment in the config so you know what to check.
+
+## What you get that's hard to find elsewhere
+
+- **One scenario, three boundaries.** Assert on the HTTP response, the rows in the real database and the calls to third-party APIs in the same test, in any language the app is written in.
+- **`db.changes()`**: a diff of every row the scenario inserted, updated or deleted. `toEqual` on it catches writes you didn't expect.
+- **Stubs that can't lie.** Give a stub the provider's OpenAPI spec, and a canned reply the real service would never send fails the test.
+- **Whole-scenario snapshots.** `expect(await trace()).toMatchSnapshot()` pins the responses, the outbound calls and the database changes in one reviewable file, with dates and UUIDs masked.
+- **Record the real service once, replay forever.** Point a stub at the real API with `SLICETEST_RECORD=1`, commit the YAML it writes, and later runs are offline and deterministic.
+- **OpenAPI coverage** of your own API, per operation and status, across all scenarios, and `slicetest gen --uncovered` to scaffold scenarios for what's missing.
+- **Postgres or MySQL**, with the same scenarios and the same row types on both, plus Redis, MinIO or any other `containers` reset between scenarios.
+- **Fast resets.** `TRUNCATE` between scenarios (about 1.5 ms) with the app still running, and a cached migrated template, so the second run skips container start-up and migrations.
+
 ## Install
 
 ```sh
@@ -39,6 +59,16 @@ npm i -D slicetest vitest
 
 You also need Docker or Podman. slicetest finds a running Podman machine on its own (on Windows too). Alternatively, pass `db.url` or set `SLICETEST_DATABASE_URL` to use an existing Postgres server, for example a CI service container.
 
+### MySQL
+
+Set `db: { engine: "mysql" }` (or give a `mysql://` URL) and install the driver:
+
+```sh
+npm i -D mysql2 @testcontainers/mysql   # the second is only needed without db.url
+```
+
+Everything works the same: `mysql:8.4` in a container, a migrated template cloned per worker (tables, foreign keys, views and triggers; stored routines are not copied), a `TRUNCATE` reset that only touches tables that were written to, and `db.*` helpers whose rows look like Postgres's (`BOOLEAN` as `true`/`false`, `BIGINT` ids as numbers, `DATETIME` in UTC). Only the SQL you write yourself differs: `?` placeholders in `db.query` and YAML `sql` steps. `db.schemas` defaults to the database in the URL. `SLICETEST_DATABASE_URL` is only used by projects on the same engine as its scheme, so a CI job can provide one Postgres server while a MySQL project starts its own container.
+
 Works on macOS, Linux and Windows. On Windows the app's process tree is stopped with `taskkill /T`, and `app.command` / `db.migrate.command` run through `cmd.exe`.
 
 ## Configure
@@ -73,11 +103,11 @@ export default defineConfig({
 
 ### How a run works
 
-1. **Once per run.** slicetest starts `postgres:17-alpine` and migrates a template database.
+1. **Once per run.** slicetest starts `postgres:17-alpine` and migrates a template database. Locally, the container is kept running and the migrated template is cached by the contents of your migrations, so the next run with unchanged migrations skips both steps (see `db.reuse`).
 2. **Once per worker.** It clones the template into the worker's own database.
-3. **Once per test file.** It starts the stub servers and your app.
-4. **Before each scenario.** It truncates every table except migration bookkeeping tables (`atlas_schema_revisions`, `_prisma_migrations`, `alembic_version`, `django_migrations`, …) and extension-owned tables such as PostGIS's `spatial_ref_sys`, re-runs the seed, and clears the stubs, cookies and request history. If the app crashed in the previous scenario, it is restarted.
-5. **After each scenario.** The scenario fails if the app crashed or called a stub route you didn't register.
+3. **Once per test file.** It starts the stub servers, your `services` and your app.
+4. **Before each scenario.** It truncates every table except migration bookkeeping tables (`atlas_schema_revisions`, `_prisma_migrations`, `alembic_version`, `django_migrations`, …) and extension-owned tables such as PostGIS's `spatial_ref_sys`, re-runs the seed, and clears the stubs, cookies and request history. If the app or a service crashed in the previous scenario, it is restarted.
+5. **After each scenario.** The scenario fails if the app or a service crashed, the app called a stub route you didn't register, or (with `openapi`) any traffic didn't match the spec.
 
 Database names are unique per run, so several projects or CI jobs can share one Postgres server via `db.url`.
 
@@ -94,16 +124,22 @@ stub calls with no matching route:
 requests to the app:
   POST /signup → 500 (14ms)  {"error":"internal"}
 
+database changes during this scenario:
+  users: 1 inserted
+    + {"id":1,"email":"a@example.com","verified":false}
+  audit_log: 1 updated
+    ~ id=7  status: "pending" → "failed"
+
 app output during this scenario:
 TypeError: Cannot read properties of undefined (reading 'email')
 -----------------
 ```
 
-Only this scenario's app output is shown, not the whole log. Requests that never got a response (for example because the app crashed) appear as `failed`.
+Only this scenario's app output is shown, not the whole log. The database section is a diff against the state right after the reset and seed, so you see what the app actually wrote. Requests that never got a response (for example because the app crashed) appear as `failed`.
 
 ## API
 
-Every scenario receives `{ http, db, stub, app }`.
+Every scenario receives `{ http, db, stub, app, service }`.
 
 ### `http` — talk to the app
 
@@ -132,7 +168,25 @@ await db.sql`SELECT * FROM users WHERE id = ${user.id}`;          // values beco
 await db.query("UPDATE users SET name = $1", ["b"]);
 ```
 
-In `where`, `null` means `IS NULL` and an array means `IN (...)`. `bigint` columns (bigserial ids, `count(*)`) come back as numbers when they fit safely.
+In `where`, `null` means `IS NULL` and an array means `IN (...)`.
+
+#### `db.changes()` — assert on everything the app wrote
+
+Instead of guessing which tables to query, ask for the diff. Rows are matched by primary key, so updates show which columns changed:
+
+```ts
+await db.insert("users", { email: "a@example.com" });
+await db.checkpoint();                                   // ignore what the test itself arranged
+
+await http.post("/users/1/verify");
+
+expect(await db.changes()).toEqual({
+  users: { inserted: [], deleted: [], updated: [expect.objectContaining({ changed: ["verified"] })] },
+  audit_log: { inserted: [expect.objectContaining({ action: "verify" })], updated: [], deleted: [] },
+});
+```
+
+`toEqual` fails if the app wrote to a table you didn't list, which catches unexpected side effects. Each entry in `updated` has `key`, `before`, `after` and `changed`. Tables without a primary key report an update as one deleted row plus one inserted row. `bigint` columns (bigserial ids, `count(*)`) come back as numbers when they fit safely.
 
 ### `stub(name)` — fake the services the app calls
 
@@ -158,6 +212,71 @@ stub("slack").calls("POST", "/hook");                         // recorded calls:
 
 Later routes win. `path` may also be a RegExp, and `method` may be `*`. Unanswered calls get a `501` and fail the scenario.
 
+### OpenAPI contracts — for your app and for the services you stub
+
+Point slicetest at OpenAPI 3.0 / 3.1 files and every scenario doubles as a contract test, with no extra assertions:
+
+```ts
+slicetest({
+  openapi: "openapi.yaml",                                       // your app's spec
+  stubs: ["slack", { name: "stripe", openapi: "specs/stripe.yaml" }], // a provider's spec
+  // ...
+});
+```
+
+- **Your app's responses** must be documented (path, method, status) and match the schema.
+- **The app's requests to a stub** must match the provider's spec: required query parameters, content type and request body. Spec paths are matched with or without the server's base path (`/v1`).
+- **Your stubs' replies** must be something the real service could send. A stub that returns `200 { ok: true }` where the provider documents `202 { messageId }` makes tests pass against an API that doesn't exist; slicetest fails the scenario instead.
+
+```
+slicetest: traffic doesn't match the OpenAPI spec:
+  app: GET /users/{id} → 200: /id must be integer
+  app → mail: POST /mail/send request: body must have required property 'subject'
+  stub mail reply (the real service wouldn't answer this way): POST /mail/send responded 200, which specs/mail.yaml doesn't document (documented: 202)
+```
+
+#### `autoReply`: stubs generated from the provider's spec
+
+Add `autoReply: true` to a stub with a spec, and calls that no route matches are answered with the provider's documented example, or with values built from the schema (formats such as `email` and `date-time`, enums, `minimum`, `allOf` are respected). Register routes only for what a scenario cares about; a registered route always wins.
+
+```ts
+stubs: [{ name: "stripe", openapi: "specs/stripe.yaml", autoReply: true }],
+```
+
+Calls answered this way have `call.fallback === true`. Paths that aren't in the spec still get a 501 and fail the scenario.
+
+At the end of the run, slicetest prints which documented responses your scenarios actually produced, merged across workers and across TypeScript and YAML scenarios:
+
+```
+slicetest: OpenAPI coverage (openapi.yaml): 8/9 documented responses (89%)
+  GET    /health            200 ✓
+  POST   /polls             201 ✓  400 ✓  502 ✓
+  GET    /polls/{id}        200 ✓  404 ✗
+  POST   /polls/{id}/votes  204 ✓  400 ✓  404 ✓
+```
+
+To fail the run below a threshold, use `openapi: { spec: "openapi.yaml", minCoverage: 100 }`. Filtered runs (`-t`, a single file) count too, so you may want `minCoverage: process.env.CI ? 100 : undefined`.
+
+The example apps in `examples/` run every scenario against `examples/openapi.yaml` with `minCoverage: 100`, and their Slack calls against `examples/slack.openapi.yaml`.
+
+### Recording a real service
+
+A stub can also answer from recordings of the real service, the way VCR or Polly do, except that it works for an app in any language because the stub is a server. Give it the real base URL:
+
+```ts
+stubs: [{ name: "github", upstream: "https://api.github.com" }],
+```
+
+Record once, with real credentials in the app's environment:
+
+```sh
+SLICETEST_RECORD=github npx vitest     # or SLICETEST_RECORD=1 for every stub with an upstream
+```
+
+Calls no route matches are forwarded to `upstream` (under its path prefix, headers included) and the answers are written to `recordings/github.yaml` (`recordings:` changes the path). Later runs replay them without touching the network. A request is identified by method, path, query and body (JSON key order doesn't matter); identical requests replay their recordings in the order they were made. Only `content-type`, `location`, `retry-after`, `link` and `etag` response headers are kept, and request headers are never stored, so tokens stay out of the file; bodies are stored as sent, so review the file before committing it.
+
+Precedence is: registered route, then recording, then `autoReply`, then a 501 that says how to record the call. Replayed calls have `call.fallback === true`, and are checked against the provider's spec when the stub has one. To refresh recordings, delete the file (or the entries) and record again.
+
 ### Matchers
 
 Registered automatically:
@@ -173,10 +292,85 @@ await expect(db).toHaveRow("votes", { poll_id: 1 }, 3);          // exactly thre
 
 Failure messages list the calls the stub actually received, or the first rows of the table.
 
+### Services: workers and other processes
+
+Real apps are rarely one process. Declare the others under `services` and slicetest starts them before the app (in order), watches them like the app, and restarts one that crashed — on the same port, so URLs handed to other processes stay valid:
+
+```ts
+slicetest({
+  services: {
+    pricing: { command: "go run ./cmd/pricing", ready: { path: "/health" } }, // another HTTP service
+    worker: { command: "bundle exec sidekiq" },                                 // no port, no ready check
+  },
+  app: {
+    command: "node server.js",
+    env: { PORT: "{{app.port}}", DATABASE_URL: "{{db.url}}", PRICING_URL: "{{service.pricing}}" },
+  },
+});
+```
+
+Each service gets `PORT` = `{{service.<name>.port}}` and `DATABASE_URL` unless you pass `env`. A crash fails the scenario, and each service's output during the scenario is part of the failure output.
+
+```ts
+scenario("uploading an image queues a thumbnail job", async ({ http, db, service }) => {
+  await http.post("/images", { url: "https://example.com/cat.png" });
+
+  await service("worker").waitForLog(/thumbnail \d+ done/);   // this scenario's output only
+  await expect(db).toHaveRow("images", { thumbnail_ready: true });
+});
+```
+
+`waitForLog(pattern, timeout = 5000)` resolves with the matching line and also works on `app`. In YAML: `- log: thumbnail \d+ done` with `from: worker` and `within: <ms>`.
+
+### Containers: Redis, search, S3 and other dependencies
+
+Anything else the app talks to can run as a container next to the database. Each test file gets its own, and `reset` runs inside it before every scenario, like the database's `TRUNCATE`:
+
+```ts
+slicetest({
+  containers: {
+    cache: { image: "redis:7-alpine", port: 6379, reset: ["redis-cli", "FLUSHALL"] },
+    s3: { image: "minio/minio", port: 9000, command: ["server", "/data"], env: { MINIO_ROOT_USER: "test", MINIO_ROOT_PASSWORD: "testtest" } },
+  },
+  app: { command: "node server.js", env: { REDIS_URL: "redis://{{container.cache}}", S3_ENDPOINT: "http://{{container.s3}}" } },
+});
+```
+
+`{{container.<name>}}` is `host:port`; `.host` and `.port` are there too. The container is ready when its port accepts connections, or when it prints `ready: { log }`. In a scenario, `container("cache").exec(["redis-cli", "GET", "hits"])` runs a command inside it and returns its stdout.
+
+### Asynchronous side effects
+
+If the app does work in the background (a job queue, a fire-and-forget webhook), wait for the effect with Vitest's own helpers. slicetest doesn't need its own:
+
+```ts
+await vi.waitFor(() => expect(stub("mail")).toHaveReceived("POST", "/send"));
+await expect.poll(() => db.count("jobs", { status: "done" })).toBe(1);
+```
+
+In YAML, add `within: <ms>` to a `db`, `sql`, `received` or `changes` step.
+
+### Snapshot the whole scenario: `trace()`
+
+Because every scenario starts from the same database, ids and rows come out the same on every run. `trace()` returns everything the scenario did at the three boundaries: requests to the app with their responses, calls to each stub with the replies' statuses, and the database changes. Snapshot it, and a change in any of them shows up in review:
+
+```ts
+scenario("voting flow", async ({ http, stub, trace }) => {
+  stub("slack").on("POST", "/hook").reply(200, "ok");
+  const { json } = await http.post("/polls", { title: "Tea or coffee", a: "tea", b: "coffee" });
+  await http.post(`/polls/${json.id}/votes`, { choice: "b" });
+
+  expect(await trace()).toMatchSnapshot();
+});
+```
+
+Dates (`Date` values and ISO strings) become `[date]` and UUIDs `[uuid]`. Mask more with `trace({ keys: ["token"], patterns: [/^tok_/] })`, or use `mask(value, opts)` from `slicetest` on anything else. Update snapshots with `vitest -u`. In YAML, the step is `snapshot: true` (with `mask: [token]`).
+
+The example apps share one snapshot file: the Node and the Python implementation must produce the same trace, byte for byte.
+
 ### Scenarios
 
 ```ts
-scenario("name", async ({ http, db, stub, app }) => { ... }, timeoutMs?);
+scenario("name", async ({ http, db, stub, app, service, container, trace }) => { ... }, timeoutMs?);
 scenario.only / scenario.skip / scenario.todo
 scenario.each([{ choice: "a", status: 204 }, { choice: "x", status: 400 }])(
   "voting $choice returns $status",
@@ -195,13 +389,18 @@ Scenarios in one file share an app and a database, so they always run one at a t
 | `app.cwd` | vitest root | |
 | `app.ready` | `{ path: "/" }` | Poll a path until it answers below 500, or `{ log: "listening" \| /regex/ }`. |
 | `app.readyTimeout` | `30000` | |
-| `db.migrate` | none | `{ atlas: { dir } }`, `{ sql: "file-or-dir" }` or `{ command }` (gets `DATABASE_URL`). |
+| `db.engine` | `postgres`, or `mysql` for a `mysql://` URL | `postgres` or `mysql` (see [MySQL](#mysql)). |
+| `db.migrate` | none | `{ atlas: { dir } }`, `{ sql: "file-or-dir" }` or `{ command, inputs? }` (gets `DATABASE_URL`). |
 | `db.seed` | none | SQL file re-run after every reset. |
 | `db.schemas` | `["public"]` | Schemas whose tables are reset. |
 | `db.keep` | `[]` | Extra tables (`name` or `schema.name`) never truncated. |
 | `db.url` | `$SLICETEST_DATABASE_URL`, else a container | Use an existing Postgres server (e.g. a CI service container) instead of Testcontainers. |
-| `db.image` | `postgres:17-alpine` | |
-| `stubs` | `[]` | Names of stubbed services. |
+| `db.image` | `postgres:17-alpine` / `mysql:8.4` | |
+| `db.reuse` | on, unless `CI` is set or `db.url` is given | Keep the container between runs and cache the migrated template. The cache key is the migration files' contents; for `{ command }`, list what it reads in `inputs: ["prisma/migrations"]`, or it migrates every run. Databases left by killed runs are dropped after a day. Remove the container (`docker rm -f` / `podman rm -f`) to start clean. |
+| `containers` | `{}` | Dependencies as containers: `{ name: { image, port, env?, command?, ready?: { log }, reset? } }`. See [Containers](#containers-redis-search-s3-and-other-dependencies). |
+| `services` | `{}` | Other processes: `{ name: { command, env?, cwd?, ready?, readyTimeout? } }`. Without `ready` a service is not waited for. |
+| `stubs` | `[]` | Names of stubbed services, or `{ name, openapi?, autoReply?, upstream?, recordings? }`: check calls against the provider's spec, answer from it, or [replay recordings](#recording-a-real-service) of the real service. |
+| `openapi` | none | The app's OpenAPI 3 spec, or `{ spec, minCoverage }`. Every response must match it; the run ends with a coverage report. |
 | `http` | `{}` | Default `headers` / `query` for every request. |
 
 The config is validated up front: a missing `app.command`, an ambiguous `db.migrate` or a duplicate stub name fails with a clear message instead of a timeout.
@@ -237,6 +436,9 @@ scenarios:
         when:
           json: { text: "New poll: Dogs or cats?" }
 
+      - changes:                  # and nothing else was written
+          polls: { inserted: 1 }
+
   - name: voting {{choice}} returns {{status}}
     each:
       - { choice: a, status: 204 }
@@ -255,6 +457,12 @@ scenarios:
 | `db: <table>` | `where`, `orderBy`, `expect: { rows, count }`, `capture` |
 | `sql: <query>` | `params`, `expect: { rows, count }`, `capture` |
 | `received: <stub>` | `call: METHOD /path`, `when`, `times` (exact; default at least once) |
+| `log: <regex>` | `from` (a service; default the app), `within` (ms, default 5000). Waits for a matching line printed during the scenario. |
+| `changes: { <table>: { inserted, updated, deleted } }` | Each is a count or a list of subset rows (`updated` matches the row after the update). Tables that aren't listed must be unchanged. |
+| `checkpoint: true` | Later `changes` steps only see what happens after this step. |
+| `snapshot: true` | The scenario's [trace](#snapshot-the-whole-scenario-trace) so far must match its stored snapshot. `mask: [keys]` hides more values. |
+
+`db`, `sql`, `received` and `changes` steps take `within: <ms>` to retry until they pass, for effects the app applies asynchronously.
 
 - `{{name}}` inserts a captured value or an `each` field. A string that is only `{{name}}` keeps the value's type, so `id: "{{pollId}}"` compares as a number.
 - Expected `json`, `rows` and `headers` are subsets: extra keys are fine. `{ $type: number }`, `{ $regex: "^ch_" }`, `{ $contains: "..." }` and `{ $any: true }` match loosely.
@@ -282,6 +490,17 @@ npx slicetest polls -t voting # filter by file and scenario name
 npx slicetest --watch
 ```
 
+### Scenarios from your OpenAPI spec: `npx slicetest gen`
+
+```sh
+npx slicetest gen                 # uses `openapi` from slicetest.config.yaml, or --spec openapi.yaml
+npx slicetest gen --uncovered     # only the documented responses the last run didn't produce
+```
+
+writes `scenarios/<resource>.gen.scenario.yaml` with one scenario per documented response. Requests are built from the spec's examples and schemas. A path that needs an id gets a step that creates the resource first through the collection's `POST` and captures its id. A 404 on a made-up id and a 400/422 on an empty body are runnable as is; other responses are generated as `skip: true` scenarios marked TODO, so the skipped list in the test output is what's left to cover. Existing files are kept unless you pass `--force`.
+
+`--uncovered` reads the coverage the last run left in `node_modules/.cache/slicetest/`, which closes the loop: run, look at the ✗ in the coverage table, `gen --uncovered`, fill in the TODOs.
+
 ## Examples
 
 `examples/` has a Node app (`node:http` + `pg`) and a Python app (`http.server` + `psycopg`) with the same API. **The same scenario files (`polls.test.ts` and `polls.scenario.yaml`) run against both**:
@@ -291,6 +510,10 @@ npm test            # unit tests + both example apps
 npm run test:dist   # the built package, and the CLI with examples/slicetest.config.yaml
 ```
 
+## Using a coding agent
+
+[`.claude/skills/slicetest-write-tests`](.claude/skills/slicetest-write-tests/SKILL.md) teaches Claude Code (or any agent that reads skills) how to write slicetest scenarios. Copy it into your project's `.claude/skills/`. Contributors: see [`AGENTS.md`](AGENTS.md).
+
 ## Status
 
-Early prototype. Postgres only. CI runs on Linux and Windows. Planned: container reuse across runs, MySQL.
+Early. Postgres and MySQL. CI runs on Linux and Windows.

package/dist/app.d.ts

@@ -1,24 +1,47 @@
-import type { ResolvedOptions } from "./config.js";
+import type { ResolvedProcess } from "./config.js";
+type ProcessOptions = ResolvedProcess;
 type Exit = {
     code: number | null;
     signal: NodeJS.Signals | null;
     error?: Error;
 };
-/** The app under test, running as a real child process. */
+/** The app under test (or one of its `services`), running as a real child process. */
 export declare class App {
     #private;
+    readonly port: number;
+    /** `app`, or `service <name>`, for messages. */
+    readonly label: string;
     readonly url: string;
     private constructor();
-    static start(opts: ResolvedOptions["app"], root: string, vars: Record<string, string>): Promise<App>;
+    /**
+     * `key` names the process in placeholders and messages: `app`, or
+     * `service.<name>` for a service (its port is then `{{service.<name>.port}}`).
+     */
+    static start(opts: ProcessOptions, root: string, vars: Record<string, string>, key?: string, fixedPort?: number): Promise<App>;
     get exited(): Exit | undefined;
     /**
      * The exit event is delivered asynchronously, so a crash caused by the last
      * request may not be visible yet. Give it a moment before trusting `exited`.
+     * Windows reports it later (the process runs under cmd.exe), so it waits longer.
      */
     settle(ms?: number): Promise<Exit | undefined>;
     /** The app's recent output (last 200 lines), or only what it printed after `since` (a value from `mark()`). */
     logs(since?: number): string;
     mark(): number;
+    /** What the process printed during the current scenario. */
+    scenarioLogs(): string;
+    /** Called before each scenario; `waitForLog()` only looks at output after this point. */
+    beginScenario(): number;
+    /**
+     * Wait until the process prints a line matching `pattern` during the current
+     * scenario (lines printed earlier in the scenario count). Resolves with the line.
+     *
+     * ```ts
+     * await http.post("/orders", { ... });
+     * await service("worker").waitForLog(/order \d+ shipped/);
+     * ```
+     */
+    waitForLog(pattern: string | RegExp, timeout?: number): Promise<string>;
     /**
      * POSIX: SIGTERM the whole process group, then SIGKILL whatever is left (including orphaned grandchildren).
      * Windows has no signals to ask politely with, so the tree is terminated at once.

package/dist/app.js

@@ -7,19 +7,27 @@ const LOG_LINES = 200;
 const DRAIN_MS = 100;
 const KILL_GRACE_MS = 3000;
 const WINDOWS = process.platform === "win32";
-/** The app under test, running as a real child process. */
+/** The app under test (or one of its `services`), running as a real child process. */
 export class App {
-    url;
+    port;
+    label;
     #child;
     #log = [];
     /** Lines ever received, so callers can ask for output since a point in time. */
     #lineCount = 0;
     #exit;
     #exited;
-    #onLine;
-    constructor(child, url) {
-        this.url = url;
+    #listeners = new Set();
+    /** `mark()` at the start of the current scenario. */
+    #scenarioMark = 0;
+    url;
+    constructor(child, port, 
+    /** `app`, or `service <name>`, for messages. */
+    label) {
+        this.port = port;
+        this.label = label;
         this.#child = child;
+        this.url = `http://127.0.0.1:${port}`;
         for (const stream of [child.stdout, child.stderr]) {
             // Keep partial lines (and split multi-byte characters) until the rest arrives.
             const decoder = new StringDecoder("utf8");
@@ -31,7 +39,8 @@ export class App {
                 this.#lineCount++;
                 if (this.#log.length > LOG_LINES)
                     this.#log.shift();
-                this.#onLine?.(line);
+                for (const listener of this.#listeners)
+                    listener(line);
             };
             stream.on("data", (chunk) => {
                 const lines = (partial + decoder.write(chunk)).split(/\r?\n/);
@@ -52,21 +61,26 @@ export class App {
             child.on("close", (code, signal) => done({ code, signal }));
         });
     }
-    static async start(opts, root, vars) {
-        const port = await freePort();
-        vars = { ...vars, "app.port": String(port) };
-        const env = opts.env ?? { PORT: "{{app.port}}", DATABASE_URL: "{{db.url}}" };
-        const child = spawn(interpolate(opts.command, vars, "app.command"), {
+    /**
+     * `key` names the process in placeholders and messages: `app`, or
+     * `service.<name>` for a service (its port is then `{{service.<name>.port}}`).
+     */
+    static async start(opts, root, vars, key = "app", fixedPort) {
+        // A restarted service keeps its port, so URLs already handed to other processes stay valid.
+        const port = fixedPort ?? (await freePort());
+        vars = { ...vars, [`${key}.port`]: String(port) };
+        const env = opts.env ?? { PORT: `{{${key}.port}}`, DATABASE_URL: "{{db.url}}" };
+        const child = spawn(interpolate(opts.command, vars, `${key}.command`), {
             shell: true,
             cwd: path.resolve(root, opts.cwd ?? "."),
-            env: { ...process.env, ...mapValues(env, (v) => interpolate(v, vars, "app.env")) },
+            env: { ...process.env, ...mapValues(env, (v) => interpolate(v, vars, `${key}.env`)) },
             stdio: ["ignore", "pipe", "pipe"],
             // POSIX: own process group, so stop() also kills whatever the shell spawned.
             // Windows: detaching would open a console window; taskkill /T walks the tree instead.
             detached: !WINDOWS,
             windowsHide: true,
         });
-        const app = new App(child, `http://127.0.0.1:${port}`);
+        const app = new App(child, port, key === "app" ? "app" : key.replace(/^service\./, "service "));
         running.add(app);
         try {
             await app.#waitReady(opts);
@@ -83,8 +97,9 @@ export class App {
     /**
      * The exit event is delivered asynchronously, so a crash caused by the last
      * request may not be visible yet. Give it a moment before trusting `exited`.
+     * Windows reports it later (the process runs under cmd.exe), so it waits longer.
      */
-    async settle(ms = 20) {
+    async settle(ms = WINDOWS ? 100 : 20) {
         if (this.#exit)
             return this.#exit;
         let timer;
@@ -102,6 +117,44 @@ export class App {
     mark() {
         return this.#lineCount;
     }
+    /** What the process printed during the current scenario. */
+    scenarioLogs() {
+        return this.logs(this.#scenarioMark);
+    }
+    /** Called before each scenario; `waitForLog()` only looks at output after this point. */
+    beginScenario() {
+        this.#scenarioMark = this.#lineCount;
+        return this.#scenarioMark;
+    }
+    /**
+     * Wait until the process prints a line matching `pattern` during the current
+     * scenario (lines printed earlier in the scenario count). Resolves with the line.
+     *
+     * ```ts
+     * await http.post("/orders", { ... });
+     * await service("worker").waitForLog(/order \d+ shipped/);
+     * ```
+     */
+    async waitForLog(pattern, timeout = 5000) {
+        const re = typeof pattern === "string" ? new RegExp(escapeRegExp(pattern)) : new RegExp(pattern.source, pattern.flags.replace(/[gy]/g, ""));
+        const n = Math.min(this.#lineCount - this.#scenarioMark, this.#log.length);
+        const seen = n > 0 ? this.#log.slice(-n).find((l) => re.test(l)) : undefined;
+        if (seen !== undefined)
+            return seen;
+        return new Promise((resolve, reject) => {
+            const done = (fn) => {
+                clearTimeout(timer);
+                this.#listeners.delete(listener);
+                fn();
+            };
+            const listener = (line) => {
+                if (re.test(line))
+                    done(() => resolve(line));
+            };
+            const timer = setTimeout(() => done(() => reject(new Error(`slicetest: ${this.label} printed no line matching ${re} within ${timeout}ms. Output during this scenario:\n${this.logs(this.#scenarioMark) || "(none)"}`))), timeout);
+            this.#listeners.add(listener);
+        });
+    }
     /**
      * POSIX: SIGTERM the whole process group, then SIGKILL whatever is left (including orphaned grandchildren).
      * Windows has no signals to ask politely with, so the tree is terminated at once.
@@ -139,18 +192,23 @@ export class App {
         const timeout = opts.readyTimeout ?? 30_000;
         const deadline = Date.now() + timeout;
         const ready = opts.ready;
+        // A service without `ready` (e.g. a queue worker) counts as ready once it's spawned.
+        if (!ready)
+            return;
         let logSeen = false;
+        let onLine;
         if ("log" in ready) {
             // Drop g/y so test() doesn't keep state between lines.
             const pattern = new RegExp(ready.log, ready.flags.replace(/[gy]/g, ""));
             logSeen = this.#log.some((l) => pattern.test(l));
-            this.#onLine = (line) => (logSeen ||= pattern.test(line));
+            onLine = (line) => (logSeen ||= pattern.test(line));
+            this.#listeners.add(onLine);
         }
         try {
             while (Date.now() < deadline) {
                 if (this.#exit) {
                     const why = this.#exit.error ? this.#exit.error.message : `code ${this.#exit.code}, signal ${this.#exit.signal}`;
-                    throw new Error(`slicetest: app exited before becoming ready (${why})\n${this.logs()}`);
+                    throw new Error(`slicetest: ${this.label} exited before becoming ready (${why})\n${this.logs()}`);
                 }
                 if ("log" in ready) {
                     if (logSeen)
@@ -168,10 +226,11 @@ export class App {
                 }
                 await new Promise((r) => setTimeout(r, 50));
             }
-            throw new Error(`slicetest: app did not become ready within ${timeout}ms\n${this.logs()}`);
+            throw new Error(`slicetest: ${this.label} did not become ready within ${timeout}ms\n${this.logs()}`);
         }
         finally {
-            this.#onLine = undefined;
+            if (onLine)
+                this.#listeners.delete(onLine);
         }
     }
 }
@@ -201,6 +260,9 @@ export function interpolate(template, vars, where = "app.env") {
         return vars[key];
     });
 }
+function escapeRegExp(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
 function mapValues(obj, fn) {
     return Object.fromEntries(Object.entries(obj).map(([k, v]) => [k, fn(v)]));
 }