@luckystack/test-runner 0.14.0 → 0.15.0

package/dist/probeRequest.d.ts

@@ -8,7 +8,7 @@ export interface ProbeRequestInput {
     requestTimeoutMs: number;
 }
 export interface ProbeResponse {
-    /** HTTP status. Absent when the probe travelled over Socket.io. */
+    /** HTTP status. Over Socket.io: the envelope's `httpStatus`, when it carries one. */
     httpStatus?: number;
     parsed: {
         status?: string;
@@ -25,7 +25,7 @@ export interface ProbeTransportRequest {
     baseUrl: string;
     /** The route payload — the API `data`, or the sync `data` (the transport adds the sync envelope). */
     body: unknown;
-    /** HTTP headers (session Cookie, CSRF). A socket transport reads only the Cookie. */
+    /** HTTP headers (session Cookie or Bearer, CSRF). A socket transport reads only the session. */
     headers?: Record<string, string>;
     requestTimeoutMs: number;
 }

package/dist/runAllTests.d.ts

@@ -19,6 +19,19 @@ export interface RunAllTestsInput {
      * probes over HTTP — CSRF is an HTTP-only guard.
      */
     syncTransport?: 'socket' | 'http';
+    /**
+     * How API routes are probed. Defaults to the project's own
+     * `transport.invocation`: `'socket'` → Socket.io (the `apiRequest` pipeline
+     * real clients hit), `'routed-http'` → the `/api/*` HTTP route. The CSRF
+     * layer always probes over HTTP — CSRF is an HTTP-only guard.
+     */
+    apiTransport?: 'socket' | 'http';
+    /**
+     * Routes designed to fail on the server (e.g. a playground route that throws
+     * on purpose), matched like `skip`. The contract layer lets their shaped 5xx
+     * pass; any other route answering 5xx fails it.
+     */
+    expectServerError?: string[];
     /**
      * Write the full `RunAllTestsSummary` as JSON to this path (relative to the
      * process cwd). Defaults to `TEST_OUTPUT_FILE`, else `test-results.json`;
@@ -34,9 +47,13 @@ export interface RunAllTestsInput {
     apiMetaMap: ApiMetaMap;
     apiInputSchemas: InputSchemaMap;
     baseUrl: string;
-    /** Cookie name for the session token. Defaults to the project's configured session cookie name (`projectConfig.http.sessionCookieName`). */
+    /** Cookie name for the session token. Defaults to the project's configured session cookie name (`projectConfig.http.sessionCookieName`, with `http.sessionCookiePrefix` applied). */
     sessionCookieName?: string;
-    /** Auth token applied as a `Cookie` header to sweep-layer requests that need a session. */
+    /**
+     * Session token for sweep-layer requests that need a session: sent as the
+     * session `Cookie` in cookie mode, as `Authorization: Bearer` in token mode
+     * (`session.basedToken`).
+     */
     authToken?: string;
     /** Endpoints to skip from the sweep layers, e.g. routes that need a file upload. */
     skip?: string[];

package/dist/runAuthEnforcementTests.d.ts

@@ -10,8 +10,10 @@ export interface RunAuthEnforcementTestsInput {
     /** Substring filter on `<page>/<name>/<version>`; other routes are not requested at all. */
     filter?: string;
     inputFor?: (endpoint: EndpointDescriptor) => unknown;
-    /** Transport for sync routes (e.g. the socket transport). API routes always use HTTP. */
+    /** Transport for sync routes (e.g. the socket transport). Defaults to HTTP. */
     syncTransport?: ProbeTransport;
+    /** Transport for API routes (e.g. the socket transport). Defaults to HTTP. */
+    apiTransport?: ProbeTransport;
     onResult?: (result: ContractCheckResult) => void;
 }
 export declare const runAuthEnforcementTests: (input: RunAuthEnforcementTestsInput) => Promise<RunContractSummary>;

package/dist/runContractTests.d.ts

@@ -11,12 +11,26 @@ export interface RunContractTestsInput {
      * are known to need real input (e.g. a file upload).
      */
     skip?: string[];
+    /**
+     * Routes designed to fail on the server (e.g. a playground route that throws
+     * on purpose), matched like `skip`. Their shaped 5xx reply passes; every
+     * other route's 5xx fails the layer.
+     */
+    expectServerError?: string[];
     /** Substring filter on `<page>/<name>/<version>`; other routes are not requested at all. */
     filter?: string;
     inputFor?: (endpoint: EndpointDescriptor) => unknown;
     headers?: Record<string, string>;
-    /** Transport for sync routes (e.g. the socket transport). API routes always use HTTP. */
+    /** Transport for sync routes (e.g. the socket transport). Defaults to HTTP. */
     syncTransport?: ProbeTransport;
+    /** Transport for API routes (e.g. the socket transport). Defaults to HTTP. */
+    apiTransport?: ProbeTransport;
+    /**
+     * When given, rate limits are reset (`/_test/reset?only=rateLimits`) before
+     * each route, so the shared per-IP bucket cannot fill up mid-sweep and turn
+     * the remaining probes into limiter rejections.
+     */
+    resetToken?: string;
     onResult?: (result: ContractCheckResult) => void;
 }
 export declare const runContractTests: (input: RunContractTestsInput) => Promise<RunContractSummary>;

package/dist/runFuzzTests.d.ts

@@ -9,8 +9,16 @@ export interface RunFuzzTestsInput {
     /** Substring filter on `<page>/<name>/<version>`; other routes are not requested at all. */
     filter?: string;
     headers?: Record<string, string>;
-    /** Transport for sync routes (e.g. the socket transport). API routes always use HTTP. */
+    /** Transport for sync routes (e.g. the socket transport). Defaults to HTTP. */
     syncTransport?: ProbeTransport;
+    /** Transport for API routes (e.g. the socket transport). Defaults to HTTP. */
+    apiTransport?: ProbeTransport;
+    /**
+     * When given, rate limits are reset (`/_test/reset?only=rateLimits`) before
+     * each route, so the shared per-IP bucket cannot fill up mid-sweep and turn
+     * the remaining payloads into limiter rejections.
+     */
+    resetToken?: string;
     onResult?: (result: ContractCheckResult) => void;
 }
 export declare const runFuzzTests: (input: RunFuzzTestsInput) => Promise<RunContractSummary>;

package/dist/runRateLimitTests.d.ts

@@ -11,8 +11,10 @@ export interface RunRateLimitTestsInput {
     filter?: string;
     inputFor?: (endpoint: EndpointDescriptor) => unknown;
     headers?: Record<string, string>;
-    /** Transport for sync routes (e.g. the socket transport). API routes always use HTTP. */
+    /** Transport for sync routes (e.g. the socket transport). Defaults to HTTP. */
     syncTransport?: ProbeTransport;
+    /** Transport for API routes (e.g. the socket transport). Defaults to HTTP. */
+    apiTransport?: ProbeTransport;
     /**
      * Max rateLimit value to test. Endpoints with a higher limit are skipped
      * to avoid firing thousands of requests in CI.

package/dist/testLayerHelpers.d.ts

@@ -29,8 +29,18 @@ export interface SelectEndpointsInput {
 export declare const selectEndpoints: (input: SelectEndpointsInput) => EndpointDescriptor[];
 /** The meta map that describes `endpoint`: `syncMetaMap` for sync routes, else `apiMetaMap`. */
 export declare const metaMapFor: (endpoint: EndpointDescriptor, apiMetaMap: ApiMetaMap, syncMetaMap: SyncMetaMap | undefined) => RouteMetaMap;
-/** The transport for `endpoint`: `syncTransport` for sync routes when given, else HTTP. */
-export declare const transportFor: (endpoint: EndpointDescriptor, syncTransport: ProbeTransport | undefined) => ProbeTransport;
+/**
+ * The transport for `endpoint`: `syncTransport` for sync routes and
+ * `apiTransport` for API routes when given, else HTTP.
+ */
+export declare const transportFor: (endpoint: EndpointDescriptor, syncTransport: ProbeTransport | undefined, apiTransport?: ProbeTransport) => ProbeTransport;
+/**
+ * Whether sweep headers carry a session: a session Cookie (cookie mode) or an
+ * `Authorization: Bearer` token (token mode). Layers that must not fire junk
+ * at mutating routes treat both as an authenticated sweep.
+ */
+export declare const hasSessionHeaders: (headers: Record<string, string> | undefined) => boolean;
+export declare const isRateLimitedCode: (errorCode: string | undefined) => boolean;
 /**
  * Whether an endpoint is in the explicit skip list. Matched against
  * `<page>/<name>` (version-agnostic) and `<page>/<name>/<version>`

package/dist/testSocket.d.ts

@@ -1,4 +1,5 @@
 import { Socket } from 'socket.io-client';
+export declare const projectSessionCookieName: () => string;
 export declare const nextResponseIndex: () => number;
 export interface ConnectTestSocketInput {
     baseUrl: string;
@@ -56,3 +57,15 @@ export type EmitSyncOutcome = {
  * resolve with the server's single reply on `sync-<responseIndex>`.
  */
 export declare const emitSyncOverSocket: (socket: Socket, input: EmitSyncInput) => Promise<EmitSyncOutcome>;
+export interface EmitApiInput {
+    /** `<page>/<name>/<version>` — the route path without the `api/` prefix. */
+    routePath: string;
+    data: unknown;
+    timeoutMs: number;
+}
+/**
+ * Send one API request over `socket` exactly like the real client does in
+ * socket mode and resolve with the server's single reply on
+ * `apiResponse-<responseIndex>`.
+ */
+export declare const emitApiOverSocket: (socket: Socket, input: EmitApiInput) => Promise<EmitSyncOutcome>;

package/docs/contract-tests.md

@@ -4,13 +4,19 @@ Generated route maps drive a smoke check over the API surface so tests catch mis
 
 ## Probes follow the project transport
 
-A route is only meaningfully tested over the path real users hit (ADR 0064). API routes go over HTTP. Sync routes go over the project's own `transport.invocation`: Socket.io in a socket-mode project (the default), the routed `/sync/*` HTTP path in a routed-HTTP project; the caller may override this. The CSRF layer always probes sync over HTTP, because CSRF is an HTTP-only guard. Layer-5 `ctx.callSync` follows the same rule, so a socket-mode project's custom sync tests run through the socket pipeline and differences between the two pipelines surface as failures instead of being masked.
+A route is only meaningfully tested over the path real users hit (ADR 0064). API and sync routes both go over the project's own `transport.invocation`: Socket.io in a socket-mode project (the default), the routed `/api/*` and `/sync/*` HTTP paths in a routed-HTTP project; the caller may override each. The CSRF layer always probes over HTTP, because CSRF is an HTTP-only guard. Layer-5 `ctx.callApi` and `ctx.callSync` follow the same rule, so a socket-mode project's custom tests run through the socket pipelines and differences between the pipelines surface as failures instead of being masked.
 
 - Sync routes are swept only when the sweep receives the generated sync metadata (and sync input schemas for valid samples). Without it the sweep warns and covers API routes only.
 - All sync probes in one run target a single throwaway room that the sweep's own session joins, so room-membership enforcement sees a member rather than rejecting every probe.
 - Sockets the runner opens on the caller's session close as an intentional disconnect, the signal a real client sends; a plain close would let presence log that session out shortly after the sweep.
 - GET probes carry their payload in the query string under the reserved key the real client uses (ADR 0062); `fetch` cannot send a GET body, and dropping the payload made every GET route with a required field fail validation.
 
+## What counts as a pass
+
+A shaped error envelope is not enough on its own. A routing error (unknown route, wrong method, invalid name) means the generated route map and the live server disagree, and a 5xx or execution-failed reply means the handler crashed on a well-formed probe; both fail the layer. A route that is designed to fail on the server is listed explicitly as expected to error, so its 5xx passes without hiding everyone else's. A rate-limited reply never reached validation or the handler, so it is reported as skipped rather than passed; with a reset token the sweep clears rate limits between routes so the shared per-IP bucket does not fill up mid-sweep.
+
+In token mode (`session.basedToken`) the sweep sends its session as a Bearer token, the token-mode credential, and skips the CSRF layer: token-mode requests carry no ambient cookie, so the server does not enforce CSRF, and probing would only run mutating handlers.
+
 ## Sweep boundaries
 
 A route filter narrows the selection before any request is sent; filtered-out routes are never called. An authenticated sweep calls every selected route with its own session, logout-type routes included: a route that destroys the current session (logout, account deletion, session revoke) leaves every later layer running anonymously, so skip such routes explicitly.

package/docs/fuzz-tests.md

@@ -4,4 +4,4 @@ This slow layer deliberately sends malformed inputs to exercise error shaping an
 
 In an authenticated sweep, state-changing routes are reported as skipped so junk bodies cannot mutate the test database. Every sync route counts as state-changing, so an authenticated sweep does not fuzz sync routes at all; an anonymous sweep does. GET probes carry the junk payload in the query string like the real client (ADR 0062).
 
-A rejected unauthenticated request does not prove protected handler input was fuzzed; create authenticated, project-specific tests where necessary. Keep test traffic away from production and avoid payloads that trigger irreversible side effects. The fuzz source defines the actual probe catalogue; do not duplicate it as a static list here.
+A rate-limited reply means the payload never reached validation or the handler, so a route whose probes hit the limiter is reported as skipped, not passed; with a reset token the sweep clears rate limits before each route. A rejected unauthenticated request does not prove protected handler input was fuzzed; create authenticated, project-specific tests where necessary. Keep test traffic away from production and avoid payloads that trigger irreversible side effects. The fuzz source defines the actual probe catalogue; do not duplicate it as a static list here.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@luckystack/test-runner",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "private": false,
   "publishConfig": {
     "access": "public",
@@ -54,11 +54,11 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@luckystack/core": "^0.14.0"
+    "@luckystack/core": "^0.15.0"
   },
   "peerDependencies": {
-    "@luckystack/login": "^0.14.0",
-    "@luckystack/secret-manager": "^0.14.0",
+    "@luckystack/login": "^0.15.0",
+    "@luckystack/secret-manager": "^0.15.0",
     "socket.io-client": "^4.8.0",
     "zod": "^4.0.0"
   },