slicetest 0.4.0 → 0.6.0

package/dist/drivers/mysql.js

@@ -134,6 +134,44 @@ export class MysqlDriver {
         const conds = Object.keys(where).map((k) => `${this.column(k)} = ?`);
         return this.query(`SELECT * FROM ${this.ident(table)} WHERE ${conds.join(" AND ")}`, Object.values(where));
     }
+    async describe(table) {
+        const [schema, name] = table.includes(".") ? table.split(".", 2) : [null, table];
+        const columns = await this.query(`SELECT COLUMN_NAME AS name, COLUMN_TYPE AS type, IS_NULLABLE AS nullable, COLUMN_DEFAULT AS dflt, EXTRA AS extra,
+              CHARACTER_MAXIMUM_LENGTH AS max
+         FROM information_schema.COLUMNS
+        WHERE TABLE_SCHEMA = COALESCE(?, DATABASE()) AND TABLE_NAME = ?
+        ORDER BY ORDINAL_POSITION`, [schema, name]);
+        if (columns.length === 0)
+            throw new Error(`slicetest: there is no table "${table}"`);
+        const keys = await this.query(`SELECT CONSTRAINT_NAME AS id, COLUMN_NAME AS \`column\`, REFERENCED_TABLE_SCHEMA AS \`schema\`,
+              REFERENCED_TABLE_NAME AS \`table\`, REFERENCED_COLUMN_NAME AS ref, DATABASE() AS current
+         FROM information_schema.KEY_COLUMN_USAGE
+        WHERE TABLE_SCHEMA = COALESCE(?, DATABASE()) AND TABLE_NAME = ? AND REFERENCED_TABLE_NAME IS NOT NULL
+        ORDER BY CONSTRAINT_NAME, ORDINAL_POSITION`, [schema, name]);
+        const foreignKeys = new Map();
+        for (const k of keys) {
+            const fk = foreignKeys.get(k.id) ?? { columns: [], table: k.schema === k.current ? k.table : `${k.schema}.${k.table}`, references: [] };
+            fk.columns.push(k.column);
+            fk.references.push(k.ref);
+            foreignKeys.set(k.id, fk);
+        }
+        const checks = await this.query(`SELECT c.CHECK_CLAUSE AS def
+         FROM information_schema.CHECK_CONSTRAINTS c
+         JOIN information_schema.TABLE_CONSTRAINTS t ON t.CONSTRAINT_SCHEMA = c.CONSTRAINT_SCHEMA AND t.CONSTRAINT_NAME = c.CONSTRAINT_NAME
+        WHERE t.TABLE_SCHEMA = COALESCE(?, DATABASE()) AND t.TABLE_NAME = ?`, [schema, name]);
+        return {
+            columns: columns.map((c) => ({
+                name: c.name,
+                type: c.type,
+                nullable: c.nullable === "YES",
+                hasDefault: c.dflt !== null || /auto_increment|generated/i.test(c.extra),
+                maxLength: c.max === null ? undefined : Number(c.max),
+                values: /^enum\(/i.test(c.type) ? [...c.type.matchAll(/'((?:[^']|'')*)'/g)].map((m) => m[1].replace(/''/g, "'")) : undefined,
+            })),
+            foreignKeys: [...foreignKeys.values()],
+            checks: checks.map((c) => c.def),
+        };
+    }
     async #primaryKey(table) {
         let key = this.#keys.get(table);
         if (!key) {

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

@@ -1,4 +1,4 @@
-import type { Driver, Engine, Row, Table } from "./driver.js";
+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;
@@ -18,6 +18,7 @@ export declare class SqliteDriver implements Driver {
     /** 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

@@ -35,6 +35,27 @@ export function sqliteUrl(file) {
     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;
@@ -117,6 +138,37 @@ export class SqliteDriver {
             : `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();
     }

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/form.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Submitting an HTML form the way a browser with JavaScript off does: every
+ * successful control of the form, plus the button that was pressed. This is
+ * what makes hidden fields work without the test knowing about them: CSRF
+ * tokens (Django, Rails, Laravel) and Next.js / Remix server actions, whose
+ * forms carry the action id and bound arguments in hidden inputs.
+ */
+export interface SubmitOptions {
+    /**
+     * The submit button to press, by its text, `value`, `name` or `id`. Pressing it
+     * also picks its form. Default: the form's only submit button, or none.
+     */
+    button?: string;
+    /** The form, by `id`, `name` or position (0-based), when the page has several and no `button` picks one. */
+    form?: string | number;
+    /** Values typed into the form, by field name. A name the form doesn't have is an error (a typo, usually). */
+    fields?: Record<string, string | number | boolean | (string | number)[]>;
+}
+export interface FormRequest {
+    method: "GET" | "POST";
+    /** Path (and query) relative to the page. */
+    action: string;
+    body?: URLSearchParams | FormData;
+}
+interface Control {
+    tag: "input" | "button" | "select" | "textarea";
+    attrs: Record<string, string>;
+    /** Text content: a button's label, a textarea's value. */
+    text: string;
+    /** For select: its options. */
+    options: {
+        value: string;
+        selected: boolean;
+    }[];
+}
+interface ParsedForm {
+    attrs: Record<string, string>;
+    controls: Control[];
+}
+export declare function decodeEntities(s: string): string;
+/** The forms of a page with their controls, in document order. Controls with a `form="id"` attribute join that form. */
+export declare function parseForms(html: string): ParsedForm[];
+/** Works out the request a browser would send for this page's form. */
+export declare function formRequest(html: string, opts?: SubmitOptions): FormRequest;
+export {};

package/dist/form.js

@@ -0,0 +1,226 @@
+/**
+ * Submitting an HTML form the way a browser with JavaScript off does: every
+ * successful control of the form, plus the button that was pressed. This is
+ * what makes hidden fields work without the test knowing about them: CSRF
+ * tokens (Django, Rails, Laravel) and Next.js / Remix server actions, whose
+ * forms carry the action id and bound arguments in hidden inputs.
+ */
+const TAG = /<!--[\s\S]*?-->|<(\/?)([a-zA-Z][\w-]*)((?:\s+[^\s=>/]+(?:\s*=\s*(?:"[^"]*"|'[^']*'|[^\s>]+))?)*)\s*\/?>/g;
+const ATTR = /([^\s=>/]+)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s>]+)))?/g;
+const RAW_TEXT = new Set(["script", "style", "template"]);
+const ENTITIES = { amp: "&", lt: "<", gt: ">", quot: '"', apos: "'", nbsp: " ", "#39": "'" };
+export function decodeEntities(s) {
+    return s.replace(/&(#x[0-9a-f]+|#\d+|[a-z]+\d*);/gi, (m, e) => {
+        if (e[0] === "#") {
+            const code = e[1] === "x" || e[1] === "X" ? Number.parseInt(e.slice(2), 16) : Number.parseInt(e.slice(1), 10);
+            return Number.isFinite(code) ? String.fromCodePoint(code) : m;
+        }
+        return ENTITIES[e.toLowerCase()] ?? m;
+    });
+}
+function parseAttrs(s) {
+    const attrs = {};
+    for (const m of s.matchAll(ATTR)) {
+        const name = m[1].toLowerCase();
+        if (!(name in attrs))
+            attrs[name] = decodeEntities(m[2] ?? m[3] ?? m[4] ?? "");
+    }
+    return attrs;
+}
+const textOf = (html) => decodeEntities(html.replace(/<[^>]*>/g, "")).replace(/\s+/g, " ").trim();
+/** The forms of a page with their controls, in document order. Controls with a `form="id"` attribute join that form. */
+export function parseForms(html) {
+    const forms = [];
+    const byId = new Map();
+    const orphans = [];
+    let current;
+    let open;
+    let select;
+    let option;
+    const add = (control) => {
+        const formId = control.attrs.form;
+        if (formId !== undefined)
+            orphans.push({ formId, control });
+        else
+            current?.controls.push(control);
+    };
+    const closeOption = (end) => {
+        if (!option || !select)
+            return;
+        const value = option.attrs.value ?? textOf(html.slice(option.start, end));
+        select.options.push({ value, selected: "selected" in option.attrs });
+        option = undefined;
+    };
+    TAG.lastIndex = 0;
+    for (let m = TAG.exec(html); m; m = TAG.exec(html)) {
+        if (!m[2])
+            continue; // comment
+        const closing = m[1] === "/";
+        const tag = m[2].toLowerCase();
+        if (!closing && RAW_TEXT.has(tag)) {
+            const end = html.toLowerCase().indexOf(`</${tag}`, TAG.lastIndex);
+            TAG.lastIndex = end < 0 ? html.length : end;
+            continue;
+        }
+        if (tag === "form") {
+            if (closing)
+                current = undefined;
+            else if (!current) {
+                current = { attrs: parseAttrs(m[3] ?? ""), controls: [] };
+                forms.push(current);
+                if (current.attrs.id)
+                    byId.set(current.attrs.id, current);
+            }
+            continue;
+        }
+        if (tag === "button" || tag === "textarea") {
+            if (closing) {
+                if (open?.control.tag === tag) {
+                    open.control.text = tag === "textarea" ? decodeEntities(html.slice(open.start, m.index)).replace(/^\r?\n/, "") : textOf(html.slice(open.start, m.index));
+                    open = undefined;
+                }
+            }
+            else {
+                const control = { tag, attrs: parseAttrs(m[3] ?? ""), text: "", options: [] };
+                add(control);
+                open = { control, start: TAG.lastIndex };
+                if (tag === "textarea") {
+                    // Its content is text, not markup.
+                    const end = html.toLowerCase().indexOf("</textarea", TAG.lastIndex);
+                    TAG.lastIndex = end < 0 ? html.length : end;
+                }
+            }
+            continue;
+        }
+        if (tag === "select") {
+            if (closing) {
+                closeOption(m.index);
+                select = undefined;
+            }
+            else {
+                select = { tag, attrs: parseAttrs(m[3] ?? ""), text: "", options: [] };
+                add(select);
+            }
+            continue;
+        }
+        if (tag === "option" || tag === "optgroup") {
+            closeOption(m.index);
+            if (tag === "option" && !closing && select)
+                option = { attrs: parseAttrs(m[3] ?? ""), start: TAG.lastIndex };
+            continue;
+        }
+        if (tag === "input" && !closing)
+            add({ tag, attrs: parseAttrs(m[3] ?? ""), text: "", options: [] });
+    }
+    for (const { formId, control } of orphans)
+        byId.get(formId)?.controls.push(control);
+    return forms;
+}
+const isSubmit = (c) => (c.tag === "button" && (c.attrs.type ?? "submit").toLowerCase() === "submit") || (c.tag === "input" && ["submit", "image"].includes((c.attrs.type ?? "").toLowerCase()));
+const label = (c) => (c.tag === "button" ? c.text : (c.attrs.value ?? (c.attrs.type?.toLowerCase() === "image" ? (c.attrs.alt ?? "") : "Submit")));
+function describe(form, i) {
+    const name = form.attrs.id ? `#${form.attrs.id}` : form.attrs.name ? `name=${form.attrs.name}` : `form ${i}`;
+    const buttons = form.controls.filter(isSubmit).map((b) => JSON.stringify(label(b)));
+    return `${name} (${(form.attrs.method ?? "get").toUpperCase()} ${form.attrs.action || "<this page>"}; buttons: ${buttons.join(", ") || "none"})`;
+}
+/** Works out the request a browser would send for this page's form. */
+export function formRequest(html, opts = {}) {
+    const forms = parseForms(html);
+    const list = () => (forms.length ? forms.map((f, i) => `  ${describe(f, i)}`).join("\n") : "  (none)");
+    if (forms.length === 0)
+        throw new Error("slicetest: submit: the page has no <form>");
+    let form;
+    if (opts.form !== undefined) {
+        form = typeof opts.form === "number" ? forms[opts.form] : forms.find((f) => f.attrs.id === opts.form || f.attrs.name === opts.form);
+        if (!form)
+            throw new Error(`slicetest: submit: no form ${JSON.stringify(opts.form)} on the page. Forms:\n${list()}`);
+    }
+    let button;
+    if (opts.button !== undefined) {
+        const want = opts.button.trim();
+        const matches = (b) => [label(b).trim(), b.attrs.value, b.attrs.name, b.attrs.id].includes(want);
+        const candidates = (form ? [form] : forms).flatMap((f) => f.controls.filter((c) => isSubmit(c) && matches(c)).map((c) => ({ f, c })));
+        if (candidates.length === 0)
+            throw new Error(`slicetest: submit: no submit button ${JSON.stringify(want)}${form ? " in that form" : ""}. Forms:\n${list()}`);
+        if (candidates.length > 1 && new Set(candidates.map((x) => x.f)).size > 1) {
+            throw new Error(`slicetest: submit: ${candidates.length} forms have a button ${JSON.stringify(want)}; pick one with \`form\`. Forms:\n${list()}`);
+        }
+        form = candidates[0].f;
+        button = candidates[0].c;
+    }
+    if (!form) {
+        if (forms.length > 1)
+            throw new Error(`slicetest: submit: the page has ${forms.length} forms; pick one with \`button\` or \`form\`. Forms:\n${list()}`);
+        form = forms[0];
+    }
+    if (!button) {
+        const submits = form.controls.filter(isSubmit);
+        if (submits.length === 1)
+            button = submits[0];
+    }
+    if (button && "disabled" in button.attrs)
+        throw new Error(`slicetest: submit: the button ${JSON.stringify(label(button))} is disabled`);
+    const names = new Set(form.controls.filter((c) => c.attrs.name !== undefined && !isSubmit(c) && c.tag !== "button").map((c) => c.attrs.name));
+    const typed = new Map();
+    for (const [name, value] of Object.entries(opts.fields ?? {})) {
+        if (!names.has(name)) {
+            const shown = [...names].filter((n) => !n.startsWith("$ACTION_"));
+            throw new Error(`slicetest: submit: the form has no field "${name}". Fields: ${shown.join(", ") || "(none)"}`);
+        }
+        typed.set(name, typeof value === "boolean" ? value : (Array.isArray(value) ? value : [value]).map(String));
+    }
+    // The successful controls, in document order (HTML's "constructing the entry list").
+    // A typed value replaces what the page had: text for a field, the checked state for
+    // checkboxes and radios (true / false, or the values to check), the options of a select.
+    const entries = [];
+    const done = new Set();
+    for (const c of form.controls) {
+        const name = c.attrs.name;
+        if (name === undefined || "disabled" in c.attrs)
+            continue;
+        if (c.tag === "button" || isSubmit(c)) {
+            if (c === button)
+                entries.push([name, c.attrs.value ?? ""]);
+            continue;
+        }
+        const type = c.tag === "input" ? (c.attrs.type ?? "text").toLowerCase() : c.tag;
+        if (type === "reset" || type === "button" || type === "file")
+            continue;
+        const want = typed.get(name);
+        if (type === "checkbox" || type === "radio") {
+            const value = c.attrs.value ?? "on";
+            const checked = want === undefined ? "checked" in c.attrs : typeof want === "boolean" ? want : want.includes(value);
+            if (checked)
+                entries.push([name, value]);
+        }
+        else if (want !== undefined) {
+            // Every value goes out at the first control of that name.
+            if (!done.has(name))
+                for (const v of want === true ? ["on"] : want === false ? [] : want)
+                    entries.push([name, v]);
+            done.add(name);
+        }
+        else if (c.tag === "textarea")
+            entries.push([name, c.text]);
+        else if (c.tag === "select") {
+            const selected = c.options.filter((o) => o.selected);
+            const chosen = selected.length ? selected : "multiple" in c.attrs || c.options.length === 0 ? [] : [c.options[0]];
+            for (const o of chosen)
+                entries.push([name, o.value]);
+        }
+        else
+            entries.push([name, c.attrs.value ?? ""]);
+    }
+    const pick = (attr) => (button && button.attrs[`form${attr}`] !== undefined ? button.attrs[`form${attr}`] : form.attrs[attr]);
+    const method = (pick("method") ?? "get").toUpperCase() === "POST" ? "POST" : "GET";
+    const action = pick("action") ?? "";
+    if (method === "GET")
+        return { method, action: `${action.replace(/[?#].*$/, "")}?${new URLSearchParams(entries)}` };
+    const multipart = (pick("enctype") ?? "").toLowerCase() === "multipart/form-data";
+    if (!multipart)
+        return { method, action, body: new URLSearchParams(entries) };
+    const body = new FormData();
+    for (const [k, v] of entries)
+        body.append(k, v);
+    return { method, action, body };
+}

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.d.ts

@@ -13,3 +13,4 @@ export declare function migrationKey(opts: Pick<ResolvedOptions, "db" | "root">)
  * Windows drive paths) are made relative to the root, which is the cwd Atlas runs in.
  */
 export declare function atlasDirUrl(dir: string, root: string): string;
+export declare function buildAll(opts: Pick<ResolvedOptions, "app" | "services" | "root">): Promise<void>;