slicetest 0.2.0 → 0.4.0

package/dist/config.js

@@ -4,6 +4,8 @@ export function resolveOptions(opts, root) {
         root,
         app: { ...opts.app, ready: resolveReady(opts.app.ready ?? { path: "/" }) },
         services: Object.fromEntries(Object.entries(opts.services ?? {}).map(([name, s]) => [name, { ...s, ready: s.ready && resolveReady(s.ready) }])),
+        containers: opts.containers ?? {},
+        mail: opts.mail ?? false,
         db: resolveDb(opts.db ?? {}),
         stubs: (opts.stubs ?? []).map(stubName),
         openapi: {
@@ -12,21 +14,39 @@ export function resolveOptions(opts, root) {
             stubs: Object.fromEntries((opts.stubs ?? []).flatMap((s) => (typeof s === "object" && s.openapi ? [[s.name, s.openapi]] : []))),
             autoReply: (opts.stubs ?? []).flatMap((s) => (typeof s === "object" && s.autoReply ? [s.name] : [])),
         },
+        recordings: resolveRecordings(opts.stubs ?? []),
         http: opts.http,
     };
 }
+function resolveRecordings(stubs) {
+    const withUpstream = stubs.filter((s) => typeof s === "object" && !!s.upstream);
+    const env = (process.env.SLICETEST_RECORD ?? "").trim();
+    const all = ["1", "true", "all", "*"].includes(env.toLowerCase());
+    const names = all || !env ? [] : env.split(",").map((n) => n.trim()).filter(Boolean);
+    for (const n of names) {
+        if (!withUpstream.some((s) => s.name === n)) {
+            throw new Error(`slicetest: SLICETEST_RECORD names "${n}", but no stub of that name has an upstream. Stubs with one: ${withUpstream.map((s) => s.name).join(", ") || "(none)"}`);
+        }
+    }
+    return Object.fromEntries(withUpstream.map((s) => [s.name, { file: s.recordings ?? `recordings/${s.name}.yaml`, upstream: s.upstream, record: all || names.includes(s.name) }]));
+}
 function resolveReady(ready) {
     if (!("log" in ready))
         return ready;
     return typeof ready.log === "string" ? { log: escapeRegExp(ready.log), flags: "" } : { log: ready.log.source, flags: ready.log.flags };
 }
 function resolveDb(db) {
-    const url = db.url ?? (process.env.SLICETEST_DATABASE_URL || undefined);
+    const isMysql = (u) => /^mysql:/i.test(u);
+    const env = process.env.SLICETEST_DATABASE_URL || undefined;
+    const engine = db.engine ?? (isMysql(db.url ?? env ?? "") ? "mysql" : "postgres");
+    // The environment variable names one server for the whole CI job; a project on the other engine starts its own.
+    const url = engine === "sqlite" ? undefined : (db.url ?? (env && isMysql(env) === (engine === "mysql") ? env : undefined));
     return {
-        image: "postgres:17-alpine",
+        image: engine === "mysql" ? "mysql:8.4" : engine === "sqlite" ? "" : "postgres:17-alpine",
         schemas: ["public"],
         keep: [],
         ...db,
+        engine,
         url,
         reuse: db.reuse ?? (!url && !process.env.CI),
     };
@@ -52,6 +72,26 @@ function validate(opts) {
             fail(`services.${name}.command is required`);
         checkReady(s.ready, `services.${name}`);
     }
+    for (const [name, c] of Object.entries(opts.containers ?? {})) {
+        if (!/^[\w-]+$/.test(name))
+            fail(`container name "${name}" may only contain letters, digits, "_" and "-"`);
+        if (!c || typeof c.image !== "string" || !c.image)
+            fail(`containers.${name}.image is required, e.g. "redis:7-alpine"`);
+        if (!Number.isInteger(c.port) || c.port <= 0)
+            fail(`containers.${name}.port must be the port the service listens on inside the container, e.g. 6379`);
+        for (const key of ["command", "reset"]) {
+            const v = c[key];
+            if (v !== undefined && !(Array.isArray(v) && v.length > 0 && v.every((x) => typeof x === "string")))
+                fail(`containers.${name}.${key} must be a list of strings, e.g. ["redis-cli", "FLUSHALL"]`);
+        }
+    }
+    if (opts.mail !== undefined && typeof opts.mail !== "boolean")
+        fail(`mail must be true or false, got ${JSON.stringify(opts.mail)}`);
+    const engine = opts.db?.engine;
+    if (engine !== undefined && engine !== "postgres" && engine !== "mysql" && engine !== "sqlite")
+        fail(`db.engine must be "postgres", "mysql" or "sqlite", got ${JSON.stringify(engine)}`);
+    if (engine === "sqlite" && opts.db?.url)
+        fail("db.url doesn't apply to sqlite: slicetest creates the database files itself and passes them to the app as {{db.url}} / {{db.path}}");
     const migrate = opts.db?.migrate;
     if (migrate) {
         const keys = Object.keys(migrate).filter((k) => ["atlas", "sql", "command"].includes(k));
@@ -72,6 +112,10 @@ function validate(opts) {
             fail(`each stub must be a name or { name, openapi }, got ${JSON.stringify(s)}`);
         if (typeof s === "object" && s.autoReply && !s.openapi)
             fail(`stub "${s.name}": autoReply needs an openapi spec to answer from`);
+        if (typeof s === "object" && s.upstream !== undefined && !/^https?:\/\/[^/]/.test(s.upstream))
+            fail(`stub "${s.name}": upstream must be an http(s) URL, got ${JSON.stringify(s.upstream)}`);
+        if (typeof s === "object" && s.recordings !== undefined && !s.upstream)
+            fail(`stub "${s.name}": recordings needs an upstream to record from`);
     }
     const stubs = (opts.stubs ?? []).map(stubName);
     for (const name of stubs) {

package/dist/containers.d.ts

@@ -0,0 +1,22 @@
+import type { ContainerOptions } from "./config.js";
+/**
+ * A container the app depends on (Redis, a search engine, an S3 emulator),
+ * started for one test file and emptied between scenarios with `reset`.
+ */
+export declare class Dependency {
+    readonly name: string;
+    private readonly container;
+    private readonly opts;
+    private constructor();
+    static start(name: string, opts: ContainerOptions): Promise<Dependency>;
+    get host(): string;
+    /** The host port mapped to the container's `port`. */
+    get port(): number;
+    /** `host:port`, to put after a scheme: `redis://{{container.cache}}`. */
+    get address(): string;
+    /** Run a command inside the container; throws with its output unless it exits with 0. */
+    exec(command: string[]): Promise<string>;
+    /** Start of a scenario: run the `reset` command, if any. */
+    reset(): Promise<void>;
+    stop(): Promise<void>;
+}

package/dist/containers.js

@@ -0,0 +1,59 @@
+import { configureContainerRuntime } from "./container-runtime.js";
+/**
+ * A container the app depends on (Redis, a search engine, an S3 emulator),
+ * started for one test file and emptied between scenarios with `reset`.
+ */
+export class Dependency {
+    name;
+    container;
+    opts;
+    constructor(name, container, opts) {
+        this.name = name;
+        this.container = container;
+        this.opts = opts;
+    }
+    static async start(name, opts) {
+        configureContainerRuntime();
+        const { GenericContainer, Wait } = await import("testcontainers");
+        let definition = new GenericContainer(opts.image).withExposedPorts(opts.port);
+        if (opts.env)
+            definition = definition.withEnvironment(opts.env);
+        if (opts.command)
+            definition = definition.withCommand(opts.command);
+        if (opts.ready)
+            definition = definition.withWaitStrategy(Wait.forLogMessage(opts.ready.log));
+        try {
+            return new Dependency(name, await definition.start(), opts);
+        }
+        catch (e) {
+            throw new Error(`slicetest: container "${name}" (${opts.image}) didn't start: ${e.message}`);
+        }
+    }
+    get host() {
+        return this.container.getHost();
+    }
+    /** The host port mapped to the container's `port`. */
+    get port() {
+        return this.container.getMappedPort(this.opts.port);
+    }
+    /** `host:port`, to put after a scheme: `redis://{{container.cache}}`. */
+    get address() {
+        return `${this.host}:${this.port}`;
+    }
+    /** Run a command inside the container; throws with its output unless it exits with 0. */
+    async exec(command) {
+        const res = await this.container.exec(command);
+        if (res.exitCode !== 0) {
+            throw new Error(`slicetest: \`${command.join(" ")}\` in container "${this.name}" exited with ${res.exitCode}:\n${res.output.trim()}`);
+        }
+        return res.stdout;
+    }
+    /** Start of a scenario: run the `reset` command, if any. */
+    async reset() {
+        if (this.opts.reset)
+            await this.exec(this.opts.reset);
+    }
+    async stop() {
+        await this.container.stop();
+    }
+}

package/dist/doctor.d.ts

@@ -0,0 +1,22 @@
+import { type ResolvedOptions } from "./config.js";
+/**
+ * `slicetest doctor`: everything a run needs, checked up front, each problem
+ * with what to do about it. Meant for a first setup and for CI logs, where a
+ * container runtime that isn't there otherwise shows up as a timeout.
+ */
+export interface Check {
+    status: "ok" | "warn" | "fail";
+    label: string;
+    /** What was found, or what to do. */
+    detail?: string;
+}
+/** Things that touch the machine, replaceable in tests. */
+export interface Probes {
+    containerRuntime(): Promise<string>;
+    database(opts: ResolvedOptions, url: string): Promise<void>;
+    command(name: string, args: string[]): Promise<string>;
+    resolvePackage(name: string, from: string): boolean;
+}
+export declare const machine: Probes;
+export declare function doctor(configPath: string | undefined, probes?: Probes, env?: NodeJS.ProcessEnv): Promise<Check[]>;
+export declare function formatChecks(checks: Check[]): string;

package/dist/doctor.js

@@ -0,0 +1,190 @@
+import { execFile } from "node:child_process";
+import { existsSync } from "node:fs";
+import { readFile, stat } from "node:fs/promises";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { promisify } from "node:util";
+import { parse } from "yaml";
+import { resolveOptions } from "./config.js";
+import { configureContainerRuntime } from "./container-runtime.js";
+import { engineFor } from "./drivers/index.js";
+import { OpenApiSpec } from "./openapi.js";
+const exec = promisify(execFile);
+export const machine = {
+    async containerRuntime() {
+        configureContainerRuntime();
+        const { getContainerRuntimeClient } = await import("testcontainers");
+        const client = await withTimeout(getContainerRuntimeClient(), 15_000, "no answer from the container runtime");
+        const { containerRuntime: rt } = client.info;
+        return `${rt.operatingSystem} ${rt.serverVersion} at ${rt.host}`;
+    },
+    async database(opts, url) {
+        const admin = await withTimeout((await engineFor(opts)).admin(url), 10_000, "connection timed out");
+        await admin.close();
+    },
+    async command(name, args) {
+        const { stdout, stderr } = await exec(name, args, { windowsHide: true, timeout: 10_000, shell: process.platform === "win32" });
+        return (stdout || stderr).trim().split(/\r?\n/)[0];
+    },
+    resolvePackage(name, from) {
+        try {
+            createRequire(path.join(from, "noop.js")).resolve(`${name}/package.json`);
+            return true;
+        }
+        catch {
+            try {
+                createRequire(import.meta.url).resolve(name);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        }
+    },
+};
+export async function doctor(configPath, probes = machine, env = process.env) {
+    const checks = [];
+    const add = (status, label, detail) => checks.push({ status, label, ...(detail ? { detail } : {}) });
+    const major = Number(process.versions.node.split(".")[0]);
+    add(major >= 20 ? "ok" : "fail", `Node.js ${process.versions.node}`, major >= 20 ? undefined : "slicetest needs Node.js 20 or later");
+    if (!configPath || !existsSync(configPath)) {
+        add("warn", "no slicetest.config.yaml", "checked the machine only. `npx slicetest init` writes a config; with the Vitest plugin, pass the same options to --config as YAML to check them");
+        await checkContainerRuntime(add, probes);
+        return checks;
+    }
+    const root = path.dirname(configPath);
+    const rel = (p) => path.relative(process.cwd(), path.resolve(root, p)) || ".";
+    let opts;
+    try {
+        const raw = (parse(await readFile(configPath, "utf8")) ?? {});
+        delete raw.include;
+        opts = resolveOptions(raw, root);
+        add("ok", `config ${rel(configPath)}`);
+    }
+    catch (e) {
+        add("fail", `config ${rel(configPath)}`, e.message.replace(/^slicetest: /, ""));
+        return checks;
+    }
+    // Database: a server that's there already, or a container runtime to start one in.
+    const url = opts.db.engine === "sqlite" ? undefined : (opts.db.url ?? env.SLICETEST_DATABASE_URL);
+    if (opts.db.engine === "sqlite") {
+        const [maj = 0, min = 0] = process.versions.node.split(".").map(Number);
+        if (maj > 22 || (maj === 22 && min >= 5))
+            add("ok", "sqlite (node:sqlite, no server needed)");
+        else
+            add("fail", "sqlite needs Node.js 22.5 or later", `this is ${process.versions.node}; slicetest uses the built-in node:sqlite`);
+        if (Object.keys(opts.containers).length)
+            await checkContainerRuntime(add, probes, `runs ${Object.values(opts.containers).map((c) => c.image).join(", ")}`);
+    }
+    else if (url) {
+        try {
+            await probes.database(opts, url);
+            add("ok", `${opts.db.engine} at ${redact(url)}`);
+        }
+        catch (e) {
+            add("fail", `${opts.db.engine} at ${redact(url)}`, `can't connect: ${e.message}. It must be a superuser (root) connection that can create databases`);
+        }
+    }
+    else {
+        await checkContainerRuntime(add, probes, `runs ${[opts.db.image, ...Object.values(opts.containers).map((c) => c.image)].join(", ")}`);
+    }
+    if (opts.db.engine === "mysql") {
+        for (const pkg of ["mysql2", ...(url ? [] : ["@testcontainers/mysql"])]) {
+            if (probes.resolvePackage(pkg, root))
+                add("ok", `${pkg} installed`);
+            else
+                add("fail", `${pkg} not installed`, `db.engine "mysql" needs it: npm i -D ${pkg}`);
+        }
+    }
+    const m = opts.db.migrate;
+    if (!m)
+        add("warn", "db.migrate not set", "scenarios run against an empty database unless the app creates its own tables");
+    else if ("atlas" in m) {
+        await checkPath(add, "migrations", m.atlas.dir.replace(/^file:\/\//, ""), root, rel);
+        try {
+            add("ok", `atlas CLI (${await probes.command("atlas", ["version"])})`);
+        }
+        catch {
+            add("fail", "atlas CLI not found", "db.migrate.atlas runs `atlas migrate apply`. Install it: https://atlasgo.io/getting-started");
+        }
+    }
+    else if ("sql" in m)
+        await checkPath(add, "migrations", m.sql, root, rel);
+    else
+        for (const input of m.inputs ?? [])
+            await checkPath(add, "migration input", input, root, rel);
+    if (opts.db.seed)
+        await checkPath(add, "seed", opts.db.seed, root, rel);
+    for (const [label, p] of [["app", opts.app], ...Object.entries(opts.services).map(([n, s]) => [`service ${n}`, s])]) {
+        if (p.cwd)
+            await checkPath(add, `${label} cwd`, p.cwd, root, rel);
+        const program = firstWord(p.command);
+        if (program && !/^[.\\/]|\{\{|\$/.test(program)) {
+            if (await onPath(program, env))
+                add("ok", `${label}: ${program} found`);
+            else
+                add("warn", `${label}: ${program} not found on PATH`, `\`${p.command}\` may fail to start. Fine if a shell alias or a relative script provides it`);
+        }
+    }
+    const specs = [...(opts.openapi.app ? [["app OpenAPI", opts.openapi.app]] : []), ...Object.entries(opts.openapi.stubs).map(([n, f]) => [`stub ${n} OpenAPI`, f])];
+    for (const [label, file] of specs) {
+        try {
+            const spec = await OpenApiSpec.load(path.resolve(root, file), file);
+            add("ok", `${label} ${rel(file)}`, `${spec.operations().length} operation(s)`);
+        }
+        catch (e) {
+            add("fail", `${label} ${rel(file)}`, e.message.replace(/^slicetest: /, ""));
+        }
+    }
+    for (const [name, r] of Object.entries(opts.recordings)) {
+        if (existsSync(r.file))
+            add("ok", `stub ${name}: recordings ${rel(r.file)}`);
+        else
+            add("warn", `stub ${name}: no recordings yet (${rel(r.file)})`, `run once with SLICETEST_RECORD=${name} to record ${r.upstream}`);
+    }
+    return checks;
+}
+async function checkContainerRuntime(add, probes, forWhat) {
+    try {
+        add("ok", `container runtime: ${await probes.containerRuntime()}`, forWhat);
+    }
+    catch (e) {
+        add("fail", "no container runtime", `${e.message.split("\n")[0]}. Start Docker or a Podman machine (\`podman machine start\`), or set SLICETEST_DATABASE_URL / db.url to an existing database server`);
+    }
+}
+async function checkPath(add, label, p, root, rel) {
+    try {
+        await stat(path.resolve(root, p));
+        add("ok", `${label} ${rel(p)}`);
+    }
+    catch {
+        add("fail", `${label} ${rel(p)} not found`, `paths in the config are relative to the config file's directory (${rel(".")})`);
+    }
+}
+function firstWord(command) {
+    return /^\s*(?:"([^"]+)"|(\S+))/.exec(command)?.slice(1).find(Boolean);
+}
+async function onPath(program, env) {
+    const exts = process.platform === "win32" ? (env.PATHEXT ?? ".EXE;.CMD;.BAT").split(";") : [""];
+    for (const dir of (env.PATH ?? env.Path ?? "").split(path.delimiter).filter(Boolean)) {
+        for (const ext of exts) {
+            if (existsSync(path.join(dir, program + ext)) || existsSync(path.join(dir, program)))
+                return true;
+        }
+    }
+    return false;
+}
+function redact(url) {
+    return url.replace(/\/\/([^:/@]+):[^@]*@/, "//$1:***@");
+}
+function withTimeout(p, ms, message) {
+    return Promise.race([p, new Promise((_, reject) => setTimeout(() => reject(new Error(message)), ms).unref())]);
+}
+export function formatChecks(checks) {
+    const icon = { ok: "✓", warn: "!", fail: "✗" };
+    const lines = checks.map((c) => `  ${icon[c.status]} ${c.label}${c.detail ? `\n      ${c.detail}` : ""}`);
+    const fails = checks.filter((c) => c.status === "fail").length;
+    const warns = checks.filter((c) => c.status === "warn").length;
+    const summary = fails ? `${fails} problem(s) to fix before running.` : warns ? `Ready to run, with ${warns} warning(s).` : "Ready to run.";
+    return `${lines.join("\n")}\n\n${summary}\n`;
+}

package/dist/drivers/driver.d.ts

@@ -54,6 +54,8 @@ export interface Engine {
     name: string;
     /** Container image used when no `db.url` is given. */
     defaultImage: string;
+    /** Runs in-process (SQLite): no container runtime needed. */
+    local?: boolean;
     startContainer(image: string, reuse: boolean): Promise<{
         url: string;
         stop(): Promise<unknown>;

package/dist/drivers/index.d.ts

@@ -1,5 +1,5 @@
 import type { ResolvedOptions } from "../config.js";
 import type { Engine } from "./driver.js";
 export type { Admin, Driver, Engine, Row, Table } from "./driver.js";
-/** The database engine a run uses. */
-export declare function engineFor(_opts: Pick<ResolvedOptions, "db">): Engine;
+/** The database engine a run uses. MySQL's driver is an optional dependency, loaded only when asked for. */
+export declare function engineFor(opts: Pick<ResolvedOptions, "db">): Promise<Engine>;

package/dist/drivers/index.js

@@ -1,5 +1,16 @@
 import { postgres } from "./postgres.js";
-/** The database engine a run uses. */
-export function engineFor(_opts) {
+/** The database engine a run uses. MySQL's driver is an optional dependency, loaded only when asked for. */
+export async function engineFor(opts) {
+    if (opts.db.engine === "mysql") {
+        const mod = await import("./mysql.js").catch((e) => {
+            if (e.code === "ERR_MODULE_NOT_FOUND") {
+                throw new Error('slicetest: db.engine "mysql" needs the mysql2 package: npm i -D mysql2');
+            }
+            throw e;
+        });
+        return mod.mysqlEngine;
+    }
+    if (opts.db.engine === "sqlite")
+        return (await import("./sqlite.js")).sqliteEngine;
     return postgres;
 }

package/dist/drivers/mysql.d.ts

@@ -0,0 +1,29 @@
+import type { Driver, Engine, Row, Table } from "./driver.js";
+export declare class MysqlDriver implements Driver {
+    #private;
+    private readonly conn;
+    private constructor();
+    static connect(url: string): Promise<MysqlDriver>;
+    query<T extends Row = Row>(sql: string, params?: unknown[]): Promise<T[]>;
+    queryAll(sqls: string[]): Promise<Row[][]>;
+    exec(script: string): Promise<void>;
+    ident(name: string): string;
+    column(name: string): string;
+    param(_n: number): string;
+    inList(column: string, values: unknown[], params: unknown[]): string;
+    /**
+     * Base tables in the configured schemas. In MySQL a schema is a database;
+     * `public` (the default) stands for the database the URL points at.
+     */
+    listTables(schemas: string[], keep: string[]): Promise<Table[]>;
+    /**
+     * TRUNCATE also restarts AUTO_INCREMENT, but it is DDL and costs a few
+     * milliseconds per table, so only tables that have rows or a used counter are
+     * truncated. Foreign key checks are off for this session only.
+     */
+    truncate(tables: Table[]): Promise<void>;
+    /** MySQL has no RETURNING: insert, then read the row back by its primary key. */
+    insert(table: string, row: Row): Promise<Row[]>;
+    close(): Promise<void>;
+}
+export declare const mysqlEngine: Engine;