slicetest 0.1.0

package/dist/config.d.ts

@@ -0,0 +1,69 @@
+import type { RequestOptions } from "./http.js";
+export interface SlicetestOptions {
+    app: AppOptions;
+    db?: DbOptions;
+    /** Names of outbound HTTP services to stub. Each gets its own server, referenced as `{{stub.<name>}}` in `app.env`. */
+    stubs?: string[];
+    /** Defaults for every request made with `http`, e.g. `{ headers: { accept: "application/json" } }`. */
+    http?: RequestOptions;
+}
+export interface AppOptions {
+    /** Command that starts the app, run through the shell. */
+    command: string;
+    cwd?: string;
+    /**
+     * Environment passed to the app. Values may reference
+     * `{{app.port}}`, `{{db.url}}` and `{{stub.<name>}}`.
+     * Defaults to `{ PORT: "{{app.port}}", DATABASE_URL: "{{db.url}}" }`.
+     */
+    env?: Record<string, string>;
+    /** How to tell the app is up. Defaults to polling `GET /` until it answers. */
+    ready?: {
+        path: string;
+    } | {
+        log: string | RegExp;
+    };
+    /** Milliseconds to wait for readiness. Default 30000. */
+    readyTimeout?: number;
+}
+export interface DbOptions {
+    /** Postgres image used when no `url` is given. Default `postgres:17-alpine`. */
+    image?: string;
+    /**
+     * Use an existing Postgres server instead of starting a container. Must point at a superuser-capable database.
+     * Defaults to the `SLICETEST_DATABASE_URL` environment variable, which is handy in CI.
+     */
+    url?: string;
+    migrate?: MigrateOptions;
+    /** SQL file (relative to the vitest root) run after every reset. */
+    seed?: string;
+    /** Schemas whose tables are reset between scenarios. Default `["public"]`. */
+    schemas?: string[];
+    /** Extra tables kept across resets, in addition to known migration bookkeeping tables. */
+    keep?: string[];
+}
+export type MigrateOptions = {
+    atlas: {
+        dir: string;
+    };
+} | {
+    sql: string;
+} | {
+    command: string;
+};
+/** Normalized shape passed from the plugin to globalSetup and workers. Must stay JSON-serializable. */
+export interface ResolvedOptions {
+    root: string;
+    app: Omit<AppOptions, "ready"> & {
+        ready: {
+            path: string;
+        } | {
+            log: string;
+            flags: string;
+        };
+    };
+    db: Required<Pick<DbOptions, "image" | "schemas" | "keep">> & Omit<DbOptions, "image" | "schemas" | "keep">;
+    stubs: string[];
+    http?: RequestOptions;
+}
+export declare function resolveOptions(opts: SlicetestOptions, root: string): ResolvedOptions;

package/dist/config.js

@@ -0,0 +1,54 @@
+export function resolveOptions(opts, root) {
+    validate(opts);
+    const ready = opts.app.ready ?? { path: "/" };
+    return {
+        root,
+        app: {
+            ...opts.app,
+            ready: "log" in ready
+                ? typeof ready.log === "string"
+                    ? { log: escapeRegExp(ready.log), flags: "" }
+                    : { log: ready.log.source, flags: ready.log.flags }
+                : ready,
+        },
+        db: {
+            image: "postgres:17-alpine",
+            schemas: ["public"],
+            keep: [],
+            ...opts.db,
+            url: opts.db?.url ?? (process.env.SLICETEST_DATABASE_URL || undefined),
+        },
+        stubs: opts.stubs ?? [],
+        http: opts.http,
+    };
+}
+function validate(opts) {
+    const fail = (msg) => {
+        throw new Error(`slicetest: invalid config: ${msg}`);
+    };
+    if (!opts?.app || typeof opts.app.command !== "string" || !opts.app.command.trim()) {
+        fail("app.command is required, e.g. { app: { command: \"node server.js\" } }");
+    }
+    const ready = opts.app.ready;
+    if (ready !== undefined && !("path" in ready) && !("log" in ready))
+        fail("app.ready must be { path } or { log }");
+    if (ready && "path" in ready && !ready.path.startsWith("/"))
+        fail(`app.ready.path must start with "/", got "${ready.path}"`);
+    const migrate = opts.db?.migrate;
+    if (migrate) {
+        const keys = Object.keys(migrate).filter((k) => ["atlas", "sql", "command"].includes(k));
+        if (keys.length !== 1)
+            fail(`db.migrate takes exactly one of atlas / sql / command, got ${keys.join(", ") || "none"}`);
+    }
+    const stubs = opts.stubs ?? [];
+    for (const name of stubs) {
+        if (!/^[\w-]+$/.test(name))
+            fail(`stub name "${name}" may only contain letters, digits, "_" and "-"`);
+    }
+    const dup = stubs.find((n, i) => stubs.indexOf(n) !== i);
+    if (dup)
+        fail(`stub "${dup}" is declared twice`);
+}
+function escapeRegExp(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}

package/dist/container-runtime.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Testcontainers talks to the Docker API. When Docker isn't configured but a
+ * Podman machine is running, point Testcontainers at Podman's socket (macOS,
+ * Linux) or named pipe (Windows).
+ */
+export declare function configureContainerRuntime(platform?: NodeJS.Platform): void;
+/** `\\.\pipe\podman-machine-default` → `npipe:////./pipe/podman-machine-default`. */
+export declare function dockerHost(location: string, windows: boolean): string;

package/dist/container-runtime.js

@@ -0,0 +1,31 @@
+import { execFileSync } from "node:child_process";
+/**
+ * Testcontainers talks to the Docker API. When Docker isn't configured but a
+ * Podman machine is running, point Testcontainers at Podman's socket (macOS,
+ * Linux) or named pipe (Windows).
+ */
+export function configureContainerRuntime(platform = process.platform) {
+    if (process.env.DOCKER_HOST)
+        return;
+    const windows = platform === "win32";
+    try {
+        const field = windows ? "PodmanPipe" : "PodmanSocket";
+        const location = execFileSync("podman", ["machine", "inspect", "--format", `{{.ConnectionInfo.${field}.Path}}`], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+            windowsHide: true,
+        }).trim();
+        if (!location || location === "<no value>")
+            return;
+        process.env.DOCKER_HOST = dockerHost(location, windows);
+        // Ryuk needs a privileged socket mount that rootless Podman usually refuses.
+        process.env.TESTCONTAINERS_RYUK_DISABLED ??= "true";
+    }
+    catch {
+        // No podman; let Testcontainers find Docker on its own.
+    }
+}
+/** `\\.\pipe\podman-machine-default` → `npipe:////./pipe/podman-machine-default`. */
+export function dockerHost(location, windows) {
+    return windows ? `npipe://${location.replace(/\\/g, "/")}` : `unix://${location}`;
+}

package/dist/db.d.ts

@@ -0,0 +1,39 @@
+export declare function withDatabase(url: string, database: string): string;
+export interface Row {
+    [column: string]: unknown;
+}
+/**
+ * Column filters. `null` means IS NULL and an array means IN (...);
+ * every other value is compared with `=`.
+ */
+export type Where = Record<string, unknown>;
+export interface RowsOptions {
+    /** Column(s) to sort by; prefix with `-` for descending. Default: the first column. */
+    orderBy?: string | string[];
+    limit?: number;
+}
+/** Test-side handle to the database the app under test is using. */
+export declare class Db {
+    #private;
+    readonly url: string;
+    private readonly opts;
+    private constructor();
+    static connect(url: string, opts: {
+        schemas: string[];
+        keep: string[];
+        seedFile?: string;
+    }): Promise<Db>;
+    query<T extends Row = Row>(sql: string, params?: unknown[]): Promise<T[]>;
+    /** Rows of a table, optionally filtered, ordered by the first column unless `orderBy` is given. */
+    rows<T extends Row = Row>(table: string, where?: Where, opts?: RowsOptions): Promise<T[]>;
+    /** The single row matching `where`. Throws, listing what was found, unless there is exactly one. */
+    one<T extends Row = Row>(table: string, where?: Where): Promise<T>;
+    /** Tagged-template query: values become bind parameters. */
+    sql<T extends Row = Row>(strings: TemplateStringsArray, ...values: unknown[]): Promise<T[]>;
+    count(table: string, where?: Where): Promise<number>;
+    /** Insert rows and return them as stored (with defaults and generated ids). */
+    insert<T extends Row = Row>(table: string, rows: Row | Row[]): Promise<T[]>;
+    /** Empty every data table without dropping the app's connections, then re-apply the seed. */
+    reset(): Promise<void>;
+    close(): Promise<void>;
+}

package/dist/db.js

@@ -0,0 +1,166 @@
+import { readFile } from "node:fs/promises";
+import pg from "pg";
+/** Tables that record applied migrations. Truncating them would make tools re-run migrations. */
+const MIGRATION_TABLES = [
+    "atlas_schema_revisions",
+    "schema_migrations",
+    "_prisma_migrations",
+    "__drizzle_migrations",
+    "knex_migrations",
+    "knex_migrations_lock",
+    "alembic_version",
+    "flyway_schema_history",
+    "goose_db_version",
+    "_sqlx_migrations",
+    "__diesel_schema_migrations",
+    "django_migrations",
+    "databasechangelog",
+    "databasechangeloglock",
+    "SequelizeMeta",
+    "ar_internal_metadata",
+    "__EFMigrationsHistory",
+];
+export function withDatabase(url, database) {
+    const u = new URL(url);
+    u.pathname = `/${database}`;
+    return u.toString();
+}
+const INT8 = 20;
+/** int8 columns (bigserial ids, count(*)) come back as numbers when they fit, instead of strings. */
+const types = {
+    getTypeParser(oid, format) {
+        if (oid === INT8 && format !== "binary") {
+            return (v) => {
+                const n = Number(v);
+                return Number.isSafeInteger(n) ? n : v;
+            };
+        }
+        return pg.types.getTypeParser(oid, format);
+    },
+};
+/** Test-side handle to the database the app under test is using. */
+export class Db {
+    url;
+    opts;
+    #client;
+    #tables;
+    #seed;
+    constructor(client, url, opts) {
+        this.url = url;
+        this.opts = opts;
+        this.#client = client;
+    }
+    static async connect(url, opts) {
+        const client = new pg.Client({ connectionString: url, types });
+        // Without a listener, a dropped connection would crash the worker; the next query reports it instead.
+        client.on("error", () => { });
+        await client.connect();
+        const db = new Db(client, url, opts);
+        if (opts.seedFile)
+            db.#seed = await readFile(opts.seedFile, "utf8");
+        return db;
+    }
+    async query(sql, params = []) {
+        return (await this.#client.query(sql, params)).rows;
+    }
+    /** Rows of a table, optionally filtered, ordered by the first column unless `orderBy` is given. */
+    async rows(table, where = {}, opts = {}) {
+        const { clause, params } = whereClause(where);
+        const order = [opts.orderBy ?? []]
+            .flat()
+            .map((c) => (c.startsWith("-") ? `${ident(c.slice(1))} DESC` : ident(c)))
+            .join(", ");
+        const limit = opts.limit === undefined ? "" : ` LIMIT ${Math.trunc(opts.limit)}`;
+        return this.query(`SELECT * FROM ${ident(table)}${clause} ORDER BY ${order || "1"}${limit}`, params);
+    }
+    /** The single row matching `where`. Throws, listing what was found, unless there is exactly one. */
+    async one(table, where = {}) {
+        const rows = await this.rows(table, where, { limit: 3 });
+        if (rows.length === 1)
+            return rows[0];
+        const found = rows.length === 0 ? "none" : `${rows.length === 3 ? "3 or more" : rows.length}, e.g.\n${rows.map((r) => `  ${JSON.stringify(r)}`).join("\n")}`;
+        throw new Error(`slicetest: expected exactly one row in ${table} where ${JSON.stringify(where)}, found ${found}`);
+    }
+    /** Tagged-template query: values become bind parameters. */
+    sql(strings, ...values) {
+        const text = strings.reduce((acc, s, i) => acc + `$${i}` + s);
+        return this.query(text, values);
+    }
+    async count(table, where = {}) {
+        const { clause, params } = whereClause(where);
+        const [row] = await this.query(`SELECT count(*) AS n FROM ${ident(table)}${clause}`, params);
+        return Number(row.n);
+    }
+    /** Insert rows and return them as stored (with defaults and generated ids). */
+    async insert(table, rows) {
+        const list = Array.isArray(rows) ? rows : [rows];
+        const out = [];
+        for (const row of list) {
+            const cols = Object.keys(row);
+            const sql = cols.length === 0
+                ? `INSERT INTO ${ident(table)} DEFAULT VALUES RETURNING *`
+                : `INSERT INTO ${ident(table)} (${cols.map(ident).join(", ")}) VALUES (${cols
+                    .map((_, i) => `$${i + 1}`)
+                    .join(", ")}) RETURNING *`;
+            out.push(...(await this.query(sql, Object.values(row))));
+        }
+        return out;
+    }
+    /** Empty every data table without dropping the app's connections, then re-apply the seed. */
+    async reset() {
+        this.#tables ??= await this.#listTables();
+        if (this.#tables.length > 0) {
+            await this.#client.query(`TRUNCATE ${this.#tables.join(", ")} RESTART IDENTITY CASCADE`);
+        }
+        if (this.#seed)
+            await this.#client.query(this.#seed);
+    }
+    /**
+     * Tables to empty: ordinary tables in the configured schemas, minus migration
+     * bookkeeping, `keep` (bare or `schema.table`) and tables owned by extensions
+     * such as PostGIS's `spatial_ref_sys`.
+     */
+    async #listTables() {
+        const keep = [...MIGRATION_TABLES, ...this.opts.keep];
+        const rows = await this.query(`SELECT n.nspname AS schema, c.relname AS name
+         FROM pg_class c
+         JOIN pg_namespace n ON n.oid = c.relnamespace
+        WHERE c.relkind IN ('r', 'p')
+          AND NOT c.relispartition
+          AND n.nspname = ANY($1)
+          AND NOT (c.relname = ANY($2) OR n.nspname || '.' || c.relname = ANY($2))
+          AND NOT EXISTS (
+            SELECT 1 FROM pg_depend d
+             WHERE d.classid = 'pg_class'::regclass AND d.objid = c.oid AND d.deptype = 'e')
+        ORDER BY 1, 2`, [this.opts.schemas, keep]);
+        return rows.map((r) => `${ident(r.schema)}.${ident(r.name)}`);
+    }
+    async close() {
+        await this.#client.end();
+    }
+}
+function whereClause(where) {
+    const conds = [];
+    const params = [];
+    for (const [col, value] of Object.entries(where)) {
+        if (value === null || value === undefined) {
+            conds.push(`${ident(col)} IS NULL`);
+        }
+        else if (Array.isArray(value)) {
+            params.push(value);
+            conds.push(`${ident(col)} = ANY($${params.length})`);
+        }
+        else {
+            params.push(value);
+            conds.push(`${ident(col)} = $${params.length}`);
+        }
+    }
+    return { clause: conds.length ? ` WHERE ${conds.join(" AND ")}` : "", params };
+}
+/** Quote an identifier; `schema.table` is split on the dot. */
+function ident(name) {
+    return name
+        .split(".")
+        .map((part) => `"${part.replace(/"/g, '""')}"`)
+        .join(".");
+}

package/dist/global-setup.d.ts

@@ -0,0 +1,9 @@
+import type { TestProject } from "vitest/node";
+import "./provided.js";
+/** Runs once per vitest run: start Postgres, migrate a template database, hand its location to the workers. */
+export default function setup(project: TestProject): Promise<() => Promise<void>>;
+/**
+ * Atlas wants `file://<path>` with forward slashes. Absolute paths (including
+ * Windows drive paths) are made relative to the root, which is the cwd Atlas runs in.
+ */
+export declare function atlasDirUrl(dir: string, root: string): string;

package/dist/global-setup.js

@@ -0,0 +1,105 @@
+import { execFile } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { readdir, readFile, stat } from "node:fs/promises";
+import path from "node:path";
+import { promisify } from "node:util";
+import pg from "pg";
+import { configureContainerRuntime } from "./container-runtime.js";
+import { withDatabase } from "./db.js";
+import "./provided.js";
+const exec = promisify(execFile);
+/** Runs once per vitest run: start Postgres, migrate a template database, hand its location to the workers. */
+export default async function setup(project) {
+    const opts = project.getProvidedContext().slicetestOptions;
+    let adminUrl;
+    let stopContainer;
+    if (opts.db.url) {
+        adminUrl = opts.db.url;
+    }
+    else {
+        configureContainerRuntime();
+        const { PostgreSqlContainer } = await import("@testcontainers/postgresql");
+        const container = await new PostgreSqlContainer(opts.db.image).start();
+        adminUrl = container.getConnectionUri();
+        stopContainer = () => container.stop();
+    }
+    // Unique per run and project, so parallel runs and projects sharing one server never collide.
+    const prefix = `slicetest_${randomBytes(4).toString("hex")}`;
+    const template = `${prefix}_template`;
+    const admin = new pg.Client({ connectionString: adminUrl });
+    try {
+        await admin.connect();
+        await admin.query(`CREATE DATABASE "${template}"`);
+        await migrate(opts, withDatabase(adminUrl, template));
+    }
+    catch (e) {
+        await admin.end().catch(() => { });
+        await stopContainer?.();
+        throw e;
+    }
+    project.provide("slicetestDb", { adminUrl, template, prefix });
+    return async () => {
+        try {
+            if (!stopContainer) {
+                // Shared server: drop only the databases this run created.
+                const { rows } = await admin.query("SELECT datname FROM pg_database WHERE starts_with(datname, $1)", [`${prefix}_`]);
+                for (const { datname } of rows)
+                    await admin.query(`DROP DATABASE "${datname}" WITH (FORCE)`);
+            }
+        }
+        finally {
+            await admin.end();
+            await stopContainer?.();
+        }
+    };
+}
+async function migrate(opts, url) {
+    const m = opts.db.migrate;
+    if (!m)
+        return;
+    if ("atlas" in m) {
+        const dir = atlasDirUrl(m.atlas.dir, opts.root);
+        const u = new URL(url);
+        if (!u.searchParams.has("sslmode"))
+            u.searchParams.set("sslmode", "disable");
+        await run("atlas", ["migrate", "apply", "--url", u.toString(), "--dir", dir], opts.root);
+    }
+    else if ("sql" in m) {
+        const target = path.resolve(opts.root, m.sql);
+        const files = (await stat(target)).isDirectory()
+            ? (await readdir(target)).filter((f) => f.endsWith(".sql")).sort().map((f) => path.join(target, f))
+            : [target];
+        const client = new pg.Client({ connectionString: url });
+        await client.connect();
+        try {
+            for (const file of files)
+                await client.query(await readFile(file, "utf8"));
+        }
+        finally {
+            await client.end();
+        }
+    }
+    else {
+        // Through the platform shell (sh or cmd.exe), like app.command.
+        await run(m.command, [], opts.root, { DATABASE_URL: url }, true);
+    }
+}
+/**
+ * Atlas wants `file://<path>` with forward slashes. Absolute paths (including
+ * Windows drive paths) are made relative to the root, which is the cwd Atlas runs in.
+ */
+export function atlasDirUrl(dir, root) {
+    if (dir.startsWith("file://"))
+        return dir;
+    const rel = path.isAbsolute(dir) || /^[a-zA-Z]:[\\/]/.test(dir) ? path.relative(root, dir) : dir;
+    return `file://${rel.replace(/\\/g, "/")}`;
+}
+async function run(cmd, args, cwd, env = {}, shell = false) {
+    try {
+        await exec(cmd, args, { cwd, env: { ...process.env, ...env }, shell, windowsHide: true });
+    }
+    catch (e) {
+        const err = e;
+        throw new Error(`slicetest: migration failed: ${cmd} ${args.join(" ")}\n${err.stderr || err.stdout || err.message}`);
+    }
+}

package/dist/http.d.ts

@@ -0,0 +1,51 @@
+export interface HttpResponse {
+    method: string;
+    url: string;
+    status: number;
+    headers: Headers;
+    text: string;
+    /** Parsed JSON body, or undefined when the body isn't JSON. */
+    json: any;
+    /** Wall-clock time of the request in milliseconds. */
+    durationMs: number;
+}
+export interface RequestOptions {
+    headers?: Record<string, string>;
+    query?: Record<string, string | number | boolean | undefined>;
+    /** Follow redirects instead of returning the 3xx response. Default false. */
+    follow?: boolean;
+}
+/** Per-scenario state shared by a client and every client derived from it with `with()`. */
+declare class Session {
+    cookies: Map<string, string>;
+    history: HttpResponse[];
+}
+/** HTTP client bound to the app under test. Keeps cookies for the duration of a scenario. */
+export declare class HttpClient {
+    #private;
+    readonly baseUrl: string;
+    private readonly defaults;
+    constructor(baseUrl: string, defaults?: RequestOptions, session?: Session);
+    /** A client that adds `opts` (e.g. an auth header) to every request, sharing this one's cookies. */
+    with(opts: RequestOptions): HttpClient;
+    /** Wrap fields to be sent as `application/x-www-form-urlencoded`. */
+    form(fields: Record<string, string | number | boolean>): URLSearchParams;
+    get(path: string, opts?: RequestOptions): Promise<HttpResponse>;
+    head(path: string, opts?: RequestOptions): Promise<HttpResponse>;
+    delete(path: string, opts?: RequestOptions): Promise<HttpResponse>;
+    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>;
+    /** 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>;
+    /** Cookies the app has set during this scenario. Mutations are sent with later requests. */
+    get cookies(): Map<string, string>;
+    clearCookies(): void;
+    /** Requests made during the current scenario, oldest first (last 20). */
+    get history(): readonly HttpResponse[];
+    /** Start a new scenario: forget cookies and history. */
+    reset(): void;
+}
+/** One line per request, for failure output. */
+export declare function formatHistory(history: readonly HttpResponse[]): string;
+export {};