@classytic/arc-testkit 0.6.0 → 0.7.0

package/dist/story.d.mts

@@ -1,8 +1,8 @@
 import { expect } from "vitest";
-type Clauses = string | readonly string[];
+export type Clauses = string | readonly string[];
 /** `[REQ-1 | Reminders] the reminder reached the holder`. */
-declare function clauseMessage(clauses: Clauses | undefined, what: string): string;
-interface StepContext {
+export declare function clauseMessage(clauses: Clauses | undefined, what: string): string;
+export interface StepContext {
   /** The step's number in the story. */
   readonly n: number;
   readonly title: string;
@@ -16,14 +16,14 @@ interface StepContext {
   /** A known defect: soft, tagged `KNOWN DEFECT <id>` so the report names the open finding. */
   known<T>(defect: string, actual: T, what: string, clauses?: Clauses): ReturnType<typeof expect.soft<T>>;
 }
-interface StepOptions {
+export interface StepOptions {
   clauses?: Clauses;
   /** Per-step timeout in ms. */
   timeout?: number;
 }
 /** What a step body is: the step context, then the vitest test context (fixtures of an extended `test`). */
-type StepBody<Ctx> = (t: StepContext, ctx: Ctx) => void | Promise<void>;
-interface Story<Ctx = unknown> {
+export type StepBody<Ctx> = (t: StepContext, ctx: Ctx) => void | Promise<void>;
+export interface Story<Ctx = unknown> {
   /** Register the next numbered step. */
   step(title: string, run: StepBody<Ctx>): void;
   step(title: string, options: StepOptions, run: StepBody<Ctx>): void;
@@ -31,10 +31,10 @@ interface Story<Ctx = unknown> {
   readonly next: number;
 }
 /** The registration function of an extended `test` (`test.extend(...)`), so steps receive its fixtures. */
-type StepRegistrar<Ctx> = (name: string, fn: (ctx: Ctx & {
+export type StepRegistrar<Ctx> = (name: string, fn: (ctx: Ctx & {
   skip(note?: string): never;
 }) => Promise<void>, timeout?: number) => unknown;
-interface StoryOptions<Ctx = unknown> {
+export interface StoryOptions<Ctx = unknown> {
   /** An extended `test`: steps then get its fixtures as their second argument. Default: vitest's `it`. */
   test?: StepRegistrar<Ctx>;
   /** Names of the extended test's fixtures the steps use; they arrive in the second argument. */
@@ -47,19 +47,19 @@ interface StoryOptions<Ctx = unknown> {
   clauses?: Clauses;
 }
 /** Registers a `describe` holding the story's numbered steps. */
-declare function describeStory<Ctx = unknown>(title: string, define: (story: Story<Ctx>) => void, options?: StoryOptions<Ctx>): void;
+export declare function describeStory<Ctx = unknown>(title: string, define: (story: Story<Ctx>) => void, options?: StoryOptions<Ctx>): void;
 /** Read a handed-over value, with an error that names the missing step instead of a bare `undefined`. */
-declare function need<T>(bag: Readonly<Record<string, T | undefined>>, key: string): T;
+export declare function need<T>(bag: Readonly<Record<string, T | undefined>>, key: string): T;
 type Row = Record<string, unknown>;
 type Awaitable<T> = T | PromiseLike<T>;
 /** A string / RegExp (tested on the row's key field), a function, or an object matched as a deep subset. */
-type RowMatch = string | RegExp | ((row: never) => boolean) | Row;
-interface FeedItem {
+export type RowMatch = string | RegExp | ((row: never) => boolean) | Row;
+export interface FeedItem {
   title?: string;
   message?: string;
   [key: string]: unknown;
 }
-interface StoryPorts<TActor = unknown> {
+export interface StoryPorts<TActor = unknown> {
   /** Deliver everything pending in the transactional outbox (one pass). */
   drain?: () => Awaitable<unknown>;
   /** The domain events seen so far (see {@link createEventLog}). */
@@ -73,7 +73,7 @@ interface StoryPorts<TActor = unknown> {
   /** Field holding an event's type. Default: `type`. */
   eventTypeKey?: string;
 }
-interface Expectation {
+export interface Expectation {
   clauses?: Clauses;
   /** Exact number of matching rows. */
   count?: number;
@@ -82,13 +82,13 @@ interface Expectation {
   /** Ignore the first `since` events (a mark from {@link EventLog.mark}). */
   since?: number;
 }
-interface RelayOptions {
+export interface RelayOptions {
   timeout?: number;
   interval?: number;
 }
 /** True when `actual` carries every field of `expected` (RegExp and function leaves are tested, not compared). */
-declare function subsetMatches(actual: unknown, expected: unknown): boolean;
-interface StoryAssertions<TActor> {
+export declare function subsetMatches(actual: unknown, expected: unknown): boolean;
+export interface StoryAssertions<TActor> {
   /** Drain the outbox `rounds` times (a handler may write further events). */
   drain(rounds?: number): Promise<void>;
   /** Drain, then assert; repeat until the assertion holds (events are relayed asynchronously). */
@@ -104,8 +104,8 @@ interface StoryAssertions<TActor> {
   expectMail(match: RowMatch, spec?: Expectation): Promise<Row[]>;
   expectAudit(filter: Row | undefined, match: RowMatch, spec?: Expectation): Promise<Row[]>;
 }
-declare function createStoryAssertions<TActor = unknown>(ports: StoryPorts<TActor>): StoryAssertions<TActor>;
-interface EventLog<E extends Row = Row> {
+export declare function createStoryAssertions<TActor = unknown>(ports: StoryPorts<TActor>): StoryAssertions<TActor>;
+export interface EventLog<E extends Row = Row> {
   record(event: E): void;
   all(): readonly E[];
   /** The number of events so far: pass it as `since` to look only at what happens next. */
@@ -118,18 +118,18 @@ interface EventLog<E extends Row = Row> {
   tap(subscribe: (pattern: string, handler: (event: E) => unknown) => unknown, patterns: readonly string[]): void;
 }
 /** An in-memory event log fed by a tap on the host's event bus; the `events` port reads it. */
-declare function createEventLog<E extends Row = Row>(): EventLog<E>;
+export declare function createEventLog<E extends Row = Row>(): EventLog<E>;
 /**
  * A cast: the named users of a story, each provisioned with roles by a host function that signs the
  * user up on the booted app and returns whatever the story talks through (a client, a token).
  */
-interface CastSpecEntry<TOpts> {
+export interface CastSpecEntry<TOpts> {
   roles: readonly string[];
   opts?: TOpts;
 }
 /** `roles` shorthand, or `{ roles, opts }` when the host's provisioner takes options (e.g. `{ mfa: false }`). */
-type CastSpec<TOpts> = readonly string[] | CastSpecEntry<TOpts>;
-interface Cast<TActor, TOpts> {
+export type CastSpec<TOpts> = readonly string[] | CastSpecEntry<TOpts>;
+export interface Cast<TActor, TOpts> {
   /** Provision every member of `spec` (in order) and remember them by name. */
   build<const S extends Record<string, CastSpec<TOpts>>>(spec: S): Promise<{ [K in keyof S]: TActor; }>;
   /** Provision one member. */
@@ -138,15 +138,15 @@ interface Cast<TActor, TOpts> {
   get(name: string): TActor;
   names(): string[];
 }
-declare function createCast<TActor, TOpts = undefined>(provision: (roles: readonly string[], opts: TOpts | undefined, name: string) => Promise<TActor>): Cast<TActor, TOpts>;
+export declare function createCast<TActor, TOpts = undefined>(provision: (roles: readonly string[], opts: TOpts | undefined, name: string) => Promise<TActor>): Cast<TActor, TOpts>;
 /** `Authorization` headers for a bearer token. */
-declare const bearer: (token: string) => Record<string, string>;
+export declare const bearer: (token: string) => Record<string, string>;
 /**
  * A controllable clock with time-travel helpers, and the civil-date arithmetic a story needs to say
  * "thirty days later" without drifting across a zone's day boundary. The clock satisfies
  * `{ now(): Date }`, the shape hosts inject into their app; the story moves it, the app reads it.
  */
-interface StoryClock {
+export interface StoryClock {
   /** The `{ now }` the app reads. */
   now(): Date;
   /** The IANA zone civil dates are read in. */
@@ -162,23 +162,23 @@ interface StoryClock {
   /** Called after every move with the new instant. */
   onChange(listener: (at: Date) => void): () => void;
 }
-interface StoryClockOptions {
+export interface StoryClockOptions {
   start?: Date | string | number;
   /** IANA zone for civil dates. Default: UTC. */
   zone?: string;
 }
 /** The civil date (`YYYY-MM-DD`) of an instant in a zone. */
-declare function civilDateOf(at: Date, zone?: string): string;
+export declare function civilDateOf(at: Date, zone?: string): string;
 /** A civil date plus whole days. */
-declare function addCivilDays(day: string, days: number): string;
+export declare function addCivilDays(day: string, days: number): string;
 /** A civil date plus whole months (same day of month; keep stories off the 29th to 31st). */
-declare function addCivilMonths(day: string, months: number): string;
+export declare function addCivilMonths(day: string, months: number): string;
 /** Whole days from civil date `a` to civil date `b`. */
-declare function daysBetween(a: string, b: string): number;
+export declare function daysBetween(a: string, b: string): number;
 /** The instant at `hour:00` (default noon) on a civil date in a zone: a stable "that day". */
-declare function instantOn(day: string, zone?: string, hour?: number): Date;
-declare function createStoryClock(options?: StoryClockOptions): StoryClock;
-interface IdempotencyOptions<TResult, TSnapshot> {
+export declare function instantOn(day: string, zone?: string, hour?: number): Date;
+export declare function createStoryClock(options?: StoryClockOptions): StoryClock;
+export interface IdempotencyOptions<TResult, TSnapshot> {
   /** The sweep. */
   run: () => Promise<TResult>;
   /** What must be identical after run 1 and after run 2 (counts, ids, rows). */
@@ -189,14 +189,14 @@ interface IdempotencyOptions<TResult, TSnapshot> {
   /** Names the sweep in the failure. */
   label?: string;
 }
-interface IdempotencyOutcome<TResult, TSnapshot> {
+export interface IdempotencyOutcome<TResult, TSnapshot> {
   first: TResult;
   second: TResult;
   afterFirst: TSnapshot;
   afterSecond: TSnapshot;
 }
 /** Run twice; fail unless the snapshot after the second run equals the one after the first. */
-declare function expectIdempotent<TResult, TSnapshot>(opts: IdempotencyOptions<TResult, TSnapshot>): Promise<IdempotencyOutcome<TResult, TSnapshot>>;
+export declare function expectIdempotent<TResult, TSnapshot>(opts: IdempotencyOptions<TResult, TSnapshot>): Promise<IdempotencyOutcome<TResult, TSnapshot>>;
 /** {@link expectIdempotent} for several named sweeps sharing one snapshot. */
-declare function expectSweepsIdempotent<TSnapshot>(sweeps: Readonly<Record<string, () => Promise<unknown>>>, common: Pick<IdempotencyOptions<unknown, TSnapshot>, "snapshot" | "settle" | "clauses">): Promise<void>;
-export { Cast, CastSpec, CastSpecEntry, Clauses, EventLog, Expectation, FeedItem, IdempotencyOptions, IdempotencyOutcome, RelayOptions, RowMatch, StepBody, StepContext, StepOptions, StepRegistrar, Story, StoryAssertions, StoryClock, StoryClockOptions, StoryOptions, StoryPorts, addCivilDays, addCivilMonths, bearer, civilDateOf, clauseMessage, createCast, createEventLog, createStoryAssertions, createStoryClock, daysBetween, describeStory, expectIdempotent, expectSweepsIdempotent, instantOn, need, subsetMatches };
+export declare function expectSweepsIdempotent<TSnapshot>(sweeps: Readonly<Record<string, () => Promise<unknown>>>, common: Pick<IdempotencyOptions<unknown, TSnapshot>, "snapshot" | "settle" | "clauses">): Promise<void>;
+export {};

package/llms.txt

@@ -1,7 +1,7 @@
 # @classytic/arc-testkit
 
 > Test harness for arc apps: boot modules on in-memory MongoDB, pool servers, cost and plan asserts,
-> conformance guards and a story kit. Needs @classytic/arc >=2.43.0; the guards and stories need vitest >=3.
+> conformance guards and a story kit. Needs @classytic/arc >=2.49.0 for the root entry (an optional peer); the guards and stories need vitest >=4.1.11.
 
 Hand-rolling any row below is a bug. Skill: skills/arc-testkit/SKILL.md (+ references/).
 
@@ -12,7 +12,7 @@ Hand-rolling any row below is a bug. Skill: skills/arc-testkit/SKILL.md (+ refer
 | Worker cap by cores and RAM | safeWorkerCount | /mongo |
 | Wait for index builds | awaitIndexBuilds | /mongo |
 | N+1 detection | countCommands, assertConstantCommands | /mongo-commands |
-| Index plan proof | assertIndexServed, summarizeExplain | /mongo-explain |
+| Index plan proof | assertIndexServed, summarizeExplain, explainCaptured | /mongo-explain |
 | List routes answer the repo-core envelope | checkListEnvelopes, registerListEnvelopeGuard | /conformance |
 | Actions and write routes have schemas | checkRouteSchemas, registerRouteSchemaGuard | /conformance |
 | Verb and route-family naming | checkNaming, registerNamingGuard | /conformance |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/arc-testkit",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Boot a real @classytic/arc app around the module(s) under test on in-memory MongoDB — the ecosystem test harness. Thin Mongo-typed wrapper over @classytic/arc/testing (arc 2.22+). If your arc module boots green here, it composes into any arc host.",
   "type": "module",
   "exports": {
@@ -60,11 +60,14 @@
     "mongodb-memory-server": ">=10.0.0"
   },
   "peerDependencies": {
-    "vitest": ">=5.0.5",
-    "@classytic/arc": ">=2.46.0",
+    "vitest": ">=4.1.11",
+    "@classytic/arc": ">=2.49.0",
     "mongoose": ">=9.11.4"
   },
   "peerDependenciesMeta": {
+    "@classytic/arc": {
+      "optional": true
+    },
     "mongoose": {
       "optional": true
     },

package/skills/arc-testkit/SKILL.md

@@ -10,7 +10,7 @@ metadata:
 
 # @classytic/arc-testkit
 
-Needs `@classytic/arc >=2.43.0`; `mongoose >=9.4.1` for root, `/pool`, `/mongo*`; `/conformance` and `/story` need `vitest >=3` only. Guards are `check*` (returns problems) plus `register*` (vitest tests).
+Root needs `@classytic/arc >=2.49.0`; `mongoose >=9.11.4` for root, `/pool`, `/mongo*`; `/conformance`, `/story` need only `vitest >=4.1.11`. Guards are `check*` (returns problems) + `register*` (vitest tests).
 
 ## Do not hand-roll
 
@@ -21,7 +21,7 @@ Needs `@classytic/arc >=2.43.0`; `mongoose >=9.4.1` for root, `/pool`, `/mongo*`
 | Worker cap by cores and RAM | `safeWorkerCount(envVar)` | `/mongo` |
 | Wait for index builds | `awaitIndexBuilds` | `/mongo` |
 | Count driver commands (N+1) | `countCommands`, `assertConstantCommands` | `/mongo-commands` |
-| Prove a query uses an index | `assertIndexServed`, `summarizeExplain` | `/mongo-explain` |
+| Query uses an index | `assertIndexServed`, `summarizeExplain`, `explainCaptured` | `/mongo-explain` |
 | Every list answers the repo-core envelope | `checkListEnvelopes`, `registerListEnvelopeGuard` | `/conformance` |
 | Every action/write route has a schema | `checkRouteSchemas`, `registerRouteSchemaGuard` | `/conformance` |
 | Verb and route-family naming | `checkNaming`, `registerNamingGuard` | `/conformance` |
@@ -95,8 +95,7 @@ describeStory("checkout", (s) => {
 - `checkErrorContracts` needs a probe per class (`require` narrows them); its unknown-route probe also fails when the query string is echoed.
 - Fastify's own 404 body fails the contract: set a not-found handler.
 - `checkRouteSchemas` reads `app.arc.registry`: the app must be booted by arc.
-- A pool needs `globalSetup` to preboot, else every worker boots its own mongod. `countCommands` needs `monitorCommands: true`.
-- `loadOpenApiDump` throws when the dump is older than the `.ts` under `sources`: regenerate it.
+- A pool needs `globalSetup` to preboot, else every worker boots its own mongod. `countCommands` needs `monitorCommands: true`.- `loadOpenApiDump` throws when the dump is older than the `.ts` under `sources`: regenerate it.
 
 ## Never
 

package/skills/arc-testkit/references/conformance.md

@@ -65,14 +65,14 @@ Options (`OpenApiOptions`): `spec` (document or getter; `fetchOpenApi(caller, pa
 ## Client drift
 
 `checkClientDrift({ spec, routes, bodyFields, minRoutes })`. `routes`: `[{ method, path, source? }]` the client can emit;
-a path may be concrete (`/api/x/507f...`), a template (`/api/x/:id`, `/api/x/{id}`), with a query or trailing slash.
-`bodyFields`: `[{ method, path: "/api/x/{id}/action", fields: [...], in: "request" | "response", status: "200", name? }]`
-(path spelled as the spec does; fields resolved through `$ref`, `oneOf`, `allOf`, `anyOf`). Failures: `client route
+a path may be concrete (`/api/x/507f...`) or a template (`:id`, `{id}`), with a query or trailing slash.
+`bodyFields`: `[{ method, path: "/api/x/{id}/action", fields: [...], values?: [...], in: "request" | "response", status: "200", name? }]`
+(path as the spec spells it; through `$ref`, `oneOf`, `allOf`, `anyOf`; `values`: sent `enum`/`const` literals). Failures: `client route
 missing from the document: DELETE /api/x/:id/archive   (source)`, `NAME: field "f" is not in the schema`, `NAME: the
-document declares no request schema`. Carry the spec between processes: `dumpOpenApi(spec, file)` on the server,
+document declares no request schema`. Across processes: `dumpOpenApi(spec, file)` on the server,
 `loadOpenApiDump(file, { sources: [dirs], regenerate: "cd apps/server && npm run openapi:dump" })` on the client; it throws
-when the dump is missing or older than a `.ts` under `sources`. Exported helpers: `specMatcher`, `missingClientRoutes`,
-`bodyFieldProblems`, `propertyNames`, `resolveRef`. Needs the node environment (reads files).
+when the dump is missing or older than a `.ts` under `sources`. Helpers: `specMatcher`, `missingClientRoutes`,
+`bodyFieldProblems`, `propertyNames`, `schemaValues`, `resolveRef`. Node environment.
 
 ## Error contract
 
@@ -94,11 +94,12 @@ registered`, `/api/x/: a collection is addressed by its bare path`, `GET /api/x
 
 ## Refusal does no work
 
-`checkRefusalDoesNoWork({ app, anonymous, unprivileged, snapshot, routes, prefix, exclude, paramValue, refusedStatuses, settleMs, minRoutes })`.
-Calls every mutating route (default: POST PUT PATCH DELETE of the route table, `:param` filled with `paramValue`; or
-`routes: [{ method, path, body? }]`) as `anonymous` and as `unprivileged` (`InjectCaller`s). Each call must answer
-401/403 and leave `snapshot()` (host state: row counts, a phase, an outbox length) deep-equal before and after. A gate
-that only calls `reply.send` still answers 403 when 2+ async `preSerialization`/`onSend` hooks defer the write, yet the
-handler runs: only the snapshot shows it. `exclude`: `METHOD /path` keys that accept the caller, with the reason.
-Failures: `anonymous POST /x: answered 403 but the snapshot changed: the handler ran after the refusal`, `unprivileged
-PATCH /x/1: answered 200, expected a refusal (401/403)`, `stale exclusion KEY`. Fix: `return reply.send(...)` or throw.
+`checkRefusalDoesNoWork({ app, anonymous, unprivileged, snapshot, routes, prefix, exclude, paramValue, actionBodies, refusedStatuses, settleMs, minRoutes, name })`.
+Calls every mutating route (default: POST PUT PATCH DELETE of the route table; or `routes: [{ method, path, body? }]`)
+as `anonymous` and `unprivileged`; each must answer 401/403 and leave `snapshot()` deep-equal. A gate that only calls
+`reply.send` answers 403 while the handler still runs: only the snapshot shows it.
+`paramValue`: id or `({ method, path, resource }) => id`. `exclude`: `METHOD /path` or `resource.verb` keys with the
+reason, one list or `{ anonymous, unprivileged }`. `actionBodies: { "resource.verb": body | (ctx) => body }`: one call
+per verb on each action route (`{}` alone is a 400); no body fails. `name` titles the test.
+Failures: `anonymous POST /x: answered 403 but the snapshot changed`, `unprivileged PATCH /x/1: answered 200, expected
+a refusal (401/403)`, `stale exclusion KEY`. Fix: `return reply.send(...)` or throw.

package/skills/arc-testkit/references/fixtures.md

@@ -90,3 +90,15 @@ const { stages, indexes, docsExamined } = summarizeExplain(explain);
 `assertIndexServed` fails on COLLSCAN, on a plan scanning no index (empty or missing collection), on an index in `index`
 that is not scanned, a stage in `stages` that is absent, and on `maxDocsExamined` exceeded (needs `executionStats`).
 Rejected plans and query predicates are never read.
+
+A query built inside a repository or plugin is explained as sent, not copied into the test:
+
+```ts
+import { assertIndexServed, explainCaptured } from "@classytic/arc-testkit/mongo-explain";
+
+const { explain, command } = await explainCaptured(connection, () => service.claim(now), { collection: "timers", commands: ["findAndModify"] });
+assertIndexServed(explain, { index: "state_due", maxDocsExamined: 6 });
+```
+
+`explainCaptured(source, run, { collection, commands?, index?, verbosity? })` needs `monitorCommands: true`; it fails
+when `run` sent no matching command, or several without `index`. The explain applies no write.