@fuzdev/fuz_app 0.12.0 → 0.13.0

package/dist/testing/error_coverage.d.ts

@@ -1,52 +1,116 @@
 import './assert_dev_env.js';
+/**
+ * Error reachability coverage tracking.
+ *
+ * Tracks which declared error statuses (and specific error codes) are
+ * actually exercised in tests. `ErrorCoverageCollector` records status
+ * codes (optionally with body `error` codes) observed during test runs,
+ * then `assert_error_coverage` compares against declared error schemas
+ * to find uncovered error paths — reporting per-code when the declared
+ * schema is a literal or enum, per-status otherwise.
+ *
+ * @module
+ */
+import { z } from 'zod';
 import type { RouteSpec } from '../http/route_spec.js';
 /**
- * Tracks which route × status combinations have been exercised in tests.
+ * Extract declared error code values from an error response schema.
+ *
+ * Recognizes schemas shaped like `z.object({error: z.literal(...)})` or
+ * `z.object({error: z.enum([...])})` (incl. `looseObject`/`strictObject`).
+ * Returns the set of declared code values, or `null` if the schema doesn't
+ * expose a literal/enum `error` field (e.g., bare `ApiError` with `z.string()`).
  *
- * Use `record()` to log an observed status, or `assert_and_record()` to
- * combine response validation with tracking. After all tests, call
- * `uncovered()` to find declared error statuses never exercised.
+ * Used by coverage reporting to split a single declared status into per-code
+ * rows when the route's error schema names specific codes.
+ */
+export declare const extract_declared_error_codes: (schema: z.ZodType) => Array<string> | null;
+/** Uncovered entry — either a status-level row (no `code`) or a specific-code row. */
+export interface UncoveredEntry {
+    method: string;
+    path: string;
+    status: number;
+    /** Declared code value missing, when the status's error schema names specific codes. */
+    code?: string;
+}
+/** Options controlling which routes/statuses are considered for coverage. */
+export interface CoverageFilterOptions {
+    /** Routes to skip, in `'METHOD /path'` format. */
+    ignore_routes?: Array<string>;
+    /** HTTP status codes to skip. */
+    ignore_statuses?: Array<number>;
+}
+/**
+ * Tracks which route × status (and route × status × code) combinations have
+ * been exercised in tests.
+ *
+ * Use `record()` to log an observed status (optionally with the body's `error`
+ * code), or `assert_and_record()` to combine response validation with tracking
+ * (auto-extracts `body.error` from the response when present).
+ * After all tests, call `uncovered()` to find declared error paths never
+ * exercised.
+ *
+ * An observation recorded without a code still satisfies "any-code" coverage
+ * requirements for the same status — i.e., if a caller records just the status,
+ * all declared codes for that status are considered covered. Per-code tracking
+ * is additive: callers who know the body's `error` value should pass it to get
+ * precise per-code gap reporting on routes with literal/enum error schemas.
  */
 export declare class ErrorCoverageCollector {
-    /** Observed route × status keys: `"METHOD /spec-path:STATUS"`. */
+    /**
+     * Observed keys: `"METHOD /spec-path:STATUS"` or `"METHOD /spec-path:STATUS:CODE"`.
+     *
+     * Both shapes coexist — the code-less key marks the status as covered at any
+     * code; a code-bearing key adds per-code precision.
+     */
     readonly observed: Set<string>;
     /**
-     * Record an observed error status for a route.
+     * Record an observed error status (optionally with the body's `error` code) for a route.
      *
      * Resolves the concrete request path back to the spec template path
-     * (e.g., `/api/accounts/abc` → `/api/accounts/:id`).
+     * (e.g., `/api/accounts/abc` → `/api/accounts/:id`). When `code` is provided,
+     * it is stored alongside the status for per-code coverage tracking.
      *
      * @param route_specs - route specs for path resolution
      * @param method - HTTP method
      * @param path - request path (may be concrete)
      * @param status - observed HTTP status code
+     * @param code - observed body `error` code (pass when the route's error
+     *   schema declares specific codes via `z.literal` or `z.enum`)
      */
-    record(route_specs: Array<RouteSpec>, method: string, path: string, status: number): void;
+    record(route_specs: Array<RouteSpec>, method: string, path: string, status: number, code?: string): void;
     /**
      * Validate a response against its route spec and record the status.
      *
-     * Wraps `assert_response_matches_spec` and records the status code.
+     * Wraps `assert_response_matches_spec` and records the status code. For
+     * error responses, auto-extracts `body.error` from the JSON body (via a
+     * cloned response, so the original stream stays usable) and records it
+     * for per-code coverage. Pass an explicit `code` to override the
+     * auto-extracted value or when the body was already consumed.
      *
      * @param route_specs - route specs for schema lookup and path resolution
      * @param method - HTTP method
      * @param path - request path
      * @param response - the Response to validate and record
+     * @param code - observed body `error` code (override; if omitted and the
+     *   response body is a JSON object with a string `error` field, that value
+     *   is auto-extracted)
      */
-    assert_and_record(route_specs: Array<RouteSpec>, method: string, path: string, response: Response): Promise<void>;
+    assert_and_record(route_specs: Array<RouteSpec>, method: string, path: string, response: Response, code?: string): Promise<void>;
     /**
-     * Find declared error statuses that were never observed.
+     * Find declared error paths that were never observed.
      *
-     * Computes the declared set from `merge_error_schemas` for each route spec,
-     * then subtracts observed keys.
+     * Computes the declared set from `merge_error_schemas` for each route spec.
+     * For statuses whose error schema names specific codes (via `z.literal` or
+     * `z.enum`), reports per-code rows; otherwise reports one row per status.
+     * A status-only observation (no code) satisfies all declared codes for that
+     * status — the "any-code" rule.
      *
      * @param route_specs - route specs to check coverage against
-     * @returns uncovered entries with method, path, and status
+     * @param options - exclusion configuration (skip routes or statuses)
+     * @returns uncovered entries with method, path, status, and optional code
      */
-    uncovered(route_specs: Array<RouteSpec>): Array<{
-        method: string;
-        path: string;
-        status: number;
-    }>;
+    uncovered(route_specs: Array<RouteSpec>, options?: CoverageFilterOptions): Array<UncoveredEntry>;
 }
 /**
  * Default minimum error coverage threshold for the standard integration
@@ -55,20 +119,22 @@ export declare class ErrorCoverageCollector {
  */
 export declare const DEFAULT_INTEGRATION_ERROR_COVERAGE = 0.2;
 /** Options for `assert_error_coverage`. */
-export interface ErrorCoverageOptions {
+export interface ErrorCoverageOptions extends CoverageFilterOptions {
     /** Minimum coverage ratio (0–1). Default `0` (informational only). */
     min_coverage?: number;
-    /** Routes to skip, in `'METHOD /path'` format. */
-    ignore_routes?: Array<string>;
-    /** HTTP status codes to skip. */
-    ignore_statuses?: Array<number>;
 }
 /**
  * Assert error coverage meets a minimum threshold.
  *
- * Computes the ratio of exercised error statuses to total declared error
- * statuses. When `min_coverage` is 0 (default), logs coverage info without
- * failing. When > 0, fails if coverage is below the threshold.
+ * Computes the ratio of exercised error paths to total declared error paths.
+ * For routes whose status error schema names specific codes (`z.literal` or
+ * `z.enum`), each declared code counts as one coverage path; for schemas
+ * without declared codes (`ApiError`/`z.string()`), the status counts as one
+ * path. A status-only observation covers all declared codes for that status
+ * (the "any-code" rule).
+ *
+ * When `min_coverage` is 0 (default), logs coverage info without failing.
+ * When > 0, fails if coverage is below the threshold.
  *
  * @param collector - the coverage collector with recorded observations
  * @param route_specs - route specs to check coverage against

package/dist/testing/error_coverage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"error_coverage.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/testing/error_coverage.ts"],"names":[],"mappings":"AAAA,OAAO,qBAAqB,CAAC;AAe7B,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,uBAAuB,CAAC;AAIrD;;;;;;GAMG;AACH,qBAAa,sBAAsB;IAClC,kEAAkE;IAClE,QAAQ,CAAC,QAAQ,EAAE,GAAG,CAAC,MAAM,CAAC,CAAa;IAE3C;;;;;;;;;;OAUG;IACH,MAAM,CAAC,WAAW,EAAE,KAAK,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI;IAMzF;;;;;;;;;OASG;IACG,iBAAiB,CACtB,WAAW,EAAE,KAAK,CAAC,SAAS,CAAC,EAC7B,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,QAAQ,GAChB,OAAO,CAAC,IAAI,CAAC;IAKhB;;;;;;;;OAQG;IACH,SAAS,CAAC,WAAW,EAAE,KAAK,CAAC,SAAS,CAAC,GAAG,KAAK,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAC,CAAC;CAe/F;AAED;;;;GAIG;AACH,eAAO,MAAM,kCAAkC,MAAM,CAAC;AAEtD,2CAA2C;AAC3C,MAAM,WAAW,oBAAoB;IACpC,sEAAsE;IACtE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,kDAAkD;IAClD,aAAa,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAC9B,iCAAiC;IACjC,eAAe,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;CAChC;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,qBAAqB,GACjC,WAAW,sBAAsB,EACjC,aAAa,KAAK,CAAC,SAAS,CAAC,EAC7B,UAAU,oBAAoB,KAC5B,IA6CF,CAAC"}
+{"version":3,"file":"error_coverage.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/testing/error_coverage.ts"],"names":[],"mappings":"AAAA,OAAO,qBAAqB,CAAC;AAE7B;;;;;;;;;;;GAWG;AAEH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAGtB,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,uBAAuB,CAAC;AAIrD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,4BAA4B,GAAI,QAAQ,CAAC,CAAC,OAAO,KAAG,KAAK,CAAC,MAAM,CAAC,GAAG,IAWhF,CAAC;AAEF,sFAAsF;AACtF,MAAM,WAAW,cAAc;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,wFAAwF;IACxF,IAAI,CAAC,EAAE,MAAM,CAAC;CACd;AAED,6EAA6E;AAC7E,MAAM,WAAW,qBAAqB;IACrC,kDAAkD;IAClD,aAAa,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAC9B,iCAAiC;IACjC,eAAe,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;CAChC;AAqDD;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,sBAAsB;IAClC;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,EAAE,GAAG,CAAC,MAAM,CAAC,CAAa;IAE3C;;;;;;;;;;;;;OAaG;IACH,MAAM,CACL,WAAW,EAAE,KAAK,CAAC,SAAS,CAAC,EAC7B,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,IAAI,CAAC,EAAE,MAAM,GACX,IAAI;IAUP;;;;;;;;;;;;;;;;OAgBG;IACG,iBAAiB,CACtB,WAAW,EAAE,KAAK,CAAC,SAAS,CAAC,EAC7B,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,QAAQ,EAClB,IAAI,CAAC,EAAE,MAAM,GACX,OAAO,CAAC,IAAI,CAAC;IAgBhB;;;;;;;;;;;;OAYG;IACH,SAAS,CAAC,WAAW,EAAE,KAAK,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC,EAAE,qBAAqB,GAAG,KAAK,CAAC,cAAc,CAAC;CAKhG;AAED;;;;GAIG;AACH,eAAO,MAAM,kCAAkC,MAAM,CAAC;AAEtD,2CAA2C;AAC3C,MAAM,WAAW,oBAAqB,SAAQ,qBAAqB;IAClE,sEAAsE;IACtE,YAAY,CAAC,EAAE,MAAM,CAAC;CACtB;AAaD;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,qBAAqB,GACjC,WAAW,sBAAsB,EACjC,aAAa,KAAK,CAAC,SAAS,CAAC,EAC7B,UAAU,oBAAoB,KAC5B,IAqBF,CAAC"}

package/dist/testing/error_coverage.js

@@ -2,80 +2,183 @@ import './assert_dev_env.js';
 /**
  * Error reachability coverage tracking.
  *
- * Tracks which declared error statuses are actually exercised in tests.
- * `ErrorCoverageCollector` records status codes observed during test runs,
+ * Tracks which declared error statuses (and specific error codes) are
+ * actually exercised in tests. `ErrorCoverageCollector` records status
+ * codes (optionally with body `error` codes) observed during test runs,
  * then `assert_error_coverage` compares against declared error schemas
- * to find uncovered error paths.
+ * to find uncovered error paths — reporting per-code when the declared
+ * schema is a literal or enum, per-status otherwise.
  *
  * @module
  */
+import { z } from 'zod';
 import { assert } from 'vitest';
 import { merge_error_schemas } from '../http/schema_helpers.js';
 import { find_route_spec, assert_response_matches_spec } from './integration_helpers.js';
 /**
- * Tracks which route × status combinations have been exercised in tests.
+ * Extract declared error code values from an error response schema.
  *
- * Use `record()` to log an observed status, or `assert_and_record()` to
- * combine response validation with tracking. After all tests, call
- * `uncovered()` to find declared error statuses never exercised.
+ * Recognizes schemas shaped like `z.object({error: z.literal(...)})` or
+ * `z.object({error: z.enum([...])})` (incl. `looseObject`/`strictObject`).
+ * Returns the set of declared code values, or `null` if the schema doesn't
+ * expose a literal/enum `error` field (e.g., bare `ApiError` with `z.string()`).
+ *
+ * Used by coverage reporting to split a single declared status into per-code
+ * rows when the route's error schema names specific codes.
+ */
+export const extract_declared_error_codes = (schema) => {
+    if (!(schema instanceof z.ZodObject))
+        return null;
+    const error_field = schema.shape.error;
+    if (!error_field)
+        return null;
+    if (error_field instanceof z.ZodLiteral) {
+        return [...error_field.values].map(String);
+    }
+    if (error_field instanceof z.ZodEnum) {
+        return error_field.options.map(String);
+    }
+    return null;
+};
+/**
+ * Shared walk over declared error paths.
+ *
+ * Single source of truth for the route → status → code traversal used by
+ * both `uncovered()` and `assert_error_coverage`. Yields one entry per
+ * declared coverage path with a `covered` flag, applying the "any-code"
+ * rule (status-only observation covers all declared codes).
+ */
+const walk_coverage = (collector, route_specs, options) => {
+    const ignore_routes = new Set(options?.ignore_routes);
+    const ignore_statuses = new Set(options?.ignore_statuses);
+    const entries = [];
+    for (const spec of route_specs) {
+        const route_key = `${spec.method} ${spec.path}`;
+        if (ignore_routes.has(route_key))
+            continue;
+        const merged = merge_error_schemas(spec);
+        if (!merged)
+            continue;
+        for (const status_str of Object.keys(merged)) {
+            const status = Number(status_str);
+            if (ignore_statuses.has(status))
+                continue;
+            const error_schema = merged[status];
+            if (!error_schema)
+                continue;
+            const status_key = `${spec.method} ${spec.path}:${status}`;
+            const status_observed = collector.observed.has(status_key);
+            const codes = extract_declared_error_codes(error_schema);
+            if (codes && codes.length > 0) {
+                for (const code of codes) {
+                    const covered = status_observed || collector.observed.has(`${status_key}:${code}`);
+                    entries.push({ method: spec.method, path: spec.path, status, code, covered });
+                }
+            }
+            else {
+                entries.push({ method: spec.method, path: spec.path, status, covered: status_observed });
+            }
+        }
+    }
+    return entries;
+};
+/**
+ * Tracks which route × status (and route × status × code) combinations have
+ * been exercised in tests.
+ *
+ * Use `record()` to log an observed status (optionally with the body's `error`
+ * code), or `assert_and_record()` to combine response validation with tracking
+ * (auto-extracts `body.error` from the response when present).
+ * After all tests, call `uncovered()` to find declared error paths never
+ * exercised.
+ *
+ * An observation recorded without a code still satisfies "any-code" coverage
+ * requirements for the same status — i.e., if a caller records just the status,
+ * all declared codes for that status are considered covered. Per-code tracking
+ * is additive: callers who know the body's `error` value should pass it to get
+ * precise per-code gap reporting on routes with literal/enum error schemas.
  */
 export class ErrorCoverageCollector {
-    /** Observed route × status keys: `"METHOD /spec-path:STATUS"`. */
+    /**
+     * Observed keys: `"METHOD /spec-path:STATUS"` or `"METHOD /spec-path:STATUS:CODE"`.
+     *
+     * Both shapes coexist — the code-less key marks the status as covered at any
+     * code; a code-bearing key adds per-code precision.
+     */
     observed = new Set();
     /**
-     * Record an observed error status for a route.
+     * Record an observed error status (optionally with the body's `error` code) for a route.
      *
      * Resolves the concrete request path back to the spec template path
-     * (e.g., `/api/accounts/abc` → `/api/accounts/:id`).
+     * (e.g., `/api/accounts/abc` → `/api/accounts/:id`). When `code` is provided,
+     * it is stored alongside the status for per-code coverage tracking.
      *
      * @param route_specs - route specs for path resolution
      * @param method - HTTP method
      * @param path - request path (may be concrete)
      * @param status - observed HTTP status code
+     * @param code - observed body `error` code (pass when the route's error
+     *   schema declares specific codes via `z.literal` or `z.enum`)
      */
-    record(route_specs, method, path, status) {
+    record(route_specs, method, path, status, code) {
         const spec = find_route_spec(route_specs, method, path);
         const spec_path = spec ? spec.path : path;
-        this.observed.add(`${method} ${spec_path}:${status}`);
+        const base_key = `${method} ${spec_path}:${status}`;
+        this.observed.add(base_key);
+        if (code !== undefined) {
+            this.observed.add(`${base_key}:${code}`);
+        }
     }
     /**
      * Validate a response against its route spec and record the status.
      *
-     * Wraps `assert_response_matches_spec` and records the status code.
+     * Wraps `assert_response_matches_spec` and records the status code. For
+     * error responses, auto-extracts `body.error` from the JSON body (via a
+     * cloned response, so the original stream stays usable) and records it
+     * for per-code coverage. Pass an explicit `code` to override the
+     * auto-extracted value or when the body was already consumed.
      *
      * @param route_specs - route specs for schema lookup and path resolution
      * @param method - HTTP method
      * @param path - request path
      * @param response - the Response to validate and record
+     * @param code - observed body `error` code (override; if omitted and the
+     *   response body is a JSON object with a string `error` field, that value
+     *   is auto-extracted)
      */
-    async assert_and_record(route_specs, method, path, response) {
+    async assert_and_record(route_specs, method, path, response, code) {
         await assert_response_matches_spec(route_specs, method, path, response);
-        this.record(route_specs, method, path, response.status);
+        let resolved_code = code;
+        if (resolved_code === undefined && !response.ok && !response.bodyUsed) {
+            try {
+                const body = await response.clone().json();
+                if (body && typeof body.error === 'string') {
+                    resolved_code = body.error;
+                }
+            }
+            catch {
+                // non-JSON body — no code to extract
+            }
+        }
+        this.record(route_specs, method, path, response.status, resolved_code);
     }
     /**
-     * Find declared error statuses that were never observed.
+     * Find declared error paths that were never observed.
      *
-     * Computes the declared set from `merge_error_schemas` for each route spec,
-     * then subtracts observed keys.
+     * Computes the declared set from `merge_error_schemas` for each route spec.
+     * For statuses whose error schema names specific codes (via `z.literal` or
+     * `z.enum`), reports per-code rows; otherwise reports one row per status.
+     * A status-only observation (no code) satisfies all declared codes for that
+     * status — the "any-code" rule.
      *
      * @param route_specs - route specs to check coverage against
-     * @returns uncovered entries with method, path, and status
+     * @param options - exclusion configuration (skip routes or statuses)
+     * @returns uncovered entries with method, path, status, and optional code
      */
-    uncovered(route_specs) {
-        const missing = [];
-        for (const spec of route_specs) {
-            const merged = merge_error_schemas(spec);
-            if (!merged)
-                continue;
-            for (const status_str of Object.keys(merged)) {
-                const status = Number(status_str);
-                const key = `${spec.method} ${spec.path}:${status}`;
-                if (!this.observed.has(key)) {
-                    missing.push({ method: spec.method, path: spec.path, status });
-                }
-            }
-        }
-        return missing;
+    uncovered(route_specs, options) {
+        return walk_coverage(this, route_specs, options)
+            .filter((entry) => !entry.covered)
+            .map(({ method, path, status, code }) => ({ method, path, status, ...(code && { code }) }));
     }
 }
 /**
@@ -84,12 +187,25 @@ export class ErrorCoverageCollector {
  * in the composable suites. Consumers should increase as their test suites mature.
  */
 export const DEFAULT_INTEGRATION_ERROR_COVERAGE = 0.2;
+/**
+ * Format an uncovered entry for human-readable log output.
+ *
+ * Uses `status (code)` — spaces around the code make `:` unambiguous as
+ * the route_key / status separator.
+ */
+const format_uncovered = (entry) => `${entry.method} ${entry.path} → ${entry.status}${entry.code ? ` (${entry.code})` : ''}`;
 /**
  * Assert error coverage meets a minimum threshold.
  *
- * Computes the ratio of exercised error statuses to total declared error
- * statuses. When `min_coverage` is 0 (default), logs coverage info without
- * failing. When > 0, fails if coverage is below the threshold.
+ * Computes the ratio of exercised error paths to total declared error paths.
+ * For routes whose status error schema names specific codes (`z.literal` or
+ * `z.enum`), each declared code counts as one coverage path; for schemas
+ * without declared codes (`ApiError`/`z.string()`), the status counts as one
+ * path. A status-only observation covers all declared codes for that status
+ * (the "any-code" rule).
+ *
+ * When `min_coverage` is 0 (default), logs coverage info without failing.
+ * When > 0, fails if coverage is below the threshold.
  *
  * @param collector - the coverage collector with recorded observations
  * @param route_specs - route specs to check coverage against
@@ -97,39 +213,16 @@ export const DEFAULT_INTEGRATION_ERROR_COVERAGE = 0.2;
  */
 export const assert_error_coverage = (collector, route_specs, options) => {
     const min_coverage = options?.min_coverage ?? 0;
-    const ignore_routes = new Set(options?.ignore_routes);
-    const ignore_statuses = new Set(options?.ignore_statuses);
-    let total = 0;
-    let covered = 0;
-    const uncovered_entries = [];
-    for (const spec of route_specs) {
-        const route_key = `${spec.method} ${spec.path}`;
-        if (ignore_routes.has(route_key))
-            continue;
-        const merged = merge_error_schemas(spec);
-        if (!merged)
-            continue;
-        for (const status_str of Object.keys(merged)) {
-            const status = Number(status_str);
-            if (ignore_statuses.has(status))
-                continue;
-            total++;
-            const key = `${spec.method} ${spec.path}:${status}`;
-            if (collector.observed.has(key)) {
-                covered++;
-            }
-            else {
-                uncovered_entries.push(`${route_key} → ${status}`);
-            }
-        }
-    }
+    const entries = walk_coverage(collector, route_specs, options);
+    const total = entries.length;
+    const uncovered_entries = entries.filter((e) => !e.covered);
+    const covered = total - uncovered_entries.length;
+    const uncovered_lines = uncovered_entries.map(format_uncovered);
     const ratio = total > 0 ? covered / total : 1;
     console.log(`[error coverage] ${covered}/${total} (${(ratio * 100).toFixed(1)}%)` +
-        (uncovered_entries.length > 0
-            ? `\n  uncovered:\n    ${uncovered_entries.join('\n    ')}`
-            : ''));
+        (uncovered_lines.length > 0 ? `\n  uncovered:\n    ${uncovered_lines.join('\n    ')}` : ''));
     if (min_coverage > 0) {
         assert.ok(ratio >= min_coverage, `Error coverage ${(ratio * 100).toFixed(1)}% below threshold ${(min_coverage * 100).toFixed(1)}%` +
-            `\n  uncovered:\n    ${uncovered_entries.join('\n    ')}`);
+            `\n  uncovered:\n    ${uncovered_lines.join('\n    ')}`);
     }
 };

package/dist/testing/integration.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"integration.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/testing/integration.ts"],"names":[],"mappings":"AAAA,OAAO,qBAAqB,CAAC;AAsB7B,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,2BAA2B,CAAC;AAC9D,OAAO,KAAK,EAAC,gBAAgB,EAAE,gBAAgB,EAAC,MAAM,yBAAyB,CAAC;AAChF,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,uBAAuB,CAAC;AAGrD,OAAO,EAIN,KAAK,SAAS,EACd,MAAM,SAAS,CAAC;AAgBjB;;GAEG;AACH,MAAM,WAAW,8BAA8B;IAC9C,4CAA4C;IAC5C,eAAe,EAAE,cAAc,CAAC,MAAM,CAAC,CAAC;IACxC,wDAAwD;IACxD,kBAAkB,EAAE,CAAC,GAAG,EAAE,gBAAgB,KAAK,KAAK,CAAC,SAAS,CAAC,CAAC;IAChE,iDAAiD;IACjD,WAAW,CAAC,EAAE,OAAO,CACpB,IAAI,CAAC,gBAAgB,EAAE,SAAS,GAAG,iBAAiB,GAAG,oBAAoB,CAAC,CAC5E,CAAC;IACF;;;OAGG;IACH,YAAY,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC;CAChC;AAeD;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,mCAAmC,GAC/C,SAAS,8BAA8B,KACrC,IAo+CF,CAAC"}
+{"version":3,"file":"integration.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/testing/integration.ts"],"names":[],"mappings":"AAAA,OAAO,qBAAqB,CAAC;AAsB7B,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,2BAA2B,CAAC;AAC9D,OAAO,KAAK,EAAC,gBAAgB,EAAE,gBAAgB,EAAC,MAAM,yBAAyB,CAAC;AAChF,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,uBAAuB,CAAC;AAGrD,OAAO,EAIN,KAAK,SAAS,EACd,MAAM,SAAS,CAAC;AAgBjB;;GAEG;AACH,MAAM,WAAW,8BAA8B;IAC9C,4CAA4C;IAC5C,eAAe,EAAE,cAAc,CAAC,MAAM,CAAC,CAAC;IACxC,wDAAwD;IACxD,kBAAkB,EAAE,CAAC,GAAG,EAAE,gBAAgB,KAAK,KAAK,CAAC,SAAS,CAAC,CAAC;IAChE,iDAAiD;IACjD,WAAW,CAAC,EAAE,OAAO,CACpB,IAAI,CAAC,gBAAgB,EAAE,SAAS,GAAG,iBAAiB,GAAG,oBAAoB,CAAC,CAC5E,CAAC;IACF;;;OAGG;IACH,YAAY,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC;CAChC;AAeD;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,mCAAmC,GAC/C,SAAS,8BAA8B,KACrC,IAm/CF,CAAC"}

package/dist/testing/integration.js

@@ -127,9 +127,9 @@ export const describe_standard_integration_tests = (options) => {
                     }),
                 });
                 assert.strictEqual(res.status, 401);
-                error_collector.record(test_app.route_specs, 'POST', login_route.path, 401);
-                const body = await res.json();
+                const body = await res.clone().json();
                 assert.strictEqual(body.error, 'invalid_credentials');
+                await error_collector.assert_and_record(test_app.route_specs, 'POST', login_route.path, res);
             });
             test('login with nonexistent user returns 401', async () => {
                 const test_app = await create_test_app(build_test_app_options(options, get_db()));
@@ -148,9 +148,9 @@ export const describe_standard_integration_tests = (options) => {
                     }),
                 });
                 assert.strictEqual(res.status, 401);
-                error_collector.record(test_app.route_specs, 'POST', login_route.path, 401);
-                const body = await res.json();
+                const body = await res.clone().json();
                 assert.strictEqual(body.error, 'invalid_credentials');
+                await error_collector.assert_and_record(test_app.route_specs, 'POST', login_route.path, res);
             });
             test('login trims whitespace from username', async () => {
                 const test_app = await create_test_app(build_test_app_options(options, get_db()));
@@ -821,9 +821,9 @@ export const describe_standard_integration_tests = (options) => {
                 // third attempt should be rate-limited
                 const limited_res = await make_bad_login();
                 assert.strictEqual(limited_res.status, 429, 'Expected 429 after exceeding rate limit');
-                error_collector.record(test_app.route_specs, 'POST', login_route.path, 429);
-                const limited_body = await limited_res.json();
+                const limited_body = await limited_res.clone().json();
                 assert.strictEqual(limited_body.error, 'rate_limit_exceeded');
+                await error_collector.assert_and_record(test_app.route_specs, 'POST', login_route.path, limited_res);
                 // Retry-After header present
                 const retry_after = limited_res.headers.get('Retry-After');
                 assert.ok(retry_after, 'Expected Retry-After header on 429 response');

package/dist/testing/integration_helpers.d.ts

@@ -2,6 +2,7 @@ import './assert_dev_env.js';
 import type { RouteSpec, RouteMethod } from '../http/route_spec.js';
 import type { Keyring } from '../auth/keyring.js';
 import { type SessionOptions } from '../auth/session_cookie.js';
+import type { TestApp, TestAccount } from './app_server.js';
 /**
  * Find a route spec matching the given method and path.
  *
@@ -99,4 +100,20 @@ export declare const collect_json_keys_recursive: (value: unknown) => Set<string
  * @param context - description for error messages
  */
 export declare const assert_no_sensitive_fields_in_json: (body: unknown, blocklist: ReadonlyArray<string>, context: string) => void;
+/**
+ * Pick request headers matching a route spec's auth requirement.
+ *
+ * Maps `RouteAuth` onto a test account's credentials:
+ * - `none` — origin headers only
+ * - `authenticated` — the authed account's session cookie
+ * - `role: admin` — the admin account's session cookie
+ * - `role: <other>` — the test app's bootstrapped keeper session
+ * - `keeper` — the test app's daemon token
+ *
+ * @param spec - route spec to inspect
+ * @param test_app - the assembled test app (for bootstrapped credentials)
+ * @param authed_account - an account with no roles (for `authenticated` auth)
+ * @param admin_account - an account with `admin` role (for role-gated routes)
+ */
+export declare const pick_auth_headers: (spec: RouteSpec, test_app: TestApp, authed_account: TestAccount, admin_account: TestAccount) => Record<string, string>;
 //# sourceMappingURL=integration_helpers.d.ts.map

package/dist/testing/integration_helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"integration_helpers.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/testing/integration_helpers.ts"],"names":[],"mappings":"AAAA,OAAO,qBAAqB,CAAC;AAU7B,OAAO,KAAK,EAAC,SAAS,EAAE,WAAW,EAAC,MAAM,uBAAuB,CAAC;AAElE,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,oBAAoB,CAAC;AAChD,OAAO,EAA8B,KAAK,cAAc,EAAC,MAAM,2BAA2B,CAAC;AAE3F;;;;;;;;;GASG;AACH,eAAO,MAAM,eAAe,GAC3B,OAAO,KAAK,CAAC,SAAS,CAAC,EACvB,QAAQ,MAAM,EACd,MAAM,MAAM,KACV,SAAS,GAAG,SAad,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,eAAe,GAC3B,OAAO,KAAK,CAAC,SAAS,CAAC,EACvB,QAAQ,MAAM,EACd,QAAQ,WAAW,KACjB,SAAS,GAAG,SAEd,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,4BAA4B,GACxC,aAAa,KAAK,CAAC,SAAS,CAAC,EAC7B,QAAQ,MAAM,EACd,MAAM,MAAM,EACZ,UAAU,QAAQ,KAChB,OAAO,CAAC,IAAI,CAmDd,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,0BAA0B,GACtC,SAAS,OAAO,EAChB,iBAAiB,cAAc,CAAC,MAAM,CAAC,KACrC,OAAO,CAAC,MAAM,CAGhB,CAAC;AAuCF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,2BAA2B,GAAI,MAAM,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAG,KAAK,CAAC,MAAM,CAQvF,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,4BAA4B,GACxC,MAAM,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,SAAS,MAAM,KACb,IAkBF,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,oCAAoC,GAChD,UAAU,QAAQ,EAClB,MAAM;IAAC,WAAW,EAAE,MAAM,CAAA;CAAC,KACzB,IAUF,CAAC;AAIF,oEAAoE;AACpE,eAAO,MAAM,yBAAyB,EAAE,aAAa,CAAC,MAAM,CAAmC,CAAC;AAEhG,0EAA0E;AAC1E,eAAO,MAAM,0BAA0B,EAAE,aAAa,CAAC,MAAM,CAAgC,CAAC;AAE9F;;;;;;;GAOG;AACH,eAAO,MAAM,2BAA2B,GAAI,OAAO,OAAO,KAAG,GAAG,CAAC,MAAM,CAetE,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,kCAAkC,GAC9C,MAAM,OAAO,EACb,WAAW,aAAa,CAAC,MAAM,CAAC,EAChC,SAAS,MAAM,KACb,IAKF,CAAC"}
+{"version":3,"file":"integration_helpers.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/testing/integration_helpers.ts"],"names":[],"mappings":"AAAA,OAAO,qBAAqB,CAAC;AAU7B,OAAO,KAAK,EAAC,SAAS,EAAE,WAAW,EAAC,MAAM,uBAAuB,CAAC;AAElE,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,oBAAoB,CAAC;AAChD,OAAO,EAA8B,KAAK,cAAc,EAAC,MAAM,2BAA2B,CAAC;AAE3F,OAAO,KAAK,EAAC,OAAO,EAAE,WAAW,EAAC,MAAM,iBAAiB,CAAC;AAE1D;;;;;;;;;GASG;AACH,eAAO,MAAM,eAAe,GAC3B,OAAO,KAAK,CAAC,SAAS,CAAC,EACvB,QAAQ,MAAM,EACd,MAAM,MAAM,KACV,SAAS,GAAG,SAad,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,eAAe,GAC3B,OAAO,KAAK,CAAC,SAAS,CAAC,EACvB,QAAQ,MAAM,EACd,QAAQ,WAAW,KACjB,SAAS,GAAG,SAEd,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,4BAA4B,GACxC,aAAa,KAAK,CAAC,SAAS,CAAC,EAC7B,QAAQ,MAAM,EACd,MAAM,MAAM,EACZ,UAAU,QAAQ,KAChB,OAAO,CAAC,IAAI,CAmDd,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,0BAA0B,GACtC,SAAS,OAAO,EAChB,iBAAiB,cAAc,CAAC,MAAM,CAAC,KACrC,OAAO,CAAC,MAAM,CAGhB,CAAC;AAuCF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,2BAA2B,GAAI,MAAM,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAG,KAAK,CAAC,MAAM,CAQvF,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,4BAA4B,GACxC,MAAM,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,SAAS,MAAM,KACb,IAkBF,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,oCAAoC,GAChD,UAAU,QAAQ,EAClB,MAAM;IAAC,WAAW,EAAE,MAAM,CAAA;CAAC,KACzB,IAUF,CAAC;AAIF,oEAAoE;AACpE,eAAO,MAAM,yBAAyB,EAAE,aAAa,CAAC,MAAM,CAAmC,CAAC;AAEhG,0EAA0E;AAC1E,eAAO,MAAM,0BAA0B,EAAE,aAAa,CAAC,MAAM,CAAgC,CAAC;AAE9F;;;;;;;GAOG;AACH,eAAO,MAAM,2BAA2B,GAAI,OAAO,OAAO,KAAG,GAAG,CAAC,MAAM,CAetE,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,kCAAkC,GAC9C,MAAM,OAAO,EACb,WAAW,aAAa,CAAC,MAAM,CAAC,EAChC,SAAS,MAAM,KACb,IAKF,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,iBAAiB,GAC7B,MAAM,SAAS,EACf,UAAU,OAAO,EACjB,gBAAgB,WAAW,EAC3B,eAAe,WAAW,KACxB,MAAM,CAAC,MAAM,EAAE,MAAM,CAcvB,CAAC"}

package/dist/testing/integration_helpers.js

@@ -7,6 +7,7 @@ import './assert_dev_env.js';
 import { assert } from 'vitest';
 import { is_null_schema, merge_error_schemas } from '../http/schema_helpers.js';
 import { create_session_cookie_value } from '../auth/session_cookie.js';
+import { ROLE_ADMIN } from '../auth/role_schema.js';
 /**
  * Find a route spec matching the given method and path.
  *
@@ -249,3 +250,33 @@ export const assert_no_sensitive_fields_in_json = (body, blocklist, context) =>
         assert.ok(!keys.has(field), `${context}: response contains blocklisted field '${field}'`);
     }
 };
+/**
+ * Pick request headers matching a route spec's auth requirement.
+ *
+ * Maps `RouteAuth` onto a test account's credentials:
+ * - `none` — origin headers only
+ * - `authenticated` — the authed account's session cookie
+ * - `role: admin` — the admin account's session cookie
+ * - `role: <other>` — the test app's bootstrapped keeper session
+ * - `keeper` — the test app's daemon token
+ *
+ * @param spec - route spec to inspect
+ * @param test_app - the assembled test app (for bootstrapped credentials)
+ * @param authed_account - an account with no roles (for `authenticated` auth)
+ * @param admin_account - an account with `admin` role (for role-gated routes)
+ */
+export const pick_auth_headers = (spec, test_app, authed_account, admin_account) => {
+    switch (spec.auth.type) {
+        case 'none':
+            return { host: 'localhost', origin: 'http://localhost:5173' };
+        case 'authenticated':
+            return authed_account.create_session_headers();
+        case 'role':
+            if (spec.auth.role === ROLE_ADMIN) {
+                return admin_account.create_session_headers();
+            }
+            return test_app.create_session_headers();
+        case 'keeper':
+            return test_app.create_daemon_token_headers();
+    }
+};

package/dist/testing/round_trip.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"round_trip.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/testing/round_trip.ts"],"names":[],"mappings":"AAAA,OAAO,qBAAqB,CAAC;AAc7B,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,uBAAuB,CAAC;AACrD,OAAO,KAAK,EAAC,gBAAgB,EAAE,gBAAgB,EAAC,MAAM,yBAAyB,CAAC;AAChF,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,2BAA2B,CAAC;AAG9D,OAAO,EAAwB,KAAK,SAAS,EAAC,MAAM,SAAS,CAAC;AAO9D,oDAAoD;AACpD,MAAM,WAAW,oBAAoB;IACpC,4CAA4C;IAC5C,eAAe,EAAE,cAAc,CAAC,MAAM,CAAC,CAAC;IACxC,wDAAwD;IACxD,kBAAkB,EAAE,CAAC,GAAG,EAAE,gBAAgB,KAAK,KAAK,CAAC,SAAS,CAAC,CAAC;IAChE,iDAAiD;IACjD,WAAW,CAAC,EAAE,OAAO,CACpB,IAAI,CAAC,gBAAgB,EAAE,SAAS,GAAG,iBAAiB,GAAG,oBAAoB,CAAC,CAC5E,CAAC;IACF,qEAAqE;IACrE,YAAY,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC;IAChC,kDAAkD;IAClD,WAAW,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAC5B,+EAA+E;IAC/E,eAAe,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACvD;AAED;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,8BAA8B,GAAI,SAAS,oBAAoB,KAAG,IAqF9E,CAAC"}
+{"version":3,"file":"round_trip.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/testing/round_trip.ts"],"names":[],"mappings":"AAAA,OAAO,qBAAqB,CAAC;AAc7B,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,uBAAuB,CAAC;AACrD,OAAO,KAAK,EAAC,gBAAgB,EAAE,gBAAgB,EAAC,MAAM,yBAAyB,CAAC;AAChF,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,2BAA2B,CAAC;AAG9D,OAAO,EAAwB,KAAK,SAAS,EAAC,MAAM,SAAS,CAAC;AAQ9D,oDAAoD;AACpD,MAAM,WAAW,oBAAoB;IACpC,4CAA4C;IAC5C,eAAe,EAAE,cAAc,CAAC,MAAM,CAAC,CAAC;IACxC,wDAAwD;IACxD,kBAAkB,EAAE,CAAC,GAAG,EAAE,gBAAgB,KAAK,KAAK,CAAC,SAAS,CAAC,CAAC;IAChE,iDAAiD;IACjD,WAAW,CAAC,EAAE,OAAO,CACpB,IAAI,CAAC,gBAAgB,EAAE,SAAS,GAAG,iBAAiB,GAAG,oBAAoB,CAAC,CAC5E,CAAC;IACF,qEAAqE;IACrE,YAAY,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC;IAChC,kDAAkD;IAClD,WAAW,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAC5B,+EAA+E;IAC/E,eAAe,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACvD;AAED;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,8BAA8B,GAAI,SAAS,oBAAoB,KAAG,IA6F9E,CAAC"}