slicetest 0.3.0 → 0.5.0

package/dist/drivers/postgres.d.ts

@@ -1,4 +1,4 @@
-import type { Driver, Engine, Row, Table } from "./driver.js";
+import type { Driver, Engine, Row, Table, TableShape } from "./driver.js";
 export declare class PostgresDriver implements Driver {
     private readonly client;
     private constructor();
@@ -14,6 +14,7 @@ export declare class PostgresDriver implements Driver {
     listTables(schemas: string[], keep: string[]): Promise<Table[]>;
     truncate(tables: Table[]): Promise<void>;
     insert(table: string, row: Row): Promise<Row[]>;
+    describe(table: string): Promise<TableShape>;
     close(): Promise<void>;
 }
 export declare const postgres: Engine;

package/dist/drivers/postgres.js

@@ -88,6 +88,34 @@ export class PostgresDriver {
             : `INSERT INTO ${this.ident(table)} (${cols.map((c) => this.ident(c)).join(", ")}) VALUES (${cols.map((_, i) => `$${i + 1}`).join(", ")}) RETURNING *`;
         return this.query(sql, Object.values(row));
     }
+    async describe(table) {
+        const [{ oid } = { oid: null }] = await this.query("SELECT to_regclass($1)::oid AS oid", [this.ident(table)]);
+        if (oid === null)
+            throw new Error(`slicetest: there is no table "${table}"`);
+        const columns = await this.query(`SELECT a.attname AS name, format_type(a.atttypid, a.atttypmod) AS type, NOT a.attnotnull AS nullable,
+              (a.atthasdef OR a.attidentity <> '' OR a.attgenerated <> '') AS has_default,
+              information_schema._pg_char_max_length(a.atttypid, a.atttypmod) AS max,
+              (SELECT array_agg(e.enumlabel::text ORDER BY e.enumsortorder) FROM pg_enum e WHERE e.enumtypid = a.atttypid) AS values
+         FROM pg_attribute a
+        WHERE a.attrelid = $1 AND a.attnum > 0 AND NOT a.attisdropped
+        ORDER BY a.attnum`, [oid]);
+        const keys = await this.query(`SELECT (SELECT array_agg(a.attname::text ORDER BY k.ord) FROM unnest(c.conkey) WITH ORDINALITY k(n, ord)
+                JOIN pg_attribute a ON a.attrelid = c.conrelid AND a.attnum = k.n) AS columns,
+              n.nspname AS schema, r.relname AS table,
+              (SELECT array_agg(a.attname::text ORDER BY k.ord) FROM unnest(c.confkey) WITH ORDINALITY k(n, ord)
+                JOIN pg_attribute a ON a.attrelid = c.confrelid AND a.attnum = k.n) AS references
+         FROM pg_constraint c
+         JOIN pg_class r ON r.oid = c.confrelid
+         JOIN pg_namespace n ON n.oid = r.relnamespace
+        WHERE c.contype = 'f' AND c.conrelid = $1
+        ORDER BY c.conname`, [oid]);
+        const checks = await this.query("SELECT pg_get_constraintdef(oid) AS def FROM pg_constraint WHERE contype = 'c' AND conrelid = $1", [oid]);
+        return {
+            columns: columns.map((c) => ({ name: c.name, type: c.type, nullable: c.nullable, hasDefault: c.has_default, maxLength: c.max ?? undefined, values: c.values ?? undefined })),
+            foreignKeys: keys.map((k) => ({ columns: k.columns, table: k.schema === "public" ? k.table : `${k.schema}.${k.table}`, references: k.references })),
+            checks: checks.map((c) => c.def),
+        };
+    }
     async close() {
         await this.client.end();
     }

package/dist/drivers/sqlite.d.ts

@@ -0,0 +1,24 @@
+import type { Driver, Engine, Row, Table, TableShape } from "./driver.js";
+/** `sqlite:///tmp/a.db` → `/tmp/a.db`; `sqlite:///C:/x/a.db` → `C:/x/a.db`. Plain paths pass through. */
+export declare function sqlitePath(url: string): string;
+export declare function sqliteUrl(file: string): string;
+export declare class SqliteDriver implements Driver {
+    private readonly db;
+    private constructor();
+    static connect(url: string): Promise<SqliteDriver>;
+    query<T extends Row = Row>(sql: string, params?: unknown[]): Promise<T[]>;
+    queryAll(sqls: string[]): Promise<Row[][]>;
+    exec(script: string): Promise<void>;
+    ident(name: string): string;
+    column(name: string): string;
+    param(n: number): string;
+    inList(column: string, values: unknown[], params: unknown[]): string;
+    /** SQLite has one schema per file (`main`), so `schemas` doesn't apply. */
+    listTables(_schemas: string[], keep: string[]): Promise<Table[]>;
+    /** DELETE, then forget AUTOINCREMENT counters. Foreign keys are off for this connection only. */
+    truncate(tables: Table[]): Promise<void>;
+    insert(table: string, row: Row): Promise<Row[]>;
+    describe(table: string): Promise<TableShape>;
+    close(): Promise<void>;
+}
+export declare const sqliteEngine: Engine;

package/dist/drivers/sqlite.js

@@ -0,0 +1,255 @@
+import { existsSync } from "node:fs";
+import { mkdir, mkdtemp, open, readdir, rm } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+let loaded;
+/** `node:sqlite` warns that it's experimental on every import; that's noise in test output. */
+function load() {
+    return (loaded ??= (async () => {
+        const emit = process.emitWarning;
+        process.emitWarning = ((warning, ...rest) => {
+            if (String(typeof warning === "string" ? warning : warning.message).includes("SQLite"))
+                return;
+            emit.call(process, warning, ...rest);
+        });
+        try {
+            return await import("node:sqlite");
+        }
+        catch {
+            throw new Error(`slicetest: db.engine "sqlite" needs Node.js 22.5 or later (node:sqlite); this is ${process.versions.node}`);
+        }
+        finally {
+            process.emitWarning = emit;
+        }
+    })());
+}
+/** `sqlite:///tmp/a.db` → `/tmp/a.db`; `sqlite:///C:/x/a.db` → `C:/x/a.db`. Plain paths pass through. */
+export function sqlitePath(url) {
+    if (!url.startsWith("sqlite:"))
+        return url;
+    const p = decodeURIComponent(url.replace(/^sqlite:(\/\/)?/, "").replace(/[?#].*$/, ""));
+    return /^\/[a-zA-Z]:[\\/]/.test(p) ? p.slice(1) : p;
+}
+export function sqliteUrl(file) {
+    const p = path.resolve(file).replace(/\\/g, "/");
+    return `sqlite://${p.startsWith("/") ? "" : "/"}${p}`;
+}
+/** Values node:sqlite can't bind are stored the way an app would store them. */
+/** The parenthesised bodies of every CHECK in a CREATE TABLE statement. */
+function checkBodies(sql) {
+    const bodies = [];
+    for (const m of sql.matchAll(/\bcheck\s*\(/gi)) {
+        let depth = 1;
+        let i = m.index + m[0].length;
+        const start = i;
+        for (; i < sql.length && depth > 0; i++) {
+            if (sql[i] === "'")
+                i = sql.indexOf("'", i + 1);
+            else if (sql[i] === "(")
+                depth++;
+            else if (sql[i] === ")")
+                depth--;
+            if (i < 0)
+                return bodies;
+        }
+        bodies.push(sql.slice(start, i - 1));
+    }
+    return bodies;
+}
+function bind(v) {
+    if (typeof v === "boolean")
+        return v ? 1 : 0;
+    if (v instanceof Date)
+        return v.toISOString();
+    if (v !== null && typeof v === "object" && !(v instanceof Uint8Array))
+        return JSON.stringify(v);
+    return v === undefined ? null : v;
+}
+async function openDb(file) {
+    const { DatabaseSync } = await load();
+    const db = new DatabaseSync(file);
+    // The app may be writing; wait for its lock instead of failing with SQLITE_BUSY.
+    db.exec("PRAGMA busy_timeout = 5000");
+    return db;
+}
+export class SqliteDriver {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    static async connect(url) {
+        return new SqliteDriver(await openDb(sqlitePath(url)));
+    }
+    async query(sql, params = []) {
+        const stmt = this.db.prepare(sql);
+        const values = params.map(bind);
+        // Rows come with a null prototype; plain objects compare and print as expected.
+        return stmt.columns().length === 0 ? (stmt.run(...values), []) : stmt.all(...values).map((r) => ({ ...r }));
+    }
+    async queryAll(sqls) {
+        return Promise.all(sqls.map((s) => this.query(s)));
+    }
+    async exec(script) {
+        this.db.exec(script);
+    }
+    ident(name) {
+        return name
+            .split(".")
+            .map((part) => this.column(part))
+            .join(".");
+    }
+    column(name) {
+        return `"${name.replace(/"/g, '""')}"`;
+    }
+    param(n) {
+        return `?${n}`;
+    }
+    inList(column, values, params) {
+        if (values.length === 0)
+            return "0";
+        const start = params.length;
+        params.push(...values);
+        return `${this.ident(column)} IN (${values.map((_, i) => `?${start + i + 1}`).join(", ")})`;
+    }
+    /** SQLite has one schema per file (`main`), so `schemas` doesn't apply. */
+    async listTables(_schemas, keep) {
+        const rows = await this.query(`SELECT m.name AS name,
+              (SELECT group_concat(name, char(10)) FROM (SELECT name FROM pragma_table_info(m.name) WHERE pk > 0 ORDER BY pk)) AS key
+         FROM sqlite_master m
+        WHERE m.type = 'table' AND m.name NOT LIKE 'sqlite\\_%' ESCAPE '\\'
+        ORDER BY 1`);
+        return rows
+            .filter((r) => !keep.includes(r.name) && !keep.includes(`main.${r.name}`))
+            .map((r) => ({ name: r.name, quoted: this.ident(r.name), key: r.key ? r.key.split("\n") : [] }));
+    }
+    /** DELETE, then forget AUTOINCREMENT counters. Foreign keys are off for this connection only. */
+    async truncate(tables) {
+        if (tables.length === 0)
+            return;
+        const sequence = (await this.query("SELECT 1 FROM sqlite_master WHERE name = 'sqlite_sequence'")).length > 0;
+        const names = tables.map((t) => `'${t.name.replace(/'/g, "''")}'`).join(", ");
+        this.db.exec(`PRAGMA foreign_keys = OFF; BEGIN IMMEDIATE; ${tables.map((t) => `DELETE FROM ${t.quoted};`).join(" ")}` +
+            `${sequence ? ` DELETE FROM sqlite_sequence WHERE name IN (${names});` : ""} COMMIT; PRAGMA foreign_keys = ON;`);
+    }
+    async insert(table, row) {
+        const cols = Object.keys(row);
+        const sql = cols.length === 0
+            ? `INSERT INTO ${this.ident(table)} DEFAULT VALUES RETURNING *`
+            : `INSERT INTO ${this.ident(table)} (${cols.map((c) => this.column(c)).join(", ")}) VALUES (${cols.map((_, i) => `?${i + 1}`).join(", ")}) RETURNING *`;
+        return this.query(sql, Object.values(row));
+    }
+    async describe(table) {
+        const [master] = await this.query("SELECT sql FROM sqlite_master WHERE type = 'table' AND name = ?1", [table]);
+        if (!master)
+            throw new Error(`slicetest: there is no table "${table}"`);
+        const columns = await this.query("SELECT name, type, \"notnull\", dflt_value, pk, hidden FROM pragma_table_xinfo(?1) ORDER BY cid", [table]);
+        const pk = columns.filter((c) => c.pk > 0);
+        // An INTEGER PRIMARY KEY is the rowid: SQLite assigns it.
+        const rowid = pk.length === 1 && pk[0].type.toUpperCase() === "INTEGER" ? pk[0].name : undefined;
+        const keys = await this.query('SELECT id, "table", "from", "to" FROM pragma_foreign_key_list(?1) ORDER BY id, seq', [table]);
+        const foreignKeys = new Map();
+        for (const k of keys) {
+            const fk = foreignKeys.get(k.id) ?? { columns: [], table: k.table, references: [] };
+            fk.columns.push(k.from);
+            if (k.to !== null)
+                fk.references.push(k.to);
+            foreignKeys.set(k.id, fk);
+        }
+        return {
+            columns: columns
+                .filter((c) => c.hidden !== 1)
+                .map((c) => ({
+                name: c.name,
+                type: c.type,
+                nullable: c.notnull === 0 && c.pk === 0,
+                hasDefault: c.dflt_value !== null || c.hidden > 1 || c.name === rowid,
+                maxLength: Number(/\((\d+)\)/.exec(c.type)?.[1]) || undefined,
+            })),
+            foreignKeys: [...foreignKeys.values()],
+            checks: checkBodies(master.sql),
+        };
+    }
+    async close() {
+        this.db.close();
+    }
+}
+class SqliteAdmin {
+    dir;
+    constructor(dir) {
+        this.dir = dir;
+    }
+    #file(name) {
+        return path.join(this.dir, `${name}.db`);
+    }
+    async databases(prefix) {
+        return (await readdir(this.dir)).filter((f) => f.endsWith(".db") && f.startsWith(prefix)).map((f) => f.slice(0, -3));
+    }
+    async create(name) {
+        const db = await openDb(this.#file(name));
+        // Persisted in the file: the app and slicetest can then read and write at the same time.
+        db.exec("PRAGMA journal_mode = WAL");
+        db.close();
+    }
+    async clone(template, name) {
+        const db = await openDb(this.#file(template));
+        try {
+            db.prepare("VACUUM INTO ?").run(this.#file(name));
+        }
+        finally {
+            db.close();
+        }
+        const copy = await openDb(this.#file(name));
+        copy.exec("PRAGMA journal_mode = WAL");
+        copy.close();
+    }
+    async drop(name) {
+        for (const suffix of ["", "-wal", "-shm", "-journal"])
+            await rm(this.#file(name) + suffix, { force: true });
+    }
+    /** A lock file, for runs sharing the directory (with `reuse`). */
+    async withLock(key, fn) {
+        const lock = path.join(this.dir, `${key}.lock`);
+        const deadline = Date.now() + 120_000;
+        for (;;) {
+            try {
+                await (await open(lock, "wx")).close();
+                break;
+            }
+            catch (e) {
+                if (e.code !== "EEXIST" || Date.now() > deadline)
+                    throw e;
+                await new Promise((r) => setTimeout(r, 100));
+            }
+        }
+        try {
+            return await fn();
+        }
+        finally {
+            await rm(lock, { force: true });
+        }
+    }
+    urlFor(name) {
+        return sqliteUrl(this.#file(name));
+    }
+    async close() { }
+}
+export const sqliteEngine = {
+    name: "sqlite",
+    defaultImage: "",
+    local: true,
+    /** No container: a directory of database files, kept between runs with `reuse`. */
+    async startContainer(_image, reuse) {
+        await load();
+        const dir = reuse ? path.join(os.tmpdir(), "slicetest-sqlite") : await mkdtemp(path.join(os.tmpdir(), "slicetest-sqlite-"));
+        await mkdir(dir, { recursive: true });
+        return { url: sqliteUrl(dir), stop: () => rm(dir, { recursive: true, force: true }) };
+    },
+    async admin(url) {
+        const dir = sqlitePath(url);
+        if (!existsSync(dir))
+            await mkdir(dir, { recursive: true });
+        return new SqliteAdmin(dir);
+    },
+    driver: (url) => SqliteDriver.connect(url),
+    atlasUrl: (url) => `sqlite://${sqlitePath(url)}`,
+};

package/dist/factory.d.ts

@@ -0,0 +1,21 @@
+import type { Column, Row, TableShape } from "./drivers/driver.js";
+/**
+ * `db.make()`: rows that satisfy the schema without spelling it out. Required
+ * columns the caller doesn't give get a value of their type, enum and
+ * `CHECK (col IN (...))` columns their first allowed value, and required
+ * foreign keys a parent row made the same way. Values are numbered per
+ * scenario, so they are unique and the same on every run.
+ */
+export declare class Factory {
+    #private;
+    private readonly describe;
+    private readonly insert;
+    constructor(describe: (table: string) => Promise<TableShape>, insert: (table: string, row: Row) => Promise<Row[]>);
+    /** Restart numbering; called when the database is reset. */
+    reset(): void;
+    make(table: string, overrides?: Row, path?: string[]): Promise<Row>;
+}
+/** String literals allowed by a CHECK on `column` such as `status IN ('open', 'closed')` or `status = ANY (ARRAY[...])`. */
+export declare function allowedValues(column: string, checks: string[]): string[] | undefined;
+/** A value of `column`'s type, distinct for each `n`. */
+export declare function valueFor(table: string, column: Column, n: number, allowed?: string[]): unknown;

package/dist/factory.js

@@ -0,0 +1,129 @@
+/**
+ * `db.make()`: rows that satisfy the schema without spelling it out. Required
+ * columns the caller doesn't give get a value of their type, enum and
+ * `CHECK (col IN (...))` columns their first allowed value, and required
+ * foreign keys a parent row made the same way. Values are numbered per
+ * scenario, so they are unique and the same on every run.
+ */
+export class Factory {
+    describe;
+    insert;
+    #n = 0;
+    #shapes = new Map();
+    constructor(describe, insert) {
+        this.describe = describe;
+        this.insert = insert;
+    }
+    /** Restart numbering; called when the database is reset. */
+    reset() {
+        this.#n = 0;
+    }
+    async make(table, overrides = {}, path = []) {
+        const shape = await this.#shape(table);
+        for (const col of Object.keys(overrides)) {
+            if (!shape.columns.some((c) => c.name === col)) {
+                throw new Error(`slicetest: db.make("${table}"): there is no column "${col}" (columns: ${shape.columns.map((c) => c.name).join(", ")})`);
+            }
+        }
+        const n = ++this.#n;
+        const row = { ...overrides };
+        const byName = new Map(shape.columns.map((c) => [c.name, c]));
+        const needed = (name) => {
+            const c = byName.get(name);
+            return !!c && !c.nullable && !c.hasDefault && !(name in row);
+        };
+        for (const fk of shape.foreignKeys) {
+            // Only fill keys that must be set and that the caller left entirely to us.
+            if (!fk.columns.some(needed) || fk.columns.some((c) => c in overrides))
+                continue;
+            if (fk.table === table || path.includes(fk.table)) {
+                const chain = [...path, table, fk.table].join(" → ");
+                throw new Error(`slicetest: db.make("${table}") can't create a parent for ${fk.columns.join(", ")}: the foreign keys form a cycle (${chain}). Pass ${fk.columns.join(", ")} yourself.`);
+            }
+            const parent = await this.make(fk.table, {}, [...path, table]);
+            const refs = fk.references.length ? fk.references : (await this.#primaryKey(fk.table, parent));
+            fk.columns.forEach((c, i) => (row[c] = parent[refs[i]]));
+        }
+        for (const c of shape.columns) {
+            if (needed(c.name))
+                row[c.name] = valueFor(table, c, n, allowedValues(c.name, shape.checks));
+        }
+        try {
+            const [stored] = await this.insert(table, row);
+            return stored ?? row;
+        }
+        catch (e) {
+            const generated = Object.fromEntries(Object.entries(row).filter(([k]) => !(k in overrides)));
+            throw new Error(`slicetest: db.make("${table}") failed: ${e.message}\n` +
+                `  generated: ${JSON.stringify(generated)}\n` +
+                `  pass the columns that need specific values, e.g. db.make("${table}", { ${Object.keys(generated)[0] ?? "column"}: ... })`, { cause: e });
+        }
+    }
+    #shape(table) {
+        let shape = this.#shapes.get(table);
+        if (!shape) {
+            shape = this.describe(table);
+            this.#shapes.set(table, shape);
+            shape.catch(() => this.#shapes.delete(table));
+        }
+        return shape;
+    }
+    /** SQLite foreign keys may omit the referenced columns: they mean the parent's primary key, or its rowid. */
+    async #primaryKey(table, parent) {
+        const shape = await this.#shape(table);
+        const key = shape.columns.filter((c) => c.hasDefault && /^integer$/i.test(c.type)).map((c) => c.name);
+        return key.length ? key : Object.keys(parent).slice(0, 1);
+    }
+}
+/** String literals allowed by a CHECK on `column` such as `status IN ('open', 'closed')` or `status = ANY (ARRAY[...])`. */
+export function allowedValues(column, checks) {
+    const esc = column.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const mention = new RegExp(`(^|[^\\w])[\`"]?${esc}[\`"]?\\)?(::\\w+(\\s\\w+)?)?\\s*(in\\s*\\(|=\\s*any\\s*\\()`, "i");
+    for (const check of checks) {
+        if (!mention.test(check))
+            continue;
+        const literals = [...check.matchAll(/(?:_\w+)?'((?:[^']|'')*)'/g)].map((m) => m[1].replace(/''/g, "'"));
+        if (literals.length)
+            return literals;
+    }
+    return undefined;
+}
+const EPOCH = Date.UTC(2026, 0, 1);
+/** A value of `column`'s type, distinct for each `n`. */
+export function valueFor(table, column, n, allowed) {
+    const values = column.values?.length ? column.values : allowed;
+    if (values?.length)
+        return values[0];
+    const t = column.type.toLowerCase();
+    if (/\[\]$/.test(t))
+        return "{}";
+    if (/^bool/.test(t) || t === "tinyint(1)")
+        return false;
+    if (/uuid/.test(t))
+        return `00000000-0000-4000-8000-${n.toString(16).padStart(12, "0")}`;
+    if (/json/.test(t))
+        return "{}";
+    if (/^(timestamp|datetime)/.test(t))
+        return new Date(EPOCH + n * 1000).toISOString().slice(0, 19).replace("T", " ");
+    if (/^date/.test(t))
+        return new Date(EPOCH + (n - 1) * 86_400_000).toISOString().slice(0, 10);
+    if (/^time/.test(t))
+        return "00:00:00";
+    if (/int|serial|numeric|decimal|real|double|float|money|number/.test(t))
+        return n;
+    if (/bytea|blob|binary/.test(t))
+        return Buffer.from(String(n));
+    if (/^inet/.test(t))
+        return `10.0.${Math.floor(n / 256) % 256}.${n % 256}`;
+    if (t === "" || /char|text|clob|string|citext|name/.test(t))
+        return text(table, column, n);
+    throw new Error(`slicetest: db.make("${table}") doesn't know how to make a value for ${column.name} (${column.type}); pass it yourself: db.make("${table}", { ${column.name}: ... })`);
+}
+function text(table, column, n) {
+    const name = column.name.toLowerCase();
+    let s = /e_?mail/.test(name) ? `${table}-${n}@example.test` : /url|website|link/.test(name) ? `https://example.test/${table}/${n}` : `${column.name}-${n}`;
+    const max = column.maxLength;
+    if (max !== undefined && s.length > max)
+        s = String(n).padStart(max, "0").slice(-max);
+    return s;
+}

package/dist/gen.d.ts

@@ -21,4 +21,5 @@ export declare function gen(root: string, opts: GenOptions): Promise<{
     written: string[];
     skipped: string[];
     count: number;
+    needsAuth: boolean;
 }>;

package/dist/gen.js

@@ -58,7 +58,7 @@ export async function gen(root, opts) {
         await writeFile(file, header + stringify({ scenarios }, { lineWidth: 0, aliasDuplicateObjects: false }));
         written.push(rel);
     }
-    return { written, skipped, count };
+    return { written, skipped, count, needsAuth: ops.some((o) => o.bearer) };
 }
 function scenarioFor(op, key, all) {
     const steps = [];
@@ -80,9 +80,11 @@ function scenarioFor(op, key, all) {
     // Two error responses need no arranging: a made-up id is not found, and an empty body is invalid.
     const notFound = status === 404 && Object.keys(op.pathParams).length > 0;
     const invalid = (status === 400 || status === 422) && isFilledObject(op.json);
-    steps.push(requestStep(invalid ? { ...op, json: {} } : op, pathText, { status }));
+    // A protected operation answers 401 to a request without a token, whatever its state.
+    const unauthenticated = status === 401 && !!op.bearer;
+    steps.push(requestStep(invalid ? { ...op, json: {} } : op, pathText, { status }, undefined, unauthenticated));
     const name = `${op.method} ${op.template} → ${key}${op.summary ? ` (${op.summary})` : ""}`;
-    const runnable = success ? !unresolved : notFound || invalid;
+    const runnable = success ? !unresolved : notFound || invalid || unauthenticated;
     return runnable ? { name, steps } : { name: `${name} — TODO: arrange the state that produces this`, skip: true, steps };
 }
 /**
@@ -99,8 +101,11 @@ function creatorFor(op, param, all) {
     const status = post.responses.filter((k) => /^2\d\d$/.test(k)).sort()[0];
     return field && status ? { op: post, field, status } : undefined;
 }
-function requestStep(op, pathText, expect, capture) {
+function requestStep(op, pathText, expect, capture, anonymous = false) {
     const step = { request: `${op.method} ${pathText}` };
+    // Tokens come from the `auth` issuer; scopes the spec requires go into the `scope` claim.
+    if (op.bearer && !anonymous)
+        step.auth = op.bearer.scopes.length ? { scope: op.bearer.scopes.join(" ") } : true;
     if (Object.keys(op.query).length)
         step.query = Object.fromEntries(Object.entries(op.query).map(([k, v]) => [k, String(v)]));
     if (op.json !== undefined)

package/dist/global-setup.js

@@ -4,6 +4,7 @@ import { mkdir, mkdtemp, readdir, readFile, rm, stat, writeFile } from "node:fs/
 import os from "node:os";
 import path from "node:path";
 import { promisify } from "node:util";
+import { annotation, appendSummary, failureAnnotations, failureSummary, onGitHub, repoPath, yamlFailures } from "./ci.js";
 import { configureContainerRuntime } from "./container-runtime.js";
 import { engineFor } from "./drivers/index.js";
 import { coverageCacheFile } from "./gen.js";
@@ -21,7 +22,8 @@ export default async function setup(project) {
         adminUrl = opts.db.url;
     }
     else {
-        configureContainerRuntime();
+        if (!engine.local)
+            configureContainerRuntime();
         const container = await engine.startContainer(opts.db.image, opts.db.reuse);
         adminUrl = container.url;
         if (!opts.db.reuse)
@@ -50,7 +52,9 @@ export default async function setup(project) {
     // Likewise for recordings made against real services, merged into the recordings files at the end.
     const recording = Object.values(opts.recordings).some((r) => r.record);
     const recordDir = recording ? await mkdtemp(path.join(os.tmpdir(), "slicetest-recordings-")) : undefined;
-    project.provide("slicetestDb", { adminUrl, template, prefix, coverageDir, recordDir });
+    // On GitHub Actions, failed YAML steps are collected here and turned into annotations at the end.
+    const ciDir = onGitHub() ? await mkdtemp(path.join(os.tmpdir(), "slicetest-ci-")) : undefined;
+    project.provide("slicetestDb", { adminUrl, template, prefix, coverageDir, recordDir, ciDir });
     return async () => {
         try {
             if (!stopContainer) {
@@ -66,6 +70,8 @@ export default async function setup(project) {
                 await reportCoverage(opts, coverageDir);
             if (recordDir)
                 await saveRecordings(opts, recordDir);
+            if (ciDir)
+                await reportToGitHub(ciDir);
         }
     };
 }
@@ -85,10 +91,14 @@ async function reportCoverage(opts, dir) {
         const cache = coverageCacheFile(opts.root);
         await mkdir(path.dirname(cache), { recursive: true }).then(() => writeFile(cache, JSON.stringify([...hits]))).catch(() => { });
         console.log(`\n${report.text}\n`);
+        await appendSummary(report.markdown);
         const min = opts.openapi.minCoverage;
         if (min !== undefined && report.percent < min) {
             // Not thrown: Vitest reports teardown errors as a crash. The failing exit code is what CI needs.
-            console.error(`slicetest: OpenAPI coverage ${report.percent}% is below openapi.minCoverage (${min}%)\n`);
+            const message = `OpenAPI coverage ${report.percent}% is below openapi.minCoverage (${min}%)`;
+            console.error(`slicetest: ${message}\n`);
+            if (onGitHub())
+                console.log(annotation("error", message, { file: repoPath(path.resolve(opts.root, opts.openapi.app)), title: "slicetest: OpenAPI coverage" }));
             process.exitCode = 1;
         }
     }
@@ -96,6 +106,17 @@ async function reportCoverage(opts, dir) {
         await rm(dir, { recursive: true, force: true });
     }
 }
+async function reportToGitHub(dir) {
+    try {
+        const failures = await yamlFailures(dir);
+        for (const line of failureAnnotations(failures))
+            console.log(line);
+        await appendSummary(failureSummary(failures));
+    }
+    finally {
+        await rm(dir, { recursive: true, force: true });
+    }
+}
 async function saveRecordings(opts, dir) {
     try {
         const files = await readdir(dir);

package/dist/http.d.ts

@@ -1,3 +1,4 @@
+import { type WebhookOptions } from "./webhook.js";
 export interface HttpResponse {
     method: string;
     url: string;
@@ -37,6 +38,18 @@ export declare class HttpClient {
     post(path: string, body?: unknown, opts?: RequestOptions): Promise<HttpResponse>;
     put(path: string, body?: unknown, opts?: RequestOptions): Promise<HttpResponse>;
     patch(path: string, body?: unknown, opts?: RequestOptions): Promise<HttpResponse>;
+    /**
+     * POST `payload` to the app as `provider` would deliver it, signed with `secret`:
+     * `http.webhook("/webhooks/stripe", event, { provider: "stripe", secret: "whsec_test" })`.
+     * `{ invalidSignature: true }` and `{ stale: true }` make deliveries the app must refuse.
+     */
+    webhook(path: string, payload: unknown, opts: WebhookOptions): Promise<HttpResponse>;
+    /**
+     * Run `send` `n` times at once and wait for every response, to provoke races
+     * (double bookings, lost updates). Pair with `toHaveStatuses({ 201: 1, 409: n - 1 })`
+     * and a check of the database. Requests are released together once all are prepared.
+     */
+    concurrently(n: number, send: (i: number) => Promise<HttpResponse>): Promise<HttpResponse[]>;
     /** Strings, URLSearchParams, FormData, Blob and byte arrays are sent as-is; anything else is sent as JSON. */
     request(method: string, path: string, body?: unknown, options?: RequestOptions): Promise<HttpResponse>;
     /** Call `fn` with every response this client (or one derived with `with()`) receives. */

package/dist/http.js

@@ -1,3 +1,4 @@
+import { signWebhook, webhookBody } from "./webhook.js";
 /** Per-scenario state shared by a client and every client derived from it with `with()`. */
 class Session {
     cookies = new Map();
@@ -41,6 +42,29 @@ export class HttpClient {
     patch(path, body, opts) {
         return this.request("PATCH", path, body, opts);
     }
+    /**
+     * POST `payload` to the app as `provider` would deliver it, signed with `secret`:
+     * `http.webhook("/webhooks/stripe", event, { provider: "stripe", secret: "whsec_test" })`.
+     * `{ invalidSignature: true }` and `{ stale: true }` make deliveries the app must refuse.
+     */
+    webhook(path, payload, opts) {
+        const { body, type } = webhookBody(payload);
+        return this.request("POST", path, body, { headers: { "content-type": type, ...signWebhook(body, opts), ...opts.headers } });
+    }
+    /**
+     * Run `send` `n` times at once and wait for every response, to provoke races
+     * (double bookings, lost updates). Pair with `toHaveStatuses({ 201: 1, 409: n - 1 })`
+     * and a check of the database. Requests are released together once all are prepared.
+     */
+    async concurrently(n, send) {
+        if (!Number.isInteger(n) || n < 1)
+            throw new Error(`slicetest: concurrently() needs a positive number of requests, got ${n}`);
+        let release;
+        const gate = new Promise((r) => (release = r));
+        const all = Promise.all(Array.from({ length: n }, (_, i) => gate.then(() => send(i))));
+        release();
+        return all;
+    }
     /** 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);