slicetest 0.2.0 → 0.4.0

package/dist/global-setup.js

@@ -1,25 +1,29 @@
 import { execFile } from "node:child_process";
 import { createHash, randomBytes } from "node:crypto";
-import { mkdtemp, readdir, readFile, rm, stat } from "node:fs/promises";
+import { mkdir, mkdtemp, readdir, readFile, rm, stat, writeFile } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { promisify } from "node:util";
+import { annotation, appendSummary, failureAnnotations, failureSummary, onGitHub, repoPath, yamlFailures } from "./ci.js";
 import { configureContainerRuntime } from "./container-runtime.js";
 import { engineFor } from "./drivers/index.js";
+import { coverageCacheFile } from "./gen.js";
 import { formatCoverage, OpenApiSpec } from "./openapi.js";
+import { mergeRecordings } from "./recording.js";
 import "./provided.js";
 const exec = promisify(execFile);
 /** Runs once per vitest run: start the database server, migrate a template database, hand its location to the workers. */
 export default async function setup(project) {
     const opts = project.getProvidedContext().slicetestOptions;
-    const engine = engineFor(opts);
+    const engine = await engineFor(opts);
     let adminUrl;
     let stopContainer;
     if (opts.db.url) {
         adminUrl = opts.db.url;
     }
     else {
-        configureContainerRuntime();
+        if (!engine.local)
+            configureContainerRuntime();
         const container = await engine.startContainer(opts.db.image, opts.db.reuse);
         adminUrl = container.url;
         if (!opts.db.reuse)
@@ -45,7 +49,12 @@ export default async function setup(project) {
     const server = admin;
     // Each worker writes the documented responses it saw here; they are merged when the run ends.
     const coverageDir = opts.openapi.app ? await mkdtemp(path.join(os.tmpdir(), "slicetest-coverage-")) : undefined;
-    project.provide("slicetestDb", { adminUrl, template, prefix, coverageDir });
+    // Likewise for recordings made against real services, merged into the recordings files at the end.
+    const recording = Object.values(opts.recordings).some((r) => r.record);
+    const recordDir = recording ? await mkdtemp(path.join(os.tmpdir(), "slicetest-recordings-")) : undefined;
+    // On GitHub Actions, failed YAML steps are collected here and turned into annotations at the end.
+    const ciDir = onGitHub() ? await mkdtemp(path.join(os.tmpdir(), "slicetest-ci-")) : undefined;
+    project.provide("slicetestDb", { adminUrl, template, prefix, coverageDir, recordDir, ciDir });
     return async () => {
         try {
             if (!stopContainer) {
@@ -59,6 +68,10 @@ export default async function setup(project) {
             await stopContainer?.();
             if (coverageDir)
                 await reportCoverage(opts, coverageDir);
+            if (recordDir)
+                await saveRecordings(opts, recordDir);
+            if (ciDir)
+                await reportToGitHub(ciDir);
         }
     };
 }
@@ -74,11 +87,18 @@ async function reportCoverage(opts, dir) {
             return;
         const spec = await OpenApiSpec.load(path.resolve(opts.root, opts.openapi.app), opts.openapi.app);
         const report = formatCoverage(spec, hits);
+        // For `slicetest gen --uncovered`.
+        const cache = coverageCacheFile(opts.root);
+        await mkdir(path.dirname(cache), { recursive: true }).then(() => writeFile(cache, JSON.stringify([...hits]))).catch(() => { });
         console.log(`\n${report.text}\n`);
+        await appendSummary(report.markdown);
         const min = opts.openapi.minCoverage;
         if (min !== undefined && report.percent < min) {
             // Not thrown: Vitest reports teardown errors as a crash. The failing exit code is what CI needs.
-            console.error(`slicetest: OpenAPI coverage ${report.percent}% is below openapi.minCoverage (${min}%)\n`);
+            const message = `OpenAPI coverage ${report.percent}% is below openapi.minCoverage (${min}%)`;
+            console.error(`slicetest: ${message}\n`);
+            if (onGitHub())
+                console.log(annotation("error", message, { file: repoPath(path.resolve(opts.root, opts.openapi.app)), title: "slicetest: OpenAPI coverage" }));
             process.exitCode = 1;
         }
     }
@@ -86,6 +106,34 @@ async function reportCoverage(opts, dir) {
         await rm(dir, { recursive: true, force: true });
     }
 }
+async function reportToGitHub(dir) {
+    try {
+        const failures = await yamlFailures(dir);
+        for (const line of failureAnnotations(failures))
+            console.log(line);
+        await appendSummary(failureSummary(failures));
+    }
+    finally {
+        await rm(dir, { recursive: true, force: true });
+    }
+}
+async function saveRecordings(opts, dir) {
+    try {
+        const files = await readdir(dir);
+        for (const [name, r] of Object.entries(opts.recordings)) {
+            const added = [];
+            for (const f of files.filter((f) => f.startsWith(`${name}.`)).sort())
+                added.push(...JSON.parse(await readFile(path.join(dir, f), "utf8")));
+            if (added.length === 0)
+                continue;
+            await mergeRecordings(path.resolve(opts.root, r.file), r.upstream, added);
+            console.log(`slicetest: recorded ${added.length} call(s) to ${r.upstream} in ${r.file}`);
+        }
+    }
+    finally {
+        await rm(dir, { recursive: true, force: true });
+    }
+}
 const RUN_PREFIX = "slicetest_r";
 const TEMPLATE_PREFIX = "slicetest_tpl_";
 const STALE_MS = 24 * 60 * 60 * 1000;

package/dist/http.d.ts

@@ -37,6 +37,12 @@ export declare class HttpClient {
     post(path: string, body?: unknown, opts?: RequestOptions): Promise<HttpResponse>;
     put(path: string, body?: unknown, opts?: RequestOptions): Promise<HttpResponse>;
     patch(path: string, body?: unknown, opts?: RequestOptions): Promise<HttpResponse>;
+    /**
+     * Run `send` `n` times at once and wait for every response, to provoke races
+     * (double bookings, lost updates). Pair with `toHaveStatuses({ 201: 1, 409: n - 1 })`
+     * and a check of the database. Requests are released together once all are prepared.
+     */
+    concurrently(n: number, send: (i: number) => Promise<HttpResponse>): Promise<HttpResponse[]>;
     /** Strings, URLSearchParams, FormData, Blob and byte arrays are sent as-is; anything else is sent as JSON. */
     request(method: string, path: string, body?: unknown, options?: RequestOptions): Promise<HttpResponse>;
     /** Call `fn` with every response this client (or one derived with `with()`) receives. */

package/dist/http.js

@@ -41,6 +41,20 @@ export class HttpClient {
     patch(path, body, opts) {
         return this.request("PATCH", path, body, opts);
     }
+    /**
+     * Run `send` `n` times at once and wait for every response, to provoke races
+     * (double bookings, lost updates). Pair with `toHaveStatuses({ 201: 1, 409: n - 1 })`
+     * and a check of the database. Requests are released together once all are prepared.
+     */
+    async concurrently(n, send) {
+        if (!Number.isInteger(n) || n < 1)
+            throw new Error(`slicetest: concurrently() needs a positive number of requests, got ${n}`);
+        let release;
+        const gate = new Promise((r) => (release = r));
+        const all = Promise.all(Array.from({ length: n }, (_, i) => gate.then(() => send(i))));
+        release();
+        return all;
+    }
     /** Strings, URLSearchParams, FormData, Blob and byte arrays are sent as-is; anything else is sent as JSON. */
     async request(method, path, body, options = {}) {
         const opts = merge(this.defaults, options);

package/dist/index.d.ts

@@ -1,8 +1,12 @@
 export { scenario } from "./scenario.js";
+export { mask } from "./trace.js";
+export type { Trace, MaskOptions } from "./trace.js";
 export type { ScenarioContext } from "./runtime.js";
 export type { Db, Row, Where, RowsOptions, Changes, TableChanges } from "./db.js";
 export type { Stub, RecordedCall, StubResponse, Responder, MatchOptions, RouteBuilder } from "./stub.js";
 export type { HttpClient, HttpResponse, RequestOptions } from "./http.js";
 export type { App } from "./app.js";
-export type { SlicetestOptions } from "./config.js";
+export type { Dependency } from "./containers.js";
+export type { Mailbox, Mail, MailFilter } from "./mail.js";
+export type { SlicetestOptions, ContainerOptions } from "./config.js";
 export type {} from "./matchers.js";

package/dist/index.js

@@ -1 +1,2 @@
 export { scenario } from "./scenario.js";
+export { mask } from "./trace.js";

package/dist/init.d.ts

@@ -16,3 +16,5 @@ export declare function init(root: string, { force }?: {
     files: string[];
     notes: string[];
 }>;
+/** `"6379:6379"`, `"127.0.0.1:5432:5432/tcp"`, `9000`, `{ target: 6379 }` → the port inside the container. */
+export declare function containerPort(spec: unknown): number | undefined;

package/dist/init.js

@@ -1,7 +1,7 @@
 import { existsSync } from "node:fs";
 import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
-import { stringify } from "yaml";
+import { parse, stringify } from "yaml";
 const TODO_COMMAND = "echo 'TODO: the command that starts your app' && exit 1";
 export async function detect(root) {
     const notes = [];
@@ -92,18 +92,93 @@ export async function detect(root) {
     else {
         notes.push("db: no migrations found; the database starts empty. Set db.migrate.");
     }
+    // --- docker compose: the database image and other dependencies ---
+    const { db: composeDb, containers, appEnv, mail: composeMail } = await fromCompose(root, notes);
+    Object.assign(env, appEnv);
+    let mail = composeMail;
+    if (!mail && (deps.nodemailer || /\b(flask-mail|fastapi-mail|django-anymail)\b/.test(python) || (has("manage.py") && /EMAIL_HOST/.test(await read(await djangoSettings(root)))))) {
+        mail = true;
+        Object.assign(env, { SMTP_HOST: "{{mail.host}}", SMTP_PORT: "{{mail.port}}" });
+        notes.push("mail: the app sends mail; slicetest catches it over SMTP (SMTP_HOST / SMTP_PORT, rename them to what your app reads)");
+    }
+    const sqlite = await detectSqlite(root, read, deps, python, gemfile);
+    if (sqlite && !composeDb.engine) {
+        composeDb.engine = "sqlite";
+        env.DATABASE_URL = sqlite.url;
+        notes.push(`db: SQLite (${sqlite.why}), no container needed. The app gets DATABASE_URL=${sqlite.url}; {{db.path}} is the plain file path`);
+    }
+    const stubs = await stubsFromEnvExample(root, read, env, notes);
+    const mysqlDeps = !!deps.mysql2 || !!deps.mysql || /\b(pymysql|mysqlclient|aiomysql)\b/.test(python) || /\bgem ['"]mysql2['"]/.test(gemfile);
+    if (!composeDb.engine && mysqlDeps) {
+        composeDb.engine = "mysql";
+        notes.push("db: MySQL (a MySQL driver is a dependency). Install mysql2 and @testcontainers/mysql next to slicetest.");
+    }
     // --- OpenAPI ---
     const openapi = ["openapi.yaml", "openapi.yml", "openapi.json", "docs/openapi.yaml", "docs/openapi.yml", "docs/openapi.json"].find(has);
     if (openapi)
         notes.push(`openapi: ${openapi}. Every response will be checked against it.`);
     const config = {
         app: { command, env, ready: { path: "/" } },
-        ...(migrate ? { db: { migrate } } : {}),
-        stubs: [],
+        ...(migrate || Object.keys(composeDb).length ? { db: { ...composeDb, ...(migrate ? { migrate } : {}) } } : {}),
+        ...(Object.keys(containers).length ? { containers } : {}),
+        ...(mail ? { mail: true } : {}),
+        stubs,
         ...(openapi ? { openapi } : {}),
     };
     return { config, notes };
 }
+async function djangoSettings(root) {
+    for (const dir of await readdir(root, { withFileTypes: true }).catch(() => [])) {
+        if (dir.isDirectory() && existsSync(path.join(root, dir.name, "settings.py")))
+            return path.join(dir.name, "settings.py");
+    }
+    return "settings.py";
+}
+/** Where the project says it uses SQLite, and the URL form its framework reads. */
+async function detectSqlite(root, read, deps, python, gemfile) {
+    if (/provider\s*=\s*"sqlite"/.test(await read("prisma/schema.prisma")))
+        return { why: "Prisma provider", url: "file:{{db.path}}" };
+    if (/adapter:\s*sqlite3/.test(await read("config/database.yml")))
+        return { why: "config/database.yml", url: "sqlite3:{{db.path}}" };
+    if (/\bgem ['"]sqlite3['"]/.test(gemfile) && !/\bgem ['"](pg|mysql2)['"]/.test(gemfile))
+        return { why: "sqlite3 gem", url: "sqlite3:{{db.path}}" };
+    if (existsSync(path.join(root, "manage.py")) && /django\.db\.backends\.sqlite3/.test(await read(await djangoSettings(root)))) {
+        return { why: "Django settings; make DATABASES read DATABASE_URL, e.g. with dj-database-url", url: "{{db.url}}" };
+    }
+    const pgOrMysql = deps.pg || deps.postgres || deps.mysql2 || /\b(psycopg|asyncpg|pymysql|mysqlclient)/.test(python);
+    if (!pgOrMysql && (deps["better-sqlite3"] || deps.sqlite3 || deps["@libsql/client"]))
+        return { why: "a SQLite driver is a dependency", url: "{{db.url}}" };
+    return undefined;
+}
+/** Hosts that are never third-party APIs to stub. */
+const LOCAL_HOST = /^(localhost|127\.|0\.0\.0\.0|\[::1\]|host\.docker\.internal|[\w-]+$)/;
+/**
+ * `.env.example` lines like `STRIPE_API_BASE=https://api.stripe.com` name the
+ * services the app calls: each becomes a stub recorded from that URL, and the
+ * variable points the app at the stub.
+ */
+async function stubsFromEnvExample(root, read, env, notes) {
+    const file = [".env.example", ".env.sample", ".env.template", ".env.dist"].find((f) => existsSync(path.join(root, f)));
+    if (!file)
+        return [];
+    const stubs = [];
+    for (const line of (await read(file)).split(/\r?\n/)) {
+        const m = /^\s*(?:export\s+)?([A-Z][A-Z0-9_]*)\s*=\s*["']?(https?:\/\/[^\s"'#]+)/.exec(line);
+        if (!m || !/(URL|URI|ENDPOINT|HOST|BASE)$/.test(m[1]) || /DATABASE|REDIS|MONGO|AMQP|SMTP|MAIL|CALLBACK|REDIRECT|FRONTEND|PUBLIC|APP_URL|SITE_URL|WEBHOOK_URL$/.test(m[1]))
+            continue;
+        const url = new URL(m[2]);
+        if (LOCAL_HOST.test(url.hostname))
+            continue;
+        const base = url.hostname.split(".").filter((p) => !["api", "www", "com", "io", "net", "org", "co", "dev", "app"].includes(p))[0] ?? url.hostname;
+        let name = base.replace(/[^\w-]/g, "-").toLowerCase();
+        while (stubs.some((s) => s.name === name))
+            name += "2";
+        stubs.push({ name, upstream: url.origin });
+        env[m[1]] = `{{stub.${name}}}${url.pathname.replace(/\/$/, "")}`;
+        notes.push(`stubs.${name}: ${m[1]} in ${file} points at ${url.origin}. Record it once with SLICETEST_RECORD=${name}, or register routes in scenarios`);
+    }
+    return stubs;
+}
 const SCENARIO = `# yaml-language-server: $schema=https://unpkg.com/slicetest/schema/scenario.schema.json
 # A first scenario. Run it with: npx slicetest
 scenarios:
@@ -132,3 +207,105 @@ export async function init(root, { force = false } = {}) {
     await writeFile(scenarioFile, SCENARIO);
     return { files: [configFile, scenarioFile].map((f) => path.relative(root, f)), notes };
 }
+const COMPOSE_FILES = ["compose.yaml", "compose.yml", "docker-compose.yml", "docker-compose.yaml"];
+/** Development mail servers; `mail: true` does their job in-process. */
+const MAIL_CATCHERS = /(^|\/)(mailpit|mailhog|maildev|smtp4dev|greenmail[\w-]*|mailcatcher|inbucket)(:|$)/;
+/** Known images: the port they listen on, how to empty them, and the variable apps usually read. */
+const KNOWN = [
+    { match: /(^|\/)(redis|redis-stack|keydb)(:|$)/, port: 6379, reset: ["redis-cli", "FLUSHALL"], env: (n) => ["REDIS_URL", `redis://{{container.${n}}}`] },
+    { match: /(^|\/)valkey(:|$)/, port: 6379, reset: ["valkey-cli", "FLUSHALL"], env: (n) => ["REDIS_URL", `redis://{{container.${n}}}`] },
+    { match: /(^|\/)memcached(:|$)/, port: 11211 },
+    {
+        match: /(^|\/)mongo(:|$)/,
+        port: 27017,
+        reset: ["mongosh", "--quiet", "--eval", "db.getMongo().getDBNames().filter((n) => !['admin', 'config', 'local'].includes(n)).forEach((n) => db.getSiblingDB(n).dropDatabase())"],
+        env: (n) => ["MONGODB_URL", `mongodb://{{container.${n}}}`],
+    },
+    { match: /(^|\/)(elasticsearch|opensearch)(:|$)/, port: 9200, env: (n) => ["ELASTICSEARCH_URL", `http://{{container.${n}}}`] },
+    { match: /(^|\/)minio(:|$)/, port: 9000, env: (n) => ["S3_ENDPOINT", `http://{{container.${n}}}`] },
+    { match: /(^|\/)rabbitmq(:|$)/, port: 5672, env: (n) => ["AMQP_URL", `amqp://guest:guest@{{container.${n}}}`] },
+];
+/**
+ * Reads docker compose: a postgres / mysql service sets the database engine
+ * and image; Redis, Mongo, MinIO and other images become `containers`.
+ */
+async function fromCompose(root, notes) {
+    const db = {};
+    const containers = {};
+    const appEnv = {};
+    let mail = false;
+    const file = COMPOSE_FILES.find((f) => existsSync(path.join(root, f)));
+    if (!file)
+        return { db, containers, appEnv, mail };
+    let doc;
+    try {
+        doc = (parse(await readFile(path.join(root, file), "utf8")) ?? {});
+    }
+    catch (e) {
+        notes.push(`${file}: couldn't parse it (${e.message}); skipped`);
+        return { db, containers, appEnv, mail };
+    }
+    for (const [name, svc] of Object.entries(doc.services ?? {})) {
+        const image = typeof svc?.image === "string" ? svc.image : undefined;
+        if (!image) {
+            if (svc?.build)
+                notes.push(`${file}: service "${name}" is built from source; if it's the app, app.command replaces it`);
+            continue;
+        }
+        if (/(^|\/)(postgres|postgis)(:|$)/.test(image) || /(^|\/)postgis\//.test(image)) {
+            db.image = image;
+            notes.push(`db: Postgres image ${image} (${file} service "${name}")`);
+            continue;
+        }
+        if (/(^|\/)(mysql|mariadb)(:|$)/.test(image)) {
+            db.engine = "mysql";
+            db.image = image;
+            notes.push(`db: MySQL image ${image} (${file} service "${name}"). Install mysql2 and @testcontainers/mysql next to slicetest.`);
+            continue;
+        }
+        if (MAIL_CATCHERS.test(image)) {
+            mail = true;
+            Object.assign(appEnv, { SMTP_HOST: "{{mail.host}}", SMTP_PORT: "{{mail.port}}" });
+            notes.push(`mail: ${image} (${file} service "${name}") is replaced by slicetest's own SMTP server, passed to the app as SMTP_HOST / SMTP_PORT. Rename them to what your app reads`);
+            continue;
+        }
+        const known = KNOWN.find((k) => k.match.test(image));
+        const port = known?.port ?? containerPort(svc.ports?.[0] ?? svc.expose?.[0]);
+        if (!port) {
+            notes.push(`${file}: service "${name}" (${image}) exposes no port; skipped`);
+            continue;
+        }
+        const environment = envOf(svc.environment);
+        const command = Array.isArray(svc.command) ? svc.command.map(String) : typeof svc.command === "string" ? svc.command.split(/\s+/).filter(Boolean) : undefined;
+        containers[name] = {
+            image,
+            port,
+            ...(Object.keys(environment).length ? { env: environment } : {}),
+            ...(command?.length ? { command } : {}),
+            ...(known?.reset ? { reset: known.reset } : {}),
+        };
+        const [key, value] = known?.env?.(name) ?? [];
+        if (key && value)
+            appEnv[key] = value;
+        notes.push(`containers.${name}: ${image} (${file})${key ? `, passed to the app as ${key}` : `, at {{container.${name}}}`}${known?.reset ? "" : ". Add `reset` to empty it between scenarios"}`);
+    }
+    return { db, containers, appEnv, mail };
+}
+/** `"6379:6379"`, `"127.0.0.1:5432:5432/tcp"`, `9000`, `{ target: 6379 }` → the port inside the container. */
+export function containerPort(spec) {
+    if (spec && typeof spec === "object" && "target" in spec)
+        return Number(spec.target) || undefined;
+    if (typeof spec !== "string" && typeof spec !== "number")
+        return undefined;
+    const last = String(spec).split("/")[0].split(":").at(-1);
+    const n = Number(last.split("-")[0]);
+    return Number.isInteger(n) && n > 0 ? n : undefined;
+}
+function envOf(environment) {
+    if (Array.isArray(environment)) {
+        return Object.fromEntries(environment.map(String).filter((e) => e.includes("=")).map((e) => [e.slice(0, e.indexOf("=")), e.slice(e.indexOf("=") + 1)]));
+    }
+    if (environment && typeof environment === "object")
+        return Object.fromEntries(Object.entries(environment).map(([k, v]) => [k, String(v ?? "")]));
+    return {};
+}

package/dist/mail.d.ts

@@ -0,0 +1,58 @@
+/**
+ * An SMTP server that accepts every message and keeps it, so scenarios can
+ * check the mail an app sends (sign-up confirmations, password resets,
+ * receipts) without a real mail server. Apps in any language reach it at
+ * `{{mail.host}}:{{mail.port}}` with no TLS; any credentials are accepted.
+ */
+export interface Mail {
+    from: string;
+    /** Envelope recipients (RCPT TO), which include Cc and Bcc. */
+    to: string[];
+    subject: string;
+    /** The text/plain part, decoded. */
+    text: string;
+    /** The text/html part, decoded, if there is one. */
+    html?: string;
+    /** Header names are lower-case. Repeated headers are joined with ", ". */
+    headers: Record<string, string>;
+    /** Every http(s) URL in the text and HTML parts, in order, without duplicates. */
+    links: string[];
+    raw: string;
+}
+/**
+ * Which messages to look at. Strings match the address exactly (`to`, `from`,
+ * case-insensitive) or as a substring (`subject`, `text`, `html`); RegExps test the value.
+ */
+export interface MailFilter {
+    to?: string | RegExp;
+    from?: string | RegExp;
+    subject?: string | RegExp;
+    text?: string | RegExp;
+    html?: string | RegExp;
+}
+export declare class Mailbox {
+    #private;
+    private readonly server;
+    private constructor();
+    static start(): Promise<Mailbox>;
+    get host(): string;
+    get port(): number;
+    /** `smtp://127.0.0.1:<port>`, for libraries configured with a URL. */
+    get url(): string;
+    /** Messages received during this scenario, oldest first. */
+    messages(filter?: MailFilter): Mail[];
+    /** The most recent message matching `filter`, or undefined. */
+    last(filter?: MailFilter): Mail | undefined;
+    /**
+     * 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 }?: {
+        within?: number | undefined;
+    }): Promise<Mail>;
+    /** One line per message received this scenario, for failure output. */
+    describe(): string;
+    reset(): void;
+    close(): Promise<void>;
+}
+export declare function parseMail(raw: string, from: string, to: string[]): Mail;