slicetest 0.4.0 → 0.6.0

package/dist/runtime.js

@@ -1,13 +1,18 @@
 import { randomUUID } from "node:crypto";
 import { writeFile } from "node:fs/promises";
+import os from "node:os";
 import path from "node:path";
 import { App } from "./app.js";
+import { Issuer } from "./auth.js";
 import { Dependency } from "./containers.js";
-import { Db, formatChanges } from "./db.js";
+import { Db, formatChanges, noDatabase } from "./db.js";
 import { engineFor } from "./drivers/index.js";
 import { formatHistory, HttpClient } from "./http.js";
+import { Interceptor } from "./intercept.js";
 import { Mailbox } from "./mail.js";
-import { OpenApiSpec } from "./openapi.js";
+import { NEON_DOMAIN, NeonEndpoint, neonUrl } from "./neon.js";
+import { appSpecFile, OpenApiSpec } from "./openapi.js";
+import { QueryLog } from "./query-log.js";
 import { Recorder } from "./recording.js";
 import { Stub } from "./stub.js";
 import { buildTrace, mask } from "./trace.js";
@@ -25,12 +30,16 @@ export class Runtime {
     recordDir;
     containers;
     mailbox;
+    issuer;
+    queryLog;
+    interceptor;
+    neon;
     #http;
     /** Responses from the app that don't match its OpenAPI spec, this scenario. */
     #contract = [];
     /** Documented responses seen in this file, for the run's coverage report. */
     #covered = new Set();
-    constructor(app, services, db, stubs, opts, vars, specs, coverageDir, recorders = new Map(), recordDir, containers = new Map(), mailbox) {
+    constructor(app, services, db, stubs, opts, vars, specs, coverageDir, recorders = new Map(), recordDir, containers = new Map(), mailbox, issuer, queryLog, interceptor, neon) {
         this.app = app;
         this.services = services;
         this.db = db;
@@ -43,10 +52,16 @@ export class Runtime {
         this.recordDir = recordDir;
         this.containers = containers;
         this.mailbox = mailbox;
+        this.issuer = issuer;
+        this.queryLog = queryLog;
+        this.interceptor = interceptor;
+        this.neon = neon;
         this.#http = this.#client();
     }
     #client() {
         const http = new HttpClient(this.app.url, this.opts.http);
+        for (const [host, name] of Object.entries(this.opts.intercept))
+            http.intercept(host, this.stubs.get(name).url);
         const spec = this.specs.app;
         if (spec) {
             http.onResponse((res) => {
@@ -68,14 +83,18 @@ export class Runtime {
         return this.#http;
     }
     static async start(opts, shared) {
-        const engine = await engineFor(opts);
-        const url = await ensureWorkerDatabase(engine, shared.adminUrl, shared.template, shared.prefix);
+        const engine = opts.db.none ? undefined : await engineFor(opts);
+        const url = engine ? await ensureWorkerDatabase(engine, shared.adminUrl, shared.template, shared.prefix) : "";
         const stubs = new Map();
         const recorders = new Map();
         const containers = new Map();
         const services = new Map();
         let db;
         let mailbox;
+        let issuer;
+        let queryLog;
+        let interceptor;
+        let neon;
         try {
             // Loaded first: a broken spec should fail before anything is started.
             const specs = {
@@ -96,22 +115,41 @@ export class Runtime {
                     continue;
                 stub.fallback(async (call) => (await recorder?.answer(call)) ?? spec?.exampleResponse(call.method, call.path), recorder?.hint());
             }
-            db = await Db.connect(await engine.driver(url), url, {
-                schemas: opts.db.schemas,
-                keep: opts.db.keep,
-                seedFile: opts.db.seed && path.resolve(opts.root, opts.db.seed),
-            });
+            db = engine
+                ? await Db.connect(await engine.driver(url), url, {
+                    schemas: opts.db.schemas,
+                    keep: opts.db.keep,
+                    seedFile: opts.db.seed && path.resolve(opts.root, opts.db.seed),
+                })
+                : noDatabase();
             const started = await Promise.allSettled(Object.entries(opts.containers).map(async ([name, c]) => containers.set(name, await Dependency.start(name, c))));
             const failed = started.find((r) => r.status === "rejected");
             if (failed)
                 throw failed.reason;
-            const vars = { "db.url": url };
-            if (engine.name === "sqlite")
+            const vars = engine ? { "db.url": url } : {};
+            if (engine && opts.db.queries && engine.name !== "sqlite") {
+                const u = new URL(url);
+                queryLog = await QueryLog.start(engine.name, { host: u.hostname, port: Number(u.port || (engine.name === "mysql" ? 3306 : 5432)) });
+                vars["db.url"] = queryLog.proxyUrl(url);
+                db.attachQueryLog(queryLog);
+            }
+            if (engine?.name === "sqlite")
                 vars["db.path"] = (await import("./drivers/sqlite.js")).sqlitePath(url);
+            if (engine)
+                Object.assign(vars, connectionVars(engine.name, vars["db.url"], vars["db.path"]));
+            if (opts.db.neon) {
+                // Queries the app sends to Neon's HTTP API run on the worker database (through the db.queries proxy, if on).
+                neon = await NeonEndpoint.start(vars["db.url"]);
+                vars["db.url"] = neonUrl(url);
+            }
             if (opts.mail) {
                 mailbox = await Mailbox.start();
                 Object.assign(vars, { "mail.host": mailbox.host, "mail.port": String(mailbox.port), "mail.url": mailbox.url });
             }
+            if (opts.auth) {
+                issuer = await Issuer.start(opts.auth);
+                Object.assign(vars, { "auth.issuer": issuer.url, "auth.jwks": issuer.jwksUrl, "auth.audience": issuer.audience, "auth.publicKey": issuer.publicKeyPem });
+            }
             for (const [name, c] of containers) {
                 vars[`container.${name}`] = c.address;
                 vars[`container.${name}.host`] = c.host;
@@ -119,6 +157,22 @@ export class Runtime {
             }
             for (const [name, stub] of stubs)
                 vars[`stub.${name}`] = stub.url;
+            if (Object.keys(opts.intercept).length > 0 || opts.offline || neon) {
+                const routes = new Map(Object.entries(opts.intercept).map(([host, name]) => {
+                    const stub = stubs.get(name);
+                    return [host, { attach: (s) => stub.attach(s), port: stub.port }];
+                }));
+                if (neon) {
+                    const endpoint = neon;
+                    routes.set(`*.${NEON_DOMAIN}`, { attach: (s) => endpoint.attach(s), port: endpoint.port });
+                }
+                interceptor = await Interceptor.start(routes);
+                interceptor.offline = opts.offline;
+                Object.assign(vars, { "proxy.url": interceptor.url, "proxy.ca": interceptor.files.ca, "proxy.bundle": interceptor.files.bundle, "proxy.truststore": interceptor.files.trustStore });
+                // Every process gets the proxy settings; a key in its own `env` still wins.
+                const baseEnv = interceptor.env();
+                opts = { ...opts, app: { ...opts.app, baseEnv }, services: Object.fromEntries(Object.entries(opts.services).map(([n, s]) => [n, { ...s, baseEnv }])) };
+            }
             for (const [name, service] of Object.entries(opts.services)) {
                 const started = await App.start(service, opts.root, vars, `service.${name}`);
                 services.set(name, started);
@@ -126,7 +180,9 @@ export class Runtime {
                 vars[`service.${name}.port`] = String(started.port);
             }
             const app = await App.start(opts.app, opts.root, vars);
-            return new Runtime(app, services, db, stubs, opts, vars, specs, shared.coverageDir, recorders, shared.recordDir, containers, mailbox);
+            if (opts.openapi.fromApp)
+                specs.app = await fetchAppSpec(app.url, opts.openapi.fromApp, shared.coverageDir);
+            return new Runtime(app, services, db, stubs, opts, vars, specs, shared.coverageDir, recorders, shared.recordDir, containers, mailbox, issuer, queryLog, interceptor, neon);
         }
         catch (e) {
             await Promise.all([...services.values()].map((s) => s.stop()));
@@ -134,11 +190,18 @@ export class Runtime {
             await Promise.all([...stubs.values()].map((s) => s.close()));
             await Promise.allSettled([...containers.values()].map((c) => c.stop()));
             await mailbox?.close();
+            await issuer?.close();
+            await queryLog?.close();
+            if (interceptor?.blocked.size && e instanceof Error)
+                e.message += `\n${blockedHint([...interceptor.blocked])}`;
+            await interceptor?.close();
+            await neon?.close();
             throw e;
         }
     }
     context() {
         const mailbox = this.mailbox;
+        const issuer = this.issuer;
         return {
             http: this.http,
             db: this.db,
@@ -169,6 +232,11 @@ export class Runtime {
                     throw new Error("slicetest: mail is off. Add `mail: true` to the config and point the app's SMTP settings at {{mail.host}} / {{mail.port}}.");
                 return mailbox;
             },
+            get auth() {
+                if (!issuer)
+                    throw new Error("slicetest: auth is off. Add `auth: true` to the config and point the app's JWT settings at {{auth.issuer}} / {{auth.jwks}}.");
+                return issuer;
+            },
         };
     }
     /** The app and every service, for checks that apply to all of them. */
@@ -195,6 +263,10 @@ export class Runtime {
         for (const recorder of this.recorders.values())
             recorder.reset();
         this.mailbox?.reset();
+        this.issuer?.reset();
+        this.queryLog?.reset();
+        this.interceptor?.passedThrough.clear();
+        this.interceptor?.blocked.clear();
         await Promise.all([...this.containers.values()].map((c) => c.reset()));
         this.http.reset();
         for (const p of this.#processes())
@@ -204,6 +276,8 @@ export class Runtime {
     async afterScenario() {
         await Promise.all(this.#processes().map((p) => p.settle()));
         this.#assertAlive();
+        if (this.interceptor?.blocked.size)
+            throw new Error(blockedHint([...this.interceptor.blocked]));
         const unmatched = this.#unmatched();
         if (unmatched.length > 0) {
             throw new Error(`slicetest: the app called stubbed services with no matching route:\n${unmatched.join("\n")}`);
@@ -265,20 +339,32 @@ export class Runtime {
         const unmatched = this.#unmatched();
         if (unmatched.length > 0)
             sections.push(`stub calls with no matching route:\n${unmatched.join("\n")}`);
+        const chaos = [...this.stubs.values()].map((s) => s.describeChaos()).filter((c) => c !== undefined);
+        if (chaos.length > 0)
+            sections.push(chaos.join("\n"));
         const contract = this.#contractViolations();
         if (contract.length > 0)
             sections.push(`OpenAPI mismatches:\n${contract.map((c) => `  ${c}`).join("\n")}`);
         if (this.http.history.length > 0)
             sections.push(`requests to the app:\n${formatHistory(this.http.history)}`);
-        try {
-            const changes = formatChanges(await this.db.changesSinceStart());
-            sections.push(changes ? `database changes during this scenario:\n${changes}` : "database changes during this scenario: (none)");
-        }
-        catch (e) {
-            sections.push(`database changes during this scenario: unavailable (${e.message})`);
-        }
+        if (!this.opts.db.none)
+            try {
+                const changes = formatChanges(await this.db.changesSinceStart());
+                sections.push(changes ? `database changes during this scenario:\n${changes}` : "database changes during this scenario: (none)");
+            }
+            catch (e) {
+                sections.push(`database changes during this scenario: unavailable (${e.message})`);
+            }
         if (this.mailbox)
             sections.push(this.mailbox.describe());
+        if (this.interceptor?.passedThrough.size) {
+            sections.push(`outbound calls to hosts no stub intercepts (sent to the real host; add them to a stub's \`hosts\` to answer them):\n${[...this.interceptor.passedThrough].map((h) => `  ${h}`).join("\n")}`);
+        }
+        if (this.queryLog) {
+            const q = this.queryLog.queries();
+            const top = q.shapes().slice(0, 5).map((s) => `  ${s.count > 1 ? `×${s.count} ` : ""}${s.sql.length > 160 ? `${s.sql.slice(0, 157)}...` : s.sql}`);
+            sections.push(q.length ? `SQL the app ran during this scenario (${q.length} statements, most frequent first):\n${top.join("\n")}` : "SQL the app ran during this scenario: (none)");
+        }
         const logs = this.app.scenarioLogs();
         sections.push(logs ? `app output during this scenario:\n${logs}` : "app output during this scenario: (none)");
         for (const [name, service] of this.services) {
@@ -287,15 +373,21 @@ export class Runtime {
         }
         return sections.join("\n\n");
     }
-    async stop() {
+    /** Hand the coverage and recordings gathered so far to the run (merged when it ends). */
+    async flush() {
         if (this.coverageDir && this.#covered.size > 0) {
             await writeFile(path.join(this.coverageDir, `${process.pid}-${randomUUID()}.json`), JSON.stringify([...this.#covered])).catch(() => { });
+            this.#covered.clear();
         }
         for (const [name, recorder] of this.recorders) {
-            if (this.recordDir && recorder.added().length > 0) {
-                await writeFile(path.join(this.recordDir, `${name}.${process.pid}-${randomUUID()}.json`), JSON.stringify(recorder.added())).catch(() => { });
+            const added = recorder.added().splice(0);
+            if (this.recordDir && added.length > 0) {
+                await writeFile(path.join(this.recordDir, `${name}.${process.pid}-${randomUUID()}.json`), JSON.stringify(added)).catch(() => { });
             }
         }
+    }
+    async stop() {
+        await this.flush();
         const results = await Promise.allSettled([
             this.app.stop(),
             ...[...this.services.values()].map((s) => s.stop()),
@@ -303,6 +395,10 @@ export class Runtime {
             ...[...this.stubs.values()].map((s) => s.close()),
             ...[...this.containers.values()].map((c) => c.stop()),
             this.mailbox?.close(),
+            this.issuer?.close(),
+            this.queryLog?.close(),
+            this.interceptor?.close(),
+            this.neon?.close(),
         ]);
         const failed = results.find((r) => r.status === "rejected");
         if (failed)
@@ -343,3 +439,47 @@ function parseJson(text) {
         return undefined;
     }
 }
+/**
+ * The parts of the database URL, for apps that don't take one URL: JDBC (Spring's
+ * `spring.datasource.url` plus username / password), or separate host / port / name settings.
+ */
+export function connectionVars(engine, url, sqlitePath) {
+    if (engine === "sqlite")
+        return { "db.jdbcUrl": `jdbc:sqlite:${sqlitePath}` };
+    const u = new URL(url);
+    const port = u.port || (engine === "mysql" ? "3306" : "5432");
+    const name = decodeURIComponent(u.pathname.replace(/^\//, ""));
+    return {
+        "db.host": u.hostname,
+        "db.port": port,
+        "db.name": name,
+        "db.user": decodeURIComponent(u.username),
+        "db.password": decodeURIComponent(u.password),
+        "db.jdbcUrl": `jdbc:${engine === "mysql" ? "mysql" : "postgresql"}://${u.hostname}:${port}/${encodeURIComponent(name)}`,
+    };
+}
+/** The app's own spec, served at `route` (springdoc's /v3/api-docs, FastAPI's /openapi.json, …). */
+async function fetchAppSpec(appUrl, route, coverageDir) {
+    let text;
+    try {
+        const res = await fetch(new URL(route, appUrl));
+        if (!res.ok)
+            throw new Error(`it answered ${res.status}`);
+        text = await res.text();
+    }
+    catch (e) {
+        throw new Error(`slicetest: openapi.fromApp: couldn't get the spec from GET ${route}: ${e.message}`);
+    }
+    const file = coverageDir ? appSpecFile(coverageDir) : path.join(os.tmpdir(), `slicetest-spec-${process.pid}.json`);
+    await writeFile(file, text);
+    return OpenApiSpec.load(file, `GET ${route}`);
+}
+/** Hosts package managers download from: a build tool fetching dependencies while it starts the app. */
+const REGISTRIES = /(^|\.)(maven\.apache\.org|repo1\.maven\.org|plugins\.gradle\.org|services\.gradle\.org|registry\.npmjs\.org|registry\.yarnpkg\.com|proxy\.golang\.org|sum\.golang\.org|pypi\.org|files\.pythonhosted\.org|crates\.io|rubygems\.org)$/;
+export function blockedHint(hosts) {
+    const message = `slicetest: offline: the app tried to reach ${hosts.join(", ")}, which no stub answers. Add ${hosts.length > 1 ? "them" : "it"} to a stub's \`hosts\` (or remove \`offline\`).`;
+    const registries = hosts.filter((h) => REGISTRIES.test(h));
+    if (registries.length === 0)
+        return message;
+    return `${message}\n${registries.join(", ")} ${registries.length > 1 ? "are package registries" : "is a package registry"}: the command that starts the app (gradle bootRun, mvn spring-boot:run, go run, …) is downloading dependencies, through slicetest's proxy. Download them in \`app.build\` (./gradlew bootJar, mvn package), or start a built artifact (java -jar).`;
+}

package/dist/setup-file.js

@@ -4,11 +4,28 @@ import { Runtime } from "./runtime.js";
 import "./provided.js";
 import "./matchers.js";
 let runtime;
+// With app.scope "worker" the runtime outlives the file: Vitest runs this worker's next
+// files in the same module state (isolate: false), and the processes go when it exits.
+const shared = globalThis;
 beforeAll(async () => {
-    runtime = await Runtime.start(inject("slicetestOptions"), inject("slicetestDb"));
+    const options = inject("slicetestOptions");
+    if (options.app.scope === "worker") {
+        const starting = (shared.__slicetestRuntime ??= Runtime.start(options, inject("slicetestDb")));
+        starting.catch(() => {
+            if (shared.__slicetestRuntime === starting)
+                shared.__slicetestRuntime = undefined;
+        });
+        runtime = await starting;
+    }
+    else {
+        runtime = await Runtime.start(options, inject("slicetestDb"));
+    }
     setRuntime(runtime);
 });
 afterAll(async () => {
     setRuntime(undefined);
-    await runtime?.stop();
+    if (inject("slicetestOptions").app.scope === "worker")
+        await runtime?.flush();
+    else
+        await runtime?.stop();
 });

package/dist/stub.d.ts

@@ -19,6 +19,27 @@ export interface RecordedCall {
     };
     /** Answered by the fallback (e.g. an example from the provider's OpenAPI spec), not a registered route. */
     fallback?: boolean;
+    /** The fault `chaos()` injected instead of the normal answer: `503`, `reset`. */
+    fault?: string;
+}
+/**
+ * Faults injected into a stub's answers, to test the app's retries, timeouts and
+ * fallbacks. Random faults come from a seeded generator, so a failing run can be
+ * replayed with the seed printed in the failure output.
+ */
+export interface ChaosOptions {
+    /** Fail the first `n` calls, then answer normally: the shape of a retry test. */
+    failFirst?: number;
+    /** Share of calls (0–1) answered with one of `statuses`. */
+    errorRate?: number;
+    /** Error statuses to pick from. Default [500, 502, 503]; 429 and 503 come with `Retry-After: 1`. */
+    statuses?: number[];
+    /** Share of calls (0–1) whose connection is dropped without an answer. */
+    networkErrorRate?: number;
+    /** Extra delay for every call, in ms: a fixed value or a [min, max] range. */
+    latency?: number | [number, number];
+    /** Seed for the random choices. Default: `SLICETEST_CHAOS_SEED`, else random. */
+    seed?: number;
 }
 export interface StubResponse {
     status?: number;
@@ -26,6 +47,17 @@ export interface StubResponse {
     /** Objects are sent as JSON. */
     body?: unknown;
 }
+/** One server-sent event: `[event, data]`, or `{ event, data, id }`. Data that isn't a string is sent as JSON. */
+export type ServerSentEvent = [event: string, data: unknown] | {
+    event?: string;
+    data: unknown;
+    id?: string;
+};
+/**
+ * A streaming reply in Server-Sent Events format, as LLM APIs stream (Anthropic, OpenAI):
+ * `stub("anthropic").on("POST", "/v1/messages").reply(sse([["message_start", {...}], ...]))`.
+ */
+export declare function sse(events: ServerSentEvent[], init?: Omit<StubResponse, "body">): StubResponse;
 export type Responder = StubResponse | ((call: RecordedCall) => StubResponse | Promise<StubResponse>);
 /**
  * Extra conditions a call must meet for a route to answer it. Plain values are
@@ -64,12 +96,26 @@ export declare class Stub {
     readonly name: string;
     url: string;
     private constructor();
+    /** Serve a connection that arrived elsewhere, e.g. TLS the intercepting proxy terminated. */
+    attach(socket: import("node:net").Socket): void;
+    get port(): number;
     static start(name: string): Promise<Stub>;
     /**
      * Answer `method path`. `path` may contain `:name` segments (captured into
      * `call.params`) or be a RegExp; `method` may be `*`. Later routes win.
      */
     on(method: string, path: string | RegExp, match?: MatchOptions): RouteBuilder;
+    /**
+     * Inject faults into this stub's answers for the rest of the scenario:
+     * `stub("payments").chaos({ failFirst: 2 })` to test a retry,
+     * `chaos({ errorRate: 0.3, latency: [50, 200] })` to test resilience.
+     * Calls that fault don't use up `once()` / `times()` routes.
+     */
+    chaos(opts: ChaosOptions): this;
+    /** Calls `chaos()` answered with a fault. */
+    faults(): RecordedCall[];
+    /** The active `chaos()` settings and what they did, for failure output; undefined when off. */
+    describeChaos(): string | undefined;
     /** Calls received so far, optionally filtered by method, path and conditions (same syntax as `on()`). */
     calls(method?: string, path?: string | RegExp, match?: MatchOptions): RecordedCall[];
     unmatched(): RecordedCall[];

package/dist/stub.js

@@ -1,5 +1,20 @@
 import http from "node:http";
 import { isDeepStrictEqual } from "node:util";
+/**
+ * A streaming reply in Server-Sent Events format, as LLM APIs stream (Anthropic, OpenAI):
+ * `stub("anthropic").on("POST", "/v1/messages").reply(sse([["message_start", {...}], ...]))`.
+ */
+export function sse(events, init = {}) {
+    const body = events
+        .map((e) => {
+        const { event, data, id } = Array.isArray(e) ? { event: e[0], data: e[1], id: undefined } : e;
+        const text = typeof data === "string" ? data : JSON.stringify(data);
+        const lines = [...(id !== undefined ? [`id: ${id}`] : []), ...(event ? [`event: ${event}`] : []), ...text.split("\n").map((l) => `data: ${l}`)];
+        return `${lines.join("\n")}\n\n`;
+    })
+        .join("");
+    return { status: init.status ?? 200, headers: { "content-type": "text/event-stream", "cache-control": "no-cache", ...init.headers }, body };
+}
 /**
  * A fake outbound service. The app is pointed at `url`; tests register routes
  * with `on()` and inspect what the app sent with `calls()`.
@@ -12,6 +27,7 @@ export class Stub {
     #fallback;
     /** Appended to the 501 answer for a call nothing could answer. */
     #hint;
+    #chaos;
     url = "";
     constructor(name) {
         this.name = name;
@@ -20,6 +36,13 @@ export class Stub {
             this.#handle(req, res).catch(() => res.destroy());
         });
     }
+    /** Serve a connection that arrived elsewhere, e.g. TLS the intercepting proxy terminated. */
+    attach(socket) {
+        this.#server.emit("connection", socket);
+    }
+    get port() {
+        return Number(new URL(this.url).port);
+    }
     static async start(name) {
         const stub = new Stub(name);
         await new Promise((resolve) => stub.#server.listen(0, "127.0.0.1", resolve));
@@ -61,6 +84,74 @@ export class Stub {
         };
         return builder;
     }
+    /**
+     * Inject faults into this stub's answers for the rest of the scenario:
+     * `stub("payments").chaos({ failFirst: 2 })` to test a retry,
+     * `chaos({ errorRate: 0.3, latency: [50, 200] })` to test resilience.
+     * Calls that fault don't use up `once()` / `times()` routes.
+     */
+    chaos(opts) {
+        for (const key of ["errorRate", "networkErrorRate"]) {
+            const v = opts[key];
+            if (v !== undefined && !(v >= 0 && v <= 1))
+                throw new Error(`slicetest: chaos ${key} must be between 0 and 1, got ${v}`);
+        }
+        if (opts.statuses && (opts.statuses.length === 0 || opts.statuses.some((s) => !Number.isInteger(s) || s < 400 || s > 599))) {
+            throw new Error(`slicetest: chaos statuses must be 4xx/5xx codes, got ${JSON.stringify(opts.statuses)}`);
+        }
+        const envSeed = Number(process.env.SLICETEST_CHAOS_SEED);
+        const seed = opts.seed ?? (Number.isInteger(envSeed) ? envSeed : Math.floor(Math.random() * 2 ** 31));
+        this.#chaos = { opts, seed, random: mulberry32(seed), calls: 0 };
+        return this;
+    }
+    /** Calls `chaos()` answered with a fault. */
+    faults() {
+        return this.#calls.filter((c) => c.fault !== undefined);
+    }
+    /** The active `chaos()` settings and what they did, for failure output; undefined when off. */
+    describeChaos() {
+        const c = this.#chaos;
+        if (!c)
+            return undefined;
+        const settings = Object.entries(c.opts)
+            .filter(([k]) => k !== "seed")
+            .map(([k, v]) => `${k} ${JSON.stringify(v)}`)
+            .join(", ");
+        return `chaos on ${this.name}: ${settings}; ${this.faults().length} of ${c.calls} calls faulted. Replay with SLICETEST_CHAOS_SEED=${c.seed}`;
+    }
+    /** Delay and fault for the next call, consuming the random sequence in a fixed order. */
+    async #injectFault() {
+        const c = this.#chaos;
+        if (!c)
+            return undefined;
+        const { opts, random } = c;
+        const n = ++c.calls;
+        const lat = opts.latency;
+        const ms = lat === undefined ? 0 : Array.isArray(lat) ? lat[0] + Math.floor(random() * (lat[1] - lat[0] + 1)) : lat;
+        if (ms > 0)
+            await new Promise((r) => setTimeout(r, ms));
+        const statuses = opts.statuses ?? [500, 502, 503];
+        const pick = () => statuses[Math.floor(random() * statuses.length)];
+        if (opts.failFirst !== undefined && n <= opts.failFirst)
+            return { status: pick() };
+        const roll = random();
+        if (roll < (opts.networkErrorRate ?? 0))
+            return "reset";
+        if (roll < (opts.networkErrorRate ?? 0) + (opts.errorRate ?? 0))
+            return { status: pick() };
+        return undefined;
+    }
+    #fail(call, req, res, fault) {
+        call.matched = true;
+        if (fault === "reset") {
+            call.fault = "reset";
+            req.socket.destroy();
+            return;
+        }
+        call.fault = String(fault.status);
+        const retry = fault.status === 429 || fault.status === 503 ? { "retry-after": "1" } : undefined;
+        this.#send(call, res, { status: fault.status, headers: retry, body: { error: "slicetest chaos", status: fault.status } });
+    }
     /** Calls received so far, optionally filtered by method, path and conditions (same syntax as `on()`). */
     calls(method, path, match = {}) {
         const compiled = path === undefined ? undefined : compilePath(path);
@@ -82,6 +173,7 @@ export class Stub {
     reset() {
         this.#routes = [];
         this.#calls = [];
+        this.#chaos = undefined;
     }
     /**
      * Answer calls that no registered route matches, instead of failing with 501.
@@ -127,6 +219,12 @@ export class Stub {
             route = r;
             break;
         }
+        // Faults only replace answers the stub would give: an unknown route still fails as unmatched.
+        if (route || this.#fallback) {
+            const fault = await this.#injectFault();
+            if (fault)
+                return this.#fail(call, req, res, fault);
+        }
         if (!route) {
             let out;
             try {
@@ -262,3 +360,14 @@ function parseJson(body) {
         return undefined;
     }
 }
+/** A small seeded PRNG: the same seed gives the same faults on every run. */
+function mulberry32(seed) {
+    let a = seed >>> 0;
+    return () => {
+        a = (a + 0x6d2b79f5) >>> 0;
+        let t = a;
+        t = Math.imul(t ^ (t >>> 15), t | 1);
+        t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+}

package/dist/vitest.d.ts

@@ -1,6 +1,16 @@
 import type { Plugin } from "vite";
 import { type SlicetestOptions } from "./config.js";
+/**
+ * Reads a slicetest.config.yaml, so the CLI and a vitest.config share one file.
+ * `file` is relative to `root`; without it the first of CONFIG_NAMES in `root` is used.
+ * The CLI-only `include` is dropped.
+ */
+export declare function loadConfigFile(root: string, file?: string): SlicetestOptions;
 /** YAML scenario files are picked up next to the regular test files. */
 export declare const YAML_SCENARIOS = "**/*.scenario.{yaml,yml}";
-export declare function slicetest(options: SlicetestOptions): Plugin;
+/**
+ * The Vitest plugin. Pass the options, or the path of a slicetest.config.yaml (relative to the
+ * Vitest root), or nothing to read the slicetest.config.yaml next to the Vitest config.
+ */
+export declare function slicetest(options?: SlicetestOptions | string): Plugin;
 export type { SlicetestOptions } from "./config.js";

package/dist/vitest.js

@@ -1,15 +1,34 @@
+import { existsSync, readFileSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { configDefaults } from "vitest/config";
-import { resolveOptions } from "./config.js";
+import { CONFIG_NAMES, resolveOptions } from "./config.js";
 import { SESSION_ENV } from "./record.js";
+import { parse } from "yaml";
 import { parseScenarioFile } from "./yaml.js";
+/**
+ * Reads a slicetest.config.yaml, so the CLI and a vitest.config share one file.
+ * `file` is relative to `root`; without it the first of CONFIG_NAMES in `root` is used.
+ * The CLI-only `include` is dropped.
+ */
+export function loadConfigFile(root, file) {
+    const found = file ? path.resolve(root, file) : CONFIG_NAMES.map((n) => path.join(root, n)).find((p) => existsSync(p));
+    if (!found || !existsSync(found)) {
+        throw new Error(`slicetest: ${file ? `config file ${found} not found` : `no ${CONFIG_NAMES.join(" / ")} in ${root}; pass the options to slicetest({ ... }) or run "npx slicetest init"`}`);
+    }
+    const { include: _, ...options } = (parse(readFileSync(found, "utf8")) ?? {});
+    return options;
+}
 /** YAML scenario files are picked up next to the regular test files. */
 export const YAML_SCENARIOS = "**/*.scenario.{yaml,yml}";
 const YAML_ID = /\.scenario\.ya?ml$/;
 const here = path.dirname(fileURLToPath(import.meta.url));
 // Resolve sibling modules with this file's own extension, so it works from both src (.ts) and dist (.js).
 const ext = path.extname(fileURLToPath(import.meta.url));
+/**
+ * The Vitest plugin. Pass the options, or the path of a slicetest.config.yaml (relative to the
+ * Vitest root), or nothing to read the slicetest.config.yaml next to the Vitest config.
+ */
 export function slicetest(options) {
     let root;
     return {
@@ -21,11 +40,17 @@ export function slicetest(options) {
             // `slicetest record` runs only its session file.
             if (!process.env[SESSION_ENV])
                 test.include = [...(test.include ?? configDefaults.include), YAML_SCENARIOS];
+            const resolved = resolveOptions(typeof options === "object" ? options : loadConfigFile(root, options), root);
             return {
                 test: {
+                    // One app per worker means module state (the running app) must survive from file to file.
+                    ...(resolved.app.scope === "worker" ? { isolate: false } : {}),
+                    // Vitest runs projects with different maxWorkers in separate groups and wants a distinct
+                    // groupOrder for each; one per worker count keeps slicetest projects out of each other's way.
+                    ...(resolved.workers ? { maxWorkers: resolved.workers, sequence: { groupOrder: 1000 + resolved.workers } } : {}),
                     globalSetup: [path.join(here, `global-setup${ext}`)],
                     setupFiles: [path.join(here, `setup-file${ext}`)],
-                    provide: { slicetestOptions: resolveOptions(options, root) },
+                    provide: { slicetestOptions: resolved },
                     hookTimeout: 120_000,
                 },
             };