@voltro/cli 0.33.0 → 0.34.0

package/templates/agent-docs/testing.md

@@ -23,9 +23,13 @@ Everything in it is in-memory and synchronous-friendly — no docker, no running
 
 | Export | Use |
 |---|---|
-| `makeTestContext(options?)` | The request `ctx` a handler/tool sees at runtime — subject-scoped `ctx.store`, `clock`, `email`, `webhooks`, optional `ai`. → [Unit testing](/docs/testing/unit-testing) |
+| `makeTestContext(options?)` | The request `ctx` a handler/tool sees at runtime — subject-scoped `ctx.store`, `clock`, `webhooks`, `llm`, optional `ai`. → [Unit testing](/docs/testing/unit-testing) |
 | `mockStore(seed)` | Seed rows: `makeTestContext({ store: mockStore({ todos: [...] }) })`. |
-| `MockClock` / `MockEmail` / `MockLLM` | Deterministic clock, captured email, queued LLM responses. |
+| `user(id, opts?)` / `apiKey` / `serviceAccount` / `anonymous` / `system` | Subject factories — the acting identity, instead of a hand-written `{ type: 'user', … }` literal. |
+| `MockClock` / `MockLLM` | Deterministic clock, queued LLM responses. |
+| `invoke(descriptor, handler, input, ctx)` | Run a procedure the way the dispatcher does — guards, decode, transaction, plugin interceptors. → [Unit testing](/docs/testing/unit-testing) |
+| `makeTestApp({ ctx, restRoutes, publicApi, strategies })` | The request-level harness — a real HTTP request through the real REST pipeline. → [Unit testing](/docs/testing/unit-testing#request-level-testing-maketestapp) |
+| `fixtureRow(table, over?)` / `defineFactory(table, opts?)` | Complete a required-column row; a named factory with defaults, traits and associations. |
 | `makeVoltroTestClient(config)` | The frontend harness — render a component against mocked `useSubscription` / `useMutation`, from the `@voltro/testing/client` subpath. → [Component testing](/docs/testing/component-testing) |
 | `makeWorkflowRunner({ ctx, workflows })` | Drive a workflow in-process and assert on its steps. → [Workflows](/docs/testing/workflows) |
 | `runDialectParity(fixture)` | Run one fixture across a SQL dialect for portability — from the `@voltro/testing/dialect` subpath. → [Dialect parity](/docs/testing/dialect-parity) |
@@ -35,10 +39,11 @@ Everything in it is in-memory and synchronous-friendly — no docker, no running
 Voltro's primitives are designed so the cheapest test covers the most surface. Reach for the lowest layer that proves what you need:
 
 1. **Unit — handlers, tools, mutations, queries.** Call the executor directly with a `makeTestContext()` ctx. The store is the real mixin-wrapped store, so tenant scoping, soft-delete, and audit auto-fill all behave as in production — without a database. This is 90% of your tests. See [Unit testing](/docs/testing/unit-testing).
-2. **Component — the reactive frontend.** `makeVoltroTestClient` renders a component against mocked `useSubscription` / `useMutation`, so loading, empty, stream-error and failing-write branches are all assertable without a running server. See [Component testing](/docs/testing/component-testing).
-3. **Workflow — durable, multi-step logic.** `makeWorkflowRunner` drives a workflow end-to-end in-process and hands back the same step log the dashboard shows, including real retry counts. See [Workflows](/docs/testing/workflows).
-4. **Parity — hand-written SQL that must stay portable.** `runDialectParity` runs a fixed scenario suite against a dialect you stand up. Mostly for dialect-package authors and apps with `unsafe()` SQL. See [Dialect parity](/docs/testing/dialect-parity).
-5. **End-to-end — the running stack.** `voltro e2e` boots the api + web siblings, runs your tests against the live processes, and tears them down.
+2. **Request — the transport hop.** `makeTestApp` sends a real request through the framework's own REST pipeline: the `x-tenant` header, the auth strategy chain, path-param decode, the 405/404/410 the transport produces, HTTP idempotency, and a `publicApi` annotation's scopes. Everything a handler test structurally cannot reach, and still no server, no port, no docker. See [Unit testing → request-level testing](/docs/testing/unit-testing#request-level-testing-maketestapp).
+3. **Component — the reactive frontend.** `makeVoltroTestClient` renders a component against mocked `useSubscription` / `useMutation`, so loading, empty, stream-error and failing-write branches are all assertable without a running server. See [Component testing](/docs/testing/component-testing).
+4. **Workflow — durable, multi-step logic.** `makeWorkflowRunner` drives a workflow end-to-end in-process and hands back the same step log the dashboard shows, including real retry counts. See [Workflows](/docs/testing/workflows).
+5. **Parity — hand-written SQL that must stay portable.** `runDialectParity` runs a fixed scenario suite against a dialect you stand up. Mostly for dialect-package authors and apps with `unsafe()` SQL. See [Dialect parity](/docs/testing/dialect-parity).
+6. **End-to-end — the running stack.** `voltro e2e` boots the api + web siblings, runs each `e2e/**/*.spec.ts` as a plain tsx script against the live processes (with `WEB_URL` + `API_URL` in the environment), and tears them down. No test runner and no browser ship with it — bring your own driver. See [`voltro e2e`](/docs/cli/inspect#voltro-e2e).
 
 Agents are integration tests; tools are unit tests. Don't reach for an e2e harness to assert logic a `makeTestContext` test can prove.
 
@@ -66,7 +71,7 @@ voltro e2e     # boot api + web siblings, run tests, tear down
 <!-- source: en/testing/unit-testing.md -->
 ## Unit testing
 
-_makeTestContext — the in-memory request ctx for handler and tool tests. The real mixin-wrapped store, mockStore seeding, subject/tenant re-scoping, and the deterministic clock / email / LLM mocks._
+_makeTestContext, invoke and makeTestApp — the in-memory request ctx, the handler hop and the transport hop. The real mixin-wrapped store, subject factories, row factories, plugin services, and the deterministic clock / webhook / LLM doubles._
 
 ## tsconfig `paths` aliases
 
@@ -144,8 +149,30 @@ test('searchDocs returns matching rows', async () => {
 | `env` | ambient `process.env` | Env values sealed into the boot snapshot so handler code reading `getSecret('X')` / `serverEnv.X` resolves under test. Merged over `process.env` (these win). |
 | `relations` | — | `relations()` specs to register for this context — the boot sweep's stand-in. See [Eager loads under test](#eager-loads-under-test). |
 | `rowFilter` | the registered filter | A row filter for this context only, instead of the process-global `setRowFilter(...)`. See [Row-level security under test](#row-level-security-under-test). |
+| `plugins` | `[]` | Plugins whose rpc interceptors wrap every `invoke` **and** whose `services:` layer is provided to Effect-mode handlers. See [Plugin services](#plugin-services-mail-storage-your-own). |
+| `layers` | `[]` | Your app's own `layers:` from `app.config.ts` — the Effect services a handler `yield*`s. Merged last, so a user layer overrides a plugin layer declaring the same Tag. |
 
-The returned `TestContext` carries `{ clock, email, llm, ai?, request, cache, store, withSubject, withTenant }` — read the acting subject at `ctx.request.subject` and the in-memory cache at `ctx.cache`.
+The returned `TestContext` carries `{ clock, webhooks, llm, ai?, request, access, cache, kv, store, storeForTenant, outbox, load, loadMany, withSubject, withTenant }` — read the acting subject at `ctx.request.subject` and the in-memory cache at `ctx.cache`.
+
+### Subjects — `user()`, `apiKey()`, `anonymous()`, `system()`
+
+Every authenticated `Subject` requires a `tenantId`, so a test that hand-writes `{ type: 'user', id: 'u1', tenantId: 't1', scopes: [] }` is restating the same four fields at every call site. Use the factories:
+
+```ts
+import { user, apiKey, serviceAccount, anonymous, system, TEST_TENANT_ID } from '@voltro/testing'
+
+user('u1')                                   // tenant TEST_TENANT_ID, NO scopes → guards deny
+user('u1', { scopes: ['notes:write'] })       // the caller a guard should let through
+user('u2', { tenantId: 'other' })             // a different tenant — the store hides the first one's rows
+apiKey('key_1', { scopes: ['orders:read'] })  // what a Bearer key resolves to
+anonymous('acme')                             // unauthenticated, tenant from the `x-tenant` header
+system('job:nightly')                         // the CROSS-tenant machine actor (tenantId null, admin:full)
+```
+
+Two decisions worth knowing, because they decide what your tests mean:
+
+- **The default tenant is shared** (`TEST_TENANT_ID`). `user('a')` and `user('b')` are two members of ONE tenant, so a cross-subject read is a row-level question. A per-call-unique tenant would make the store hide everything and every such test would pass for the wrong reason.
+- **`scopes` defaults to empty, not to a bypass.** `user('b')` is refused by any `guards:` — which is the assertion most negative tests are written to make.
 
 ## `invoke` — run a handler through its guards, its input Schema, and its transaction
 
@@ -343,8 +370,96 @@ Retries are always on and carry no backoff here. Production's jitter exists to d
 
 ### What `invoke` still does NOT cover
 
-- **Transport concerns** — connection info, rate limiting, the tenant header. Those are properties of the HTTP hop, not of the procedure; faking them here would only assert against the fake.
+- **Transport concerns** — connection info, rate limiting, the tenant header. Those are properties of the HTTP hop, not of the procedure; faking them here would only assert against the fake. Reach one level up for them: [`makeTestApp`](#request-level-testing-maketestapp) drives a real request through the real REST pipeline and runs the procedure through `invoke` underneath.
 - **Undo capture and the metrics sample** — optional injections the serve entrypoint makes. Their absence changes nothing a handler can observe.
+- **The CLI-built base services** — `Cache`, `Kv`, analytics, the outbound `HttpClient`, the aggregate registry. The CLI builds those at boot from your config, and `@voltro/testing` does not depend on the CLI, so a handler that `yield*`s one gets the ordinary "Service not found". Plugin services and your own `layers:` DO resolve — see below.
+
+## Plugin services — mail, storage, your own
+
+A plugin contributes an Effect **service**, not a `ctx` field: a handler writes `const mail = yield* MailService`. Register the plugin on the context and `invoke` provides its `services:` layer, exactly as the serve pipeline does — so the handler runs, and you assert on what the plugin actually recorded:
+
+```ts
+import { invoke, makeTestContext, user } from '@voltro/testing'
+import { mailPlugin, readMailBuffer, clearMailBuffer } from '@voltro/plugin-mail'
+import { sendWelcome } from '../actions/welcome.action'
+import sendWelcomeHandler from '../actions/welcome.action.server'
+
+beforeEach(() => { clearMailBuffer() })
+
+test('signing up sends the welcome email', async () => {
+  const ctx = makeTestContext({
+    subject: user('u1'),
+    plugins: [mailPlugin({ provider: 'memory', from: 'app@acme.com' })],
+  })
+
+  await invoke(sendWelcome, sendWelcomeHandler, { to: 'ada@acme.com' }, ctx)
+
+  const sent = readMailBuffer()
+  expect(sent).toHaveLength(1)
+  expect(sent[0].to).toEqual(['ada@acme.com'])
+  expect(sent[0].subject).toBe('Welcome')
+})
+```
+
+`provider: 'memory'` is the mail plugin's own test adapter, and `readMailBuffer()` / `clearMailBuffer()` its own assertion surface — so the whole send path runs: the default `from`, the dev allowlist, suppression, per-send idempotency, the template render. There is deliberately **no `ctx.email` mock**: a double in `@voltro/testing` would model a weaker message than `MailService` accepts, and asserting against it would be asserting against the double.
+
+A service nobody provided still fails with **"Service not found"**, which is the honest outcome — it is what the handler would do at runtime, not something to paper over.
+
+Your own services work the same way, through `layers:`:
+
+```ts
+const ctx = makeTestContext({ layers: [Layer.succeed(Pricing, { quote: () => 499 })] })
+```
+
+## Request-level testing — `makeTestApp`
+
+`invoke` is the handler hop. `makeTestApp` is the one above it: an actual request through the framework's own REST pipeline — no server, no port, no docker.
+
+```ts
+import { makeTestApp, makeTestContext, anonymous, user } from '@voltro/testing'
+import { listOrders } from '../queries/orders.list.query'
+import listOrdersHandler from '../queries/orders.list.query.server'
+
+const ctx = makeTestContext({ subject: anonymous(), store: mockStore({ orders: [{ id: 'o1', tenantId: 'acme' }] }) })
+const app = makeTestApp({
+  ctx,
+  publicApi: [{ descriptor: listOrders, handler: listOrdersHandler }],
+  restRoutes: [healthRoute],
+  strategies: [myBearerStrategy],
+})
+
+// the transport gate: the publicApi annotation's scopes refuse an unscoped caller
+expect((await app.get('/v1/orders/list')).status).toBe(403)
+
+// acting as someone who holds the scope
+const res = await app.actingAs(user('u1', { tenantId: 'acme', scopes: ['orders:read'] })).get('/v1/orders/list')
+expect(res.status).toBe(200)
+expect(res.body).toEqual({ ids: ['o1'] })
+
+// how an identity is RESOLVED — headers, not an injected subject
+const viaHeader = await app.withHeaders({ 'x-tenant': 'acme', authorization: 'Bearer k1' }).get('/v1/orders/list')
+```
+
+The two ways to say who is calling are different questions, and the harness keeps them apart:
+
+- **`actingAs(subject)`** fills the same `resolveSubject` seam the serve pipeline fills with its auth resolver. Use it to test what a given identity *may do*.
+- **`withHeaders({...})`** and no `actingAs` runs the request through `composeAuthStrategies` — your real strategy chain, first-match-wins, the `x-tenant` fallback, `anonymousTenantRequired`. Use it to test how an identity *is resolved*.
+
+Both return a derived app; neither mutates the one it came from.
+
+| Method | |
+|---|---|
+| `app.get(path, opts?)` | Query string goes in the path: `app.get('/v1/orders?limit=2')`. |
+| `app.post(path, body?, opts?)` | `put` / `patch` / `delete` likewise. `body` is JSON-encoded. |
+| `app.request(method, path, opts?)` | The general form. |
+| `app.actingAs(subject)` / `app.withHeaders(h)` | Derived views. |
+| `app.paths` | Every mounted path, in mount order. |
+
+A `TestResponse` is `{ status, headers, text, body, stream }` — `body` is the parsed JSON when the route answered with a JSON content-type.
+
+What it runs is the framework's own code, not a re-implementation: `restRoutesToHttpRoutes` (method gate, sunset gate, `{ query, params, body }` assembly, input decode, guards, HTTP idempotency, output encode), `collectPublicApiRoutes` (the descriptor → REST projection, `scopes` → guards), `dispatchSharedPath` (the per-path dispatcher that lets a GET and a POST share one route), `composeAuthStrategies`, and `invoke` beneath a `publicApi` route — so the procedure's own guards, decode, transaction and interceptors still apply under the transport.
+
+Two things it deliberately does not do. An auth strategy that **refuses** (`anonymousTenantRequired` with no tenant) makes the request-call REJECT rather than return a status: mapping an auth refusal onto an HTTP code is the server's job, and inventing a number here would be a number the harness made up. And there is no WebSocket / live-subscription lifecycle and no `POST /rpc` wire — those are dispatcher concerns the CLI owns; a `publicApi:` annotation is how a procedure gets an HTTP surface this harness can reach.
 
 ## Completing a fixture row — `fixtureRow`
 
@@ -372,6 +487,39 @@ What it fills and what it leaves alone:
 
 There is no flag to turn the validation off — a test store that accepts rows production rejects is a fake testing itself. `fixtureRow` is a runtime filler for the loose `store.insert(name, row)` path. For **compile-time** payload typing (a missing required column caught as a type error at the call), use [`insertRow` / `upsertRow`](/docs/data/mutations) from `@voltro/database`, which check against `InferInsertRow<T>`.
 
+### Factories — `defineFactory`
+
+`fixtureRow` makes ONE row valid. What it cannot do is the part a fixture actually costs you: the **parent rows**. It fills a `reference()` column with a placeholder string, which satisfies the validator and points at nothing — invisible in the in-memory store, a constraint violation against a real database, and an eager `.with({ author: true })` that resolves to nothing either way.
+
+`defineFactory` adds defaults, traits and associations on top:
+
+```ts
+import { defineFactory, makeTestContext } from '@voltro/testing'
+import { users, posts } from '../schema'
+
+const userFactory = defineFactory(users, {
+  defaults: { name: 'Ada', email: (seq) => `user-${seq}@test.local` },
+  traits:   { admin: { role: 'admin' } },
+})
+const postFactory = defineFactory(posts, {
+  defaults: { title: 'A post', views: 0 },
+  traits:   { popular: { views: 10_000 } },
+  associations: { authorId: userFactory },
+})
+
+const ctx = makeTestContext({ subject })
+
+const post   = await postFactory.create(ctx.store)                  // an author IS created
+const byAdmin = await postFactory.create(ctx.store, { authorId: (await userFactory.with('admin').create(ctx.store)).id })
+const top3   = await postFactory.with('popular').createList(ctx.store, 3)
+const built  = postFactory.build()                                  // pure — writes nothing
+```
+
+- **Defaults** take a value or a `(seq) => value` function; `seq` is a process-monotonic counter shared with `fixtureRow`'s unique filler, so two sources of "unique enough" values can't collide.
+- **Traits** are named override bundles, composed left to right (`with('a', 'b')` — `b` wins). An undeclared trait **throws** rather than quietly building the base row.
+- **Associations** apply to `create` only. An ancestor is created only for a required `reference()` column your overrides leave unset — pass `{ authorId: existing.id }` and nothing extra is written. A column with no declared factory still gets its parent, built with a plain `fixtureRow`. A **cyclic** reference is refused, naming the path and the column to pass by hand.
+- `build` / `buildList` are pure: they write nothing, so a `reference()` column gets `fixtureRow`'s placeholder. Use `create` when the relations matter.
+
 ## Subscribers — `makeSubscribeContext` + the change constructors
 
 A `*.subscribe.ts` handler does not receive an `AppContext`. It receives a
@@ -512,18 +660,67 @@ ctx.clock.now()            // current instant in ms
 ctx.clock.date()           // current instant as a Date
 ctx.clock.advance('15m')   // jump forward — ms | s | m | h | d, or a number of ms
 ctx.clock.advance(900_000) // same, in milliseconds
+ctx.clock.set('2026-03-01T12:00:00Z')  // jump to an ABSOLUTE instant
+```
+
+#### Freezing GLOBAL time — `withFrozenTime` / `frozenTime`
+
+On its own a `MockClock` is a value you read: `Date.now()` and `new Date()` are
+untouched. That matters more than it sounds, because almost nothing stamps a
+timestamp through the clock you passed it — `MockWebhooks.emittedAt`, the mail
+plugin's memory provider, every `createdAt` default and most of your own code
+all call `new Date()`. Advance the mock clock, assert on one of those stamps,
+and you are comparing two unrelated clocks: the assertion passes by measuring
+the machine.
+
+`withFrozenTime` takes over the realm's `Date` for the body and restores it
+afterwards — the Rails `travel_to` / Laravel `Carbon::setTestNow()` move:
+
+```ts
+import { withFrozenTime } from '@voltro/testing'
+
+await withFrozenTime('2026-03-01T12:00:00Z', async (clock) => {
+  expect(new Date().toISOString()).toBe('2026-03-01T12:00:00.000Z')
+  await invoke(createTodo, { title: 'x' }, ctx)   // its createdAt is that instant
+  clock.advance('1h')                             // global time moves with it
+  expect(Date.now()).toBe(Date.parse('2026-03-01T13:00:00Z'))
+})
 ```
 
-### `ctx.email` — `MockEmail`
+It restores whether the body returns, throws, resolves or rejects — an async
+body is awaited *before* the clock goes back, so a `finally` cannot put the real
+clock back underneath a still-running test.
 
-Captures outgoing email for assertion.
+The Effect-native form freezes for a **scope** and releases on success, failure
+and interruption alike:
 
 ```ts
-ctx.email.sent                 // SentEmail[] — every send, in order
-ctx.email.lastTo('a@b.com')    // the most recent email to that address, or undefined
-ctx.email.clear()              // reset between cases
+import { frozenTime } from '@voltro/testing'
+
+Effect.scoped(Effect.gen(function* () {
+  const clock = yield* frozenTime('2026-03-01T12:00:00Z')
+  yield* somethingThatStampsNow
+  clock.advance('1d')
+}))
 ```
 
+`clock.install()` is the manual escape hatch and hands back the uninstall. Four
+things worth knowing before you reach for it:
+
+- **Only the zero-argument readings change.** `new Date(0)`, `new Date('2020-05-05')`
+  and `new Date(2020, 0, 2)` mean exactly what they say; `Date.parse` and
+  `Date.UTC` are untouched.
+- **A second install throws.** Nesting two would make the inner uninstall restore
+  the *outer fake*, leaving the realm frozen with nothing pointing at why.
+- **Timers are not faked.** `performance.now()` and `setTimeout` are unaffected —
+  use vitest's `vi.useFakeTimers()` for the timer wheel.
+- **A module that captured `Date` into a local before the install keeps the real
+  one.** That is inherent to any time fake.
+
+### Email is not a double — see [Plugin services](#plugin-services-mail-storage-your-own)
+
+There is no `ctx.email`. Mail is an Effect service (`yield* MailService`), so the assertion surface is the mail plugin's own memory provider — register `mailPlugin({ provider: 'memory' })` on the context and read `readMailBuffer()`.
+
 ### `ctx.webhooks` — `MockWebhooks`
 
 Records outgoing webhook emissions. Every context derived from this one — the transaction context `invoke` builds for a mutation, a `withSubject` / `withTenant` block — shares the same recorder, so what you assert on IS what the handler emitted.