@sanity/workflow-engine-test 0.9.0 → 0.11.0

package/README.md

@@ -13,6 +13,60 @@ boilerplate.
 npm install -D @sanity/workflow-engine-test
 ```
 
+## The bench
+
+`createBench()` builds an isolated bench: the real engine, a fake in-memory
+Sanity client, an all-access default actor, and a bench-owned clock. Every
+wrapped verb injects the bench's client, tag, workflow resource, access
+default, and clock, so a test reads as the workflow it exercises:
+
+- **Runtime verbs** — `deployDefinitions`, `deleteDefinition`, `startInstance`,
+  `fireAction`, `editField`, `completeEffect` (and `completePendingEffect`,
+  addressed by effect name), `tick`, `evaluate`.
+- **Instance-admin overrides** — `setStage`, `abortInstance`. Same injection,
+  so a forced move into a deadline-gated stage evaluates `$now` at bench time,
+  not wall-clock.
+- **Reads and probes** — `getInstance`, `currentStage`, `activityStatus`,
+  `listPendingEffects`, `findPendingEffects`, `children`, `instancesForSubject`,
+  `instancesByStage`, `instancesForDocument`, `definitionsForDocument`, `query`,
+  plus the guard helpers below. Helpers sharing an engine verb's name take the
+  engine's own args objects and throw its typed errors — bench reads and engine
+  reads cannot drift.
+
+```ts
+const bench = createBench({now: '2026-01-01T00:00:00Z'})
+await bench.deployDefinitions({definitions: [reviewWorkflow]})
+
+const {instance} = await bench.startInstance({
+  definition: 'review-workflow',
+  initialFields: [subjectField('article-1')],
+})
+await bench.fireAction({instanceId: instance._id, activity: 'review', action: 'approve'})
+expect(await bench.currentStage(instance._id)).toBe('approved')
+
+// Admin overrides ride the same defaults:
+await bench.abortInstance({instanceId: instance._id, reason: 'hard stop'})
+```
+
+`subjectField(docId)` and `releaseField(name)` build the runtime
+initial-field entries for the bench's default resource, so tests never
+hand-roll GDR URI strings. For denial paths, pass a restrictive
+`currentUser` / `grants` (or a full `access`) at construction, or override
+per call with the `actor` shortcut / an explicit `access`.
+
+**Time is bench-owned.** `createBench({now})` starts frozen; `setNow` /
+`advance` move it. Every wrapped verb evaluates `$now` and stamps history at
+bench time, so deadline predicates are tested by advancing the clock and
+ticking — never by waiting.
+
+## Out-of-band engines
+
+Some tests need an engine of their own — custom effect handlers, racing two
+drainers, a custom clock. `createBenchEngine(bench, overrides?)`
+builds one on the bench's client, inheriting its tag, workflow resource, and
+clock (`overrides` win). The bench exposes `tag` and `workflowResource` for
+raw `workflow.*` calls, and the default tag ships as the `BENCH_TAG` constant.
+
 ## Mutation guards
 
 A workflow stage can deploy **mutation guards** — `temp.system.guard` documents
@@ -26,10 +80,15 @@ once the lake enforces them. There are two distinct things you test, and the
 bench gives you a helper for each:
 
 - **Write-time rejection (simulated)** — `bench.editDocument({documentId, patch})`
-  writes through the bench client, and a write a deployed guard denies throws
-  `MutationGuardDeniedError` — the rejection the lake is designed to apply to
-  _any_ client once guard enforcement ships; the bench reproduces it on the
-  client it mints.
+  writes through the bench client (`patch` is a `{set?, unset?, insert?}` spec),
+  and a write a deployed guard denies throws `MutationGuardDeniedError` — the
+  rejection the lake is designed to apply to _any_ client once guard
+  enforcement ships; the bench reproduces it on the client it mints. Every
+  guard action is a real write: `action: 'delete'` deletes, `'publish'`
+  promotes the existing `drafts.<id>` draft onto the published id, and
+  `'unpublish'` retracts it — so a guard scoped to `actions: ['publish']` is
+  genuinely consulted. The helper resolves to the post-write document, or
+  `undefined` once a delete/unpublish removed it.
 - **Read-time preflight** — `bench.activeGuardsForDocument(id)` answers "_would_
   a write be denied right now?" _without_ writing. This is the check a UI uses
   to disable a button or show a lock ahead of time. It's a pure read over the
@@ -46,9 +105,9 @@ const bench = createBench({documents: [{_id: 'doc-1', _type: 'article', body: 'b
 const active = await bench.activeGuardsForDocument('doc-1')
 
 // Rejection: a guard-violating write throws (bench-simulated lake contract).
-await expect(bench.editDocument({documentId: 'doc-1', patch: {body: 'edited'}})).rejects.toThrow(
-  MutationGuardDeniedError,
-)
+await expect(
+  bench.editDocument({documentId: 'doc-1', patch: {set: {body: 'edited'}}}),
+).rejects.toThrow(MutationGuardDeniedError)
 ```
 
 > To share one store across benches with the write seam intact, pass another