slicetest 0.7.0 → 0.9.0

package/dist/yaml-runtime.js

@@ -5,6 +5,8 @@ import { formatChanges } from "./db.js";
 import "./matchers.js";
 import { scenario } from "./scenario.js";
 import { signWebhook, webhookBody } from "./webhook.js";
+import { readFile } from "node:fs/promises";
+import { parse as parseYaml } from "yaml";
 import path from "node:path";
 import { graphqlErrors } from "./graphql.js";
 import { schemaProblems } from "./schema.js";
@@ -16,7 +18,10 @@ export function defineYamlScenarios(doc) {
         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);
+            register(title, (ctx) => {
+                seq = 0;
+                return runSteps(doc, sc, [...doc.setup, ...sc.steps], ctx, { ...row });
+            }, { timeout: sc.timeout, tags: sc.tags });
         });
     }
 }
@@ -35,7 +40,8 @@ async function runSteps(doc, sc, steps, ctx, vars, trail = []) {
         try {
             // A log step waits by itself; `within` is its timeout.
             // Log and mail steps wait by themselves; `within` is their timeout.
-            await retry("within" in step && !("log" in step) && !("mail" in step) ? step.within : undefined, () => runStep(step, ctx, vars, doc.path ? path.dirname(doc.path) : undefined));
+            // Requests poll the app (`every` ms, default 200): a job answered 202 until it's done.
+            await retry("within" in step && !("log" in step) && !("mail" in step) ? step.within : undefined, () => runStep(step, ctx, vars, doc.path ? path.dirname(doc.path) : undefined), "request" in step ? (step.every ?? 200) : 50);
         }
         catch (e) {
             const label = step.name ?? describeStep(step);
@@ -76,6 +82,10 @@ function describeStep(step) {
         return "changes";
     if ("checkpoint" in step)
         return "checkpoint";
+    if ("set" in step)
+        return `set ${Object.keys(step.set).join(", ")}`;
+    if ("order" in step)
+        return `order ${step.order.map((o) => (typeof o === "string" ? o : `${o.stub} ${o.call}`)).join(" → ")}`;
     if ("snapshot" in step)
         return "snapshot";
     if ("mail" in step)
@@ -85,7 +95,7 @@ function describeStep(step) {
     return "sql";
 }
 /** Run `fn` until it passes or `within` ms have passed, then rethrow its last error. */
-async function retry(within, fn) {
+async function retry(within, fn, every = 50) {
     if (!within)
         return fn();
     const deadline = Date.now() + within;
@@ -99,13 +109,27 @@ async function retry(within, fn) {
                     e.message = `${e.message}\n(still failing after retrying for ${within}ms)`;
                 throw e;
             }
-            await new Promise((r) => setTimeout(r, 50));
+            await new Promise((r) => setTimeout(r, every));
         }
     }
 }
 async function runStep(step, ctx, vars, base) {
     if ("use" in step)
         throw new Error("slicetest: use steps are expanded by runSteps");
+    if ("order" in step) {
+        const calls = step.order.map((o) => {
+            const [name, call, when] = typeof o === "string" ? [o.slice(0, o.search(/\s/)), o.slice(o.search(/\s/)).trim(), undefined] : [o.stub, o.call, o.when];
+            const [method, p] = splitCall(interpolate(call, vars));
+            return [name, method, p, conditions(when, vars)];
+        });
+        expect(ctx.stub).toHaveReceivedInOrder(calls);
+        return;
+    }
+    if ("set" in step) {
+        for (const [k, v] of Object.entries(step.set))
+            vars[k] = interpolate(v, vars);
+        return;
+    }
     if ("checkpoint" in step) {
         await ctx.db.checkpoint();
         return;
@@ -138,7 +162,7 @@ async function runStep(step, ctx, vars, base) {
         return;
     }
     if ("changes" in step) {
-        const actual = await ctx.db.changes();
+        const actual = await ctx.db.changes({ ignore: step.ignore });
         const expected = interpolate(step.changes, vars);
         const unexpected = Object.keys(actual).filter((t) => !(t in expected));
         if (unexpected.length) {
@@ -179,8 +203,10 @@ async function runStep(step, ctx, vars, base) {
         if (step.optional)
             route = route.optional();
         // Replies are interpolated when a call arrives, so they can echo it: {{call.params.id}}, {{call.json.name}}, {{call.variables.id}}.
-        const answer = (template) => (call) => {
-            const { sse: events, data, errors, ...response } = interpolate(template, { ...vars, call: callVars(call) });
+        const answer = (prepared) => (call) => {
+            const { sse: events, data, errors, ...response } = interpolate(prepared.template, { ...vars, call: callVars(call) });
+            if (prepared.bytes)
+                return { ...response, body: prepared.bytes };
             if (data !== undefined || errors !== undefined) {
                 return { status: 200, ...response, body: { ...(errors ? { errors: graphqlErrors(errors) } : {}), ...(data !== undefined ? { data } : {}) } };
             }
@@ -190,11 +216,11 @@ async function runStep(step, ctx, vars, base) {
             route.networkError();
         else if (step.sequence) {
             let n = 0;
-            const seq = step.sequence;
+            const seq = await Promise.all(step.sequence.map((r) => prepareReply(r, vars, base)));
             route.reply((call) => answer(seq[Math.min(n++, seq.length - 1)])(call));
         }
         else
-            route.reply(answer(step.reply ?? {}));
+            route.reply(answer(await prepareReply(step.reply ?? {}, vars, base)));
         return;
     }
     if ("submit" in step) {
@@ -204,12 +230,12 @@ async function runStep(step, ctx, vars, base) {
         const res = await ctx.http.submit(page, {
             button: step.submit === true ? undefined : interpolate(step.submit, vars),
             form: interpolate(step.form, vars),
-            fields: interpolate(step.fields, vars),
+            fields: await withFiles(interpolate(step.fields, vars), base),
             headers: interpolate(step.headers, vars),
             follow: step.follow,
         });
         verifyResponse(res, step.expect, vars, base);
-        capture(step.capture, { status: res.status, json: res.json, text: res.text, headers: Object.fromEntries(res.headers) }, vars);
+        capture(step.capture, { status: res.status, json: res.json, text: res.text, headers: Object.fromEntries(res.headers), events: res.events }, vars);
         return;
     }
     if ("request" in step) {
@@ -220,6 +246,7 @@ async function runStep(step, ctx, vars, base) {
             headers: step.auth ? { ...ctx.auth.header(step.auth === true ? {} : interpolate(step.auth, vars)), ...headers } : headers,
             query: interpolate(step.query, vars),
             follow: step.follow,
+            ...(step.timeout !== undefined ? { timeout: step.timeout } : {}),
         };
         const gql = step.graphql === undefined ? undefined : interpolate(typeof step.graphql === "string" ? { query: step.graphql } : step.graphql, vars);
         let body = gql !== undefined
@@ -228,11 +255,17 @@ async function runStep(step, ctx, vars, base) {
                 ? interpolate(step.json, vars)
                 : step.form !== undefined
                     ? ctx.http.form(interpolate(step.form, vars))
-                    : interpolate(step.body, vars);
+                    : step.multipart !== undefined
+                        ? await multipart(interpolate(step.multipart, vars), base)
+                        : interpolate(step.body, vars);
         if (step.webhook) {
-            const signed = webhookBody(body);
+            const hook = interpolate(step.webhook, vars);
+            const signed = webhookBody(body, hook.provider);
             body = signed.body;
-            opts.headers = { "content-type": signed.type, ...signWebhook(signed.body, interpolate(step.webhook, vars)), ...opts.headers };
+            const url = new URL(path, ctx.http.baseUrl);
+            for (const [k, v] of Object.entries(opts.query ?? {}))
+                url.searchParams.set(k, String(v));
+            opts.headers = { "content-type": signed.type, ...signWebhook(signed.body, { url: url.href, ...hook }), ...opts.headers };
         }
         const e = step.expect;
         const verify = (res) => {
@@ -263,7 +296,7 @@ async function runStep(step, ctx, vars, base) {
             }
         }
         verify(res);
-        capture(step.capture, { status: res.status, json: res.json, text: res.text, headers: Object.fromEntries(res.headers) }, vars);
+        capture(step.capture, { status: res.status, json: res.json, text: res.text, headers: Object.fromEntries(res.headers), events: res.events }, vars);
         return;
     }
     if ("insert" in step) {
@@ -351,10 +384,82 @@ function callVars(call) {
         query: Object.fromEntries(call.query),
         headers: call.headers,
         json: call.json,
+        form: call.form,
         body: call.body,
         variables: call.graphql?.variables,
     };
 }
+const TEXT_FILE = /^(text\/|application\/(xml|javascript)|image\/svg)/;
+/** A reply with `file:` read once: JSON and YAML become the body (still templated), other text as a string, the rest as bytes. */
+async function prepareReply(reply, vars, base = process.cwd()) {
+    if (typeof reply.file !== "string")
+        return { template: reply };
+    const { file: name, ...rest } = reply;
+    const file = path.resolve(base, interpolate(name, vars));
+    const bytes = await readFile(file).catch(() => {
+        throw new Error(`reply file: can't read ${file}`);
+    });
+    const ext = path.extname(file).toLowerCase();
+    const headers = { ...rest.headers };
+    const hasType = Object.keys(headers).some((h) => h.toLowerCase() === "content-type");
+    if (ext === ".json" || ext === ".yaml" || ext === ".yml") {
+        let body;
+        try {
+            body = ext === ".json" ? JSON.parse(bytes.toString("utf8")) : parseYaml(bytes.toString("utf8"));
+        }
+        catch (e) {
+            throw new Error(`reply file ${file}: ${e.message}`);
+        }
+        return { template: { ...rest, headers, body } };
+    }
+    const type = MIME[ext] ?? "application/octet-stream";
+    if (!hasType)
+        headers["content-type"] = type;
+    if (TEXT_FILE.test(type))
+        return { template: { ...rest, headers, body: bytes.toString("utf8") } };
+    return { template: { ...rest, headers }, bytes: new Uint8Array(bytes) };
+}
+const MIME = {
+    ".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".gif": "image/gif", ".webp": "image/webp", ".svg": "image/svg+xml",
+    ".pdf": "application/pdf", ".json": "application/json", ".csv": "text/csv", ".txt": "text/plain", ".xml": "application/xml",
+    ".zip": "application/zip", ".html": "text/html", ".md": "text/markdown", ".yaml": "text/yaml", ".yml": "text/yaml",
+};
+/** A `{ file }` / `{ content }` part as a File: files are read relative to the scenario file. */
+async function toFile(name, p, base = process.cwd()) {
+    if (p.file !== undefined) {
+        const file = path.resolve(base, p.file);
+        const bytes = await readFile(file).catch(() => {
+            throw new Error(`field "${name}": can't read ${file}`);
+        });
+        const type = p.type ?? MIME[path.extname(file).toLowerCase()] ?? "application/octet-stream";
+        return new File([new Uint8Array(bytes)], p.filename ?? path.basename(file), { type });
+    }
+    const content = typeof p.content === "string" ? p.content : JSON.stringify(p.content);
+    return new File([content], p.filename ?? name, { type: p.type ?? (typeof p.content === "string" ? "text/plain" : "application/json") });
+}
+/** A YAML `multipart:` mapping as FormData. */
+async function multipart(fields, base) {
+    const data = new FormData();
+    for (const [name, value] of Object.entries(fields)) {
+        for (const part of Array.isArray(value) ? value : [value]) {
+            if (part && typeof part === "object")
+                data.append(name, await toFile(name, part, base));
+            else
+                data.append(name, String(part));
+        }
+    }
+    return data;
+}
+/** Submit fields with `{ file }` / `{ content }` values turned into Files. */
+async function withFiles(fields, base) {
+    if (!fields)
+        return undefined;
+    const out = {};
+    for (const [name, v] of Object.entries(fields)) {
+        out[name] = v && typeof v === "object" && !Array.isArray(v) ? await toFile(name, v, base) : v;
+    }
+    return out;
+}
 function splitCall(s) {
     const i = s.search(/\s/);
     return [s.slice(0, i).toUpperCase(), s.slice(i).trim()];
@@ -390,7 +495,40 @@ export function interpolate(value, vars) {
     }
     return value;
 }
+/** `{{$seq}}`: 1, 2, 3… within a scenario, so generated values are unique and the same on every run. */
+let seq = 0;
+const OFFSET = /^\$(now|today|timestamp|timestampMs)\s*(?:([+-])\s*(\d+)\s*(ms|s|m|h|d))?$/;
+const UNIT_MS = { ms: 1, s: 1000, m: 60_000, h: 3_600_000, d: 86_400_000 };
+/** Built-in values: `$uuid`, `$seq`, `$now`, `$today`, `$timestamp`, `$timestampMs` (the last four with `+1d`, `-30m`, …). */
+function builtin(name) {
+    if (name === "$uuid")
+        return crypto.randomUUID();
+    if (name === "$seq")
+        return ++seq;
+    const m = OFFSET.exec(name);
+    if (!m)
+        throw new Error(`unknown built-in {{${name}}} (available: $uuid, $seq, $now, $today, $timestamp, $timestampMs; the time ones take an offset such as $now+1d or $timestamp-30m)`);
+    const t = Date.now() + (m[2] ? (m[2] === "-" ? -1 : 1) * Number(m[3]) * UNIT_MS[m[4]] : 0);
+    switch (m[1]) {
+        case "now":
+            return new Date(t).toISOString();
+        case "today":
+            return new Date(t).toISOString().slice(0, 10);
+        case "timestamp":
+            return Math.floor(t / 1000);
+        default:
+            return t;
+    }
+}
 function resolve(name, vars) {
+    if (name.startsWith("$"))
+        return builtin(name);
+    if (name.startsWith("env.") && !("env" in vars)) {
+        const v = process.env[name.slice(4)];
+        if (v === undefined)
+            throw new Error(`{{${name}}}: the environment variable ${name.slice(4)} isn't set`);
+        return v;
+    }
     const v = lookup(vars, name);
     if (v === undefined) {
         const known = Object.keys(vars).filter((k) => k !== "call");
@@ -405,9 +543,107 @@ const TYPES = {
     array: expect.any(Array),
     object: expect.any(Object),
 };
+const FORMATS = {
+    uuid: /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i,
+    email: /^[^\s@]+@[^\s@]+\.[^\s@]+$/,
+    date: /^\d{4}-\d{2}-\d{2}$/,
+    "date-time": /^\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:?\d{2})?$/i,
+    uri: /^[a-z][a-z0-9+.-]*:\/\/\S+$/i,
+    integer: /^-?\d+$/,
+};
+const MATCHERS = ["$type", "$regex", "$contains", "$any", "$gt", "$gte", "$lt", "$lte", "$closeTo", "$len", "$not", "$oneOf", "$format"];
+/** An asymmetric matcher Vitest's `toEqual` / `toMatchObject` call, with a readable name in diffs. */
+function matcher(name, test) {
+    return { asymmetricMatch: test, toAsymmetricMatcher: () => name, toString: () => name };
+}
+/** A decimal as Postgres `numeric` and MySQL `DECIMAL` columns come back, to keep their precision: `"12.50"`. */
+const DECIMAL = /^-?\d+(\.\d+)?$/;
+/**
+ * Numbers compare as numbers, also with decimal strings from `numeric` / `DECIMAL` columns; strings
+ * (ISO dates, versions) compare as strings; anything else never matches.
+ */
+function compare(op, arg, holds) {
+    if (typeof arg !== "number" && typeof arg !== "string")
+        throw new Error(`${op} takes a number or a string, got ${JSON.stringify(arg)}`);
+    return matcher(`${op} ${JSON.stringify(arg)}`, (v) => {
+        if (typeof arg === "number")
+            return (typeof v === "number" || (typeof v === "string" && DECIMAL.test(v))) && holds(Number(v) - arg);
+        return typeof v === "string" && holds(v < arg ? -1 : v > arg ? 1 : 0);
+    });
+}
+function equalsMatcher(expected, actual) {
+    return isAsymmetric(expected) ? expected.asymmetricMatch(actual) : subsetEquals(expected, actual);
+}
+/** `expected` contained in `actual`, with matchers anywhere: the rules of expected JSON. */
+function subsetEquals(expected, actual) {
+    if (isAsymmetric(expected))
+        return expected.asymmetricMatch(actual);
+    if (Array.isArray(expected))
+        return Array.isArray(actual) && actual.length === expected.length && expected.every((e, i) => subsetEquals(e, actual[i]));
+    if (expected && typeof expected === "object") {
+        return !!actual && typeof actual === "object" && Object.entries(expected).every(([k, v]) => k in actual && subsetEquals(v, actual[k]));
+    }
+    return Object.is(expected, actual) || expected === actual;
+}
+function single(key, arg) {
+    switch (key) {
+        case "$type":
+            if (arg === "null")
+                return null;
+            if (arg === "integer")
+                return matcher("$type integer", (v) => Number.isInteger(v));
+            if (typeof arg === "string" && arg in TYPES)
+                return TYPES[arg];
+            throw new Error(`$type must be one of ${Object.keys(TYPES).join(", ")}, integer, null`);
+        case "$regex":
+            return expect.stringMatching(new RegExp(String(arg)));
+        case "$contains":
+            return matcher(`$contains ${JSON.stringify(arg)}`, (v) => typeof v === "string" ? v.includes(String(arg)) : Array.isArray(v) ? v.some((item) => equalsMatcher(toMatchers(arg), item)) : false);
+        case "$any":
+            return expect.anything();
+        case "$gt":
+            return compare(key, arg, (c) => c > 0);
+        case "$gte":
+            return compare(key, arg, (c) => c >= 0);
+        case "$lt":
+            return compare(key, arg, (c) => c < 0);
+        case "$lte":
+            return compare(key, arg, (c) => c <= 0);
+        case "$closeTo": {
+            // `$closeTo: 9.99` allows ±0.005 (two decimals, like toBeCloseTo); `$closeTo: [9.99, 0.1]` sets the tolerance.
+            const [target, tolerance = 0.005] = Array.isArray(arg) ? arg : [arg];
+            if (typeof target !== "number" || typeof tolerance !== "number" || !(tolerance >= 0))
+                throw new Error(`$closeTo takes a number or [number, tolerance], got ${JSON.stringify(arg)}`);
+            return matcher(`$closeTo ${JSON.stringify(arg)}`, (v) => (typeof v === "number" || (typeof v === "string" && DECIMAL.test(v))) && Math.abs(Number(v) - target) <= tolerance + Number.EPSILON);
+        }
+        case "$len": {
+            const want = toMatchers(arg);
+            return matcher(`$len ${JSON.stringify(arg)}`, (v) => (typeof v === "string" || Array.isArray(v)) && equalsMatcher(want, v.length));
+        }
+        case "$not": {
+            const want = toMatchers(arg);
+            return matcher(`$not ${JSON.stringify(arg)}`, (v) => !equalsMatcher(want, v));
+        }
+        case "$oneOf": {
+            if (!Array.isArray(arg))
+                throw new Error(`$oneOf takes a list, got ${JSON.stringify(arg)}`);
+            const options = arg.map(toMatchers);
+            return matcher(`$oneOf ${JSON.stringify(arg)}`, (v) => options.some((o) => equalsMatcher(o, v)));
+        }
+        case "$format": {
+            const re = FORMATS[String(arg)];
+            if (!re)
+                throw new Error(`$format must be one of ${Object.keys(FORMATS).join(", ")}`);
+            return matcher(`$format ${arg}`, (v) => typeof v === "string" && re.test(v));
+        }
+        default:
+            throw new Error(`unknown matcher ${key} (expected one of ${MATCHERS.join(", ")})`);
+    }
+}
 /**
- * `{ $type: number }`, `{ $regex: "^ch_" }`, `{ $contains: "x" }` and
- * `{ $any: true }` become Vitest asymmetric matchers.
+ * `{ $type: number }`, `{ $regex: "^ch_" }`, `{ $contains: "x" }`, `{ $any: true }`,
+ * `{ $gte: 1, $lt: 10 }`, `{ $len: 3 }`, `{ $not: … }`, `{ $oneOf: [...] }` and
+ * `{ $format: uuid }` become Vitest asymmetric matchers. Several `$` keys must all hold.
  */
 export function toMatchers(value) {
     if (Array.isArray(value))
@@ -415,25 +651,11 @@ export function toMatchers(value) {
     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)`);
-        }
+    if (keys.length > 0 && keys.every((k) => k.startsWith("$"))) {
+        const parts = keys.map((k) => single(k, value[k]));
+        if (parts.length === 1)
+            return parts[0];
+        return matcher(keys.map((k) => `${k} ${JSON.stringify(value[k])}`).join(", "), (v) => parts.every((p) => equalsMatcher(p, v)));
     }
     return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, toMatchers(v)]));
 }
@@ -459,6 +681,35 @@ function verifyResponse(res, e, vars, base) {
         check(res.json, e.json, vars, "response JSON");
     if (e?.text !== undefined)
         check(res.text, e.text, vars, "response text");
+    if (e?.events !== undefined) {
+        if (!res.events)
+            throw new Error(`${res.method} ${res.url}: expected server-sent events, but the response is ${res.headers.get("content-type") ?? "without a content type"}, not text/event-stream`);
+        const wanted = toMatchers(interpolate(e.events, vars));
+        let at = 0;
+        for (const [i, want] of wanted.entries()) {
+            const found = res.events.findIndex((ev, j) => j >= at && subsetEquals(want, ev));
+            if (found < 0) {
+                const shown = res.events.slice(0, 20).map((ev, j) => `  ${j}: ${JSON.stringify(ev).slice(0, 200)}`).join("\n");
+                throw new Error(`${res.method} ${res.url}: expected event ${i + 1} of ${wanted.length}, ${JSON.stringify(e.events[i])}, ${at > 0 ? `after event ${at - 1}` : "in the stream"}; ${res.events.length} event(s) arrived:\n${shown || "  (none)"}${res.events.length > 20 ? "\n  …" : ""}`);
+            }
+            at = found + 1;
+        }
+    }
+    if (e?.cookies !== undefined) {
+        for (const [name, attrs] of Object.entries(e.cookies)) {
+            if (attrs === null)
+                expect(res).not.toSetCookie(name);
+            else
+                expect(res).toSetCookie(name, toMatchers(interpolate(attrs, vars)));
+        }
+    }
+    if (e?.duration !== undefined) {
+        const want = interpolate(e.duration, vars);
+        if (typeof want === "number")
+            expect(res).toRespondWithin(want);
+        else
+            check(res.durationMs, want, vars, `${res.method} ${res.url} response time (${res.durationMs}ms)`);
+    }
     if (e?.schema !== undefined) {
         const problems = schemaProblems(e.schema, res.json, base);
         if (problems.length)

package/dist/yaml.d.ts

@@ -24,9 +24,11 @@ export interface YamlScenario {
     skip?: boolean;
     only?: boolean;
     timeout?: number;
+    /** Labels to select scenarios by (`npx slicetest --tag smoke`). */
+    tags?: string[];
     steps: Step[];
 }
-export type Step = (StubStep | RequestStep | SubmitStep | InsertStep | MakeStep | ChaosStep | SqlStep | DbStep | ReceivedStep | ChangesStep | CheckpointStep | LogStep | SnapshotStep | MailStep | UseStep) & {
+export type Step = (StubStep | RequestStep | SubmitStep | InsertStep | MakeStep | ChaosStep | SqlStep | DbStep | ReceivedStep | ChangesStep | CheckpointStep | SetStep | OrderStep | LogStep | SnapshotStep | MailStep | UseStep) & {
     line: number;
     name?: string;
 };
@@ -49,10 +51,12 @@ export interface StubStep {
     graphql?: string;
     when?: Conditions;
     /** `sse`: a streamed reply, a list of { event, data, id } (instead of `body`). */
+    /** `file`: the body from a file relative to the scenario (.json / .yaml as JSON, with `{{call.*}}`; others as they are). */
     reply?: {
         status?: number;
         headers?: Record<string, string>;
         body?: unknown;
+        file?: string;
         sse?: {
             event?: string;
             data: unknown;
@@ -63,6 +67,7 @@ export interface StubStep {
         status?: number;
         headers?: Record<string, string>;
         body?: unknown;
+        file?: string;
         sse?: {
             event?: string;
             data: unknown;
@@ -79,6 +84,8 @@ export interface Conditions {
     query?: Record<string, unknown>;
     headers?: Record<string, unknown>;
     json?: unknown;
+    /** Subset of a form-encoded body's fields, bracket keys nested (`metadata[order]` → `metadata: { order }`). */
+    form?: Record<string, unknown>;
     body?: unknown;
     /** Subset of a GraphQL request's variables (with `graphql`). */
     variables?: unknown;
@@ -89,6 +96,8 @@ export interface RequestStep {
     query?: Record<string, unknown>;
     json?: unknown;
     form?: Record<string, unknown>;
+    /** A `multipart/form-data` body: values are fields, `{ file, type, filename }` uploads a file relative to the scenario, `{ content, filename, type }` an inline one. */
+    multipart?: Record<string, unknown>;
     body?: string;
     /** A GraphQL operation sent as the JSON body. */
     graphql?: string | {
@@ -114,10 +123,19 @@ export interface RequestStep {
     };
     /** Send the request this many times at once. `expect` applies to every response; `statuses` counts them. */
     concurrency?: number;
+    /** Repeat the request until `expect` passes, for up to this many ms: polling a job the app finishes later. */
+    within?: number;
+    /** With `within`: ms between attempts. Default 200. */
+    every?: number;
+    /** Fail when the app hasn't answered within this many ms (overrides `http.timeout`). */
+    timeout?: number;
     /** `queries`: at most this many SQL statements (not counting BEGIN/COMMIT), with `db.queries` on. */
     /** `schema`: a JSON Schema for the response JSON, inline or `file#/pointer` relative to the scenario file. */
     expect?: {
-        status?: number;
+        events?: Record<string, unknown>[];
+        cookies?: Record<string, Record<string, unknown> | null>;
+        duration?: number | Record<string, unknown>;
+        status?: number | string | (number | string)[];
         statuses?: Record<string, number>;
         headers?: Record<string, unknown>;
         json?: unknown;
@@ -136,11 +154,15 @@ export interface SubmitStep {
     /** The form by id, name or 0-based position, when the page has several. */
     form?: string | number;
     /** Values typed into the form by field name; true / false / a list check checkboxes and radios. */
-    fields?: Record<string, string | number | boolean | (string | number)[]>;
+    /** `{ file: path }` (relative to the scenario) or `{ content, filename, type }` for a file input. */
+    fields?: Record<string, string | number | boolean | (string | number)[] | FilePart>;
     headers?: Record<string, string>;
     follow?: boolean;
     expect?: {
-        status?: number;
+        events?: Record<string, unknown>[];
+        cookies?: Record<string, Record<string, unknown> | null>;
+        duration?: number | Record<string, unknown>;
+        status?: number | string | (number | string)[];
         headers?: Record<string, unknown>;
         json?: unknown;
         text?: unknown;
@@ -216,6 +238,8 @@ export type ChangeSpec = {
 export interface ChangesStep {
     changes: Record<string, ChangeSpec>;
     within?: number;
+    /** Columns or tables to leave out: `updated_at`, `orders.synced_at`, `sessions.*`. */
+    ignore?: string[];
 }
 /** Wait until the app (or `from:` a service) prints a line matching `log` (a regex) during the scenario. */
 export interface LogStep {
@@ -224,6 +248,29 @@ export interface LogStep {
     /** Milliseconds to wait. Default 5000. */
     within?: number;
 }
+/**
+ * Calls to stubs happened in this order (others may come in between):
+ * `order: ["stripe POST /v1/charges", { stub: mail, call: POST /send, when: { json: { to: a@b.test } } }]`.
+ */
+export interface OrderStep {
+    order: (string | {
+        stub: string;
+        call: string;
+        when?: Conditions;
+    })[];
+    within?: number;
+}
+/** A file to upload: read from `file` (relative to the scenario file), or `content` given inline. */
+export interface FilePart {
+    file?: string;
+    content?: unknown;
+    filename?: string;
+    type?: string;
+}
+/** Define variables for later steps: `set: { orderId: "{{$uuid}}" }`. */
+export interface SetStep {
+    set: Record<string, unknown>;
+}
 /** Later `changes` steps only see what happens after this step. */
 export interface CheckpointStep {
     checkpoint: true;