slicetest 0.1.0

package/dist/stub.js

@@ -0,0 +1,228 @@
+import http from "node:http";
+import { isDeepStrictEqual } from "node:util";
+/**
+ * A fake outbound service. The app is pointed at `url`; tests register routes
+ * with `on()` and inspect what the app sent with `calls()`.
+ */
+export class Stub {
+    name;
+    #server;
+    #routes = [];
+    #calls = [];
+    url = "";
+    constructor(name) {
+        this.name = name;
+        this.#server = http.createServer((req, res) => {
+            // An aborted request rejects while reading the body; don't let that crash the worker.
+            this.#handle(req, res).catch(() => res.destroy());
+        });
+    }
+    static async start(name) {
+        const stub = new Stub(name);
+        await new Promise((resolve) => stub.#server.listen(0, "127.0.0.1", resolve));
+        stub.url = `http://127.0.0.1:${stub.#server.address().port}`;
+        return 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, path, match = {}) {
+        const { pattern, paramNames } = compilePath(path);
+        const route = {
+            method: method.toUpperCase(),
+            path,
+            pattern,
+            paramNames,
+            match,
+            remaining: Infinity,
+            delayMs: 0,
+            hits: 0,
+        };
+        const add = (respond, extra = {}) => {
+            this.#routes.unshift({ ...route, ...extra, respond });
+            return this;
+        };
+        const builder = {
+            times: (n) => ((route.remaining = n), builder),
+            once: () => builder.times(1),
+            delay: (ms) => ((route.delayMs = ms), builder),
+            reply: (statusOrResponse, body, headers) => add(typeof statusOrResponse === "number" ? { status: statusOrResponse, body, headers } : statusOrResponse),
+            replySequence: (responses) => {
+                if (responses.length === 0)
+                    throw new Error("slicetest: replySequence() needs at least one response");
+                let i = 0;
+                return add(() => responses[Math.min(i++, responses.length - 1)]);
+            },
+            networkError: () => add({}, { fault: "reset" }),
+        };
+        return builder;
+    }
+    /** 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);
+        return this.#calls.filter((c) => (!method || method === "*" || c.method === method.toUpperCase()) &&
+            (!compiled || matchPath(path, compiled.pattern, c.path) !== undefined) &&
+            matchConditions(match, c));
+    }
+    unmatched() {
+        return this.#calls.filter((c) => !c.matched);
+    }
+    /** Human-readable list of registered routes, for diagnostics. */
+    describeRoutes() {
+        return this.#routes.map((r) => {
+            const limit = Number.isFinite(r.remaining + r.hits) ? ` (${r.hits}/${r.remaining + r.hits} used)` : "";
+            const cond = Object.keys(r.match).length ? ` + ${Object.keys(r.match).join("/")} conditions` : "";
+            return `${r.method} ${r.path}${cond}${limit}`;
+        });
+    }
+    reset() {
+        this.#routes = [];
+        this.#calls = [];
+    }
+    async close() {
+        this.#server.closeAllConnections();
+        await new Promise((resolve) => this.#server.close(resolve));
+    }
+    async #handle(req, res) {
+        const chunks = [];
+        for await (const chunk of req)
+            chunks.push(chunk);
+        const body = Buffer.concat(chunks).toString("utf8");
+        const url = new URL(req.url ?? "/", this.url);
+        const call = {
+            method: req.method ?? "GET",
+            path: url.pathname,
+            query: url.searchParams,
+            headers: req.headers,
+            body,
+            json: parseJson(body),
+            params: {},
+            matched: false,
+        };
+        this.#calls.push(call);
+        let route;
+        for (const r of this.#routes) {
+            if (r.remaining <= 0)
+                continue;
+            if (r.method !== "*" && r.method !== call.method)
+                continue;
+            const params = matchPath(r.path, r.pattern, call.path, r.paramNames);
+            if (!params || !matchConditions(r.match, call))
+                continue;
+            call.params = params;
+            route = r;
+            break;
+        }
+        if (!route) {
+            res.writeHead(501, { "content-type": "text/plain" }).end(`slicetest: no stub for ${call.method} ${call.path}`);
+            return;
+        }
+        call.matched = true;
+        route.remaining--;
+        route.hits++;
+        if (route.delayMs > 0)
+            await new Promise((r) => setTimeout(r, route.delayMs));
+        if (route.fault === "reset") {
+            req.socket.destroy();
+            return;
+        }
+        try {
+            const out = typeof route.respond === "function" ? await route.respond(call) : route.respond;
+            const raw = out.body === undefined || typeof out.body === "string" || out.body instanceof Uint8Array;
+            const headers = { ...out.headers };
+            if (!raw && !Object.keys(headers).some((h) => h.toLowerCase() === "content-type")) {
+                headers["content-type"] = "application/json";
+            }
+            res.writeHead(out.status ?? 200, headers);
+            res.end(raw ? out.body : JSON.stringify(out.body));
+        }
+        catch (e) {
+            res.writeHead(500).end(`slicetest: stub handler threw: ${e}`);
+        }
+    }
+}
+function compilePath(path) {
+    if (typeof path !== "string" || !path.includes("/:"))
+        return { pattern: undefined, paramNames: [] };
+    const paramNames = [];
+    const source = path
+        .split("/")
+        .map((seg) => {
+        if (!seg.startsWith(":"))
+            return seg.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+        paramNames.push(seg.slice(1));
+        return "([^/]+)";
+    })
+        .join("/");
+    return { pattern: new RegExp(`^${source}$`), paramNames };
+}
+/** Returns captured params on a match, undefined otherwise. */
+function matchPath(path, pattern, actual, names = []) {
+    if (typeof path === "string" && !pattern)
+        return path === actual ? {} : undefined;
+    const re = pattern ?? path;
+    re.lastIndex = 0;
+    const m = re.exec(actual);
+    if (!m)
+        return undefined;
+    const params = { ...m.groups };
+    names.forEach((n, i) => (params[n] = decodeURIComponent(m[i + 1])));
+    return params;
+}
+function matchConditions(match, call) {
+    for (const [k, m] of Object.entries(match.query ?? {})) {
+        if (!test(m, call.query.get(k) ?? undefined))
+            return false;
+    }
+    for (const [k, m] of Object.entries(match.headers ?? {})) {
+        const v = call.headers[k.toLowerCase()];
+        if (!test(m, Array.isArray(v) ? v.join(", ") : v))
+            return false;
+    }
+    if (match.body !== undefined && !test(match.body, call.body))
+        return false;
+    if (match.json !== undefined && !subset(match.json, call.json))
+        return false;
+    return true;
+}
+function test(m, value) {
+    if (isAsymmetric(m))
+        return m.asymmetricMatch(value);
+    if (typeof m === "function")
+        return m(value);
+    if (value === undefined)
+        return false;
+    if (typeof m === "number" || typeof m === "boolean")
+        return String(m) === value;
+    return m instanceof RegExp ? m.test(value) : m === value;
+}
+/** `expected` is contained in `actual`: objects compare key by key, arrays element-wise. */
+export function subset(expected, actual) {
+    if (isAsymmetric(expected))
+        return expected.asymmetricMatch(actual);
+    if (expected instanceof RegExp)
+        return typeof actual === "string" && expected.test(actual);
+    if (Array.isArray(expected)) {
+        return Array.isArray(actual) && actual.length === expected.length && expected.every((e, i) => subset(e, actual[i]));
+    }
+    if (expected && typeof expected === "object") {
+        if (!actual || typeof actual !== "object")
+            return false;
+        return Object.entries(expected).every(([k, v]) => subset(v, actual[k]));
+    }
+    return isDeepStrictEqual(expected, actual);
+}
+function isAsymmetric(m) {
+    return !!m && typeof m === "object" && typeof m.asymmetricMatch === "function";
+}
+function parseJson(body) {
+    if (!body)
+        return undefined;
+    try {
+        return JSON.parse(body);
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/vitest.d.ts

@@ -0,0 +1,6 @@
+import type { Plugin } from "vite";
+import { type SlicetestOptions } from "./config.js";
+/** 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;
+export type { SlicetestOptions } from "./config.js";

package/dist/vitest.js

@@ -0,0 +1,46 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { configDefaults } from "vitest/config";
+import { resolveOptions } from "./config.js";
+import { parseScenarioFile } from "./yaml.js";
+/** 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));
+export function slicetest(options) {
+    let root;
+    return {
+        name: "slicetest",
+        config(config) {
+            const root = path.resolve(config.root ?? process.cwd());
+            // Mutated rather than returned: a returned list would replace Vitest's default include instead of extending it.
+            const test = (config.test ??= {});
+            test.include = [...(test.include ?? configDefaults.include), YAML_SCENARIOS];
+            return {
+                test: {
+                    globalSetup: [path.join(here, `global-setup${ext}`)],
+                    setupFiles: [path.join(here, `setup-file${ext}`)],
+                    provide: { slicetestOptions: resolveOptions(options, root) },
+                    hookTimeout: 120_000,
+                },
+            };
+        },
+        transform(code, id) {
+            const file = id.split("?")[0];
+            if (!YAML_ID.test(file))
+                return;
+            const doc = parseScenarioFile(code, path.relative(root ?? process.cwd(), file) || file);
+            const runtime = JSON.stringify(path.join(here, `yaml-runtime${ext}`));
+            return { code: `import { defineYamlScenarios } from ${runtime};\ndefineYamlScenarios(${JSON.stringify(doc)});\n`, map: null };
+        },
+        // `config.root` is often unset; the resolved root is the one relative paths should follow.
+        configResolved(resolved) {
+            root = resolved.root;
+            const provided = resolved.test?.provide;
+            if (provided?.slicetestOptions)
+                provided.slicetestOptions.root = resolved.root;
+        },
+    };
+}

package/dist/yaml-runtime.d.ts

@@ -0,0 +1,18 @@
+import "./matchers.js";
+import type { YamlFile } from "./yaml.js";
+type Vars = Record<string, unknown>;
+/** Registers the scenarios of one parsed YAML file. Called from the module the plugin generates for it. */
+export declare function defineYamlScenarios(doc: YamlFile): void;
+/** `json.items[0].id` or `json.items.0.id` */
+export declare function lookup(obj: unknown, path: string): unknown;
+/**
+ * Replace `{{name}}` in every string. A string that is only `{{name}}` takes
+ * the variable's own type, so `id: "{{pollId}}"` stays a number.
+ */
+export declare function interpolate(value: unknown, vars: Vars): unknown;
+/**
+ * `{ $type: number }`, `{ $regex: "^ch_" }`, `{ $contains: "x" }` and
+ * `{ $any: true }` become Vitest asymmetric matchers.
+ */
+export declare function toMatchers(value: unknown): unknown;
+export {};

package/dist/yaml-runtime.js

@@ -0,0 +1,255 @@
+import { expect } from "vitest";
+import "./matchers.js";
+import { scenario } from "./scenario.js";
+/** Registers the scenarios of one parsed YAML file. Called from the module the plugin generates for it. */
+export function defineYamlScenarios(doc) {
+    for (const sc of doc.scenarios) {
+        const register = sc.only ? scenario.only : sc.skip ? scenario.skip : scenario;
+        const rows = sc.each ?? [undefined];
+        rows.forEach((row, i) => {
+            const title = row ? interpolateTitle(sc.name, row, i) : sc.name;
+            register(title, (ctx) => runSteps(doc, sc, [...doc.setup, ...sc.steps], ctx, { ...row }), sc.timeout);
+        });
+    }
+}
+async function runSteps(doc, sc, steps, ctx, vars) {
+    for (const [i, step] of steps.entries()) {
+        try {
+            await runStep(step, ctx, vars);
+        }
+        catch (e) {
+            const label = step.name ?? describeStep(step);
+            const where = `${doc.file}:${step.line} (${sc.name}, step ${i + 1}: ${label})`;
+            if (e instanceof Error) {
+                e.message = `${where}\n${e.message}`;
+                throw e;
+            }
+            throw new Error(`${where}\n${String(e)}`);
+        }
+    }
+}
+function describeStep(step) {
+    if ("request" in step)
+        return step.request;
+    if ("stub" in step)
+        return `stub ${step.stub} ${step.on}`;
+    if ("received" in step)
+        return `received ${step.received}${step.call ? ` ${step.call}` : ""}`;
+    if ("insert" in step)
+        return `insert ${step.insert}`;
+    if ("db" in step)
+        return `db ${step.db}`;
+    return "sql";
+}
+async function runStep(step, ctx, vars) {
+    if ("stub" in step) {
+        const [method, path] = splitCall(step.on);
+        let route = ctx.stub(step.stub).on(method, interpolate(path, vars), conditions(step.when, vars));
+        if (step.times !== undefined)
+            route = route.times(step.times);
+        if (step.delay !== undefined)
+            route = route.delay(step.delay);
+        // Replies are interpolated when a call arrives, so they can echo it: {{call.params.id}}, {{call.json.name}}.
+        const answer = (template) => (call) => interpolate(template, { ...vars, call: callVars(call) });
+        if (step.networkError)
+            route.networkError();
+        else if (step.sequence) {
+            let n = 0;
+            const seq = step.sequence;
+            route.reply((call) => answer(seq[Math.min(n++, seq.length - 1)])(call));
+        }
+        else
+            route.reply(answer(step.reply ?? {}));
+        return;
+    }
+    if ("request" in step) {
+        const [method, rawPath] = splitCall(step.request);
+        const path = interpolate(rawPath, vars);
+        const opts = {
+            headers: interpolate(step.headers, vars),
+            query: interpolate(step.query, vars),
+            follow: step.follow,
+        };
+        const body = step.json !== undefined
+            ? interpolate(step.json, vars)
+            : step.form !== undefined
+                ? ctx.http.form(interpolate(step.form, vars))
+                : interpolate(step.body, vars);
+        const res = await ctx.http.request(method, path, body, opts);
+        const e = step.expect;
+        if (e?.status !== undefined)
+            expect(res).toHaveStatus(interpolate(e.status, vars));
+        if (e?.headers !== undefined) {
+            const expected = Object.fromEntries(Object.entries(e.headers).map(([k, v]) => [k.toLowerCase(), v]));
+            check(Object.fromEntries(res.headers), expected, vars, "response headers");
+        }
+        if (e?.json !== undefined)
+            check(res.json, e.json, vars, "response JSON");
+        if (e?.text !== undefined)
+            check(res.text, e.text, vars, "response text");
+        capture(step.capture, { status: res.status, json: res.json, text: res.text, headers: Object.fromEntries(res.headers) }, vars);
+        return;
+    }
+    if ("insert" in step) {
+        const rows = await ctx.db.insert(step.insert, interpolate(step.rows, vars));
+        capture(step.capture, { rows, row: rows[0] }, vars);
+        return;
+    }
+    if ("sql" in step) {
+        const rows = await ctx.db.query(step.sql, interpolate(step.params, vars) ?? []);
+        expectRows(step.expect, rows, vars);
+        capture(step.capture, { rows, row: rows[0], count: rows.length }, vars);
+        return;
+    }
+    if ("db" in step) {
+        const rows = await ctx.db.rows(step.db, interpolate(step.where, vars) ?? {}, { orderBy: step.orderBy });
+        expectRows(step.expect, rows, vars, step.db);
+        capture(step.capture, { rows, row: rows[0], count: rows.length }, vars);
+        return;
+    }
+    // received
+    const [method, path] = step.call ? splitCall(step.call) : [undefined, undefined];
+    const stub = ctx.stub(step.received);
+    const match = conditions(step.when, vars);
+    const p = path && interpolate(path, vars);
+    if (step.times === undefined)
+        expect(stub).toHaveReceived(method ?? "*", p ?? /.*/, match);
+    else
+        expect(stub).toHaveReceivedTimes(step.times, method, p, match);
+}
+function expectRows(e, rows, vars, table) {
+    if (!e)
+        return;
+    if (e.count !== undefined && rows.length !== e.count) {
+        const shown = rows.slice(0, 5).map((r) => `  ${JSON.stringify(r)}`).join("\n");
+        throw new Error(`expected ${e.count} row(s)${table ? ` in ${table}` : ""}, found ${rows.length}${shown ? `:\n${shown}` : ""}`);
+    }
+    if (e.rows !== undefined)
+        check(rows, e.rows, vars, table ? `rows of ${table}` : "rows");
+}
+/** Subset comparison with Vitest's diff: objects may have extra keys, arrays must have the same length. */
+function check(actual, expected, vars, what) {
+    const want = toMatchers(interpolate(expected, vars));
+    if (want && typeof want === "object" && !isAsymmetric(want))
+        expect(actual, what).toMatchObject(want);
+    else
+        expect(actual, what).toEqual(want);
+}
+function conditions(when, vars) {
+    if (!when)
+        return {};
+    return toMatchers(interpolate(when, vars));
+}
+function capture(spec, result, vars) {
+    for (const [name, path] of Object.entries(spec ?? {})) {
+        const value = lookup(result, path);
+        if (value === undefined) {
+            throw new Error(`capture "${name}": ${path} is undefined in ${JSON.stringify(result).slice(0, 300)}`);
+        }
+        vars[name] = value;
+    }
+}
+function callVars(call) {
+    return {
+        method: call.method,
+        path: call.path,
+        params: call.params,
+        query: Object.fromEntries(call.query),
+        headers: call.headers,
+        json: call.json,
+        body: call.body,
+    };
+}
+function splitCall(s) {
+    const i = s.search(/\s/);
+    return [s.slice(0, i).toUpperCase(), s.slice(i).trim()];
+}
+/** `json.items[0].id` or `json.items.0.id` */
+export function lookup(obj, path) {
+    return path
+        .replace(/\[(\d+)\]/g, ".$1")
+        .split(".")
+        .filter(Boolean)
+        .reduce((cur, key) => (cur == null ? undefined : cur[key]), obj);
+}
+const WHOLE = /^\{\{\s*([^{}]+?)\s*\}\}$/;
+const PART = /\{\{\s*([^{}]+?)\s*\}\}/g;
+/**
+ * Replace `{{name}}` in every string. A string that is only `{{name}}` takes
+ * the variable's own type, so `id: "{{pollId}}"` stays a number.
+ */
+export function interpolate(value, vars) {
+    if (typeof value === "string") {
+        const whole = WHOLE.exec(value);
+        if (whole)
+            return resolve(whole[1], vars);
+        return value.replace(PART, (_, name) => {
+            const v = resolve(name, vars);
+            return typeof v === "object" ? JSON.stringify(v) : String(v);
+        });
+    }
+    if (Array.isArray(value))
+        return value.map((v) => interpolate(v, vars));
+    if (value && typeof value === "object") {
+        return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, interpolate(v, vars)]));
+    }
+    return value;
+}
+function resolve(name, vars) {
+    const v = lookup(vars, name);
+    if (v === undefined) {
+        const known = Object.keys(vars).filter((k) => k !== "call");
+        throw new Error(`unknown variable {{${name}}}. Defined so far: ${known.join(", ") || "(none)"}`);
+    }
+    return v;
+}
+const TYPES = {
+    string: expect.any(String),
+    number: expect.any(Number),
+    boolean: expect.any(Boolean),
+    array: expect.any(Array),
+    object: expect.any(Object),
+};
+/**
+ * `{ $type: number }`, `{ $regex: "^ch_" }`, `{ $contains: "x" }` and
+ * `{ $any: true }` become Vitest asymmetric matchers.
+ */
+export function toMatchers(value) {
+    if (Array.isArray(value))
+        return value.map(toMatchers);
+    if (!value || typeof value !== "object" || isAsymmetric(value))
+        return value;
+    const keys = Object.keys(value);
+    if (keys.length === 1 && keys[0].startsWith("$")) {
+        const [key] = keys;
+        const arg = value[key];
+        switch (key) {
+            case "$type":
+                if (arg === "null")
+                    return null;
+                if (typeof arg === "string" && arg in TYPES)
+                    return TYPES[arg];
+                throw new Error(`$type must be one of ${Object.keys(TYPES).join(", ")}, null`);
+            case "$regex":
+                return expect.stringMatching(new RegExp(String(arg)));
+            case "$contains":
+                return expect.stringContaining(String(arg));
+            case "$any":
+                return expect.anything();
+            default:
+                throw new Error(`unknown matcher ${key} (expected $type, $regex, $contains, $any)`);
+        }
+    }
+    return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, toMatchers(v)]));
+}
+function isAsymmetric(v) {
+    return !!v && typeof v === "object" && typeof v.asymmetricMatch === "function";
+}
+function interpolateTitle(name, row, index) {
+    return name.replace(PART, (m, key) => {
+        if (key.trim() === "#")
+            return String(index);
+        const v = lookup(row, key);
+        return v === undefined ? m : typeof v === "object" ? JSON.stringify(v) : String(v);
+    });
+}

package/dist/yaml.d.ts

@@ -0,0 +1,99 @@
+/**
+ * YAML scenarios: the same things a TypeScript scenario can do, written as
+ * data so teams that don't use JavaScript can write them. This module parses
+ * and validates a file (in the Vitest main process, where line numbers are
+ * known); yaml-runtime.ts runs the result inside a worker.
+ */
+export interface YamlFile {
+    file: string;
+    /** Steps run at the start of every scenario in the file. */
+    setup: Step[];
+    scenarios: YamlScenario[];
+}
+export interface YamlScenario {
+    name: string;
+    line: number;
+    each?: Record<string, unknown>[];
+    skip?: boolean;
+    only?: boolean;
+    timeout?: number;
+    steps: Step[];
+}
+export type Step = (StubStep | RequestStep | InsertStep | SqlStep | DbStep | ReceivedStep) & {
+    line: number;
+    name?: string;
+};
+export interface StubStep {
+    stub: string;
+    on: string;
+    when?: Conditions;
+    reply?: {
+        status?: number;
+        headers?: Record<string, string>;
+        body?: unknown;
+    };
+    sequence?: {
+        status?: number;
+        headers?: Record<string, string>;
+        body?: unknown;
+    }[];
+    networkError?: boolean;
+    times?: number;
+    delay?: number;
+}
+export interface Conditions {
+    query?: Record<string, unknown>;
+    headers?: Record<string, unknown>;
+    json?: unknown;
+    body?: unknown;
+}
+export interface RequestStep {
+    request: string;
+    headers?: Record<string, string>;
+    query?: Record<string, unknown>;
+    json?: unknown;
+    form?: Record<string, unknown>;
+    body?: string;
+    follow?: boolean;
+    expect?: {
+        status?: number;
+        headers?: Record<string, unknown>;
+        json?: unknown;
+        text?: unknown;
+    };
+    capture?: Record<string, string>;
+}
+export interface InsertStep {
+    insert: string;
+    rows: Record<string, unknown> | Record<string, unknown>[];
+    capture?: Record<string, string>;
+}
+export interface SqlStep {
+    sql: string;
+    params?: unknown[];
+    expect?: {
+        rows?: unknown[];
+        count?: number;
+    };
+    capture?: Record<string, string>;
+}
+export interface DbStep {
+    db: string;
+    where?: Record<string, unknown>;
+    orderBy?: string | string[];
+    expect?: {
+        rows?: unknown[];
+        count?: number;
+    };
+    capture?: Record<string, string>;
+}
+export interface ReceivedStep {
+    received: string;
+    call?: string;
+    when?: Conditions;
+    /** Exact number of matching calls. Default: at least one. */
+    times?: number;
+}
+export declare class YamlScenarioError extends Error {
+}
+export declare function parseScenarioFile(text: string, file: string): YamlFile;