slicetest 0.8.0 → 0.10.0

package/dist/openapi.js

@@ -5,11 +5,17 @@ import addFormatsModule from "ajv-formats";
 import { parse } from "yaml";
 const addFormats = (addFormatsModule.default ?? addFormatsModule);
 const METHODS = ["get", "put", "post", "delete", "options", "head", "patch", "trace"];
-/**
- * An OpenAPI 3.0 / 3.1 document, used to check that real traffic matches it:
- * the app's responses against the app's own spec, and the app's calls to a
- * stubbed service (and the stub's canned replies) against that service's spec.
- */
+/** A server's URL with its `{variables}` filled in: every `enum` value, else the default. */
+function serverUrls(server) {
+    let urls = [server.url ?? "/"];
+    for (const [name, v] of Object.entries(server.variables ?? {})) {
+        const values = [...new Set([...(v.default === undefined ? [] : [v.default]), ...(v.enum ?? [])].map(String))];
+        if (values.length === 0 || !urls[0].includes(`{${name}}`))
+            continue;
+        urls = urls.flatMap((u) => values.map((value) => u.replaceAll(`{${name}}`, value))).slice(0, 50);
+    }
+    return urls;
+}
 export class OpenApiSpec {
     file;
     doc;
@@ -45,7 +51,8 @@ export class OpenApiSpec {
         // Paths in the spec are relative to the server URL, e.g. /v1 for https://api.example.com/v1.
         this.#basePaths = [
             ...new Set((doc.servers ?? [])
-                .map((s) => new URL(s.url ?? "/", "http://x").pathname.replace(/\/$/, ""))
+                .flatMap((s) => serverUrls(s))
+                .map((url) => new URL(url, "http://x").pathname.replace(/\/$/, ""))
                 .filter(Boolean)),
         ];
     }
@@ -105,7 +112,8 @@ export class OpenApiSpec {
         if (!key)
             return [`${method} ${template} responded ${status}, which ${this.file} doesn't document (documented: ${Object.keys(responses).join(", ") || "none"})`];
         const [response, at] = this.#resolve(responses[key], ["paths", template, found.method, "responses", key]);
-        return this.#checkContent(response?.content, res, [...at, "content"], `${method} ${template} → ${status}`);
+        const label = `${method} ${template} → ${status}`;
+        return [...this.#checkHeaders(label, response?.headers, [...at, "headers"], res.headers), ...this.#checkContent(response?.content, res, [...at, "content"], label)];
     }
     /**
      * A response the real service could send to `method path`: the lowest
@@ -126,8 +134,13 @@ export class OpenApiSpec {
         const response = this.#deref(responses[key]);
         const content = response?.content ?? {};
         const media = Object.keys(content).find(isJson) ?? Object.keys(content)[0];
+        // The headers the spec requires, so the example passes the same check the stub's replies are held to.
+        const required = Object.fromEntries(Object.entries(response?.headers ?? {})
+            .map(([name, def]) => [name, this.#deref(def)])
+            .filter(([name, h]) => h?.required && !["content-type", "accept", "authorization"].includes(name.toLowerCase()))
+            .map(([name, h]) => [name, String(h.example !== undefined ? h.example : this.#sample(h.schema))]));
         if (!media)
-            return { status };
+            return { status, ...(Object.keys(required).length ? { headers: required } : {}) };
         const m = content[media] ?? {};
         const named = m.examples && Object.values(m.examples)[0];
         const body = m.example !== undefined
@@ -135,7 +148,7 @@ export class OpenApiSpec {
             : named !== undefined
                 ? (this.#deref(named)?.value ?? null)
                 : this.#sample(m.schema);
-        return { status, headers: { "content-type": media === "*/*" ? "application/json" : media }, body: isJson(media) ? body : String(body ?? "") };
+        return { status, headers: { "content-type": media === "*/*" ? "application/json" : media, ...required }, body: isJson(media) ? body : String(body ?? "") };
     }
     /**
      * Every operation with what it takes to call it: sample values for its
@@ -213,10 +226,14 @@ export class OpenApiSpec {
             case "object":
                 return Object.fromEntries(Object.entries(s.properties ?? {}).map(([k, v]) => [k, this.#sample(v, depth + 1)]));
             case "array":
-                return Array.from({ length: Math.max(1, s.minItems ?? 1) }, () => this.#sample(s.items, depth + 1));
+                return Array.from({ length: Math.max(1, s.minItems ?? 1) }, (_, i) => {
+                    const items = this.#deref(s.items);
+                    // Equal items would break `uniqueItems`.
+                    return s.uniqueItems && Array.isArray(items?.enum) && items.enum.length ? items.enum[i % items.enum.length] : this.#sample(s.items, depth + 1);
+                });
             case "integer":
             case "number":
-                return typeof s.minimum === "number" ? s.minimum : typeof s.exclusiveMinimum === "number" ? s.exclusiveMinimum + 1 : 0;
+                return sampleNumber(s, type === "integer");
             case "boolean":
                 return true;
             case "string":
@@ -232,10 +249,23 @@ export class OpenApiSpec {
             return [`${method} ${path} is not in ${this.file}`];
         const { template, op } = found;
         const errors = [];
-        const params = [...(this.doc.paths[template].parameters ?? []), ...(op.parameters ?? [])].map((p) => this.#deref(p));
-        for (const p of params) {
-            if (p?.in === "query" && p.required && !req.query?.has(p.name))
-                errors.push(`${method} ${template}: required query parameter "${p.name}" is missing`);
+        const listed = [
+            ...(this.doc.paths[template].parameters ?? []).map((p, i) => this.#resolve(p, ["paths", template, "parameters", String(i)])),
+            ...(op.parameters ?? []).map((p, i) => this.#resolve(p, ["paths", template, found.method, "parameters", String(i)])),
+        ];
+        for (const [p, at] of listed) {
+            if (p?.in === "query") {
+                if (p.required && !this.#sentQuery(p, req.query))
+                    errors.push(`${method} ${template}: required query parameter "${p.name}" is missing`);
+                const values = req.query?.getAll(p.name) ?? [];
+                if (values.length && p.schema)
+                    errors.push(...this.#checkValues(`${method} ${template}`, `query parameter "${p.name}"`, values, p.schema, [...at, "schema"]));
+            }
+            // Authorization, Accept and Content-Type are the transport's business, whatever the spec lists.
+            const skipped = ["authorization", "accept", "content-type"];
+            if (p?.in === "header" && p.required && req.headers && !skipped.includes(p.name.toLowerCase()) && req.headers[p.name.toLowerCase()] === undefined) {
+                errors.push(`${method} ${template}: required header "${p.name}" is missing`);
+            }
         }
         const [body, at] = this.#resolve(op.requestBody, ["paths", template, found.method, "requestBody"]);
         if (!body)
@@ -247,6 +277,59 @@ export class OpenApiSpec {
         }
         return [...errors, ...this.#checkContent(body.content, req, [...at, "content"], `${method} ${template} request`)];
     }
+    /** Whether the request carries query parameter `p`, also as `name[key]` (deepObject) or as its properties (an exploded form object). */
+    #sentQuery(p, query) {
+        if (!query)
+            return false;
+        if (query.has(p.name))
+            return true;
+        const keys = [...query.keys()];
+        if (p.style === "deepObject")
+            return keys.some((k) => k.startsWith(`${p.name}[`));
+        const schema = this.#deref(p.schema);
+        const props = schema?.type === "object" && (p.style ?? "form") === "form" && p.explode !== false ? Object.keys(schema.properties ?? {}) : [];
+        return props.some((k) => query.has(k));
+    }
+    /** A query parameter's or header's values as strings, held to its schema after reading them as the type it declares. */
+    #checkValues(label, subject, values, schema, pointer) {
+        const [node, at] = this.#resolve(schema, pointer);
+        const one = (raw, node, at, where) => {
+            if (!["string", "integer", "number", "boolean"].includes(node?.type) && !node?.enum)
+                return [];
+            const validate = this.#validator(at);
+            const value = (node.type === "integer" || node.type === "number") && raw.trim() !== "" && Number.isFinite(Number(raw)) ? Number(raw) : node.type === "boolean" && (raw === "true" || raw === "false") ? raw === "true" : raw;
+            if (validate(value))
+                return [];
+            return [`${label}: ${subject}${where} ${validate.errors[0].message} (got ${JSON.stringify(raw)})`];
+        };
+        if (node?.type !== "array")
+            return one(values[0], node, at, "");
+        const [items, itemsAt] = this.#resolve(node.items, [...at, "items"]);
+        // One value may carry the whole list (`?ids=1,2`, explode: false). Many servers accept it for the exploded default too, so it isn't held against the spec.
+        const list = values.length > 1 ? values : values.flatMap((v) => v.split(","));
+        return list.flatMap((raw, i) => one(raw, items, itemsAt, ` item ${i + 1}`));
+    }
+    /** The headers a response documents: the required ones must be there, and what is there must fit its schema. */
+    #checkHeaders(label, documented, at, actual) {
+        if (!documented || !actual)
+            return [];
+        const errors = [];
+        for (const [name, def] of Object.entries(documented)) {
+            // The spec says to ignore these three when they are listed.
+            if (["content-type", "accept", "authorization"].includes(name.toLowerCase()))
+                continue;
+            const [h, hat] = this.#resolve(def, [...at, name]);
+            const raw = actual[name.toLowerCase()];
+            if (raw === undefined) {
+                if (h?.required)
+                    errors.push(`${label}: required header "${name}" is missing`);
+            }
+            else if (h?.schema) {
+                errors.push(...this.#checkValues(label, `header "${name}"`, [Array.isArray(raw) ? raw.join(", ") : raw], h.schema, [...hat, "schema"]));
+            }
+        }
+        return errors;
+    }
     #checkContent(content, msg, pointer, label) {
         if (!content || Object.keys(content).length === 0)
             return [];
@@ -254,9 +337,11 @@ export class OpenApiSpec {
         // Without a content-type (e.g. a stub replying with a bare string) there's nothing to hold the body to.
         if (!type)
             return [];
-        const media = Object.keys(content).find((k) => k.toLowerCase() === type) ??
-            Object.keys(content).find((k) => k.endsWith("/*") && type.startsWith(k.slice(0, -1))) ??
-            Object.keys(content).find((k) => k === "*/*");
+        // A spec may write the key with parameters (`application/json; charset=utf-8`); the type alone decides.
+        const bare = (k) => k.split(";")[0].trim().toLowerCase();
+        const media = Object.keys(content).find((k) => bare(k) === type) ??
+            Object.keys(content).find((k) => bare(k).endsWith("/*") && type.startsWith(bare(k).slice(0, -1))) ??
+            Object.keys(content).find((k) => bare(k) === "*/*");
         if (!media)
             return [`${label}: content-type "${type || "(none)"}" is not one of ${Object.keys(content).join(", ")}`];
         if (!content[media]?.schema || !isJson(media))
@@ -306,9 +391,38 @@ const FORMATS = {
     ipv6: "2001:db8::1",
 };
 function sampleString(s) {
-    const base = (s.format && FORMATS[s.format]) ?? "string";
+    let base = (s.format && FORMATS[s.format]) ?? "string";
+    // A cut-off date or address would break its format as much as the length, so only plain strings are shortened.
+    if (!s.format && s.maxLength !== undefined && base.length > s.maxLength)
+        base = base.slice(0, s.maxLength);
     return base.length >= (s.minLength ?? 0) ? base : base.padEnd(s.minLength, "x");
 }
+/** A number inside the schema's bounds (3.0's `exclusiveMinimum: true` and 3.1's numeric form), on its `multipleOf` step. */
+function sampleNumber(s, integer) {
+    const bound = (value, exclusive) => {
+        if (typeof s[exclusive] === "number")
+            return { at: s[exclusive], open: true };
+        if (typeof s[value] === "number")
+            return { at: s[value], open: s[exclusive] === true };
+        return undefined;
+    };
+    const lo = bound("minimum", "exclusiveMinimum");
+    const hi = bound("maximum", "exclusiveMaximum");
+    let n = 0;
+    if (lo)
+        n = lo.open ? lo.at + 1 : lo.at;
+    else if (hi)
+        n = hi.open ? hi.at - 1 : Math.min(0, hi.at);
+    // The step past an open lower bound can overshoot a close upper one.
+    if (lo && hi && (hi.open ? n >= hi.at : n > hi.at))
+        n = lo.open ? (lo.at + hi.at) / 2 : lo.at;
+    if (typeof s.multipleOf === "number" && s.multipleOf > 0) {
+        n = Math.ceil(n / s.multipleOf) * s.multipleOf;
+        if (lo?.open && n <= lo.at)
+            n += s.multipleOf;
+    }
+    return integer ? Math.ceil(n) : n;
+}
 function pickResponse(responses, status) {
     const s = String(status);
     return [s, `${s[0]}XX`, `${s[0]}xx`, "default"].find((k) => k in responses);
@@ -346,7 +460,8 @@ export function formatCoverage(spec, hits) {
     return { covered, total: keys.length, percent, markdown, text: `slicetest: OpenAPI coverage (${spec.file}): ${covered}/${keys.length} documented responses (${percent}%)\n${lines.join("\n")}` };
 }
 function isJson(media) {
-    return /[/+]json$/i.test(media) || media === "*/*";
+    const type = media.split(";")[0].trim();
+    return /[/+]json$/i.test(type) || type === "*/*";
 }
 function escape(s) {
     return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
@@ -359,6 +474,17 @@ export function nullableToType(node) {
         return node;
     for (const [k, v] of Object.entries(node))
         node[k] = nullableToType(v);
+    // 3.0 writes `minimum: 0, exclusiveMinimum: true`; JSON Schema (and Ajv) want `exclusiveMinimum: 0`.
+    for (const [flag, bound] of [["exclusiveMinimum", "minimum"], ["exclusiveMaximum", "maximum"]]) {
+        if (typeof node[flag] !== "boolean")
+            continue;
+        if (node[flag] && typeof node[bound] === "number") {
+            node[flag] = node[bound];
+            delete node[bound];
+        }
+        else
+            delete node[flag];
+    }
     if (node.nullable === true) {
         if (node.enum && !node.enum.includes(null))
             node.enum = [...node.enum, null];

package/dist/record-cli.js

@@ -4,6 +4,7 @@ import os from "node:os";
 import path from "node:path";
 import { createInterface } from "node:readline";
 import { fileURLToPath } from "node:url";
+import { compatStart } from "./cli-run.js";
 import { resolveOptions } from "./config.js";
 import { SESSION_ENV } from "./record.js";
 const ext = path.extname(fileURLToPath(import.meta.url));
@@ -29,7 +30,7 @@ export async function record(configPath, options, { out, port = 0 }) {
     process.env[SESSION_ENV] = JSON.stringify(session);
     const stop = () => void writeFile(session.stopFile, "").catch(() => { });
     process.once("SIGINT", stop);
-    const { startVitest } = await import("vitest/node");
+    const startVitest = compatStart(await import("vitest/node"));
     const { slicetest } = await import("./vitest.js");
     const announce = watchState(session.stateFile, (state) => {
         process.stdout.write(`\nRecording. Use the app through ${state.url} (it forwards to ${state.app}).\n` +

package/dist/record.js

@@ -5,6 +5,7 @@ import path from "node:path";
 import { stringify } from "yaml";
 import { parseForm } from "./stub.js";
 import { mask } from "./trace.js";
+import { requestUrl } from "./request-url.js";
 export const SESSION_ENV = "SLICETEST_RECORD_SESSION";
 /** Requests a browser makes on its own, not part of what the scenario is about. */
 const ASSET = /\.(ico|png|jpe?g|gif|webp|avif|svg|css|js|mjs|map|woff2?|ttf|eot)(\?|$)/i;
@@ -27,7 +28,7 @@ export async function runSession(ctx, session) {
                 headers.append(k, value);
         }
         try {
-            const upstream = await fetch(new URL(req.url ?? "/", target), {
+            const upstream = await fetch(requestUrl(req.url, target), {
                 method: req.method,
                 headers,
                 body: body.length && req.method !== "GET" && req.method !== "HEAD" ? body : undefined,

package/dist/recording.d.ts

@@ -1,10 +1,11 @@
 import type { RecordedCall, StubResponse } from "./stub.js";
 /** One recorded exchange with the real service, as stored in the recordings file. */
 export interface Recording {
+    /** A parameter sent more than once (`?ids=1&ids=2`) is a list of its values, in order. */
     request: {
         method: string;
         path: string;
-        query?: Record<string, string>;
+        query?: Record<string, string | string[]>;
         json?: unknown;
         body?: string;
     };
@@ -38,6 +39,15 @@ export declare class Recorder {
     /** Recordings made by this worker, to be merged into the file when the run ends. */
     added(): Recording[];
 }
+/** Query parameters by name, sorted; a repeated one as the list of its values. */
+export declare function queryOf(params: URLSearchParams): Record<string, string | string[]>;
+export declare const REDACTED = "[redacted]";
+/**
+ * A request with credential values replaced by `[redacted]`, so recordings can be committed and
+ * replay whatever key the test environment uses. Applied to recordings and to calls alike before
+ * they are compared.
+ */
+export declare function redactRequest(r: Recording["request"]): Recording["request"];
 export declare function readRecordings(file: string): Promise<Recording[]>;
 /** Append new recordings to `file`, skipping exact duplicates, keeping the order they were made in. */
 export declare function mergeRecordings(file: string, upstream: string, added: Recording[], source?: string): Promise<void>;

package/dist/recording.js

@@ -88,16 +88,57 @@ export class Recorder {
         };
     }
 }
+/** Query parameters by name, sorted; a repeated one as the list of its values. */
+export function queryOf(params) {
+    return Object.fromEntries([...new Set(params.keys())].sort((a, b) => a.localeCompare(b)).map((k) => {
+        const all = params.getAll(k);
+        return [k, all.length > 1 ? all : all[0]];
+    }));
+}
 function requestOf(call) {
-    const query = Object.fromEntries([...call.query.entries()].sort(([a], [b]) => a.localeCompare(b)));
-    return {
+    const query = queryOf(call.query);
+    return redactRequest({
         method: call.method,
         path: call.path,
         ...(Object.keys(query).length ? { query } : {}),
         ...(call.json !== undefined ? { json: call.json } : call.body ? { body: call.body } : {}),
-    };
+    });
+}
+/** Credentials sent in a query, a form or JSON body: `api_key`, `key`, `access_token`, `client_secret`, `password`, `appid`, signatures. */
+const SECRET = /^(api[-_]?key|apikey|key|(access|refresh|id|auth)[-_]?token|token|client[-_]?secret|app[-_]?secret|secret|password|passwd|appid|signature|sig|x-amz-(signature|credential|security-token))$/i;
+/** In bodies, a bare `key` is usually data (a KV store's key, a record's key) that tells requests apart, not a credential. */
+const bodySecret = (k) => SECRET.test(k) && k.toLowerCase() !== "key";
+export const REDACTED = "[redacted]";
+const FORM_BODY = /^[^\s=&]+=[^\s&]*(&[^\s=&]+=[^\s&]*)*$/;
+/**
+ * A request with credential values replaced by `[redacted]`, so recordings can be committed and
+ * replay whatever key the test environment uses. Applied to recordings and to calls alike before
+ * they are compared.
+ */
+export function redactRequest(r) {
+    const out = { ...r };
+    if (r.query)
+        out.query = Object.fromEntries(Object.entries(r.query).map(([k, v]) => [k, !SECRET.test(k) ? v : Array.isArray(v) ? v.map(() => REDACTED) : REDACTED]));
+    if (r.json !== undefined)
+        out.json = redactJson(r.json);
+    if (r.body && FORM_BODY.test(r.body)) {
+        const form = new URLSearchParams(r.body);
+        if ([...form.keys()].some(bodySecret)) {
+            out.body = [...form].map(([k, v]) => `${encodeURIComponent(k)}=${bodySecret(k) ? REDACTED : encodeURIComponent(v)}`).join("&");
+        }
+    }
+    return out;
+}
+function redactJson(v) {
+    if (Array.isArray(v))
+        return v.map(redactJson);
+    if (v && typeof v === "object")
+        return Object.fromEntries(Object.entries(v).map(([k, x]) => [k, typeof x === "string" && bodySecret(k) ? REDACTED : redactJson(x)]));
+    return v;
 }
-function keyOf(r) {
+function keyOf(request) {
+    // Recordings made before redaction still match: both sides are compared redacted.
+    const r = redactRequest(request);
     return JSON.stringify([r.method.toUpperCase(), r.path, sortKeys(r.query ?? {}), sortKeys(r.json ?? null), r.body ?? ""]);
 }
 function sortKeys(v) {
@@ -108,7 +149,11 @@ function sortKeys(v) {
     return v;
 }
 function toResponse(e) {
-    return { status: e.response.status, headers: e.response.headers, body: e.response.json !== undefined ? e.response.json : (e.response.body ?? "") };
+    const { status, headers, json, body } = e.response;
+    // A string is sent as it is; a JSON string reply (`"ok"`) needs its quotes back.
+    if (typeof json === "string")
+        return { status, headers: { "content-type": "application/json", ...headers }, body: JSON.stringify(json) };
+    return { status, headers, body: json !== undefined ? json : (body ?? "") };
 }
 function parse(text) {
     if (!text)
@@ -143,6 +188,6 @@ export async function mergeRecordings(file, upstream, added, source = `Recorded
         if (!entries.some((x) => isDeepStrictEqual(x, e)))
             entries.push(e);
     await mkdir(path.dirname(file), { recursive: true });
-    const header = `# ${source}. Review before committing: request bodies are stored as sent.\n`;
+    const header = `# ${source}. Review before committing: credentials in queries and bodies (api_key, access_token, client_secret, password, …) are replaced by ${REDACTED}, but other values are stored as sent.\n`;
     await writeFile(file, header + YAML.stringify(entries, { lineWidth: 0 }));
 }

package/dist/request-url.d.ts

@@ -0,0 +1 @@
+export declare function requestUrl(target: string | undefined, base: string | URL): URL;

package/dist/request-url.js

@@ -0,0 +1,5 @@
+// Not `new URL(target, base)`: for `//users/42` that reads `users` as a host, and the path is lost.
+export function requestUrl(target, base) {
+    const raw = target ?? "/";
+    return raw.startsWith("/") ? new URL(new URL(base).origin + raw) : new URL(raw, base);
+}

package/dist/runtime.d.ts

@@ -1,6 +1,6 @@
 import { App } from "./app.js";
 import { Issuer } from "./auth.js";
-import type { ResolvedOptions } from "./config.js";
+import { type ResolvedOptions } from "./config.js";
 import { Dependency } from "./containers.js";
 import { connectionVars } from "./connection.js";
 import { Db } from "./db.js";
@@ -63,8 +63,8 @@ export declare class Runtime {
     }): Promise<Runtime>;
     context(): ScenarioContext;
     beforeScenario(): Promise<void>;
-    /** Failures that the scenario body can't see on its own. */
-    afterScenario(): Promise<void>;
+    /** `deadline`: when the test's own timeout is about to end, so `idle` reports before Vitest does. */
+    afterScenario(deadline?: number): Promise<void>;
     /** The current scenario as a Mermaid sequence diagram. */
     diagram(): Promise<string>;
     /**