slicetest 0.8.0 → 0.10.0

package/dist/init.js

@@ -74,6 +74,37 @@ function runnable(dir) {
         return false;
     }
 }
+/** Where plain SQL migrations usually live (golang-migrate, goose, sqlx, Diesel, dbmate). */
+const SQL_MIGRATION_DIRS = ["migrations", "db/migrations", "sql/migrations", "database/migrations"];
+/** `.sql` files, or Diesel's directories with an `up.sql`. */
+function hasSqlMigrations(dir) {
+    if (!existsSync(dir))
+        return false;
+    return readdirSync(dir, { withFileTypes: true }).some((e) => (e.isFile() && e.name.endsWith(".sql")) || (e.isDirectory() && existsSync(path.join(dir, e.name, "up.sql"))));
+}
+/**
+ * The Go package to run: `.` when the root is package main, else the one command in `cmd/*`
+ * (or the one named server, api, app, web or like the module). Undefined when there is none.
+ */
+function goMain(root, goMod) {
+    const isMain = (dir) => {
+        try {
+            return readdirSync(dir).some((f) => f.endsWith(".go") && !f.endsWith("_test.go") && /^\s*package\s+main\b/m.test(readFileSync(path.join(dir, f), "utf8")));
+        }
+        catch {
+            return false;
+        }
+    };
+    if (isMain(root))
+        return ".";
+    const cmd = path.join(root, "cmd");
+    if (!existsSync(cmd))
+        return undefined;
+    const mains = readdirSync(cmd, { withFileTypes: true }).filter((e) => e.isDirectory() && isMain(path.join(cmd, e.name))).map((e) => e.name).sort();
+    const module = /^module\s+(\S+)/m.exec(goMod)?.[1]?.split("/").pop();
+    const pick = mains.length === 1 ? mains[0] : ["server", "api", "app", "web", "http", module].find((n) => n && mains.includes(n));
+    return pick ? `./cmd/${pick}` : undefined;
+}
 export async function detect(root) {
     const notes = [];
     // The app may live in a subdirectory (backend/, server/, …); everything about the app is read there.
@@ -83,11 +114,19 @@ export async function detect(root) {
     const appRoot = path.join(root, appDir);
     const has = (p) => existsSync(path.join(appRoot, p));
     const read = async (p) => (has(p) ? readFile(path.join(appRoot, p), "utf8") : "");
-    const pkg = has("package.json") ? JSON.parse(await read("package.json")) : undefined;
+    const readJson = async (name) => {
+        try {
+            return JSON.parse(await read(name));
+        }
+        catch (e) {
+            throw new Error(`slicetest init: ${name} isn't valid JSON (${e.message}); fix it, or run init from the folder of the app`);
+        }
+    };
+    const pkg = has("package.json") ? (await readJson("package.json")) : undefined;
     const deps = { ...pkg?.dependencies, ...pkg?.devDependencies };
     const python = `${await read("requirements.txt")}\n${await read("pyproject.toml")}`.toLowerCase();
     const gemfile = await read("Gemfile");
-    const composer = has("composer.json") ? JSON.parse(await read("composer.json")) : undefined;
+    const composer = has("composer.json") ? (await readJson("composer.json")) : undefined;
     const php = { ...composer?.require, ...composer?.["require-dev"] };
     const laravel = !!php["laravel/framework"] && has("artisan");
     const symfony = !laravel && !!php["symfony/framework-bundle"] && has("bin/console");
@@ -238,19 +277,33 @@ export async function detect(root) {
         }
     }
     else if (has("go.mod")) {
-        command = "go run .";
-        notes.push("app: Go (go.mod). It must listen on $PORT.");
+        const main = goMain(appRoot, await read("go.mod"));
+        // Built once up front, so the workers' `go run` find everything compiled instead of compiling at once.
+        build = "go build ./...";
+        command = `go run ${main ?? "."}`;
+        readyTimeout = 60_000;
+        notes.push(main && main !== "."
+            ? `app: Go (go.mod), the main package in ${main.slice(2)}/. It must listen on $PORT.`
+            : main
+                ? "app: Go (go.mod). It must listen on $PORT."
+                : "app: Go (go.mod), but no main package at the root or in cmd/*/: set the package in app.command (`go run ./cmd/server`). It must listen on $PORT.");
     }
     else if (has("Cargo.toml")) {
-        command = "cargo run";
-        notes.push("app: Rust (Cargo.toml). It must listen on $PORT.");
+        const cargo = await read("Cargo.toml");
+        // Compiled once before the workers start; `cargo run` then only checks that nothing changed.
+        build = "cargo build -q";
+        command = "cargo run -q";
+        readyTimeout = 120_000;
+        notes.push(/^\[workspace\]/m.test(cargo) && !/^\[package\]/m.test(cargo)
+            ? "app: Rust workspace (Cargo.toml): add `-p <crate>` to app.command for the server's crate. It must listen on $PORT."
+            : "app: Rust (Cargo.toml), built once with `cargo build`. It must listen on $PORT.");
     }
     else {
         notes.push("app: couldn't tell how to start the app. Set app.command.");
     }
     // --- migrations ---
     let migrate;
-    const migrationsSql = has("migrations") && (await readdir(path.join(appRoot, "migrations"))).some((f) => f.endsWith(".sql"));
+    const migrationsDir = SQL_MIGRATION_DIRS.find((d) => hasSqlMigrations(path.join(appRoot, d)));
     const atlas = await findAtlas(root, appDir);
     if (atlas) {
         migrate = { atlas: { dir: `file://${atlas}` } };
@@ -304,9 +357,9 @@ export async function detect(root) {
         migrate = { command: "npx knex migrate:latest", inputs: ["migrations"] };
         notes.push("db: Knex migrations");
     }
-    else if (migrationsSql) {
-        migrate = { sql: "migrations" };
-        notes.push("db: plain SQL files in migrations/, applied in name order");
+    else if (migrationsDir) {
+        migrate = { sql: migrationsDir };
+        notes.push(`db: SQL migrations in ${migrationsDir}/, applied in version order (down migrations left out)`);
     }
     else if (has("schema.sql")) {
         migrate = { sql: "schema.sql" };
@@ -564,6 +617,7 @@ export async function init(root, { force = false } = {}) {
     }
     const { config, notes } = await detect(root);
     const header = [
+        "# yaml-language-server: $schema=https://unpkg.com/slicetest/schema/config.schema.json",
         "# slicetest config, generated by `npx slicetest init`. Paths are relative to this file.",
         "# Everything the Vitest plugin accepts works here: https://github.com/revo1290/slicetest#configuration-reference",
         "#",

package/dist/list.d.ts

@@ -18,6 +18,7 @@ export declare function listScenarios(root: string, opts?: {
     filters?: string[];
     name?: string;
     tags?: string;
+    include?: string[];
 }): Promise<{
     scenarios: ListedScenario[];
     errors: string[];

package/dist/list.js

@@ -1,7 +1,13 @@
 import { readdir, readFile } from "node:fs/promises";
 import path from "node:path";
 import { tagsSelected } from "./scenario.js";
-import { parseScenarioFile } from "./yaml.js";
+import { parseScenarioFile, scenarioTitle } from "./yaml.js";
+function matchesGlob(file, glob) {
+    const match = path.matchesGlob;
+    if (!match)
+        throw new Error("slicetest list: the config's include needs Node.js 20.17 or later (path.matchesGlob)");
+    return match(file, glob.replace(/^\.\//, ""));
+}
 const SKIP_DIRS = new Set(["node_modules", ".git", "dist", "build", "target", "vendor", ".venv", "venv"]);
 async function scenarioFiles(dir, out = []) {
     for (const entry of await readdir(dir, { withFileTypes: true })) {
@@ -25,20 +31,27 @@ export async function listScenarios(root, opts = {}) {
     const pattern = opts.name ? new RegExp(opts.name) : undefined;
     for (const file of await scenarioFiles(root)) {
         const rel = path.relative(root, file).split(path.sep).join("/");
+        if (opts.include && !opts.include.some((glob) => matchesGlob(rel, glob)))
+            continue;
         if (opts.filters?.length && !opts.filters.some((f) => rel.includes(f)))
             continue;
         try {
             const doc = parseScenarioFile(await readFile(file, "utf8"), rel);
+            // Vitest's `.only` runs only the focused tests of that file; one the tag filter leaves out is registered as skipped.
+            const focused = doc.scenarios.some((sc) => sc.only && !sc.skip && tagsSelected(sc.tags ?? [], opts.tags));
             for (const sc of doc.scenarios) {
                 const tags = sc.tags ?? [];
-                const selected = tagsSelected(tags, opts.tags) && (!pattern || pattern.test(sc.name));
+                // `-t` is matched against the title each row runs under (`vote {{c}}` → `vote a`).
+                const titles = sc.each ? sc.each.map((row, i) => scenarioTitle(sc.name, row, i)) : [sc.name];
+                const rows = pattern ? titles.filter((t) => pattern.test(t)).length : titles.length;
+                const selected = tagsSelected(tags, opts.tags) && rows > 0 && (!focused || !!sc.only);
                 scenarios.push({
                     file: rel,
                     line: sc.line,
                     name: sc.name,
                     tags,
                     status: sc.skip ? "skip" : !selected ? "filtered" : sc.only ? "only" : "run",
-                    rows: sc.each?.length ?? 1,
+                    rows: selected ? rows : titles.length,
                     steps: doc.setup.length + sc.steps.length,
                 });
             }

package/dist/mail.d.ts

@@ -47,7 +47,7 @@ export declare class Mailbox {
      * The first message matching `filter`, waiting up to `within` ms for the app
      * to send it. Fails with the messages that did arrive.
      */
-    waitFor(filter?: MailFilter, { within }?: {
+    waitFor(filter?: MailFilter, { within: wanted }?: {
         within?: number | undefined;
     }): Promise<Mail>;
     /** One line per message received this scenario, for failure output. */

package/dist/mail.js

@@ -1,3 +1,5 @@
+import { waitBudget } from "./deadline.js";
+import { decodeEntities } from "./form.js";
 import net from "node:net";
 export class Mailbox {
     server;
@@ -37,7 +39,8 @@ export class Mailbox {
      * The first message matching `filter`, waiting up to `within` ms for the app
      * to send it. Fails with the messages that did arrive.
      */
-    async waitFor(filter = {}, { within = 5000 } = {}) {
+    async waitFor(filter = {}, { within: wanted = 5000 } = {}) {
+        const { ms: within, note } = waitBudget(wanted);
         const deadline = Date.now() + within;
         for (;;) {
             const found = this.messages(filter)[0];
@@ -45,7 +48,7 @@ export class Mailbox {
                 return found;
             const left = deadline - Date.now();
             if (left <= 0)
-                throw new Error(`slicetest: no mail matching ${describeFilter(filter)} within ${within}ms\n${this.describe()}`);
+                throw new Error(`slicetest: no mail matching ${describeFilter(filter)} within ${within}ms${note}\n${this.describe()}`);
             await new Promise((resolve) => {
                 const done = () => {
                     clearTimeout(timer);
@@ -283,11 +286,8 @@ function htmlToText(html) {
         .replace(/<(script|style)[\s\S]*?<\/\1>/gi, "")
         .replace(/<br\s*\/?>|<\/p>/gi, "\n")
         .replace(/<[^>]+>/g, "")
-        .replace(/&amp;/g, "&")
-        .replace(/&lt;/g, "<")
-        .replace(/&gt;/g, ">")
-        .replace(/&quot;/g, '"')
-        .replace(/&#39;/g, "'")
+        // One pass: replacing `&amp;` first turned the text `&lt;` (sent as `&amp;lt;`) into `<`.
+        .replace(/&[^;\s]+;/g, (e) => decodeEntities(e))
         .trim();
 }
 function links(s) {

package/dist/matchers.d.ts

@@ -1,5 +1,5 @@
 import { type Where } from "./db.js";
-import type { HttpResponse } from "./http.js";
+import { type HttpResponse } from "./http.js";
 import { type MatchOptions } from "./stub.js";
 /** One expected call for `toHaveReceivedInOrder`: `[stub, method, path, match?]`. */
 export type OrderedCall = [stub: string, method: string, path: string | RegExp, match?: MatchOptions];
@@ -22,10 +22,18 @@ interface SlicetestMatchers<R = unknown> {
      * relative to the working directory with an optional pointer, `openapi.yaml#/components/schemas/Poll`.
      */
     toMatchSchema(schema: object | string): R;
-    /** The response has this status; the failure message shows the response body. */
-    toHaveStatus(status: number): R;
-    /** An array of responses has exactly these status counts, e.g. `{ 201: 1, 409: 9 }`. */
-    toHaveStatuses(counts: Record<number, number>): R;
+    /** The response has this status, a status of this class (`"2xx"`) or one of a list (`[200, 204]`); the failure message shows the response body. */
+    toHaveStatus(status: number | `${1 | 2 | 3 | 4 | 5}xx` | (number | `${1 | 2 | 3 | 4 | 5}xx`)[]): R;
+    /**
+     * The response sets cookie `name`, with these attributes as a subset (`value`, `httpOnly`,
+     * `secure`, `sameSite`, `path`, `domain`, `maxAge`, `expires`, `partitioned`):
+     * `expect(res).toSetCookie("sid", { httpOnly: true, secure: true, sameSite: "Lax" })`.
+     */
+    toSetCookie(name: string, attributes?: Record<string, unknown>): R;
+    /** The response arrived within `ms` milliseconds (measured from sending the request to reading the whole body). */
+    toRespondWithin(ms: number): R;
+    /** An array of responses has exactly these status counts, e.g. `{ 201: 1, 409: 9 }`; classes count the rest: `{ 201: 1, "4xx": 9 }`. */
+    toHaveStatuses(counts: Partial<Record<number | `${1 | 2 | 3 | 4 | 5}xx`, number>>): R;
     /** Async: the table has at least one row matching `where` (`count` for an exact number). */
     toHaveRow(table: string, where?: Where, count?: number): Promise<void>;
 }
@@ -33,5 +41,9 @@ declare module "vitest" {
     interface Matchers<R extends void | Promise<void> = void | Promise<void>, T = unknown> extends SlicetestMatchers<R> {
     }
 }
-export declare function statusCounts(responses: HttpResponse[]): Record<number, number>;
+/** A status code, a class (`"2xx"`), or a list of either: `[200, 204]`, `["2xx", 304]`. */
+export type ExpectedStatus = number | string | (number | string)[];
+export declare function statusMatches(expected: ExpectedStatus, actual: number): boolean;
+/** Responses counted under their code when `keys` lists it, else under their class (`4xx`) when that is listed. */
+export declare function statusCounts(responses: HttpResponse[], keys?: string[]): Record<string, number>;
 export {};

package/dist/matchers.js

@@ -1,5 +1,6 @@
 import { expect } from "vitest";
 import { Db } from "./db.js";
+import { setCookies } from "./http.js";
 import { describeGraphQL } from "./graphql.js";
 import { schemaProblems } from "./schema.js";
 import { Stub, subset } from "./stub.js";
@@ -22,14 +23,38 @@ function assertStub(received) {
     if (!(received instanceof Stub))
         throw new TypeError("slicetest: expected a stub, e.g. expect(stub(\"slack\"))");
 }
-export function statusCounts(responses) {
+export function statusMatches(expected, actual) {
+    if (Array.isArray(expected)) {
+        if (expected.length === 0)
+            throw new TypeError("slicetest: toHaveStatus needs at least one status in the list");
+        return expected.some((e) => statusMatches(e, actual));
+    }
+    if (typeof expected === "number")
+        return expected === actual;
+    const s = String(expected).trim().toLowerCase();
+    if (/^\d{3}$/.test(s))
+        return Number(s) === actual;
+    if (/^[1-5]xx$/.test(s))
+        return Math.floor(actual / 100) === Number(s[0]);
+    throw new TypeError(`slicetest: a status is a code (201), a class ("2xx") or a list of them, got ${JSON.stringify(expected)}`);
+}
+function describeStatus(expected) {
+    return Array.isArray(expected) ? `one of ${expected.join(", ")}` : String(expected);
+}
+/** Responses counted under their code when `keys` lists it, else under their class (`4xx`) when that is listed. */
+export function statusCounts(responses, keys = []) {
     const out = {};
-    for (const r of responses)
-        out[r.status] = (out[r.status] ?? 0) + 1;
+    for (const r of responses) {
+        const code = String(r.status);
+        const key = keys.includes(code) ? code : keys.includes(`${code[0]}xx`) ? `${code[0]}xx` : code;
+        out[key] = (out[key] ?? 0) + 1;
+    }
     return out;
 }
 function fmtCounts(c) {
-    return `{ ${Object.entries(c).map(([k, n]) => `${k}: ${n}`).join(", ")} }`;
+    // In status order, a class before its codes; object order would put every code before every class.
+    const rank = (k) => (/xx$/.test(k) ? Number(k[0]) * 100 - 0.5 : Number(k));
+    return `{ ${Object.entries(c).sort(([a], [b]) => rank(a) - rank(b)).map(([k, n]) => `${k}: ${n}`).join(", ")} }`;
 }
 /** One example response per status, which is usually what explains the odd one out. */
 function describeResponses(responses) {
@@ -140,23 +165,65 @@ expect.extend({
         };
     },
     toHaveStatus(received, status) {
-        const pass = received?.status === status;
+        if (!received || typeof received !== "object" || typeof received.status !== "number") {
+            throw new TypeError(`slicetest: toHaveStatus expects a response from http, got ${this.utils.stringify(received)}`);
+        }
+        const pass = statusMatches(status, received.status);
         return {
             pass,
             message: () => {
                 const body = received.text.length > 1000 ? `${received.text.slice(0, 1000)}…` : received.text;
-                return (`expected ${received.method} ${received.url} ${this.isNot ? "not " : ""}to respond ${status}, got ${received.status}\n` +
+                return (`expected ${received.method} ${received.url} ${this.isNot ? "not " : ""}to respond ${describeStatus(status)}, got ${received.status}\n` +
                     `Response body:\n  ${body || "(empty)"}`);
             },
             actual: received?.status,
             expected: status,
         };
     },
+    toSetCookie(received, name, attributes = {}) {
+        if (!received || typeof received !== "object" || !(received.headers instanceof Headers)) {
+            throw new TypeError(`slicetest: toSetCookie expects a response from http, got ${this.utils.stringify(received)}`);
+        }
+        const cookies = setCookies(received);
+        const cookie = Object.hasOwn(cookies, name) ? cookies[name] : undefined;
+        // SameSite values are case-insensitive: "Lax" and "lax" are the same attribute. A matcher sees the value as sent.
+        const plain = typeof attributes.sameSite === "string";
+        const want = plain ? { ...attributes, sameSite: attributes.sameSite.toLowerCase() } : attributes;
+        const pass = !!cookie && subset(want, plain ? { ...cookie, sameSite: cookie.sameSite?.toLowerCase() } : cookie);
+        const describe = (c) => `${c.name}=${c.value.length > 40 ? `${c.value.slice(0, 40)}…` : c.value} ${JSON.stringify(Object.fromEntries(Object.entries(c).filter(([k, v]) => k !== "name" && k !== "value" && v !== undefined && v !== false)))}`;
+        return {
+            pass,
+            message: () => {
+                const head = `expected ${received.method} ${received.url} ${this.isNot ? "not " : ""}to set cookie ${name}${Object.keys(attributes).length ? ` with ${this.utils.stringify(attributes, 10, { min: true })}` : ""}`;
+                const all = Object.values(cookies);
+                return `${head}\n${all.length ? `Cookies it set:\n${all.map((c) => `  ${describe(c)}`).join("\n")}` : "It set no cookies."}`;
+            },
+        };
+    },
+    toRespondWithin(received, ms) {
+        if (!received || typeof received !== "object" || typeof received.durationMs !== "number") {
+            throw new TypeError(`slicetest: toRespondWithin expects a response from http, got ${this.utils.stringify(received)}`);
+        }
+        if (!(typeof ms === "number" && ms > 0))
+            throw new TypeError(`slicetest: toRespondWithin needs a positive number of milliseconds, got ${this.utils.stringify(ms)}`);
+        return {
+            pass: received.durationMs <= ms,
+            message: () => `expected ${received.method} ${received.url} ${this.isNot ? "not " : ""}to respond within ${ms}ms, it took ${received.durationMs}ms`,
+            actual: received.durationMs,
+            expected: ms,
+        };
+    },
     toHaveStatuses(received, counts) {
         if (!Array.isArray(received))
             throw new TypeError("slicetest: toHaveStatuses expects an array of responses, e.g. from http.concurrently()");
-        const actual = statusCounts(received);
-        const expected = Object.fromEntries(Object.entries(counts).filter(([, n]) => n > 0).map(([k, n]) => [Number(k), n]));
+        const keys = Object.keys(counts).map((k) => {
+            const key = k.trim().toLowerCase();
+            if (!/^\d{3}$|^[1-5]xx$/.test(key))
+                throw new TypeError(`slicetest: a status is a code (201) or a class ("2xx"), got ${JSON.stringify(k)}`);
+            return key;
+        });
+        const actual = statusCounts(received, keys);
+        const expected = Object.fromEntries(Object.entries(counts).filter((entry) => (entry[1] ?? 0) > 0).map(([k, n]) => [k.trim().toLowerCase(), n]));
         const pass = this.equals(actual, expected);
         return {
             pass,

package/dist/openapi.d.ts

@@ -30,12 +30,9 @@ export interface Message {
     /** Parsed JSON when the body is JSON, else the raw text. */
     body: unknown;
     query?: URLSearchParams;
+    /** Header names in lower case, as Node delivers them; undefined skips the check for required header parameters. */
+    headers?: Record<string, string | string[] | undefined>;
 }
-/**
- * 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.
- */
 export declare class OpenApiSpec {
     #private;
     readonly file: string;