@workerstack/testing 0.0.0-stage → 0.31.0

package/dist/api/steps/sender.js

@@ -0,0 +1,53 @@
+import { RequestBuilder } from "./request.js";
+/** The scenario's own principal. */
+export const SELF = {};
+/** No credential at all. */
+export const ANON = { anonymous: true };
+/** A session held in the scope, sent with `headers` (which name it as `{name}`) in place of the principal's credential. */
+export function sessionIdentity(headers) {
+    return { anonymous: true, headers };
+}
+/** Another config principal. */
+export function principalIdentity(name) {
+    return { principal: name };
+}
+/* The parts of an init that are present: an optional part given as undefined is no part at all. */
+function present(init) {
+    return Object.fromEntries(Object.entries(init).filter(([, value]) => value !== undefined));
+}
+/**
+ * Builds the request steps one identity sends. Typed over the operations `M` it may call and the
+ * caller's `T`, so an unknown operation, body field, path parameter or error key fails to compile.
+ */
+export class Sender {
+    #identity;
+    constructor(identity) {
+        this.#identity = identity;
+    }
+    /** Calls an operation the document names. */
+    call(operationId, init = {}) {
+        return new RequestBuilder(this.#step({ operationId }, init));
+    }
+    /** Calls an operation and expects it refused with `status` and the declared error `key`. */
+    refused(operationId, refusal) {
+        const { key, status, ...init } = refusal;
+        return new RequestBuilder(this.#step({ operationId }, init))
+            .status(status)
+            .equals("$.error_key", key);
+    }
+    /** Sends a raw request, for a path the document does not describe. */
+    request(method, path, init = {}) {
+        return new RequestBuilder(this.#step({ method, path }, init));
+    }
+    /** This sender, with every step it builds sent to the configured origin `name`. */
+    on(name) {
+        return new Sender({ ...this.#identity, origin: name });
+    }
+    #step(target, init) {
+        const { headers, ...rest } = present(init);
+        const own = this.#identity.headers;
+        const merged = headers === undefined && own === undefined ? {} : { headers: { ...own, ...headers } };
+        return { ...this.#identity, ...rest, ...merged, ...target };
+    }
+}
+//# sourceMappingURL=sender.js.map

package/dist/api/steps/steps.d.ts

@@ -0,0 +1,51 @@
+import type { Scenario } from "../config/types/steps.ts";
+import { type ExternalDraft } from "./external.ts";
+import { type MailDraft } from "./out-of-band.ts";
+import { type ScenarioInit } from "./scenario.ts";
+import { Sender } from "./sender.ts";
+import type { Fillable, OpId, OriginName, OriginOps, StepTypes, Unchecked } from "./types.ts";
+type Externals<T extends StepTypes> = NonNullable<T["externals"]>;
+/** An external's input argument: none for an external that takes none. */
+type ExternalArgs<T extends StepTypes, N extends keyof Externals<T>> = Externals<T>[N] extends undefined ? [] : [input: Fillable<Externals<T>[N]>];
+type MailKind<T extends StepTypes> = T extends {
+    mail: infer K extends string;
+} ? K : string;
+/** How the builders send what the caller's API leaves to it. */
+export interface StepsOptions {
+    /** The configured origin a scenario of this set belongs to; give the set that origin's operations. */
+    origin?: string;
+    /**
+     * The headers a session held in the scope as `{name}` is sent with, in place of the principal's
+     * credential: where a credential goes is the API's to say, never the API tester's.
+     */
+    session?: (name: string) => Record<string, string>;
+}
+/** The builders a scenario is written with, typed over the caller's `T`. */
+export interface Builders<T extends StepTypes> {
+    /** The scenario's own principal. */
+    self: Sender<T["ops"], T>;
+    /** No credential at all. */
+    anon: Sender<T["ops"], T>;
+    /** The session held in the scope as `{name}`, sent with the `session` option's headers. */
+    session(name: string): Sender<T["ops"], T>;
+    /** Another config principal: an invitee accepting, a peer reading. */
+    principal(name: string): Sender<T["ops"], T>;
+    /** The scenario's principal, calling a configured origin's operation as a support step. */
+    origin<O extends OriginName<T>>(name: O): Sender<OriginOps<T, O>, T>;
+    /** A wait for a mailed token, a magic link, an OTP. */
+    mail(kind: MailKind<T>, address: string): MailDraft;
+    /** A step only a person or a browser can do, answered by `hooks.external`. */
+    external<N extends keyof Externals<T> & string>(name: N, ...input: ExternalArgs<T, N>): ExternalDraft;
+    /** The plain the API tester scenario; `covers` names this document's operations. */
+    scenario(init: ScenarioInit<OpId<T["ops"]>>): Scenario;
+    /** A deliberately invalid value, sent as written. */
+    unchecked<V>(value: V): V & Unchecked;
+}
+/**
+ * The step builders for one document. `origin` makes it the set for a scenario that belongs to that
+ * configured origin: give it that origin's operations as `T["ops"]`, and its `scenario` names the
+ * origin while its steps carry none. `session` says how `session(name)` sends a scope-held session.
+ */
+export declare function steps<T extends StepTypes>(options?: StepsOptions): Builders<T>;
+export {};
+//# sourceMappingURL=steps.d.ts.map

package/dist/api/steps/steps.js

@@ -0,0 +1,30 @@
+import { external } from "./external.js";
+import { mail } from "./out-of-band.js";
+import { scenario, unchecked } from "./scenario.js";
+import { ANON, principalIdentity, SELF, Sender, sessionIdentity } from "./sender.js";
+const NO_SESSION = "session(name) needs steps({ session }), the headers a session held in the scope is sent with";
+/**
+ * The step builders for one document. `origin` makes it the set for a scenario that belongs to that
+ * configured origin: give it that origin's operations as `T["ops"]`, and its `scenario` names the
+ * origin while its steps carry none. `session` says how `session(name)` sends a scope-held session.
+ */
+export function steps(options = {}) {
+    const self = new Sender(SELF);
+    const { origin, session } = options;
+    return {
+        anon: new Sender(ANON),
+        external: (name, ...input) => external(name, input[0]),
+        mail,
+        origin: (name) => self.on(name),
+        principal: (name) => new Sender(principalIdentity(name)),
+        scenario: (init) => scenario(origin === undefined ? init : { ...init, origin }),
+        self,
+        session: (name) => {
+            if (session === undefined)
+                throw new Error(NO_SESSION);
+            return new Sender(sessionIdentity(session(name)));
+        },
+        unchecked,
+    };
+}
+//# sourceMappingURL=steps.js.map

package/dist/api/steps/types.d.ts

@@ -0,0 +1,90 @@
+import type { ScenarioStep } from "../config/types/steps.ts";
+/** One operation as a caller's types describe it. Every part is optional: a part left out takes nothing. */
+export interface OpShape {
+    /** The JSON request body. */
+    body?: unknown;
+    /** The path parameters, filled through `bind`. */
+    bind?: object;
+    /** The query parameters. */
+    query?: object;
+    /** The error keys the operation declares, per status: `{ 403: "forbidden" | "email_not_verified" }`. */
+    errors?: {
+        readonly [status: number]: string;
+    };
+}
+/** Operation id → its shape. */
+export type OpMap = {
+    readonly [operationId: string]: OpShape;
+};
+/** Everything the builders are typed over. Only `ops` is required. */
+export interface StepTypes {
+    /** The operations of the document the scenario runs against. */
+    ops: OpMap;
+    /** Configured `origins[]` name → that origin's operations, for a support step sent there. */
+    origins?: {
+        readonly [origin: string]: OpMap;
+    };
+    /** External step name → the input it takes (`undefined` for none). */
+    externals?: {
+        readonly [name: string]: object | undefined;
+    };
+    /** The out-of-band kinds `hooks.resolveOutOfBand` answers. */
+    mail?: string;
+}
+/** A text holding a `{name}` placeholder, filled from the flow's scope when the step runs. */
+export type Placeholder = `${string}{${string}}${string}`;
+type Bytes = ArrayBuffer | ArrayBufferView | Blob;
+/** `T` with every scalar leaf also accepting a placeholder text; bytes are content and pass as they are. */
+export type Fillable<T> = T extends Bytes ? T : T extends readonly (infer U)[] ? Fillable<U>[] : T extends object ? {
+    [K in keyof T]: Fillable<T[K]>;
+} : T | Placeholder;
+/** A value written `unchecked(...)`: sent as it is, outside the operation's body type. */
+export interface Unchecked {
+    readonly "~unchecked": true;
+}
+/** A builder `scenario()` turns into the plain step it stands for. */
+export interface BuiltStep {
+    toStep(): ScenarioStep;
+}
+/** What a scenario's steps may hold: builders, and plain steps such as a sign-up flow's. */
+export type StepItem = BuiltStep | ScenarioStep;
+/** An operation id of `M`. */
+export type OpId<M extends OpMap> = keyof M & string;
+/** A configured origin's name. */
+export type OriginName<T extends StepTypes> = keyof NonNullable<T["origins"]> & string;
+/** The operations of origin `O`. */
+export type OriginOps<T extends StepTypes, O extends OriginName<T>> = NonNullable<T["origins"]>[O] & OpMap;
+/** The parameter names part `K` of `S` declares, each filled with a text; none when `S` has no such part. */
+type Params<S extends OpShape, K extends "bind" | "query"> = K extends keyof S ? {
+    [P in keyof NonNullable<S[K]>]?: string;
+} : {
+    [P in never]?: string;
+};
+/** The body `S` takes; with no body declared, only an `unchecked(...)` one. */
+type BodyOf<S extends OpShape> = "body" extends keyof S ? Fillable<NonNullable<S["body"]>> | Unchecked : Unchecked;
+/** What an operation call sends besides the operation id. */
+export interface CallInit<S extends OpShape = OpShape> {
+    body?: BodyOf<S>;
+    bind?: Params<S, "bind">;
+    query?: Params<S, "query">;
+    /** Merged over a session's headers, these winning per key. */
+    headers?: Record<string, string>;
+    /** One of the request media types the operation documents. */
+    mediaType?: string;
+}
+/** A status `S` declares error keys for. */
+export type ErrorStatus<S extends OpShape> = "errors" extends keyof S ? keyof NonNullable<S["errors"]> & number : never;
+/** A refused call: the status and the declared error key the response must carry, plus the call's init. */
+export type Refusal<S extends OpShape, Status extends number> = CallInit<S> & {
+    status: Status;
+    key: Status extends keyof NonNullable<S["errors"]> ? NonNullable<S["errors"]>[Status] : never;
+};
+/** What a raw request sends besides its method and path. */
+export interface RawInit {
+    body?: unknown;
+    headers?: Record<string, string>;
+    query?: Record<string, string>;
+    redirect?: "follow" | "manual";
+}
+export {};
+//# sourceMappingURL=types.d.ts.map

package/dist/api/steps/types.js

@@ -0,0 +1,7 @@
+/*
+ * What a caller tells the step builders about its API, so a scenario that names an operation, a
+ * body field, a path parameter or an error key the API lacks fails to compile. Nothing here exists
+ * at run time: the builders emit the API tester's plain step objects.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/api/steps/view.d.ts

@@ -0,0 +1,20 @@
+import type { Scenario, ScenarioAssert, ScenarioStep } from "../config/types/steps.ts";
+/** One scenario's steps, read the way a config's own unit tests ask about them. */
+export interface ScenarioView {
+    readonly scenario: Scenario;
+    readonly steps: readonly ScenarioStep[];
+    /** The first step calling `operationId` whose fields include `where`, deep; -1 when none does. */
+    indexOf(operationId: string, where?: object): number;
+    /** Every step calling `operationId`, with its index. */
+    calls(operationId: string): Array<{
+        index: number;
+        step: ScenarioStep;
+    }>;
+    /** Every assert, flattened, in step order. */
+    asserts(): ScenarioAssert[];
+    /** Whether the scenario covers `operationId`, calls it, and a later assert names it in `observes`. */
+    observes(operationId: string): boolean;
+}
+/** The scenario `id` among `scenarios`, as a view its unit tests query. */
+export declare function stepsOf(scenarios: readonly Scenario[], id: string): ScenarioView;
+//# sourceMappingURL=view.d.ts.map

package/dist/api/steps/view.js

@@ -0,0 +1,41 @@
+/* `actual` holds every field `expected` has, deep; arrays match item by item, at the same length. */
+function includes(actual, expected) {
+    if (Array.isArray(expected)) {
+        return (Array.isArray(actual) &&
+            actual.length === expected.length &&
+            expected.every((item, i) => includes(actual[i], item)));
+    }
+    if (expected === null || typeof expected !== "object")
+        return Object.is(actual, expected);
+    if (actual === null || typeof actual !== "object")
+        return false;
+    return Object.entries(expected).every(([key, value]) => includes(actual[key], value));
+}
+const operationOf = (step) => ("operationId" in step ? step.operationId : undefined);
+const assertsOf = (step) => "assert" in step && step.assert !== undefined ? [step.assert].flat() : [];
+/** The scenario `id` among `scenarios`, as a view its unit tests query. */
+export function stepsOf(scenarios, id) {
+    const scenario = scenarios.find((candidate) => candidate.id === id);
+    if (scenario === undefined) {
+        throw new Error(`no scenario "${id}" among: ${scenarios.map((candidate) => candidate.id).join(", ")}`);
+    }
+    const { steps } = scenario;
+    const calls = (operationId) => steps.flatMap((step, index) => (operationOf(step) === operationId ? [{ index, step }] : []));
+    return {
+        asserts: () => steps.flatMap(assertsOf),
+        calls,
+        indexOf: (operationId, where = {}) => steps.findIndex((step) => operationOf(step) === operationId && includes(step, where)),
+        observes: (operationId) => {
+            const first = calls(operationId)[0]?.index;
+            if (first === undefined || !scenario.covers.includes(operationId))
+                return false;
+            return steps
+                .slice(first + 1)
+                .flatMap(assertsOf)
+                .some((assert) => assert.observes?.includes(operationId) === true);
+        },
+        scenario,
+        steps,
+    };
+}
+//# sourceMappingURL=view.js.map

package/dist/cli/main.d.ts

@@ -0,0 +1,8 @@
+import { type CliDeps } from "../api/cli/main.ts";
+/** The help: one line per subpath, made from the table above. */
+export declare const USAGE: string;
+/** `testing <subpath> …`: hands the rest to that subpath's command line. Returns the exit code. */
+export declare function main(argv: readonly string[], deps: CliDeps): Promise<number>;
+/** Runs `testing` as the process. */
+export declare function start(deps?: CliDeps): Promise<void>;
+//# sourceMappingURL=main.d.ts.map

package/dist/cli/main.js

@@ -0,0 +1,38 @@
+import { main as apiMain, start as startCli } from "../api/cli/main.js";
+import { processWriter } from "../api/cli/writer.js";
+import { EXIT } from "../api/runtime/exit.js";
+/** Every subpath with a command line, by name. */
+const SUBPATHS = {
+    api: { main: apiMain, summary: "test a live HTTP API against its OpenAPI document (testing api help)" },
+};
+/** The help: one line per subpath, made from the table above. */
+export const USAGE = /* @__PURE__ */ usage();
+function usage() {
+    const width = Math.max(...Object.keys(SUBPATHS).map((name) => name.length)) + 4;
+    const lines = Object.entries(SUBPATHS).map(([name, subpath]) => `  ${name.padEnd(width)}${subpath.summary}`);
+    return `usage: testing <subpath> <command> [flags]\n${lines.join("\n")}\n`;
+}
+/** `testing <subpath> …`: hands the rest to that subpath's command line. Returns the exit code. */
+export async function main(argv, deps) {
+    const [first, ...rest] = argv;
+    if (first === undefined) {
+        deps.writer.err(USAGE);
+        return EXIT.usage;
+    }
+    if (first === "help" || first === "--help") {
+        deps.writer.out(USAGE);
+        return 0;
+    }
+    const subpath = SUBPATHS[first];
+    if (subpath === undefined) {
+        const names = Object.keys(SUBPATHS).join(", ");
+        deps.writer.err(`testing: unknown subpath "${first}"; the subpaths are: ${names}\n\n${USAGE}`);
+        return EXIT.usage;
+    }
+    return subpath.main(rest, deps);
+}
+/** Runs `testing` as the process. */
+export function start(deps = { writer: processWriter }) {
+    return startCli(deps, main);
+}
+//# sourceMappingURL=main.js.map

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export { start } from "./cli/main.ts";
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+/*
+ * The package's executable, `testing`: `bin/testing.js` imports `start` and calls it, since its own
+ * argv[1] is the bin wrapper, not this module. Run directly, it starts itself the same way.
+ */
+import { invokedDirectly } from "./api/cli/main.js";
+import { start } from "./cli/main.js";
+export { start } from "./cli/main.js";
+if (invokedDirectly(process.argv[1], import.meta.url))
+    await start();
+//# sourceMappingURL=cli.js.map

package/docs/api/api.md

@@ -0,0 +1,78 @@
+# testing api — Programmatic API
+
+[← back to the overview](../../README.md)
+
+## Programmatic API
+
+```ts
+import {
+	defineConfig,
+	env,
+	loadConfig,
+	run,
+	loadSpec,
+	dereference,
+	buildModel,
+	renderJson,
+	renderMarkdown,
+} from "@workerstack/testing/api"
+
+const config = defineConfig({
+	spec: "./openapi.yaml",
+	baseUrl: "https://api.example.com",
+	security: { bearer: { static: env("API_TOKEN") } },
+	principals: { alpha: { tenant: "acme" } },
+})
+
+const result = await run({
+	spec: config.spec,
+	baseUrl: config.baseUrl,
+	security: config.security,
+	principals: config.principals,
+	seed: 1,
+	maxInFlight: 4,
+	onProgress: (snap) => {
+		// snap.phase, snap.entity, snap.check, snap.inflight, snap.last, snap.message, …
+	},
+})
+
+// result.findings, result.checksSkipped, result.checksSuppressed,
+// result.inconclusive, result.entitiesTested, result.teardown, result.created,
+// result.scope (per-operation status), result.checksOutOfScope
+// pass `ops: ["product.update"]` to run() for a targeted run; ScopeError on an unknown name
+```
+
+`result.teardown` is `{ removed, failed, unsupported, records }`; `records` lists every record the API tester ledgered, in creation order, as `{ entity, id, removed }`. Only ids the backend gave back are ever ledgered. `report.json` carries the same object under `teardown`.
+
+`env(name)` reads a secret for a config: `token: env("API_TOKEN")`. An unset or empty variable stops the load with `testing api: env API_TOKEN is not set (<config path>)`, so a missing secret never goes out as an empty credential.
+
+`loadConfig(path)` loads `.ts` / `.js` / `.mjs` / `.json` the same way the CLI does. The CLI then expands `${NAME}` in every string. `defineConfig` is an identity function for typing; it does not interpolate. If you call `run()` with an in-process object, resolve secrets yourself (template literals, `process.env`) before passing it.
+
+`runVerdict(result)` is the verdict the CLI and every report state: `{ outcome, reason }`, where
+`outcome` is `clean`, `defects` or `failed` (a run that graded nothing, a network that went away, or
+a `--ops` target never judged). `exitCode(result)` is that outcome as the CLI's exit code, from
+`EXIT`: 0, 1 or 3.
+
+`run(options)` does not write files. The CLI writes reports after `run` returns. To produce the same artifacts, call `renderMarkdown` / `renderJson` / `renderMatrixHtml` / `renderMatrixGraph` / `renderRepros` with a `ReportInput` (`findings`, `model`, `client`, `baseUrl`, `entitiesTested`, `checksRun`, `startedAt`, `durationMs`, plus optional skip/suppress/inconclusive lists).
+
+`transcript: { memoryBytes, dir }` bounds what a large run holds. Each client keeps up to `memoryBytes` of exchange bodies in memory (default 32 MiB) and moves the oldest to a private folder under `dir` (default the system temporary directory). Checks read those bodies back exactly as the backend sent them, so they are not redacted. Each file is encrypted with AES-256-GCM, under a key each client draws for itself and holds only in memory,, and the folder is removed when the run ends, however it ends. Choose a local, private `dir`: the encryption is what protects the files there. `memoryBytes` must be a positive integer, and `dir` must exist and be writable; `run` refuses either fault with a `UsageError` before it sends anything.
+
+Offline:
+
+```ts
+const doc = await loadSpec("./openapi.yaml")
+const { doc: resolved, externalRefs } = dereference(doc)
+const model = buildModel(resolved)
+```
+
+Types exported, by what they describe:
+
+- **Config.** `ApiConfig`; `EntityConfig` (an `entities` entry, today only its `query`); `PayloadPolicy` (`payloads`: `"full"` or `"per-write-path"`); `ProfileSpec` (a `profiles` entry); `ExternalsConfig` (`externals`: each scenario external's kind); `RateLimitSpec` (a `rateLimits` entry); `OriginSpec`; `OutOfBandConfig`; `Uploads` and `UploadFile`.
+- **Security.** `SecurityConfig` (one `Recipe` per scheme) and `PrincipalsConfig` (a `PrincipalEntry` per id).
+- **Steps and scenarios.** `AuthStep` is an `OperationStep`, a `RequestStep` or an `OutOfBandStep`. A `Scenario` runs `ScenarioStep`s: a `ScenarioRequestStep` (an operation or request step with its `ScenarioAssert`s), an `OutOfBandStep` or an `ExternalStep`.
+- **Query catalog.** `QueryCapabilities` is what `x-query` or a config's `query` declares for a list: `FilterableField`s, each a field with its `FieldType` and `FilterOp`s, and `FilterableFrom`, the read that `filterableFrom` and its siblings harvest names from. `QueryParamNames` maps a `QueryParamRole` (`filter`, `sort`, `select`, `search`, `searchMode`, `limit`, `page`, `offset`, `cursor`) to the query parameter it is sent in, as `x-query.params` and config `query.params` name it. `QueryEnvelopeNames` maps a `QueryEnvelopeRole` (`total`, `hasMore`, `nextCursor`) to the response field it is read from, as `x-query.envelope` and config `query.envelope` name it.
+- **Hooks.** `Hooks`, and what each hook receives: `HeaderRequest` (`resolveHeaders`), `InputRequest` (`resolveInput`), `UploadRequest` (`resolveUpload`, which answers an `UploadResolution`), `PathValueRequest` (`resolvePathValue`), `QueryCapabilitiesRequest` (`resolveQueryCapabilities`), `SideEffectRequest` (`awaitSideEffect`), `OutOfBandRequest` (`resolveOutOfBand`) and `TeardownPrincipalContext` (`teardownPrincipal`: the account's credential, where it goes, and `stale`, why it could not be renewed when it could not).
+- **Runs and reports.** `RunOptions`, `RunResult`, `Finding`, `Verdict`, `Actor` and `ReportInput`.
+- **The model.** `SpecModel`, `EntityModel`, `OperationModel` and `OpenApiDocument`.
+
+Also exported: `loadPersistedPrincipals`, `worstCaseWaitMs`, `allocateRunDir` and `DEFAULT_RUNS_ROOT`.

package/docs/api/assumptions.md

@@ -0,0 +1,119 @@
+# testing api — Assumptions
+
+[← back to the overview](../../README.md)
+
+The API tester tests a backend against its own document, and where the document is silent it has to assume
+something. This page lists every such assumption, what the API tester does when an API does not fit it, and
+how to declare the exception. An assumption that does not hold should never become a false
+finding: it should become a skip, an inconclusive verdict or a coverage gap that names the tag that
+would settle it. If one of these produces a finding against a correct backend, that is the API tester bug.
+
+## Shape of the API
+
+| The API tester assumes                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | when it does not hold                                                                                                                                       | declare                                                                                                                  |
+| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| A resource is a noun in the path: `/tables`, `/tables/{id}`                                                                                                                                                                                                                                                                                                                                                                                                                            | the operation is untracked; `doctor` names the gap                                                                                                          | [`x-entity`](tags.md#x-entity) `{ name, action }`                                                                        |
+| An instance is identified by `id`, `uuid`, `slug`, `key` or `name`, or by the trailing path parameter                                                                                                                                                                                                                                                                                                                                                                                  | the entity is not trackable, and checks that need a record stand down                                                                                       | `x-entity.identity`                                                                                                      |
+| A single-record answer is the record, or wraps it in `data` / `item` / `result` / `record` (create only)                                                                                                                                                                                                                                                                                                                                                                               | fields are compared against the wrong object, or an update's `{ success, id }` reads as every field dropped                                                 | [`x-entity.recordPath`](tags.md#x-entity) per operation                                                                  |
+| A list's rows are its one array of objects                                                                                                                                                                                                                                                                                                                                                                                                                                             | with two (`data` beside `fields`) the list is not treated as a collection; `doctor` names the gap                                                           | `x-entity.recordPath` on the list (`$.data`)                                                                             |
+| Each list row is the record                                                                                                                                                                                                                                                                                                                                                                                                                                                            | a row that wraps its record (`{ document, highlights }`) is compared as the record, so a created record is never found in the list                          | `x-entity.recordPath` on the list (`$.hits[*].document`)                                                                 |
+| Creating is `POST` to the collection, and the response carries the created record                                                                                                                                                                                                                                                                                                                                                                                                      | the cohort cannot be seeded; dependent checks are blocked                                                                                                   | [`x-async`](tags.md#x-async) for a receipt, `x-entity` for a create elsewhere                                            |
+| A create that answers without the record (`{ success: true }`) kept the id the client chose                                                                                                                                                                                                                                                                                                                                                                                            | the record is not tracked: the API tester leaves it behind rather than delete an id it only sent                                                            | an item read (`x-entity` action `read`): the API tester tracks the id once that read shows it with every submitted field |
+| An identifier looks like the identity: an integer, a uuid, or a token (`testing-absent-…`) for a bare string                                                                                                                                                                                                                                                                                                                                                                           | a probe for a record that does not exist is answered 400 for its format, not 404; one that cannot meet a string identity's pattern or length does not apply | type the route parameter, or the identity property (it wins over a route parameter documented as a bare string)          |
+| A client-chosen identity names no record the collection already holds                                                                                                                                                                                                                                                                                                                                                                                                                  | The API tester avoids every listed id and every id its own records hold; with no free id left, the create is not sent and the check reports a gap           | `x-unique` on the identity, so a duplicate id is a graded 409                                                            |
+| Two records may share a value the document does not declare unique                                                                                                                                                                                                                                                                                                                                                                                                                     | a server deriving a key from it (a slug) refuses one; parents and check records the API tester makes put a run token, per principal, in every string        | [`x-unique`](tags.md#x-unique) on the field                                                                              |
+| A record the API tester created can be deleted by its item route                                                                                                                                                                                                                                                                                                                                                                                                                       | teardown reports what it left behind                                                                                                                        | [`x-cleanup`](tags.md#x-cleanup)                                                                                         |
+| Path parameters the API tester cannot create are supplied                                                                                                                                                                                                                                                                                                                                                                                                                              | the entity cannot be reached                                                                                                                                | [`x-root`](tags.md#x-root), or each principal's `scope`                                                                  |
+| A list answers with an array, or an object holding one                                                                                                                                                                                                                                                                                                                                                                                                                                 | list checks stand down                                                                                                                                      | the collection schema                                                                                                    |
+| A schema's `format` is checked when ajv-formats defines it: `date`, `time`, `date-time`, `iso-time`, `iso-date-time`, `duration`, `uri`, `uri-reference`, `uri-template`, `url`, `email`, `hostname`, `ipv4`, `ipv6`, `regex`, `uuid`, `json-pointer`, `json-pointer-uri-fragment`, `relative-json-pointer`, `byte`, `int32`, `int64`, `float`, `double`, `password`, `binary`. `url` and the OpenAPI formats are not JSON Schema 2020-12 formats; any other unknown format is ignored | a value that breaks one of those formats is reported as drift (`images/seat.svg` is not a `url`); a value in an unknown format passes unchecked             | use the format the value actually has (`uri-reference` for a relative path), or drop it in an `overlay`                  |
+
+## Lists and paging
+
+| The API tester assumes                                                                                                                                                                                                                            | when it does not hold                                                         | declare                                                                     |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
+| Paging parameters carry recognizable names (`limit`, `page`, `offset`, `cursor`, …)                                                                                                                                                               | the role is unresolved and the paging checks do not apply                     | the parameter's name or default, or [`x-query`](tags.md#x-query) `maxLimit` |
+| A set has ended when a page is empty, shorter than a full page already seen, or the envelope says so — and, when the envelope carries both a total and a more-pages flag, they agree                                                              | The API tester keeps reading; it never takes the requested page size as proof | nothing: a server may serve fewer rows than asked for                       |
+| A list response names its paging facts as the API tester knows them: the next cursor `nextCursor` / `next_cursor` / `cursor` / `next`, the total `total` / `count`, the more-pages flag `hasMore` / `has_more`; a next cursor is text or a number | that fact is not read, and a cursor walk ends after its first page            | `x-query.envelope`, config `query.envelope`                                 |
+| A server pages by one mechanism consistently                                                                                                                                                                                                      | a read that sees pages repeat stops and is unresolved                         | —                                                                           |
+| A set larger than 500 records is too large to compare whole                                                                                                                                                                                       | checks that need the whole set are unresolved, not failed                     | smaller cohorts, or a filtered scope                                        |
+
+## Queries
+
+| The API tester assumes                                                                                                                                                                                                    | when it does not hold                                                                                | declare                                                        |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
+| Filtering is written in a grammar the document demonstrates (PostgREST, colon, equality), or one declared as a template                                                                                                   | filter checks do not apply; a free-text filter whose grammar is not recognized gets no terms         | `x-query.grammar` (preset or template), config `query.grammar` |
+| Sorting is written in a grammar the document demonstrates (dotted, prefixed, colon, spaced), or one declared as a template                                                                                                | the inferred grammar is used                                                                         | `x-query.sortGrammar`, config `query.sortGrammar`              |
+| Unknown operators, sort directions and malformed terms are probed only on a declared grammar                                                                                                                              | those checks do not apply                                                                            | `x-query.grammar` / `sortGrammar`                              |
+| Without `x-query`, every scalar property can be filtered, sorted and selected, bar sorting by the list's own path parameters                                                                                              | probes reach fields the backend never indexed; findings name the guess                               | `x-query` `filterable` / `sortable` / `selectable`             |
+| A declared operator is accepted for a value of the field's own type                                                                                                                                                       | —                                                                                                    | per-field `ops` and `type` in `x-query`                        |
+| Only 400 and 422 mean "this capability is not supported"                                                                                                                                                                  | 401, 403, 404 and 429 leave the check unresolved; a 5xx is a finding                                 | —                                                              |
+| Each query role's parameter goes by a name the API tester knows: `filter` / `where` / `query` / `conditions`, `sort` / `order_by`, `per_page` / `limit`, `page`, `offset`, `cursor` and the like                          | that role's checks do not apply, naming the parameter they would have sent                           | `x-query.params`, config `query.params`                        |
+| A free-text search parameter is named `q`, `search`, `query_text`, `term`, `keyword`, `text`, or `searchTerm` / `search_term`, and its declaration does not say it takes `key:value` pairs, a `:` pattern or a non-string | search checks do not apply                                                                           | `x-query.searchable`, `x-query.params.search`                  |
+| A backend may ignore a query parameter it does not declare                                                                                                                                                                | no probe is sent to one; the check that needed it does not apply, naming the parameter               | the parameter on the list operation                            |
+| Paging is by page number, by rows skipped (`offset`, `skip`, `start`, `from`) or by cursor; a total alone (`totalCount`) is enough to stop a walk                                                                         | paging checks do not apply                                                                           | —                                                              |
+| A page size of 0 or past the maximum may be refused or clamped                                                                                                                                                            | the out-of-range check does not apply                                                                | `x-query.limitOutOfRange: reject`                              |
+| A create answers the record, or wraps it under `data` / `item` / `result` / `record` beside an id                                                                                                                         | the record is the object holding what was sent; its identity comes from it or from the envelope's id | —                                                              |
+| An alias of an allowed operator is allowed                                                                                                                                                                                | —                                                                                                    | `x-query.aliases`                                              |
+
+## Ordering
+
+| The API tester assumes                                                                                          | when it does not hold                                | declare                    |
+| --------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | -------------------------- |
+| Numbers sort numerically                                                                                        | `sort.numeric-order-is-numeric` reports text order   | —                          |
+| Text sorts by one consistent collation — binary, case-insensitive or locale — whichever the backend shows first | a sequence sorted under none of them is a finding    | `x-query.sortCollation`    |
+| Nulls sit together at one end, the same end every time                                                          | nulls in the middle, or switching ends, is a finding | `x-query.sortDefaultNulls` |
+| Descending is ascending reversed, up to ties                                                                    | —                                                    | —                          |
+| Tied records may come back in any order unless a tiebreak is declared                                           | —                                                    | `x-query.stableTiebreak`   |
+
+## Writes
+
+| The API tester assumes                                                | when it does not hold                              | declare                                                          |
+| --------------------------------------------------------------------- | -------------------------------------------------- | ---------------------------------------------------------------- |
+| `PATCH` changes only the fields it names                              | the minimality and lost-update checks report it    | —                                                                |
+| `PUT` replaces the whole record                                       | partial-update checks stand down on a PUT-only API | the update operation's method                                    |
+| A field the server owns is marked `readOnly` or generated             | The API tester would try to write it               | `readOnly`, or [`x-generated`](tags.md#x-immutable--x-generated) |
+| A field that must never change after create is declared               | not tested                                         | [`x-immutable`](tags.md#x-immutable--x-generated)                |
+| A `writeOnly` field is accepted and not returned                      | —                                                  | `writeOnly`                                                      |
+| A header named like `Idempotency-Key` promises replay                 | the replay check does not apply                    | the header's name                                                |
+| A unique column set is declared, and a duplicate is refused with 409  | —                                                  | [`x-unique`](tags.md#x-unique)                                   |
+| A deleted record leaves the default listing, unless it is a tombstone | —                                                  | [`x-soft-delete`](tags.md#x-soft-delete)                         |
+
+## Errors and statuses
+
+| The API tester assumes                                                                                       | when it does not hold                                                              | declare                                    |
+| ------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------- | ------------------------------------------ |
+| A refusal of invalid input is 400 or 422; of a wrong content type, 415 (when documented); of a conflict, 409 | any other refusal leaves the check unresolved                                      | —                                          |
+| A 5xx is never the right answer to bad input                                                                 | it is a finding                                                                    | —                                          |
+| Every status an operation returns is documented, ranges (`2XX`) and `default` included                       | the status check reports the gap, apart from what deliberately invalid probes drew | the response                               |
+| A documented feature gate answers 403 with `vars.type: feature_gate`                                         | the 403 is a backend failure                                                       | [`x-feature-gate`](tags.md#x-feature-gate) |
+
+## Isolation and authorization
+
+| The API tester assumes                                                                                                                                                                        | when it does not hold                                                                                                                                                                                                      | declare                                                                                           |
+| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
+| A second principal with a different `tenant` or `scope` is another tenant                                                                                                                     | isolation checks do not apply                                                                                                                                                                                              | `principals`                                                                                      |
+| The tenant is a path parameter, or declared                                                                                                                                                   | an inferred tenant makes a cross-tenant read an ambiguity, not a security finding                                                                                                                                          | [`x-tenant`](tags.md#x-tenant)                                                                    |
+| A denial does not depend on whether the record exists                                                                                                                                         | —                                                                                                                                                                                                                          | —                                                                                                 |
+| Higher `rank` can do everything a lower rank can                                                                                                                                              | a lower rank seeing more is a finding                                                                                                                                                                                      | `rank` on principals                                                                              |
+| An invite grants nothing until accepted, and a revoke takes access away                                                                                                                       | —                                                                                                                                                                                                                          | [`x-invite`](tags.md#x-invite) and a peer's `inviteAs`                                            |
+| A record holding a credential the run depends on (an API key a security recipe minted) must never be changed or removed by a check; the mint's answer names its id, from the body or Location | a check whose request names such a record, whoever sends it, stands down naming it; the rest of its entity is tested on records the run makes; a mint that answers no id keeps its whole entity out of the run, saying why | answer the minted record's id, or declare it with `x-entity` `createdIdFrom`                      |
+| A configured principal's own record is never removed or fully replaced by a check                                                                                                             | a delete or a `PUT` of it stands down (a full replace could clear its sign-in fields); self-profile replaces run on disposable principals only                                                                             | nothing: give the operation `x-fresh-principal` so the API tester can sign up a disposable for it |
+
+## Async work, effects and pacing
+
+| The API tester assumes                                                                                                                    | when it does not hold                                                                                                    | declare                                                                    |
+| ----------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------- |
+| A write is complete when it answers                                                                                                       | —                                                                                                                        | [`x-async`](tags.md#x-async), [`x-wait`](tags.md#x-wait)                   |
+| A read the API tester sends after a write sees it: every read carries the bypass `x-consistency` declares, else `Cache-Control: no-cache` | a cache that ignores both serves the API tester stale reads; the staleness window is measured on its own, past no bypass | [`x-consistency`](tags.md#x-consistency)                                   |
+| A write affects only its own entity and the routes it declares                                                                            | other entities' changes are not tested                                                                                   | [`x-invalidate`](tags.md#x-invalidate), [`x-effects`](tags.md#x-effects)   |
+| Entities that share no parent, invalidated route or effect cannot observe each other                                                      | they are tested side by side                                                                                             | the shared relation, declared                                              |
+| A rate the document declares is the rate the backend enforces                                                                             | a 429 under it is a finding; a config-supplied rate is only paced around                                                 | [`x-rate-limit`](tags.md#x-rate-limit--pacing-the-api-testers-own-traffic) |
+
+## What the API tester never assumes
+
+- That your data has a ground truth. Every oracle compares the API with itself.
+- That the requested page size is the size served.
+- That a field absent from the cohort cannot exist: a declared field is probed with a value of its
+  own type.
+- That an unanswered question is a pass: a check that cannot conclude says why, and a check that
+  does not apply says what it needs.