@classytic/arc-testkit 0.4.0 → 0.6.0

package/README.md

@@ -7,10 +7,10 @@ The ecosystem's contributor contract for the `@classytic/arc-*` module fleet: **
 ## Install
 
 ```bash
-npm i -D @classytic/arc-testkit @classytic/mongokit mongodb-memory-server
+npm i -D @classytic/arc-testkit mongodb-memory-server
 ```
 
-`@classytic/mongokit` + `mongodb-memory-server` are **optional peers** — needed only for the default backend, and dynamically imported so they never enter a production bundle. Pass your own `backend` to skip them entirely.
+`mongoose` (>=9.4.1) is needed by `.`, `/pool`, `/mongo` and `/mongo-commands`; `/conformance` and `/story` need only `vitest` (>=3) and a booted arc app. `mongodb-memory-server` is imported lazily by the default database.
 
 ## Usage
 
@@ -39,26 +39,58 @@ const t = await bootModuleApp(({ connection }) => [createReservationModule({ con
   { replset: true });
 ```
 
-## Bring your own backend
+## Bring your own database
 
-The default backend is `mongoMemoryBackend()` from `@classytic/mongokit/testkit`. Override it to point at a shared server, a real Atlas cluster, or a different kit's backend — anything that satisfies the `TestBackend` shape (`setup() → { ctx: { connection, uri }, teardown }`):
+Pass a `TestDatabaseFactory` (from `@classytic/arc/testing`) as `database`, for example a pooled one from `createTestDatabasePool(mongoServerProvider({ mongoose })).factory` (`/pool`, `/mongo`):
 
 ```ts
-import { mongoMemoryBackend } from '@classytic/mongokit/testkit';
-
-const t = await bootModuleApp(mods, {
-  backend: mongoMemoryBackend({ uri: process.env.ATLAS_TEST_URI }), // real cluster
-});
+const t = await bootModuleApp(mods, { database: dbPool.factory });
 ```
 
 ## API
 
 | Export | |
 | --- | --- |
-| `bootModuleApp(modules, options?)` | boot arc around modules on a backend; returns `{ app, connection, mongoUri, close }` |
-| `TestBackend` | the backend seam — `setup() → { ctx: { connection, uri }, teardown }` |
+| `bootModuleApp(modules, options?)` | boot arc around modules; returns `{ app, uri, connection, exports(name), close }` |
 | `TestkitContext` | what a module factory receives: `{ connection, mongoUri }` |
-| `BootModuleAppOptions` | `{ replset?, app?, backend? }` |
+| `BootModuleAppOptions` | `{ replset?, database?, app?, actor?, ports? }` |
+| `ModulesInput`, `ModuleTestApp` | the modules argument and the boot result types |
+| `/pool` | `createTestDatabasePool`, `publishPoolServers` |
+| `/mongo` | `mongoServerProvider`, `safeWorkerCount`, `safePoolSize`, `awaitIndexBuilds`, `withDbName`, `cacheSizeGB`, `mongodMemoryArgs` |
+| `/mongo-commands`, `/mongo-explain` | `countCommands`, `assertConstantCommands`, `summarizeExplain`, `assertIndexServed` |
+| `/conformance` | `check*` / `register*` for list envelope, route schemas, naming, OpenAPI, client drift, collection routes, error contract; `expectClean`, `injectCaller`, `fetchOpenApi`, `routeTable` |
+| `/story` | `describeStory`, `createCast`, `createStoryClock`, `createStoryAssertions`, `createEventLog`, `expectIdempotent`, `expectSweepsIdempotent` |
+
+## Cost and plan assertions (MongoDB)
+
+```ts
+import { assertConstantCommands, countCommands } from '@classytic/arc-testkit/mongo-commands';
+import { assertIndexServed } from '@classytic/arc-testkit/mongo-explain';
+
+// What the driver sent (the connection needs `monitorCommands: true` — it refuses otherwise).
+const { total, byCollection } = await countCommands(conn, () => placeOrder(), { collections: ['orders'] });
+// Same commands at every size, and at least one: a per-item read fails here.
+await assertConstantCommands(conn, (n) => reader.page(n), [5, 50]);
+// No COLLSCAN, an index scanned, optionally a named one and a docs-examined ceiling.
+assertIndexServed(await Model.find(filter).explain('executionStats'), { index: 'org_state', maxDocsExamined: 40 });
+```
+
+## Conformance guards and story kit (opt-in, need `vitest`)
+
+```ts
+// tests/conformance.test.ts — one call per guard, parameters are yours
+import { fetchOpenApi, registerListEnvelopeGuard, registerOpenApiGuard, registerRouteSchemaGuard } from '@classytic/arc-testkit/conformance';
+
+registerListEnvelopeGuard({ app: () => t.app, caller: () => admin, prefix: '/api', notLists: { '/api/me': 'one document' } });
+registerRouteSchemaGuard({ app: () => t.app, actionExceptions: { 'media.signed-url': 'package-mounted' } });
+registerOpenApiGuard({ spec: () => fetchOpenApi(admin), app: () => t.app, anonymous: () => anon, prefix: '/api',
+  publicOperations: [{ path: '/api/auth/sign-in', why: 'sign-in' }] });
+```
+
+Every guard is also a `check*` function returning the problems found (empty when green). Exception
+lists fail when an entry matches nothing. `@classytic/arc-testkit/story` holds `describeStory`,
+`createCast`, `createStoryClock`, `createStoryAssertions` (outbox / events / feed / mail / audit through
+readers you inject) and `expectIdempotent`; see the module docs.
 
 ## License
 

package/dist/conformance.d.mts

@@ -0,0 +1,380 @@
+/** A lazily supplied value: build it in `beforeAll`, hand the suite a getter. */
+type Source<T> = T | (() => T | Promise<T>);
+interface InjectResponse {
+  statusCode: number;
+  body: string;
+  headers: Record<string, unknown>;
+}
+/** What the suites read of a booted arc app. Fastify's instance satisfies it. */
+interface AppLike {
+  inject(opts: {
+    method: string;
+    url: string;
+    headers?: Record<string, string>;
+    payload?: unknown;
+  }): PromiseLike<InjectResponse>;
+  printRoutes(opts?: {
+    commonPrefix?: boolean;
+    includeHooks?: boolean;
+  }): string;
+}
+/** `app.arc.registry.getAll()` entries, as far as the schema guard reads them. */
+interface RegistryEntryLike {
+  name: string;
+  actions?: Array<{
+    name: string;
+    schema?: unknown;
+  }>;
+  customRoutes?: Array<{
+    method: string;
+    path: string;
+    schema?: {
+      body?: unknown;
+    };
+  }>;
+}
+interface Reply {
+  status: number;
+  body: unknown;
+  headers?: Record<string, unknown>;
+}
+/** Sends requests as one identity. A host test client (`admin.get(path)`) already fits. */
+interface Caller {
+  get(path: string): Promise<Reply>;
+}
+interface InjectCaller extends Caller {
+  request(method: string, path: string, body?: unknown): Promise<Reply>;
+  post(path: string, body?: unknown): Promise<Reply>;
+  put(path: string, body?: unknown): Promise<Reply>;
+  patch(path: string, body?: unknown): Promise<Reply>;
+  delete(path: string): Promise<Reply>;
+}
+/** A `Caller` over `app.inject`, JSON in and out, sending `headers` (an auth token) with every request. */
+declare function injectCaller(app: AppLike, headers?: Record<string, string>): InjectCaller;
+interface RouteRow {
+  path: string;
+  methods: string[];
+}
+/** The app's route table as `{ path, methods }` rows, read from Fastify's radix-tree dump. */
+declare function routeTable(app: Pick<AppLike, "printRoutes">): RouteRow[];
+/** `/a/{id}/b`, `/a/:id|:other/b` and `/a/:id/b/` are one shape: `/a/:x/b`. */
+declare function shapeOf(path: string): string;
+/** An exception list: bare keys, or `key -> reason`. */
+type Exceptions = Iterable<string> | Readonly<Record<string, string>>;
+/** Fails with the problems listed, one per line; passes when there are none. Use it with the `check*` functions inside a host's own tests. */
+declare function expectClean(what: string, problems: readonly string[]): void;
+declare const OPENAPI_METHODS: readonly ["get", "put", "post", "delete", "patch"];
+interface OpenApiOperation {
+  [extension: string]: unknown;
+  security?: unknown[];
+  requestBody?: {
+    content?: Record<string, {
+      schema?: OpenApiSchema;
+    }>;
+  };
+  responses?: Record<string, {
+    content?: Record<string, {
+      schema?: OpenApiSchema;
+    }>;
+  }>;
+}
+interface OpenApiSchema {
+  $ref?: string;
+  type?: string;
+  properties?: Record<string, OpenApiSchema>;
+  oneOf?: OpenApiSchema[];
+  allOf?: OpenApiSchema[];
+  anyOf?: OpenApiSchema[];
+  enum?: unknown[];
+  items?: OpenApiSchema;
+}
+interface OpenApiDocument {
+  openapi?: string;
+  security?: unknown[];
+  paths: Record<string, Record<string, OpenApiOperation>>;
+  components?: {
+    schemas?: Record<string, OpenApiSchema>;
+  };
+}
+/** Read the document from the running app (default `/openapi.json`). */
+declare function fetchOpenApi(caller: Caller, path?: string): Promise<OpenApiDocument>;
+interface PublicOperation {
+  /** A path template as it appears in the document, or a test for it. */
+  path: string | RegExp | ((path: string) => boolean);
+  why: string;
+}
+interface OpenApiOptions {
+  spec: Source<OpenApiDocument>;
+  /** The booted app: enables the "names every route" check. */
+  app?: Source<AppLike>;
+  /** An unauthenticated caller: enables the "protected GETs refuse anonymous" check. */
+  anonymous?: Source<Caller>;
+  /** Every documented path starts with this, except the public ones. */
+  prefix?: string;
+  /** Operations that are public on purpose; each must still match something. */
+  publicOperations?: readonly PublicOperation[];
+  /** Routes the document does not have to name (matched on the route-table path). */
+  undocumented?: RegExp;
+  /** Document paths never probed anonymously. Default: parameterised paths and `/stream`. */
+  skipAnonymous?: RegExp;
+  /** At least this many operations must be documented. Default: 1. */
+  minOperations?: number;
+  /** Configuration values (secrets, connection strings) that must not appear in the document; ignored under 6 characters. */
+  secretValues?: Source<readonly (string | undefined)[]>;
+  /** Patterns that must not match the serialised document. Default: mongodb and redis URLs. */
+  secretPatterns?: readonly RegExp[];
+}
+/** The document is OpenAPI 3, prefixed, and has no trailing-slash path. */
+declare function checkOpenApiShape(opts: OpenApiOptions): Promise<string[]>;
+/** Every route in the table is documented (once, in its bare form). */
+declare function checkRoutesDocumented(opts: OpenApiOptions): Promise<string[]>;
+/**
+ * Every operation requires a security scheme (its own `security`, else the document's), except the
+ * public list; a public rule that matches no operation fails as stale.
+ */
+declare function checkSecurity(opts: OpenApiOptions): Promise<string[]>;
+/** An anonymous GET of every documented, protected, parameterless path is refused with 401. */
+declare function checkAnonymousRefused(opts: OpenApiOptions, expected?: number): Promise<string[]>;
+/** The serialised document carries no configuration value. */
+declare function checkNoSecrets(opts: OpenApiOptions): Promise<string[]>;
+/** Registers the OpenAPI guards as vitest tests (the optional ones only when their input is given). */
+declare function registerOpenApiGuard(opts: OpenApiOptions): void;
+interface ClientRoute {
+  method: string;
+  path: string;
+  /** Where the client emits it, named in the failure. */
+  source?: string;
+}
+/** Spec path templates as matchers: `/api/x/{id}/y` accepts `/api/x/anything/y` and `/api/x/:id/y`. */
+declare function specMatcher(spec: OpenApiDocument): (method: string, path: string) => string | undefined;
+/** Client routes the document does not have (sorted, deduplicated, with their source). */
+declare function missingClientRoutes(spec: OpenApiDocument, routes: readonly ClientRoute[]): string[];
+declare function resolveRef(spec: OpenApiDocument, schema: OpenApiSchema | undefined): OpenApiSchema | undefined;
+/** Every property name a schema offers, through refs and unions. */
+declare function propertyNames(spec: OpenApiDocument, schema: OpenApiSchema | undefined, depth?: number): Set<string>;
+interface BodyFieldCheck {
+  name?: string;
+  method: string;
+  /** The path template as the document spells it. */
+  path: string;
+  /** Fields the client reads or sends. */
+  fields: readonly string[];
+  /** Which body to read. Default: `request`. */
+  in?: "request" | "response";
+  /** Response status to read. Default: 200. */
+  status?: string;
+}
+declare function bodyFieldProblems(spec: OpenApiDocument, check: BodyFieldCheck): string[];
+interface ClientDriftOptions {
+  spec: Source<OpenApiDocument>;
+  routes: Source<readonly ClientRoute[]>;
+  bodyFields?: readonly BodyFieldCheck[];
+  /** At least this many client routes must be supplied (guards against an empty probe). Default: 1. */
+  minRoutes?: number;
+}
+declare function checkClientDrift(opts: ClientDriftOptions): Promise<string[]>;
+/** Registers the drift guard as vitest tests. */
+declare function registerClientDriftGuard(opts: ClientDriftOptions): void;
+/** Write the document to `file` (the server side of the dump: `npm run openapi:dump`). */
+declare function dumpOpenApi(spec: OpenApiDocument, file: string): void;
+/**
+ * Read a dumped document. Throws when the dump is missing or older than any `.ts` file under
+ * `sources`, so a stale document can never pass for the current API. `regenerate` names the command
+ * in the message.
+ */
+declare function loadOpenApiDump(file: string, opts?: {
+  sources?: readonly string[];
+  regenerate?: string;
+}): OpenApiDocument;
+interface CollectionRoute {
+  /** The bare collection path, e.g. `/api/things`. */
+  path: string;
+  /** The verbs the client sends to it. */
+  methods: readonly string[];
+}
+interface CollectionRoutesOptions {
+  app: Source<AppLike>;
+  collections: readonly CollectionRoute[];
+  /** Bare GET paths that must answer 200 for `caller` (and the trailing-slash form is not what is registered). */
+  served?: {
+    caller: Source<Caller>;
+    paths: readonly string[];
+  };
+}
+declare function checkCollectionRoutes(opts: CollectionRoutesOptions): Promise<string[]>;
+/** Registers the collection route guard as a vitest test. */
+declare function registerCollectionRoutesGuard(opts: CollectionRoutesOptions): void;
+type ErrorClass = "validation" | "unauthorized" | "forbidden" | "notFound" | "unknownRoute" | "conflict" | "duplicateKey";
+interface ErrorProbe {
+  /** Send the request that fails this way. */
+  provoke: () => Promise<Reply>;
+  /** Default: 400 validation, 401, 403, 404, 409. */
+  status?: number;
+  /** The exact `code`, or a test for it. Default: any non-empty string. */
+  code?: string | RegExp;
+  /** `some`: `details` is a non-empty array. `none`: absent. Default: some for validation and duplicateKey. */
+  details?: "some" | "none";
+  /** Every `details[].code` equals this. Default: `duplicate_key` for duplicateKey. */
+  detailCode?: string;
+}
+interface ErrorContractOptions {
+  probes: Partial<Record<ErrorClass, ErrorProbe | readonly ErrorProbe[]>>;
+  /** An authenticated caller for the built-in `unknownRoute` probe (so a 404 is not a 401). */
+  caller?: Source<Caller>;
+  /** Every class listed here must have a probe. Default: all seven. */
+  require?: readonly ErrorClass[];
+  /** Keys allowed on the body. Default: the ErrorContract keys. */
+  allowedKeys?: readonly string[];
+}
+declare const ERROR_CLASSES: readonly ErrorClass[];
+/** The reasons a reply is not the expected `ErrorContract` (empty: it is one). */
+declare function errorContractProblems(reply: Reply, expected: {
+  status: number;
+  code?: string | RegExp;
+  details?: "some" | "none";
+  detailCode?: string;
+}, allowedKeys?: readonly string[]): string[];
+/** Throws unless the reply is the expected `ErrorContract`; returns the body. */
+declare function expectErrorContract(reply: Reply, expected: {
+  status: number;
+  code?: string | RegExp;
+  details?: "some" | "none";
+  detailCode?: string;
+}): Record<string, unknown>;
+declare function checkErrorContracts(opts: ErrorContractOptions): Promise<string[]>;
+/** Registers the error contract guard as vitest tests. */
+declare function registerErrorContractGuard(opts: ErrorContractOptions): void;
+interface FilterDeclaration {
+  /** The list route, concrete or a template (`/api/items`). */
+  route: string;
+  /** Filters the screen sends. `op` defaults to `eq`. */
+  filters?: readonly {
+    queryField: string;
+    op?: string;
+  }[];
+  /** The screen sends free-text search. */
+  search?: boolean;
+  /** Sort fields the screen offers (`-name` and `name` are the same field). */
+  sorts?: readonly string[];
+}
+interface FilterDeclarationsOptions {
+  spec: Source<OpenApiDocument>;
+  declarations: Source<readonly FilterDeclaration[]>;
+}
+declare function checkFilterDeclarations(opts: FilterDeclarationsOptions): Promise<string[]>;
+/** Registers the declaration check as a vitest test. */
+declare function registerFilterDeclarationsGuard(opts: FilterDeclarationsOptions): void;
+interface ListEnvelopeOptions {
+  app: Source<AppLike>;
+  /** An identity allowed to read every list (an admin). */
+  caller: Source<Caller>;
+  /** Only GET routes under this prefix are probed. Default: all. */
+  prefix?: string;
+  /** Static GET paths that do not answer a list (single documents, tables, probes), with the reason. */
+  notLists?: Exceptions;
+  /** Paths that answer their own shape (package-owned routes), with the reason. */
+  customShapes?: Exceptions;
+  /** GET paths never probed (streams, downloads). Default: `/(stream|export|content|download)(/|$)`. */
+  skip?: RegExp;
+  /** Keys a list never carries beside `data`. */
+  forbiddenKeys?: readonly string[];
+  /** Page kinds accepted when a body carries `method`. Default: offset and keyset. */
+  methods?: readonly ("offset" | "keyset")[];
+  /** At least this many routes must be probed. Default: 1. */
+  minRoutes?: number;
+  /** Lists that must be among the checked ones (guards against a probe silently skipping them). */
+  expectLists?: readonly string[];
+}
+/** The reasons a body is not a canonical list (empty: it is one). */
+declare function listEnvelopeProblems(body: unknown, methods?: readonly string[], forbidden?: readonly string[]): string[];
+interface ListEnvelopeResult {
+  problems: string[];
+  /** Paths that answered a list and were checked. */
+  lists: string[];
+  /** Static GET paths considered (after prefix and skip). */
+  probed: string[];
+}
+declare function checkListEnvelopes(opts: ListEnvelopeOptions): Promise<ListEnvelopeResult>;
+/** Registers the list envelope guard as vitest tests. */
+declare function registerListEnvelopeGuard(opts: ListEnvelopeOptions): void;
+interface PathRule {
+  name: string;
+  /** Routes whose path matches belong to the family. */
+  match: RegExp;
+  /** The complete `METHOD /path` set the family may have. */
+  allowed: readonly string[];
+}
+interface NamingOptions {
+  app: Source<AppLike>;
+  /** Action verbs must match. Default: camelCase. */
+  verbPattern?: RegExp;
+  /** Verbs owned by packages the host cannot change, with the reason. */
+  exemptVerbs?: Exceptions;
+  /** Verbs that must exist (guards against reading an empty registry). */
+  requiredVerbs?: readonly string[];
+  /** At least this many verbs must exist. Default: 1. */
+  minVerbs?: number;
+  pathRules?: readonly PathRule[];
+  forbiddenPaths?: readonly RegExp[];
+}
+declare function checkNaming(opts: NamingOptions): Promise<string[]>;
+/** Registers the naming guard as vitest tests. */
+declare function registerNamingGuard(opts: NamingOptions): void;
+interface MutatingRoute {
+  method: string;
+  /** A concrete path (no `:param`); give `body` when the route needs one to reach its gate. */
+  path: string;
+  body?: unknown;
+}
+interface RefusalOptions {
+  /** The booted app. Required unless `routes` is given. */
+  app?: Source<AppLike>;
+  /** Authenticated, but holding none of the privileges the mutating routes require. */
+  unprivileged?: Source<InjectCaller>;
+  /** No credentials. */
+  anonymous?: Source<InjectCaller>;
+  /**
+   * The host's state fingerprint: anything JSON-like that changes when a handler did work (row
+   * counts, a state machine's phase, an outbox length). Compared with deep equality, before and
+   * after every call.
+   */
+  snapshot: () => unknown | Promise<unknown>;
+  /** The routes to call. Default: every POST/PUT/PATCH/DELETE in the route table. */
+  routes?: Source<readonly MutatingRoute[]>;
+  /** Only table routes whose path starts with this. */
+  prefix?: string;
+  /** `METHOD /path` keys (as the route table spells them) that legitimately accept the caller, with the reason. */
+  exclude?: Exceptions;
+  /** Value put in every `:param` of a derived path. Default: a 24-hex id. */
+  paramValue?: string;
+  /** Statuses that count as a refusal. Default: 401 and 403. */
+  refusedStatuses?: readonly number[];
+  /** Milliseconds to let a late handler finish before the second snapshot. Default: 25. */
+  settleMs?: number;
+  /** At least this many routes must be checked. Default: 1. */
+  minRoutes?: number;
+}
+/** Problems found; empty when every refusal answered and left the snapshot unchanged. */
+declare function checkRefusalDoesNoWork(opts: RefusalOptions): Promise<string[]>;
+/** Registers the refusal guard as a vitest test. */
+declare function registerRefusalDoesNoWorkGuard(opts: RefusalOptions): void;
+interface RouteSchemaOptions {
+  app: Source<AppLike>;
+  /** `<resource>.<action>` keys that need no schema (package-mounted actions), with the reason. */
+  actionExceptions?: Exceptions;
+  /** `<resource> <METHOD> <path>` keys of body-bearing routes that need no body schema, with the reason. */
+  routeExceptions?: Exceptions;
+  /** HTTP methods that must declare a body. Default: POST, PUT, PATCH. */
+  bodyMethods?: readonly string[];
+  /** At least this many actions must exist (guards against reading an empty registry). Default: 1. */
+  minActions?: number;
+}
+interface RouteSchemaResult {
+  problems: string[];
+  actions: number;
+  routes: number;
+}
+declare function checkRouteSchemas(opts: RouteSchemaOptions): Promise<RouteSchemaResult>;
+/** Registers the schema guard as vitest tests. */
+declare function registerRouteSchemaGuard(opts: RouteSchemaOptions): void;
+export { type AppLike, BodyFieldCheck, type Caller, ClientDriftOptions, ClientRoute, CollectionRoute, CollectionRoutesOptions, ERROR_CLASSES, ErrorClass, ErrorContractOptions, ErrorProbe, type Exceptions, FilterDeclaration, FilterDeclarationsOptions, type InjectCaller, ListEnvelopeOptions, ListEnvelopeResult, MutatingRoute, NamingOptions, OPENAPI_METHODS, OpenApiDocument, OpenApiOperation, OpenApiOptions, OpenApiSchema, PathRule, PublicOperation, RefusalOptions, type RegistryEntryLike, type Reply, type RouteRow, RouteSchemaOptions, RouteSchemaResult, type Source, bodyFieldProblems, checkAnonymousRefused, checkClientDrift, checkCollectionRoutes, checkErrorContracts, checkFilterDeclarations, checkListEnvelopes, checkNaming, checkNoSecrets, checkOpenApiShape, checkRefusalDoesNoWork, checkRouteSchemas, checkRoutesDocumented, checkSecurity, dumpOpenApi, errorContractProblems, expectClean, expectErrorContract, fetchOpenApi, injectCaller, listEnvelopeProblems, loadOpenApiDump, missingClientRoutes, propertyNames, registerClientDriftGuard, registerCollectionRoutesGuard, registerErrorContractGuard, registerFilterDeclarationsGuard, registerListEnvelopeGuard, registerNamingGuard, registerOpenApiGuard, registerRefusalDoesNoWorkGuard, registerRouteSchemaGuard, resolveRef, routeTable, shapeOf, specMatcher };