slicetest 0.5.0 → 0.6.0

package/dist/neon.js

@@ -0,0 +1,113 @@
+/**
+ * Neon's HTTP query endpoint, served from the test database, so apps on the Neon
+ * serverless driver (`neon()` from @neondatabase/serverless, drizzle-orm/neon-http,
+ * @vercel/postgres's `sql`) run against the local Postgres without a code change.
+ *
+ * The driver posts each query to `https://api.<domain>/sql` for a connection string
+ * at `<endpoint>.<domain>`; with `db.neon` the app gets such a string and the
+ * intercepting proxy hands that host to this server.
+ */
+import http from "node:http";
+import pg from "pg";
+/** The made-up domain of the connection string the app gets; `*.` of it is intercepted. */
+export const NEON_DOMAIN = "neon.slicetest";
+/** `url` (the real test database) with its host replaced by a Neon-style endpoint host. */
+export function neonUrl(url) {
+    const u = new URL(url);
+    u.hostname = `ep-slicetest.${NEON_DOMAIN}`;
+    u.port = "";
+    u.searchParams.set("sslmode", "require");
+    return u.toString();
+}
+// Values stay as Postgres's text: the driver parses them itself from each field's type.
+const RAW = { getTypeParser: () => (value) => value };
+const ERROR_FIELDS = ["severity", "code", "detail", "hint", "position", "internalPosition", "internalQuery", "where", "schema", "table", "column", "dataType", "constraint", "file", "line", "routine"];
+export class NeonEndpoint {
+    #server;
+    #pool;
+    constructor(databaseUrl) {
+        this.#pool = new pg.Pool({ connectionString: databaseUrl, max: 5, types: RAW });
+        this.#pool.on("error", () => { });
+        this.#server = http.createServer((req, res) => {
+            this.#handle(req, res).catch((e) => res.headersSent || res.writeHead(500).end(String(e)));
+        });
+    }
+    /** `databaseUrl` is where queries really run: the worker database, or the `db.queries` proxy in front of it. */
+    static async start(databaseUrl) {
+        const endpoint = new NeonEndpoint(databaseUrl);
+        await new Promise((resolve) => endpoint.#server.listen(0, "127.0.0.1", resolve));
+        return endpoint;
+    }
+    get port() {
+        return this.#server.address().port;
+    }
+    /** Serve a connection the intercepting proxy terminated. */
+    attach(socket) {
+        this.#server.emit("connection", socket);
+    }
+    async #handle(req, res) {
+        const send = (status, body) => res.writeHead(status, { "content-type": "application/json" }).end(JSON.stringify(body));
+        if (req.method !== "POST" || !req.url?.startsWith("/sql"))
+            return send(404, { message: `slicetest's Neon endpoint only answers POST /sql, not ${req.method} ${req.url}` });
+        let body;
+        try {
+            let raw = "";
+            for await (const chunk of req)
+                raw += chunk;
+            body = JSON.parse(raw);
+        }
+        catch {
+            return send(400, { message: "invalid JSON body" });
+        }
+        const arrayMode = req.headers["neon-array-mode"] === "true";
+        const client = await this.#pool.connect();
+        try {
+            if ("queries" in body) {
+                const level = req.headers["neon-batch-isolation-level"];
+                const readOnly = req.headers["neon-batch-read-only"] === "true";
+                const deferrable = req.headers["neon-batch-deferrable"] === "true";
+                const mode = [level && `ISOLATION LEVEL ${String(level).replace(/([a-z])([A-Z])/g, "$1 $2").toUpperCase()}`, readOnly && "READ ONLY", deferrable && "DEFERRABLE"].filter(Boolean);
+                await client.query(`BEGIN${mode.length ? ` ${mode.join(" ")}` : ""}`);
+                try {
+                    const results = [];
+                    for (const q of body.queries)
+                        results.push(await run(client, q, arrayMode));
+                    await client.query("COMMIT");
+                    return send(200, { results });
+                }
+                catch (e) {
+                    await client.query("ROLLBACK").catch(() => { });
+                    throw e;
+                }
+            }
+            return send(200, await run(client, body, arrayMode));
+        }
+        catch (e) {
+            // Shaped like Neon's: a message plus Postgres's error fields, which the driver copies onto its error.
+            const err = e;
+            return send(400, { message: err.message, ...Object.fromEntries(ERROR_FIELDS.filter((f) => err[f] !== undefined).map((f) => [f, err[f]])) });
+        }
+        finally {
+            client.release();
+        }
+    }
+    async close() {
+        this.#server.closeAllConnections();
+        await new Promise((resolve) => this.#server.close(resolve));
+        await this.#pool.end();
+    }
+}
+async function run(client, { query, params = [] }, arrayMode) {
+    const result = await client.query({ text: query, values: params, rowMode: "array" });
+    const fields = result.fields.map((f) => ({
+        name: f.name,
+        tableID: f.tableID,
+        columnID: f.columnID,
+        dataTypeID: f.dataTypeID,
+        dataTypeSize: f.dataTypeSize,
+        dataTypeModifier: f.dataTypeModifier,
+        format: "text",
+    }));
+    const rows = arrayMode ? result.rows : result.rows.map((r) => Object.fromEntries(fields.map((f, i) => [f.name, r[i]])));
+    return { command: result.command, rowCount: result.rowCount, rows, fields, rowAsArray: arrayMode };
+}

package/dist/openapi.d.ts

@@ -80,4 +80,6 @@ export declare function formatCoverage(spec: OpenApiSpec, hits: Set<string>): {
     markdown: string;
     text: string;
 };
+/** Where a spec fetched from the app (`openapi.fromApp`) is kept for the coverage report. */
+export declare function appSpecFile(coverageDir: string): string;
 export {};

package/dist/openapi.js

@@ -363,3 +363,7 @@ function nullableToType(node) {
     }
     return node;
 }
+/** Where a spec fetched from the app (`openapi.fromApp`) is kept for the coverage report. */
+export function appSpecFile(coverageDir) {
+    return `${coverageDir}.spec.json`;
+}

package/dist/runtime.d.ts

@@ -4,7 +4,9 @@ import type { ResolvedOptions } from "./config.js";
 import { Dependency } from "./containers.js";
 import { Db } from "./db.js";
 import { HttpClient } from "./http.js";
+import { Interceptor } from "./intercept.js";
 import { Mailbox } from "./mail.js";
+import { NeonEndpoint } from "./neon.js";
 import { QueryLog } from "./query-log.js";
 import { Stub } from "./stub.js";
 import { type MaskOptions, type Trace } from "./trace.js";
@@ -44,6 +46,8 @@ export declare class Runtime {
     readonly mailbox?: Mailbox | undefined;
     readonly issuer?: Issuer | undefined;
     readonly queryLog?: QueryLog | undefined;
+    readonly interceptor?: Interceptor | undefined;
+    readonly neon?: NeonEndpoint | undefined;
     private constructor();
     get http(): HttpClient;
     static start(opts: ResolvedOptions, shared: {
@@ -59,5 +63,13 @@ export declare class Runtime {
     afterScenario(): Promise<void>;
     /** What happened during the current scenario, printed when it fails. */
     diagnostics(): Promise<string>;
+    /** Hand the coverage and recordings gathered so far to the run (merged when it ends). */
+    flush(): Promise<void>;
     stop(): Promise<void>;
 }
+/**
+ * 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 declare function connectionVars(engine: string, url: string, sqlitePath?: string): Record<string, string>;
+export declare function blockedHint(hosts: string[]): string;

package/dist/runtime.js

@@ -1,14 +1,17 @@
 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";
@@ -29,12 +32,14 @@ export class Runtime {
     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, issuer, queryLog) {
+    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;
@@ -49,10 +54,14 @@ export class Runtime {
         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) => {
@@ -74,8 +83,8 @@ 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();
@@ -84,6 +93,8 @@ export class Runtime {
         let mailbox;
         let issuer;
         let queryLog;
+        let interceptor;
+        let neon;
         try {
             // Loaded first: a broken spec should fail before anything is started.
             const specs = {
@@ -104,31 +115,40 @@ 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 (opts.db.queries && 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")
+            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 });
+                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;
@@ -137,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);
@@ -144,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, issuer, queryLog);
+            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()));
@@ -154,6 +192,10 @@ export class Runtime {
             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;
         }
     }
@@ -223,6 +265,8 @@ export class Runtime {
         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())
@@ -232,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")}`);
@@ -301,15 +347,19 @@ export class Runtime {
             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}`);
@@ -323,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()),
@@ -341,6 +397,8 @@ export class Runtime {
             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)
@@ -381,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

@@ -47,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
@@ -85,6 +96,9 @@ 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

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()`.
@@ -21,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));

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,
                 },
             };

package/dist/x509.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Just enough X.509 to impersonate hosts in tests: a throwaway certificate
+ * authority, leaf certificates for the intercepted hosts, and the CA in the
+ * formats apps read it from (PEM bundle, and a PKCS#12 trust store for Java).
+ * DER is written by hand so the package needs no crypto dependency.
+ */
+import { KeyObject } from "node:crypto";
+export declare const seq: (...items: Buffer[]) => Buffer<ArrayBuffer>;
+interface Issued {
+    key: KeyObject;
+    der: Buffer;
+    pem: string;
+}
+/** A certificate authority that exists for one test run. */
+export declare class Authority {
+    #private;
+    readonly key: KeyObject;
+    readonly der: Buffer;
+    readonly pem: string;
+    constructor();
+    /** A certificate for `host`, signed by this authority (cached). */
+    leaf(host: string): Issued;
+}
+/** PEM bundle of `extra` plus the usual public roots, for SSL_CERT_FILE and friends (which replace the default store). */
+export declare function pemBundle(roots: readonly string[], extra: string): string;
+/**
+ * A PKCS#12 trust store of certificates, readable by Java without a password
+ * (`-Djavax.net.ssl.trustStoreType=PKCS12`, no `trustStorePassword`): no MAC and
+ * unencrypted certificate bags, each marked as a trusted certificate entry.
+ */
+export declare function pkcs12TrustStore(certs: {
+    alias: string;
+    der: Buffer;
+}[]): Buffer<ArrayBuffer>;
+/** DER of a PEM certificate, or undefined when it doesn't parse. */
+export declare function pemToDer(pem: string): Buffer<ArrayBuffer> | undefined;
+export {};