@nifrajs/testing 1.6.0 → 1.9.1

package/README.md

@@ -1,9 +1,78 @@
 # @nifrajs/testing
 
-Testing helpers for nifra apps. [`@nifrajs/client`](../client)'s **`testClient`** is already the typed,
-no-network in-process request client (nifra's supertest / `inject`). This package adds what it doesn't: a
-**cookie jar** and a **cookie-persisting `testSession`**, so a login → authenticated-request flow tests as
-easily as a single request.
+Contract-derived adversarial testing and stateful in-process helpers for Nifra apps.
+
+## Contract laboratory
+
+`assertAdversarialContract` turns the schemas already registered on an app into executable tests. It:
+
+- synthesizes a valid **contract witness** from inspectable JSON Schema;
+- makes small nested **hostile mutations** and sends only values the route's own Standard Schema
+  validator has proved invalid after HTTP transport normalization;
+- expects rejection at the real request boundary (422 by default);
+- executes a valid witness and validates the real success body against `response`;
+- runs the same stable case IDs across a Bun/Node/Workers runtime matrix; and
+- retains a replay seed and greedily shrinks unexpected acceptance failures.
+
+```ts
+import { test } from "bun:test"
+import { assertAdversarialContract } from "@nifrajs/testing"
+import { app } from "../src/app"
+
+test("the API contract withstands hostile inputs", async () => {
+  await assertAdversarialContract(app, {
+    seed: 73,
+    prepareRequest(request) {
+      const headers = new Headers(request.headers)
+      headers.set("authorization", "Bearer test-session")
+      return new Request(request, { headers })
+    },
+  })
+})
+```
+
+Nifra's `t` schemas carry JSON Schema, so witnesses are automatic. Standard Schema deliberately does
+not require introspection; for an opaque Zod/Valibot/ArkType schema, provide only its known-good values:
+
+```ts
+await assertAdversarialContract(app, {
+  witnesses: {
+    "POST /users/:id": {
+      params: { id: "user-1" },
+      body: { name: "Ada" },
+      query: { notify: "true" },
+    },
+  },
+})
+```
+
+The validator still decides which generated mutations are truly invalid; the supplied witness does not
+weaken validation. A missing/invalid witness is a coverage gap, not a silent pass. Set
+`requireCoverage: false` only when gaps are intentionally advisory.
+
+To exercise adapter parity, pass runtime fetch targets. The reflected `app` remains the one source of
+the contract:
+
+```ts
+const report = await assertAdversarialContract(app, {
+  runtimes: [
+    { name: "bun", fetch: (request) => bunApp.fetch(request) },
+    { name: "node", fetch: (request) => nodeAdapter.fetch(request) },
+    { name: "worker", fetch: (request) => worker.fetch(request, env) },
+  ],
+})
+```
+
+`runAdversarialContract` returns the same structured report without throwing. Every failure includes
+`replay: { seed, caseId, runtime }`; rerun one case with `only: caseId`. Contract runs execute one valid
+request for each declared response schema, so use an isolated test app/database—never point the
+laboratory at production.
+
+## Stateful sessions
+
+[`@nifrajs/client`](../client)'s **`testClient`** is already the typed, no-network in-process request
+client (Nifra's supertest / `inject`). `testSession` adds a **cookie jar**, so a login → authenticated
+request flow tests as easily as a single request.
 
 ```ts
 import { testSession } from "@nifrajs/testing"
@@ -26,6 +95,8 @@ that every call carries and captures cookies via a shared jar.
 
 ## API
 
+- `assertAdversarialContract(app, options?)` → green report or throws `AdversarialContractError`.
+- `runAdversarialContract(app, options?)` → structured `{ ok, results, failures, gaps, seed }` report.
 - `testSession<App>(app, { origin?, cookies? })` → `{ client: Treaty<App>, cookies: CookieJar }`.
 - `cookieJar()` → `CookieJar` — `header()` · `applyTo(headers)` · `store(response)` · `set` · `get` · `clear` · `size`.
   Honours removal (`Max-Age=0` / past `Expires`); other cookie attributes are ignored (in-process, same-origin).

package/dist/adversarial.d.ts

@@ -0,0 +1,129 @@
+/**
+ * Contract-derived adversarial tests.
+ *
+ * A contract witness is a request known to satisfy a route's input schemas. From that witness this
+ * module derives small hostile mutations, proves each mutation invalid with the route's own Standard
+ * Schema validator, and then drives it through one or more real fetch runtimes. Declared success
+ * responses are validated off the hot path as part of the same laboratory run.
+ */
+import { type ReflectedRoute } from "@nifrajs/core/reflection";
+type HeaderSource = ConstructorParameters<typeof Headers>[0];
+export type ContractTarget = "body" | "query" | "response";
+export type ContractCaseKind = "input-rejection" | "response-conformance";
+/** Anything that exposes reflected routes and a Web-standard in-process fetch handler. */
+export interface ContractTestApp {
+    routes(): readonly unknown[];
+    fetch(request: Request): Response | Promise<Response>;
+}
+/** A runtime target for the same generated contract cases (for example Bun, Node, and Workers). */
+export interface ContractRuntime {
+    readonly name: string;
+    fetch(request: Request): Response | Promise<Response>;
+}
+/** A known-good request. Missing body/query values are synthesized from inspectable JSON Schema. */
+export interface ContractWitness {
+    readonly params?: Readonly<Record<string, string>>;
+    readonly query?: unknown;
+    readonly body?: unknown;
+    readonly headers?: HeaderSource;
+}
+/** Stable context passed to request/rejection hooks. It contains no request payloads or secrets. */
+export interface ContractCaseContext {
+    readonly seed: number;
+    readonly caseId: string;
+    readonly route: ReflectedRoute;
+    readonly runtime: string;
+    readonly kind: ContractCaseKind;
+    readonly target: ContractTarget;
+    readonly mutation?: string;
+}
+export interface AdversarialContractOptions {
+    /** Base origin for generated requests. Default `http://nifra.contract`. */
+    readonly origin?: string;
+    /** Replayable seed used for deterministic witness generation. */
+    readonly seed?: number;
+    /** Known-good request values keyed by `"METHOD /path"`. Required for opaque Standard Schemas. */
+    readonly witnesses?: Readonly<Record<string, ContractWitness>>;
+    /** Select a subset of reflected routes. */
+    readonly include?: (route: ReflectedRoute) => boolean;
+    /** Execute every case against these targets. Default: the supplied app, named `in-process`. */
+    readonly runtimes?: readonly ContractRuntime[];
+    /** Maximum validator-proven mutations per body/query schema. Default 32. */
+    readonly maxMutationsPerInput?: number;
+    /** Maximum serialized witness size. Default 256 KiB. */
+    readonly maxWitnessBytes?: number;
+    /** Statuses that prove an invalid input was rejected. Default `[422]`. */
+    readonly expectedValidationStatuses?: readonly number[];
+    /**
+     * Attach auth, tenant, or runtime-specific state. Return a new Request; the input Request is already
+     * fresh for this case and runtime.
+     */
+    readonly prepareRequest?: (request: Request, context: ContractCaseContext) => Request | Promise<Request>;
+    /** Override rejection semantics (for apps with a custom validation response). */
+    readonly isRejected?: (response: Response, context: ContractCaseContext) => boolean | Promise<boolean>;
+    /** Validate a real successful response for every declared response schema. Default true. */
+    readonly validateResponses?: boolean;
+    /** Fail the report when a contracted target cannot be exercised. Default true. */
+    readonly requireCoverage?: boolean;
+    /** Greedily minimize an invalid input that unexpectedly reaches the app. Default true. */
+    readonly shrinkFailures?: boolean;
+    /** Cap shrink probes for one failure. Default 12. */
+    readonly maxShrinkAttempts?: number;
+    /** Replay only these stable case IDs. Coverage gaps are advisory when this is set. */
+    readonly only?: string | readonly string[];
+}
+export type ContractCoverageGapCode = "NO_CONTRACT_TARGETS" | "NO_VALIDATOR" | "NO_WITNESS" | "INVALID_WITNESS" | "WITNESS_TOO_LARGE" | "UNSUPPORTED_BODY_METHOD" | "NO_REJECTED_MUTATION" | "NO_RUNTIME" | "INVALID_RUNTIME" | "CASE_NOT_FOUND";
+export interface ContractCoverageGap {
+    readonly route?: string;
+    readonly target?: ContractTarget;
+    readonly code: ContractCoverageGapCode;
+    readonly message: string;
+}
+export interface ContractReplay {
+    readonly seed: number;
+    readonly caseId: string;
+    readonly runtime: string;
+}
+export interface AdversarialContractResult {
+    readonly id: string;
+    readonly route: string;
+    readonly runtime: string;
+    readonly kind: ContractCaseKind;
+    readonly target: ContractTarget;
+    readonly mutation?: string;
+    readonly ok: boolean;
+    readonly status?: number;
+    readonly message: string;
+    /** Number of successful greedy reductions applied to a failing hostile input. */
+    readonly shrinkSteps?: number;
+    readonly replay: ContractReplay;
+}
+export interface AdversarialContractReport {
+    readonly ok: boolean;
+    readonly seed: number;
+    readonly routeCount: number;
+    readonly targetCount: number;
+    readonly runtimeCount: number;
+    readonly results: readonly AdversarialContractResult[];
+    readonly failures: readonly AdversarialContractResult[];
+    readonly gaps: readonly ContractCoverageGap[];
+    readonly counts: {
+        readonly passed: number;
+        readonly failed: number;
+        readonly gaps: number;
+    };
+}
+export declare class AdversarialContractError extends Error {
+    readonly report: AdversarialContractReport;
+    constructor(report: AdversarialContractReport);
+}
+/**
+ * Execute contract-derived hostile inputs and declared-response conformance against a runtime matrix.
+ * Runtime/request failures are captured in the report; inspect `report.ok`, `failures`, and `gaps`
+ * (or use {@link assertAdversarialContract} for a throwing test assertion).
+ */
+export declare function runAdversarialContract(app: ContractTestApp, options?: AdversarialContractOptions): Promise<AdversarialContractReport>;
+/** Run the contract laboratory and throw an {@link AdversarialContractError} unless it is fully green. */
+export declare function assertAdversarialContract(app: ContractTestApp, options?: AdversarialContractOptions): Promise<AdversarialContractReport>;
+export {};
+//# sourceMappingURL=adversarial.d.ts.map

package/dist/adversarial.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adversarial.d.ts","sourceRoot":"","sources":["../src/adversarial.ts"],"names":[],"mappings":"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"}