@ripplo/testing 0.5.5 → 0.6.0

package/README.md

@@ -6,23 +6,19 @@ Typed TypeScript DSL for end-to-end tests with real backend state, used by [Ripp
 npm install @ripplo/testing
 ```
 
-This package ships the DSL and the server adapters. The companion [`ripplo`](https://www.npmjs.com/package/ripplo) CLI scaffolds `.ripplo/`, runs tests, and writes the lockfile.
+The companion [`ripplo`](https://www.npmjs.com/package/ripplo) CLI scaffolds `.ripplo/`, runs tests, and writes the lockfile. This package ships the DSL and the server adapters.
 
-## Architecture
+## How it fits together
 
-Definitions and implementations are kept in separate files.
+Tests are split into two halves that the type system stitches together.
 
-`createRipplo({ preconditions, observers, tests })` in `.ripplo/index.ts` collects the handles returned by `precondition()`, `observer()`, and `test()`. These factories have no side effects.
+`createRipplo({ preconditions, observers, tests })` in `.ripplo/index.ts` collects handles returned by `precondition()`, `observer()`, and `test()`. These are pure factories — they describe shape, not behavior.
 
-`createEngine(ripplo, { preconditions, observers })` in your app server wires every handle to its setup, teardown, or observer function. Missing or extra keys are TypeScript errors.
+`createEngine(ripplo, { preconditions, observers })` in your app server wires every handle to its setup, teardown, or observer function. Missing or extra keys are TypeScript errors. The engine runs server-side where it has DB access; the DSL package never invokes it directly. Everything goes over signed HTTP.
 
-Mount the resulting `engine` with one of the adapters (`@ripplo/testing/express`, `/fastify`, `/nextjs`, `/hono`, `/koa`, `/nestjs`, `/elysia`) at a path prefix (default `/ripplo`). The adapter exposes three signed routes: `PUT /execute-preconditions`, `PUT /execute-observer`, `PUT /teardown-preconditions`.
+You mount the engine with one of the adapters (`@ripplo/testing/express`, `/fastify`, `/nextjs`, `/hono`, `/koa`, `/nestjs`, `/elysia`) at a path prefix, default `/ripplo`. The adapter exposes three signed routes: `PUT /execute-preconditions`, `PUT /execute-observer`, `PUT /teardown-preconditions`.
 
-Implementations run server-side where they have DB access. The DSL package never invokes them; it dispatches over signed HTTP.
-
-## DSL
-
-### Test
+## Writing a test
 
 ```typescript
 import { test } from "@ripplo/testing";
@@ -48,16 +44,17 @@ export const inviteATeammate = test("invite-a-teammate")
   ])
   .coverage(
     "src/components/members/InviteDialog.tsx#InviteDialog.click[Invite member]",
-    "src/components/members/InviteDialog.tsx#InviteDialog.input[Email]",
     "src/components/members/InviteDialog.tsx#InviteDialog.click[Send invite]",
   );
 ```
 
-`test(id)` → `.name()` → `.description()?` → `.requires()` → `.expectedOutcome()` → `.startsAt()` → `.steps()` → `.coverage(...ids)`. Use `.notImplemented()` instead of `.startsAt() / .steps() / .coverage()` to stub during planning.
+The chain is: `test(id)`, `.name()`, optional `.description()`, `.requires()`, `.expectedOutcome()`, `.startsAt()`, `.steps()`, `.coverage()`. While planning, swap `.startsAt() / .steps() / .coverage()` for `.notImplemented()` to stub.
+
+`.coverage(...)` ids come from a generated `.ripplo/coverage.d.ts` that augments `CoverageRegistry`, so they autocomplete and stale ids break the build. Implemented tests must list every interaction they exercise. A pre-commit hook blocks net-new interactions in the diff that no test claims.
 
-`.coverage(...)` ids come from the generated `.ripplo/coverage.d.ts`, which augments `CoverageRegistry` so the call autocompletes and breaks the build on stale ids. Implemented tests must list every interaction they exercise; stubs skip it. A pre-commit hook blocks net-new interactions in the diff that no test claims.
+Every step ends with `.as("short description")`. Labels appear in the run UI and in failure detail. Duplicates within a test are a compile error. Describe intent, not mechanics.
 
-### Preconditions
+## Preconditions
 
 ```typescript
 import { precondition } from "@ripplo/testing";
@@ -74,20 +71,13 @@ export const dataProject = precondition("data:project")
 export const preconditions = { authLoggedIn, dataProject };
 ```
 
-`precondition(name)` → `.description()` → `.requires()` (optional) → `.contract<T>()`. Each field in `T` must be a primitive (`string`, `number`, or `boolean`) and is run-scoped.
-
-#### Preconditions are create-only
-
-Precondition setups must only insert. No `update`, no `delete`. Parallel runs share a database, so a `WHERE` clause that looks run-scoped can still match another run's rows. And mutating something a parent precondition produced couples them in an order that breaks the moment they're composed differently.
+Contract fields are primitives: `string`, `number`, or `boolean`. Each value is run-scoped.
 
-If a test needs a non-default state, accept that state as input on the precondition that creates the row. Don't seed a default and patch it later.
+**Setups insert; they don't update or delete.** Parallel runs share a database, so a `WHERE` clause that looks run-scoped can still match another run's rows, and mutating something a parent precondition produced couples them in an order that breaks the moment they're composed differently. If a test needs non-default state, accept that state as input on the precondition that creates the row. Don't seed a default and patch it later.
 
-Two exceptions:
+Two carve-outs: `upsert` on a row whose primary key is per-run (treat it as create-with-default), and teardown, which may delete rows this precondition created.
 
-- `upsert` on a row whose primary key is per-run (e.g. a `(userId, resourceId)` settings record). Treat it as create-with-default.
-- Teardown may delete, but only rows this precondition created.
-
-### Observers
+## Observers
 
 ```typescript
 import { observer } from "@ripplo/testing";
@@ -101,57 +91,27 @@ export const orgNameIs = observer("org:name-is")
 export const observers = { orgNameIs };
 ```
 
-Observer `.input<T>()` and precondition `.contract<T>()` fields are typed primitives: `string`, `number`, or `boolean`. The wire codec preserves the type, so a `number` field arrives as a `number` in your impl.
-
-`.budget(tier)` controls how long the runtime polls before giving up. The tiers describe poll behavior, not numeric timeouts:
-
-| Tier    | Window | Backoff    | Use for                            |
-| ------- | ------ | ---------- | ---------------------------------- |
-| `fast`  | ~5s    | 100→1000ms | Synchronous DB reads (default)     |
-| `slow`  | ~30s   | 250→2000ms | Queue drains, replication settling |
-| `async` | ~120s  | 500→5000ms | Webhooks, queue workers, LLM calls |
-
-### Locators
+`.input<T>()` fields are typed primitives — same rules as precondition contracts. The wire codec preserves the type.
 
-`role(name, accessibleName)` matches by ARIA role and accessible name. `testId(id)` matches a `data-testid` attribute and exists for elements that genuinely have no semantic role.
+`.budget(tier)` controls how long the runtime polls. Use `fast` for synchronous DB reads (default, ~5s), `slow` for queue drains and replication (~30s), `async` for webhooks and LLM calls (~120s).
 
-**Roles:** `alert`, `alertdialog`, `button`, `checkbox`, `combobox`, `dialog`, `form`, `grid`, `heading`, `img`, `link`, `list`, `listbox`, `listitem`, `menu`, `menuitem`, `navigation`, `option`, `progressbar`, `radio`, `region`, `row`, `searchbox`, `separator`, `slider`, `spinbutton`, `status`, `switch`, `tab`, `tabpanel`, `textbox`, `toolbar`, `tooltip`, `tree`, `treeitem`.
+## Locators, actions, assertions
 
-Type-narrowed locators reject the wrong role at compile time:
+`role(name, accessibleName)` matches by ARIA role and accessible name and is the right tool for almost everything. `testId(id)` matches `data-testid` and exists for elements with no semantic role.
 
-- `InputLocator` — `textbox`, `searchbox`, `combobox`, `spinbutton`, `testId()`
-- `SelectLocator` — `combobox`, `listbox`, `testId()`
-- `CheckLocator` — `checkbox`, `switch`, `testId()`
+Locators are type-narrowed by what you can do with them: `InputLocator` accepts `textbox`, `searchbox`, `combobox`, `spinbutton`, or `testId()`; `SelectLocator` accepts `combobox`, `listbox`, or `testId()`; `CheckLocator` accepts `checkbox`, `switch`, or `testId()`. Passing a `button` to `fill()` is a compile error.
 
-### Actions
+Actions live in `@ripplo/testing/actions`. Pointer (`click`, `dblclick`, `hover`, ...), keyboard (`press`, `typeText`, `fill`, `clear`), form controls (`select`, `check`, `uncheck`), navigation (`navigate`, `scrollIntoView`), and composites like `drag`, `upload`, `handleDialog`, `clipboard`, `setPermission`, `setViewport`. Each takes a locator and returns a step.
 
-Imported from `@ripplo/testing/actions`. Every action takes a locator and produces a step:
-
-- **Pointer:** `click`, `dblclick`, `rightClick`, `hover`, `focus`
-- **Keyboard:** `press` (single key or chord), `typeText` (no clear), `fill` (clear + type), `clear`
-- **Form controls:** `select`, `check`, `uncheck`
-- **Navigation:** `navigate`, `scrollIntoView`
-- **Composite:** `drag`, `upload`, `handleDialog`, `clipboard`
-- **Browser context:** `setPermission`, `setViewport`
+Assertions live in `@ripplo/testing/assert` and are exact-match. There is no `contains`, no `startsWith`, no regex. `assert.visible / .text / .value / .attribute / .enabled / .checked / .focused / .count / .url`, plus `assert.backend(observer, params)` for server-state checks.
 
 ### Upload fixtures
 
-`upload(locator, fixture("name"))` is the only way to attach files. Fixture files live in `.ripplo/fixtures/` and are committed to git so cloud runs see byte-identical inputs. Limits: 10 MB per file, 50 MB total. Pass an array to `upload` for multi-file inputs.
-
-### Assertions
-
-Imported from `@ripplo/testing/assert`. Every assertion is exact-match; there is no `contains`, `startsWith`, or regex.
-
-- **Visibility:** `assert.visible(loc)`, `assert.not.visible(loc)`
-- **Content:** `assert.text(loc, exact)`, `assert.value(loc, exact)`, `assert.attribute(loc, name, exact)`
-- **State:** `assert.enabled(loc)`, `assert.checked(loc)`, `assert.focused(loc)`
-- **Counting:** `assert.count(loc, n)`
-- **Routing:** `assert.url(path)`
-- **Backend:** `assert.backend(observer, params)` — see [Observers](#observers).
+`upload(locator, fixture("name"))` is the only way to attach files. Fixture bytes live in `.ripplo/fixtures/` and are committed to git so cloud runs see byte-identical inputs. Caps: 10 MB per file, 50 MB total. Pass an array for multi-file inputs.
 
 ### Variables
 
-`variable(name)` declares a placeholder. `extract(locator, variable)` captures the element's text or value at run time; later steps that take a string accept the variable in its place.
+`variable(name)` declares a placeholder; `extract(locator, variable)` captures the element's text or value at run time; later steps that take a string accept the variable in its place.
 
 ```typescript
 import { extract, variable } from "@ripplo/testing/control";
@@ -159,40 +119,11 @@ import { extract, variable } from "@ripplo/testing/control";
 const token = variable("token");
 extract(testId("token-value"), token).as("capture token");
 fill(role("textbox", "Paste here"), token).as("paste token");
-assert.value(role("textbox", "Paste here"), token).as("assert token");
-```
-
-### Step labels
-
-Every step ends with `.as("short description")`. Labels appear in the run UI and in failure detail, and duplicate labels within a test are a compile error. Describe intent ("open invite dialog"), not mechanics ("click button").
-
-## Data flow
-
-Precondition output reaches steps by destructuring the argument to `.startsAt()` and `.steps()`. Always destructure; never hardcode a value that came from a precondition.
-
-```typescript
-test("delete-project")
-  .requires({ project: dataProject })
-  .startsAt(({ project }) => `/projects/${project.projectId}/settings`)
-  .steps(({ project }) => [
-    navigate(`/projects/${project.projectId}/settings`).as("go to settings"),
-    // ...
-  ]);
-```
-
-Never write `"{{namespace.key}}"` as a string literal. The proxy stringifies internally, but writing the literal bypasses the type checker, so typos compile and fail at run time. The `no-literal-template-strings` rule blocks this.
-
-```typescript
-// literal: bypasses type-checking
-assert.value(role("textbox", "Table name"), "{{table.name}}").as("name visible");
-
-// proxy: checked against requires()
-assert.value(role("textbox", "Table name"), table.name).as("name visible");
 ```
 
 ## Wiring
 
-### `.ripplo/index.ts` — definitions
+### `.ripplo/index.ts`
 
 ```typescript
 import { createRipplo } from "@ripplo/testing";
@@ -203,9 +134,9 @@ import { tests } from "./tests/index.js";
 export default createRipplo({ preconditions, observers, tests });
 ```
 
-Runtime config (`RIPPLO_APP_URL`, `RIPPLO_ENGINE_URL`, `RIPPLO_WEBHOOK_SECRET`) lives in your host app's env file; `ripplo init` writes the initial values. Project id and env-file pointers live in `.ripplo/project.json`.
+Runtime config (`RIPPLO_APP_URL`, `RIPPLO_ENGINE_URL`, `RIPPLO_WEBHOOK_SECRET`) lives in your app's env file; `ripplo init` writes the initial values. Project id and env-file pointers live in `.ripplo/project.json`.
 
-### `<app>/src/test/engine.ts` — implementations
+### `<app>/src/test/engine.ts`
 
 ```typescript
 import { createEngine, notImplemented } from "@ripplo/testing";
@@ -215,7 +146,7 @@ import { prisma } from "../lib/prisma.js";
 export const engine = createEngine(ripplo, {
   preconditions: {
     authLoggedIn: {
-      // setup receives one item per concurrent run that needs this precondition.
+      // Setup receives one item per concurrent run that needs this precondition.
       // Issue one bulk write and return results in input order.
       setup: async (items) => {
         const seeds = items.map(({ ctx }) => ({
@@ -223,7 +154,6 @@ export const engine = createEngine(ripplo, {
           email: ctx.uniqueEmail(),
         }));
         await prisma.user.createMany({ data: seeds });
-        // each item.ctx.setCookie(...) flows back to that run's browser
         return seeds.map(({ id }) => ({ userId: id }));
       },
       teardown: async (items) => {
@@ -232,7 +162,7 @@ export const engine = createEngine(ripplo, {
         });
       },
     },
-    dataProject: notImplemented("awaiting prisma seed helper"), // stub for planning
+    dataProject: notImplemented("awaiting prisma seed helper"),
   },
   observers: {
     orgNameIs: async (ctx, { orgId, expectedName }) => {
@@ -248,37 +178,37 @@ export const engine = createEngine(ripplo, {
 });
 ```
 
-`setup` and `teardown` run in batches. The runtime groups concurrent runs that need the same precondition inside a 200ms window and calls your impl once for the whole batch. Use `createMany` / `deleteMany` so database load scales with wall-clock time rather than run count. Return one result per input item, in input order; the engine zips them back to runs by index.
+The runtime batches concurrent runs that need the same precondition inside a 200ms window and calls your impl once for the batch. Use `createMany` and `deleteMany` so DB load scales with wall-clock time, not run count. Return one result per input item, in input order.
 
 ### Setup context
 
-Each batched setup item exposes `ctx`:
+Each batched setup item carries a `ctx`:
 
-- `ctx.runId` — 12-char run id.
-- `ctx.fixed(value)` — static test value, type-branded so the engine can tell it apart from a raw literal.
-- `ctx.uniqueId(prefix)` returns `ripplo-test-<prefix>-<runId>-<n>`, where `n` is a per-call counter scoped to the run. Calling it repeatedly yields distinct values.
-- `ctx.uniqueEmail()` returns `ripplo-test-<runId>-<n>@test.ripplo.ai`, same per-call counter.
+- `ctx.runId` is a 12-char run id.
+- `ctx.uniqueId(prefix)` returns `ripplo-test-<prefix>-<runId>-<n>` and increments per call.
+- `ctx.uniqueEmail()` returns `ripplo-test-<runId>-<n>@test.ripplo.ai`.
 - `ctx.setCookie(name, value, options?)` applies to that run's browser context before the test starts.
+- `ctx.fixed(value)` brands a static value so the engine can tell it apart from a raw literal.
 
-Helpers return plain primitives, but the return type is branded — a bare string literal in a `setup` return fails at compile time, which is what stops tests from accidentally seeding identical-looking data across runs.
+The branding matters: helpers return plain primitives, but their return type is branded so a bare string literal in a `setup` return fails to compile. That's what stops two parallel runs from accidentally seeding identical-looking data.
 
-The shared prefix (`ripplo-test-`) is also exported as `TEST_ID_PREFIX` from `@ripplo/testing`, so teardown / cleanup logic that scopes `WHERE` clauses by `startsWith(TEST_ID_PREFIX)` doesn't have to hardcode the string.
+`TEST_ID_PREFIX` is exported so teardown logic that scopes `WHERE` clauses by `startsWith(TEST_ID_PREFIX)` doesn't have to hardcode the string.
 
 ### Observer context
 
 The observer impl returns one of three terminal states:
 
 - `ctx.pass()` — assertion satisfied; stop polling.
-- `ctx.retry(reason)` — the default; use it for anything that might succeed on a later poll (row not yet written, status not yet transitioned, queue not yet drained). The last `reason` is surfaced in failure detail. "Not found" belongs here, not in `fail`.
-- `ctx.fail(reason)` — narrow; only when polling cannot help (invariant violated, contradictory value). Stops immediately.
+- `ctx.retry(reason)` — try again later. The default. Anything that might succeed on a future poll belongs here, including "not found" — rows often arrive late. The last `reason` shows up in failure detail.
+- `ctx.fail(reason)` — give up immediately. Reserve this for invariant violations where polling cannot help.
 
-Thrown exceptions are treated as `fail`.
+Thrown exceptions count as `fail`.
 
 ## Observer coverage
 
-Two lint rules enforce backend assertions on mutation flows. `mutation-without-observer-coverage` flags save / create / update / delete clicks, uploads, and accepted dialogs that aren't followed by an `assert.backend(...)`. `observer-params-reference-variables` flags assertions whose params are all string literals while the test declares precondition variables.
+Two lint rules push backend assertions onto mutation flows. `mutation-without-observer-coverage` flags save / create / update / delete clicks, uploads, and accepted dialogs that aren't followed by an `assert.backend(...)`. `observer-params-reference-variables` flags assertions whose params are all string literals while the test declares precondition variables.
 
-Steps that genuinely touch no server state (cancel dialogs, client-side sort) opt out with `{ uiOnly: true }`:
+Steps that genuinely touch no server state opt out with `{ uiOnly: true }`:
 
 ```typescript
 click(role("button", "Cancel"), { uiOnly: true }).as("close dialog");
@@ -289,97 +219,37 @@ test("filter-sort", { uiOnly: true }).name("Filter & sort");
 
 ## Server adapters
 
-Every adapter takes the `engine` from `createEngine(...)` and a required `enabled: boolean`. Bind `enabled` to `process.env.ENABLE_RIPPLO_TESTING === "true"` so the routes can't ship to production; when it's false the adapter mounts a no-op handler.
+Every adapter takes `engine` from `createEngine(...)` and a required `enabled: boolean`. Bind `enabled` to `process.env.ENABLE_RIPPLO_TESTING === "true"` so the routes can't ship to production. When `enabled` is false the adapter mounts a no-op handler.
 
-### Express
-
-```ts
-import express from "express";
-import { createExpressHandler } from "@ripplo/testing/express";
-import { engine } from "./test/engine.js";
-
-const app = express();
-app.use("/ripplo", createExpressHandler({ enabled, engine }));
-```
-
-### Fastify
-
-```ts
-import Fastify from "fastify";
-import { registerFastifyHandler } from "@ripplo/testing/fastify";
-import { engine } from "./test/engine.js";
-
-const app = Fastify();
-await app.register(registerFastifyHandler({ enabled, engine }), { prefix: "/ripplo" });
-```
-
-### Next.js (App Router)
-
-A single catch-all route. Works on Node and Edge.
+The recommended setup is Next.js App Router:
 
 ```ts
 // app/ripplo/[action]/route.ts
 import { createNextHandler } from "@ripplo/testing/nextjs";
 import { engine } from "@/server/test/engine";
 
-export const PUT = createNextHandler({ enabled, engine });
-```
-
-### Hono
-
-```ts
-import { Hono } from "hono";
-import { createHonoHandler } from "@ripplo/testing/hono";
-import { engine } from "./test/engine.js";
-
-const app = new Hono();
-app.route("/ripplo", createHonoHandler({ enabled, engine }));
-```
-
-Web-standard `Request`/`Response`. Runs on Node, Bun, Deno, and Cloudflare Workers.
-
-### Koa
-
-```ts
-import Koa from "koa";
-import mount from "koa-mount";
-import { createKoaHandler } from "@ripplo/testing/koa";
-import { engine } from "./test/engine.js";
-
-const app = new Koa();
-app.use(mount("/ripplo", createKoaHandler({ enabled, engine })));
-```
-
-The Koa adapter reads the raw body itself; don't mount a body-parser in front of it.
-
-### NestJS
-
-```ts
-import { Module } from "@nestjs/common";
-import { RipploTestingModule } from "@ripplo/testing/nestjs";
-import { engine } from "./test/engine.js";
-
-@Module({
-  imports: [RipploTestingModule.forRoot({ enabled, engine, path: "ripplo" })],
-})
-export class AppModule {}
+export const PUT = createNextHandler({
+  enabled: process.env.ENABLE_RIPPLO_TESTING === "true",
+  engine,
+});
 ```
 
-Requires `@nestjs/platform-express` and `reflect-metadata`. `path` defaults to `"ripplo"`.
+The other adapters follow the same `{ enabled, engine }` shape and mount at a path prefix:
 
-### Elysia
+| Framework | Import                                       | Mount                                |
+| --------- | -------------------------------------------- | ------------------------------------ |
+| Express   | `createExpressHandler` from `/express`       | `app.use("/ripplo", handler)`        |
+| Fastify   | `registerFastifyHandler` from `/fastify`     | `app.register(handler, { prefix })`  |
+| Hono      | `createHonoHandler` from `/hono`             | `app.route("/ripplo", handler)`      |
+| Koa       | `createKoaHandler` from `/koa`               | `koa-mount("/ripplo", handler)`      |
+| NestJS    | `RipploTestingModule.forRoot` from `/nestjs` | Import in your `AppModule`           |
+| Elysia    | `createElysiaHandler` from `/elysia`         | `new Elysia().group("/ripplo", ...)` |
 
-```ts
-import { Elysia } from "elysia";
-import { createElysiaHandler } from "@ripplo/testing/elysia";
-import { engine } from "./test/engine.js";
-
-const app = new Elysia().group("/ripplo", (g) => g.use(createElysiaHandler({ enabled, engine })));
-```
+Two notes worth knowing. The Koa adapter reads the raw body itself, so don't mount a body-parser in front of it. NestJS requires `@nestjs/platform-express` and `reflect-metadata`.
 
-### Custom (raw engine)
+### Custom adapter
 
-For frameworks not listed above. The adapters above are thin wrappers over this API. A custom adapter reads the raw request body, verifies the signature with `verifyWebhookSignature`, dispatches the three routes to `engine.executePreconditions`, `engine.executeObserver`, and `engine.teardownPreconditions`, and shapes responses with `toBatchRunResults` / `toTeardownResults`. Cookies travel inside the JSON response body, not `Set-Cookie` headers; the runtime parses them out and applies them to the browser context.
+The wrappers above are thin. If you're on a framework not listed, read the raw request body, verify the signature with `verifyWebhookSignature`, dispatch the three routes to `engine.executePreconditions`, `engine.executeObserver`, and `engine.teardownPreconditions`, and shape responses with `toBatchRunResults` / `toTeardownResults`. Cookies travel inside the JSON response body, not `Set-Cookie` headers; the runtime parses them out and applies them to the browser context.
 
 ```ts
 import {
@@ -420,24 +290,12 @@ async function executePreconditions(req: Request): Promise<Response> {
 
 `executeObserver` and `teardownPreconditions` follow the same verify-then-dispatch shape. Request bodies: `{ batch: [{ runId, preconditions, data }] }` for teardown, `{ runId, name, params }` for observers.
 
-## Security & parallelism
+## Security and parallelism
 
-Every request is signed with Standard Webhooks (HMAC-SHA256) over the `webhook-id`, `webhook-timestamp`, and `webhook-signature` headers; verify before executing. `ENABLE_RIPPLO_TESTING` gates every adapter and must never be true in production.
+Every request is signed with [Standard Webhooks](https://www.standardwebhooks.com/) (HMAC-SHA256) over `webhook-id`, `webhook-timestamp`, and `webhook-signature`. Verify before executing. `ENABLE_RIPPLO_TESTING` gates every adapter and must never be true in production.
 
 For parallel runs, use `ctx.uniqueId(prefix)` and `ctx.uniqueEmail()` to avoid collisions, return the created entity ids in the data contract, and scope teardown's `WHERE` to those ids. `deleteMany` is fine and preferred, as long as the predicate can only match this batch's rows.
 
 ## Lockfile
 
-`ripplo compile`, `ripplo lint`, and `ripplo watch` all write `.ripplo/ripplo.lock`. Commit it; the Ripplo server reads it on every push webhook and returns 422 if it's missing or stale. `ripplo compile --check` exits non-zero on a stale lockfile and belongs in pre-commit and CI. `ripplo doctor` surfaces stale lockfiles and missing pre-commit hooks.
-
-## CLI
-
-```bash
-ripplo auth login       # authenticate
-ripplo init             # scaffold .ripplo/ and write env vars
-ripplo watch            # local executor (run as a background process)
-ripplo lint [ids..]     # compile + lint
-ripplo run [ids..]      # run tests in parallel
-```
-
-Full command reference at [`ripplo`](https://www.npmjs.com/package/ripplo).
+`ripplo compile`, `ripplo lint`, and `ripplo watch` all write `.ripplo/ripplo.lock`. Commit it. The Ripplo server reads it on every push webhook and returns 422 if it's missing or stale. Run `ripplo compile --check` in pre-commit and CI; `ripplo doctor` surfaces stale lockfiles and missing pre-commit hooks.

package/dist/lockfile.js

@@ -611,6 +611,12 @@ async function hashFixturesIntoCompileResult({
   return { ...result, fixtures: Object.fromEntries(hashed) };
 }
 async function hashOneFixture({ fixturesRoot, name }) {
+  const rawName = name;
+  if (typeof rawName !== "string" || rawName.length === 0) {
+    throw new Error(
+      `Internal error: upload step produced a non-string fixture name (got ${rawName === null ? "null" : typeof rawName}). This usually means a test passed a non-Fixture value to upload() \u2014 wrap the filename with fixture("file.png").`
+    );
+  }
   if (name.includes("..") || path.isAbsolute(name)) {
     throw new Error(`Invalid fixture name "${name}": must be a path under .ripplo/fixtures/`);
   }
@@ -634,10 +640,19 @@ async function hashOneFixture({ fixturesRoot, name }) {
 function collectFixtureReferences(result) {
   const names = /* @__PURE__ */ new Set();
   result.tests.forEach((test) => {
-    Object.values(test.spec.nodes).forEach((node) => {
-      if (node.type === "upload") {
-        node.files.forEach((name) => names.add(name));
+    Object.entries(test.spec.nodes).forEach(([stepId, node]) => {
+      if (node.type !== "upload") {
+        return;
       }
+      node.files.forEach((name, i) => {
+        const raw = name;
+        if (typeof raw !== "string" || raw.length === 0) {
+          throw new Error(
+            `Test "${test.slug}" step "${stepId}" upload files[${String(i)}] is not a non-empty string (got ${raw === null ? "null" : typeof raw}). Wrap filenames with fixture(): upload(loc, fixture("file.png")).`
+          );
+        }
+        names.add(raw);
+      });
     });
   });
   return names;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ripplo/testing",
   "description": "TypeScript DSL for defining and running Ripplo e2e workflow tests",
-  "version": "0.5.5",
+  "version": "0.6.0",
   "type": "module",
   "files": [
     "dist"
@@ -99,8 +99,8 @@
     "tsup": "^8.5.1",
     "typescript": "catalog:",
     "vitest": "^4.1.4",
-    "@ripplo/spec": "^0.0.0",
-    "@ripplo/eslint-config": "0.0.0"
+    "@ripplo/eslint-config": "0.0.0",
+    "@ripplo/spec": "^0.0.0"
   },
   "peerDependencies": {
     "@nestjs/common": "^10.0.0 || ^11.0.0",