slicetest 0.1.0

package/dist/http.js

@@ -0,0 +1,158 @@
+/** Per-scenario state shared by a client and every client derived from it with `with()`. */
+class Session {
+    cookies = new Map();
+    history = [];
+}
+const HISTORY = 20;
+/** HTTP client bound to the app under test. Keeps cookies for the duration of a scenario. */
+export class HttpClient {
+    baseUrl;
+    defaults;
+    #session;
+    constructor(baseUrl, defaults = {}, session = new Session()) {
+        this.baseUrl = baseUrl;
+        this.defaults = defaults;
+        this.#session = session;
+    }
+    /** A client that adds `opts` (e.g. an auth header) to every request, sharing this one's cookies. */
+    with(opts) {
+        return new HttpClient(this.baseUrl, merge(this.defaults, opts), this.#session);
+    }
+    /** Wrap fields to be sent as `application/x-www-form-urlencoded`. */
+    form(fields) {
+        return new URLSearchParams(Object.entries(fields).map(([k, v]) => [k, String(v)]));
+    }
+    get(path, opts) {
+        return this.request("GET", path, undefined, opts);
+    }
+    head(path, opts) {
+        return this.request("HEAD", path, undefined, opts);
+    }
+    delete(path, opts) {
+        return this.request("DELETE", path, undefined, opts);
+    }
+    post(path, body, opts) {
+        return this.request("POST", path, body, opts);
+    }
+    put(path, body, opts) {
+        return this.request("PUT", path, body, opts);
+    }
+    patch(path, body, opts) {
+        return this.request("PATCH", path, body, opts);
+    }
+    /** Strings, URLSearchParams, FormData, Blob and byte arrays are sent as-is; anything else is sent as JSON. */
+    async request(method, path, body, options = {}) {
+        const opts = merge(this.defaults, options);
+        const url = new URL(path, this.baseUrl);
+        if (url.origin !== new URL(this.baseUrl).origin) {
+            throw new Error(`slicetest: http only talks to the app under test; "${path}" resolves to ${url.origin}`);
+        }
+        for (const [k, v] of Object.entries(opts.query ?? {}))
+            if (v !== undefined)
+                url.searchParams.set(k, String(v));
+        const headers = new Headers(opts.headers);
+        if (this.#session.cookies.size > 0 && !headers.has("cookie")) {
+            headers.set("cookie", [...this.#session.cookies].map(([k, v]) => `${k}=${v}`).join("; "));
+        }
+        let payload;
+        if (body === undefined ||
+            typeof body === "string" ||
+            body instanceof URLSearchParams ||
+            body instanceof FormData ||
+            body instanceof Blob ||
+            body instanceof Uint8Array) {
+            payload = body;
+        }
+        else {
+            payload = JSON.stringify(body);
+            if (!headers.has("content-type"))
+                headers.set("content-type", "application/json");
+        }
+        const started = performance.now();
+        let res;
+        try {
+            res = await fetch(url, { method, headers, body: payload, redirect: opts.follow ? "follow" : "manual" });
+        }
+        catch (e) {
+            const cause = e.cause?.code;
+            this.#record({ method, url: url.pathname + url.search, status: 0, headers: new Headers(), text: `${e}${cause ? ` (${cause})` : ""}`, json: undefined, durationMs: Math.round(performance.now() - started) });
+            throw e;
+        }
+        for (const cookie of res.headers.getSetCookie())
+            this.#storeCookie(cookie);
+        const text = await res.text();
+        let json;
+        try {
+            json = text ? JSON.parse(text) : undefined;
+        }
+        catch { }
+        const out = {
+            method,
+            url: url.pathname + url.search,
+            status: res.status,
+            headers: res.headers,
+            text,
+            json,
+            durationMs: Math.round(performance.now() - started),
+        };
+        this.#record(out);
+        return out;
+    }
+    #record(res) {
+        this.#session.history.push(res);
+        if (this.#session.history.length > HISTORY)
+            this.#session.history.shift();
+    }
+    /** Cookies the app has set during this scenario. Mutations are sent with later requests. */
+    get cookies() {
+        return this.#session.cookies;
+    }
+    clearCookies() {
+        this.#session.cookies.clear();
+    }
+    /** Requests made during the current scenario, oldest first (last 20). */
+    get history() {
+        return this.#session.history;
+    }
+    /** Start a new scenario: forget cookies and history. */
+    reset() {
+        this.#session.cookies.clear();
+        this.#session.history = [];
+    }
+    #storeCookie(header) {
+        const [pair, ...attrs] = header.split(";");
+        const eq = pair.indexOf("=");
+        if (eq <= 0)
+            return;
+        const name = pair.slice(0, eq).trim();
+        const expired = attrs.some((a) => {
+            const [k, v = ""] = a.split("=").map((s) => s.trim());
+            if (k.toLowerCase() === "max-age")
+                return Number(v) <= 0;
+            if (k.toLowerCase() === "expires")
+                return Date.parse(v) <= Date.now();
+            return false;
+        });
+        if (expired)
+            this.#session.cookies.delete(name);
+        else
+            this.#session.cookies.set(name, pair.slice(eq + 1).trim());
+    }
+}
+function merge(a, b) {
+    return {
+        ...a,
+        ...b,
+        headers: { ...a.headers, ...b.headers },
+        query: { ...a.query, ...b.query },
+    };
+}
+/** One line per request, for failure output. */
+export function formatHistory(history) {
+    return history
+        .map((r) => {
+        const snippet = r.text.length > 120 ? `${r.text.slice(0, 120)}…` : r.text;
+        return `  ${r.method} ${r.url} → ${r.status || "failed"} (${r.durationMs}ms)${snippet ? `  ${snippet.replace(/\s+/g, " ")}` : ""}`;
+    })
+        .join("\n");
+}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { scenario } from "./scenario.js";
+export type { ScenarioContext } from "./runtime.js";
+export type { Db, Row, Where, RowsOptions } from "./db.js";
+export type { Stub, RecordedCall, StubResponse, Responder, MatchOptions, RouteBuilder } from "./stub.js";
+export type { HttpClient, HttpResponse, RequestOptions } from "./http.js";
+export type { App } from "./app.js";
+export type { SlicetestOptions } from "./config.js";

package/dist/index.js

@@ -0,0 +1 @@
+export { scenario } from "./scenario.js";

package/dist/matchers.d.ts

@@ -0,0 +1,17 @@
+import { type Where } from "./db.js";
+import { type MatchOptions } from "./stub.js";
+interface SlicetestMatchers<R = unknown> {
+    /** The stub received at least one call matching `method path` (and `match`, if given). */
+    toHaveReceived(method: string, path: string | RegExp, match?: MatchOptions): R;
+    /** The stub received exactly `n` calls matching `method path`. */
+    toHaveReceivedTimes(n: number, method?: string, path?: string | RegExp, match?: MatchOptions): R;
+    /** The response has this status; the failure message shows the response body. */
+    toHaveStatus(status: number): R;
+    /** Async: the table has at least one row matching `where` (`count` for an exact number). */
+    toHaveRow(table: string, where?: Where, count?: number): Promise<void>;
+}
+declare module "vitest" {
+    interface Matchers<R extends void | Promise<void> = void | Promise<void>, T = unknown> extends SlicetestMatchers<R> {
+    }
+}
+export {};

package/dist/matchers.js

@@ -0,0 +1,69 @@
+import { expect } from "vitest";
+import { Db } from "./db.js";
+import { Stub } from "./stub.js";
+const MAX_SHOWN = 5;
+function describeCalls(calls) {
+    if (calls.length === 0)
+        return "  (no calls)";
+    const shown = calls.slice(-MAX_SHOWN).map((c) => {
+        const q = c.query.size ? `?${c.query}` : "";
+        const body = c.body ? `  ${c.body.length > 200 ? `${c.body.slice(0, 200)}…` : c.body}` : "";
+        return `  ${c.method} ${c.path}${q}${body}`;
+    });
+    const more = calls.length > MAX_SHOWN ? [`  …and ${calls.length - MAX_SHOWN} earlier`] : [];
+    return [...more, ...shown].join("\n");
+}
+function assertStub(received) {
+    if (!(received instanceof Stub))
+        throw new TypeError("slicetest: expected a stub, e.g. expect(stub(\"slack\"))");
+}
+expect.extend({
+    toHaveReceived(received, method, path, match) {
+        assertStub(received);
+        const pass = received.calls(method, path, match).length > 0;
+        const cond = match && Object.keys(match).length ? ` with ${this.utils.stringify(match)}` : "";
+        return {
+            pass,
+            message: () => `expected stub "${received.name}" ${pass ? "not " : ""}to have received ${method} ${path}${cond}\n` +
+                `Calls received:\n${describeCalls(received.calls())}`,
+        };
+    },
+    toHaveReceivedTimes(received, n, method, path, match) {
+        assertStub(received);
+        const actual = received.calls(method, path, match).length;
+        const what = method ? `${method} ${path ?? "*"}` : "calls";
+        return {
+            pass: actual === n,
+            message: () => `expected stub "${received.name}" to have received ${what} ${this.isNot ? "not " : ""}${n} time(s), got ${actual}\n` +
+                `Calls received:\n${describeCalls(received.calls())}`,
+            actual,
+            expected: n,
+        };
+    },
+    toHaveStatus(received, status) {
+        const pass = received?.status === status;
+        return {
+            pass,
+            message: () => {
+                const body = received.text.length > 1000 ? `${received.text.slice(0, 1000)}…` : received.text;
+                return (`expected ${received.method} ${received.url} ${this.isNot ? "not " : ""}to respond ${status}, got ${received.status}\n` +
+                    `Response body:\n  ${body || "(empty)"}`);
+            },
+            actual: received?.status,
+            expected: status,
+        };
+    },
+    async toHaveRow(received, table, where = {}, count) {
+        if (!(received instanceof Db))
+            throw new TypeError("slicetest: expected the db handle, e.g. expect(db)");
+        const n = await received.count(table, where);
+        const pass = count === undefined ? n > 0 : n === count;
+        const sample = pass ? [] : await received.rows(table, {}, { limit: MAX_SHOWN });
+        const want = count === undefined ? "a row" : `${count} row(s)`;
+        return {
+            pass,
+            message: () => `expected ${table} ${this.isNot ? "not " : ""}to have ${want} matching ${this.utils.stringify(where)}, found ${n}\n` +
+                (sample.length ? `First rows in ${table}:\n${sample.map((r) => `  ${JSON.stringify(r)}`).join("\n")}` : `${table} is empty`),
+        };
+    },
+});

package/dist/provided.d.ts

@@ -0,0 +1,11 @@
+import type { ResolvedOptions } from "./config.js";
+declare module "vitest" {
+    interface ProvidedContext {
+        slicetestOptions: ResolvedOptions;
+        slicetestDb: {
+            adminUrl: string;
+            template: string;
+            prefix: string;
+        };
+    }
+}

package/dist/provided.js

@@ -0,0 +1 @@
+export {};

package/dist/runtime.d.ts

@@ -0,0 +1,34 @@
+import { App } from "./app.js";
+import type { ResolvedOptions } from "./config.js";
+import { Db } from "./db.js";
+import { HttpClient } from "./http.js";
+import { Stub } from "./stub.js";
+export interface ScenarioContext {
+    http: HttpClient;
+    db: Db;
+    stub: (name: string) => Stub;
+    app: App;
+}
+/** Everything one test file needs: its own database, stub servers and app process. */
+export declare class Runtime {
+    #private;
+    app: App;
+    readonly db: Db;
+    readonly stubs: Map<string, Stub>;
+    private readonly opts;
+    private readonly vars;
+    private constructor();
+    get http(): HttpClient;
+    static start(opts: ResolvedOptions, shared: {
+        adminUrl: string;
+        template: string;
+        prefix: string;
+    }): Promise<Runtime>;
+    context(): ScenarioContext;
+    beforeScenario(): Promise<void>;
+    /** Failures that the scenario body can't see on its own. */
+    afterScenario(): Promise<void>;
+    /** What happened during the current scenario, printed when it fails. */
+    diagnostics(): string;
+    stop(): Promise<void>;
+}

package/dist/runtime.js

@@ -0,0 +1,145 @@
+import path from "node:path";
+import pg from "pg";
+import { App } from "./app.js";
+import { Db, withDatabase } from "./db.js";
+import { formatHistory, HttpClient } from "./http.js";
+import { Stub } from "./stub.js";
+/** Everything one test file needs: its own database, stub servers and app process. */
+export class Runtime {
+    app;
+    db;
+    stubs;
+    opts;
+    vars;
+    #logMark = 0;
+    #http;
+    constructor(app, db, stubs, opts, vars) {
+        this.app = app;
+        this.db = db;
+        this.stubs = stubs;
+        this.opts = opts;
+        this.vars = vars;
+        this.#http = new HttpClient(app.url, opts.http);
+    }
+    get http() {
+        return this.#http;
+    }
+    static async start(opts, shared) {
+        const url = await ensureWorkerDatabase(shared.adminUrl, shared.template, shared.prefix);
+        const stubs = new Map();
+        let db;
+        try {
+            for (const name of opts.stubs)
+                stubs.set(name, await Stub.start(name));
+            db = await Db.connect(url, {
+                schemas: opts.db.schemas,
+                keep: opts.db.keep,
+                seedFile: opts.db.seed && path.resolve(opts.root, opts.db.seed),
+            });
+            const vars = { "db.url": url };
+            for (const [name, stub] of stubs)
+                vars[`stub.${name}`] = stub.url;
+            const app = await App.start(opts.app, opts.root, vars);
+            return new Runtime(app, db, stubs, opts, vars);
+        }
+        catch (e) {
+            await db?.close();
+            await Promise.all([...stubs.values()].map((s) => s.close()));
+            throw e;
+        }
+    }
+    context() {
+        return {
+            http: this.http,
+            db: this.db,
+            app: this.app,
+            stub: (name) => {
+                const stub = this.stubs.get(name);
+                if (!stub) {
+                    throw new Error(`slicetest: unknown stub "${name}". Declared stubs: ${[...this.stubs.keys()].join(", ") || "(none)"}`);
+                }
+                return stub;
+            },
+        };
+    }
+    async beforeScenario() {
+        // A crash already failed the scenario that caused it; give the next one a fresh app.
+        if (this.app.exited) {
+            await this.app.stop();
+            this.app = await App.start(this.opts.app, this.opts.root, this.vars);
+            this.#http = new HttpClient(this.app.url, this.opts.http);
+        }
+        await this.db.reset();
+        for (const stub of this.stubs.values())
+            stub.reset();
+        this.http.reset();
+        this.#logMark = this.app.mark();
+    }
+    /** Failures that the scenario body can't see on its own. */
+    async afterScenario() {
+        await this.app.settle();
+        this.#assertAlive();
+        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")}`);
+        }
+    }
+    #unmatched() {
+        return [...this.stubs.values()].flatMap((s) => {
+            const calls = s.unmatched();
+            if (calls.length === 0)
+                return [];
+            const routes = s.describeRoutes();
+            return [
+                ...calls.map((c) => `  ${s.name}: ${c.method} ${c.path}${c.query.size ? `?${c.query}` : ""}`),
+                `    registered on ${s.name}: ${routes.length ? routes.join(", ") : "(none)"}`,
+            ];
+        });
+    }
+    /** What happened during the current scenario, printed when it fails. */
+    diagnostics() {
+        const sections = [];
+        const exit = this.app.exited;
+        if (exit)
+            sections.push(`the app exited (code ${exit.code}, signal ${exit.signal}); it will be restarted for the next scenario`);
+        const unmatched = this.#unmatched();
+        if (unmatched.length > 0)
+            sections.push(`stub calls with no matching route:\n${unmatched.join("\n")}`);
+        if (this.http.history.length > 0)
+            sections.push(`requests to the app:\n${formatHistory(this.http.history)}`);
+        const logs = this.app.logs(this.#logMark);
+        sections.push(logs ? `app output during this scenario:\n${logs}` : "app output during this scenario: (none)");
+        return sections.join("\n\n");
+    }
+    async stop() {
+        const results = await Promise.allSettled([
+            this.app.stop(),
+            this.db.close(),
+            ...[...this.stubs.values()].map((s) => s.close()),
+        ]);
+        const failed = results.find((r) => r.status === "rejected");
+        if (failed)
+            throw failed.reason;
+    }
+    #assertAlive() {
+        const exit = this.app.exited;
+        if (exit) {
+            throw new Error(`slicetest: app process exited (code ${exit.code}, signal ${exit.signal})\n${this.app.logs()}`);
+        }
+    }
+}
+/** One database per vitest worker, cloned from the migrated template and reused across its test files. */
+async function ensureWorkerDatabase(adminUrl, template, prefix) {
+    const name = `${prefix}_w${process.env.VITEST_POOL_ID ?? process.pid}`;
+    const admin = new pg.Client({ connectionString: adminUrl });
+    await admin.connect();
+    try {
+        const { rowCount } = await admin.query("SELECT 1 FROM pg_database WHERE datname = $1", [name]);
+        if (!rowCount)
+            await admin.query(`CREATE DATABASE "${name}" TEMPLATE "${template}"`);
+    }
+    finally {
+        await admin.end();
+    }
+    return withDatabase(adminUrl, name);
+}

package/dist/scenario.d.ts

@@ -0,0 +1,15 @@
+import type { Runtime, ScenarioContext } from "./runtime.js";
+export declare function setRuntime(runtime: Runtime | undefined): void;
+type Body = (ctx: ScenarioContext) => Promise<void> | void;
+/**
+ * A test that runs against the real app. The database is reset to the
+ * migrated schema (plus seed) and stubs are cleared before each scenario.
+ */
+export declare const scenario: ((name: string, body: Body, timeout?: number) => void) & {
+    only: (name: string, body: Body, timeout?: number) => void;
+    skip: (name: string, body: Body, timeout?: number) => void;
+    todo: (name: string) => void;
+    /** Same scenario for each row: `scenario.each(rows)("name %s", async (row, ctx) => ...)`. */
+    each<T>(rows: readonly T[]): (name: string, body: (row: T, ctx: ScenarioContext) => Promise<void> | void, timeout?: number) => void;
+};
+export {};

package/dist/scenario.js

@@ -0,0 +1,59 @@
+import { test } from "vitest";
+// Kept on globalThis so it survives the setup file and the test file loading
+// separate copies of this module (e.g. one from dist, one through an alias).
+const KEY = Symbol.for("slicetest.runtime");
+const slot = globalThis;
+export function setRuntime(runtime) {
+    slot[KEY] = runtime;
+}
+function define(register) {
+    return (name, body, timeout) => register(name, async ({ onTestFailed, task }) => {
+        const runtime = slot[KEY];
+        if (!runtime) {
+            throw new Error("slicetest: runtime not started. Add the slicetest() plugin to your vitest config.");
+        }
+        if (task.concurrent) {
+            throw new Error("slicetest: scenarios share one app and database per file, so they can't run concurrently. Remove .concurrent / sequence.concurrent.");
+        }
+        onTestFailed(() => {
+            console.error(`--- slicetest ---\n${runtime.diagnostics()}\n-----------------`);
+        });
+        await runtime.beforeScenario();
+        await body(runtime.context());
+        await runtime.afterScenario();
+    }, timeout);
+}
+/**
+ * A test that runs against the real app. The database is reset to the
+ * migrated schema (plus seed) and stubs are cleared before each scenario.
+ */
+export const scenario = Object.assign(define(test), {
+    only: define(test.only),
+    skip: define(test.skip),
+    todo: (name) => test.todo(name),
+    /** Same scenario for each row: `scenario.each(rows)("name %s", async (row, ctx) => ...)`. */
+    each(rows) {
+        return (name, body, timeout) => {
+            rows.forEach((row, i) => {
+                const title = format(name, row, i);
+                define(test)(title, (ctx) => body(row, ctx), timeout);
+            });
+        };
+    },
+});
+/** printf-style `%s`/`%i`/`%j`/`%#`, plus `$field` for object rows. */
+function format(name, row, index) {
+    const args = Array.isArray(row) ? [...row] : [row];
+    let out = name.replace(/%[sdij#%]/g, (tok) => {
+        if (tok === "%%")
+            return "%";
+        if (tok === "%#")
+            return String(index);
+        const v = args.shift();
+        return tok === "%j" ? JSON.stringify(v) : typeof v === "object" ? JSON.stringify(v) : String(v);
+    });
+    if (row && typeof row === "object" && !Array.isArray(row)) {
+        out = out.replace(/\$(\w+)/g, (m, k) => (k in row ? String(row[k]) : m));
+    }
+    return out;
+}

package/dist/setup-file.d.ts

@@ -0,0 +1,2 @@
+import "./provided.js";
+import "./matchers.js";

package/dist/setup-file.js

@@ -0,0 +1,14 @@
+import { afterAll, beforeAll, inject } from "vitest";
+import { setRuntime } from "./scenario.js";
+import { Runtime } from "./runtime.js";
+import "./provided.js";
+import "./matchers.js";
+let runtime;
+beforeAll(async () => {
+    runtime = await Runtime.start(inject("slicetestOptions"), inject("slicetestDb"));
+    setRuntime(runtime);
+});
+afterAll(async () => {
+    setRuntime(undefined);
+    await runtime?.stop();
+});

package/dist/stub.d.ts

@@ -0,0 +1,75 @@
+import http from "node:http";
+export interface RecordedCall {
+    method: string;
+    path: string;
+    query: URLSearchParams;
+    headers: http.IncomingHttpHeaders;
+    body: string;
+    /** Parsed JSON body, or undefined when the body isn't JSON. */
+    json: any;
+    /** Values captured by `:name` segments of the matching route's path. */
+    params: Record<string, string>;
+    /** Whether a registered route answered this call. */
+    matched: boolean;
+}
+export interface StubResponse {
+    status?: number;
+    headers?: Record<string, string>;
+    /** Objects are sent as JSON. */
+    body?: unknown;
+}
+export type Responder = StubResponse | ((call: RecordedCall) => StubResponse | Promise<StubResponse>);
+/**
+ * Extra conditions a call must meet for a route to answer it. Plain values are
+ * compared exactly (`json` as a subset); RegExps test strings; functions and
+ * `expect.*` asymmetric matchers receive the actual value.
+ */
+export interface MatchOptions {
+    query?: Record<string, Matcher>;
+    headers?: Record<string, Matcher>;
+    json?: unknown;
+    body?: Matcher;
+}
+type Matcher = string | number | boolean | RegExp | ((value: any) => boolean) | {
+    asymmetricMatch(value: unknown): boolean;
+};
+/** Builder returned by `stub.on()`. Finish it with `reply()` or `networkError()`. */
+export interface RouteBuilder {
+    /** Answer only the next `n` matching calls; later calls fall through to other routes. */
+    times(n: number): RouteBuilder;
+    once(): RouteBuilder;
+    /** Wait before answering, e.g. to exercise the app's timeouts. */
+    delay(ms: number): RouteBuilder;
+    reply(status: number, body?: unknown, headers?: Record<string, string>): Stub;
+    reply(response: Responder): Stub;
+    /** Answer each matching call with the next response in the list; the last one repeats. */
+    replySequence(responses: StubResponse[]): Stub;
+    /** Drop the connection without answering. */
+    networkError(): Stub;
+}
+/**
+ * A fake outbound service. The app is pointed at `url`; tests register routes
+ * with `on()` and inspect what the app sent with `calls()`.
+ */
+export declare class Stub {
+    #private;
+    readonly name: string;
+    url: string;
+    private constructor();
+    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;
+    /** 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[];
+    /** Human-readable list of registered routes, for diagnostics. */
+    describeRoutes(): string[];
+    reset(): void;
+    close(): Promise<void>;
+}
+/** `expected` is contained in `actual`: objects compare key by key, arrays element-wise. */
+export declare function subset(expected: unknown, actual: unknown): boolean;
+export {};