slicetest 0.1.0 → 0.3.0

package/dist/db.js

@@ -1,5 +1,4 @@
 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",
@@ -20,52 +19,34 @@ const MIGRATION_TABLES = [
     "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;
+    #driver;
     #tables;
     #seed;
-    constructor(client, url, opts) {
+    /** Contents right after the reset (and seed); undefined means every table was empty. */
+    #start;
+    #checkpoint;
+    constructor(driver, 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);
+        this.#driver = driver;
+    }
+    static async connect(driver, url, opts) {
+        const db = new Db(driver, 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;
+        return this.#driver.query(sql, params);
     }
     /** 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 { clause, params } = this.#where(where);
+        const ident = (c) => this.#driver.ident(c);
         const order = [opts.orderBy ?? []]
             .flat()
             .map((c) => (c.startsWith("-") ? `${ident(c.slice(1))} DESC` : ident(c)))
@@ -83,37 +64,63 @@ export class Db {
     }
     /** Tagged-template query: values become bind parameters. */
     sql(strings, ...values) {
-        const text = strings.reduce((acc, s, i) => acc + `$${i}` + s);
+        const text = strings.reduce((acc, s, i) => acc + this.#driver.param(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);
+        const { clause, params } = this.#where(where);
+        const [row] = await this.query(`SELECT count(*) AS n FROM ${this.#driver.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))));
-        }
+        for (const row of list)
+            out.push(...(await this.#driver.insert(table, 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`);
+        await this.#driver.truncate(this.#tables);
+        this.#start = undefined;
+        this.#checkpoint = undefined;
+        if (this.#seed) {
+            await this.#driver.exec(this.#seed);
+            this.#start = await this.#snapshot();
         }
-        if (this.#seed)
-            await this.#client.query(this.#seed);
+    }
+    /**
+     * What changed in the database since the scenario started (after the seed),
+     * or since the last `checkpoint()`: inserted, updated and deleted rows per table.
+     *
+     * ```ts
+     * await db.checkpoint();                 // ignore the rows the test arranged
+     * await http.post("/polls", { ... });
+     * expect(await db.changes()).toEqual({ polls: { inserted: [expect.objectContaining({ title: "x" })], updated: [], deleted: [] } });
+     * ```
+     */
+    async changes() {
+        const base = this.#checkpoint === undefined || this.#checkpoint === "start" ? this.#start : this.#checkpoint;
+        return diff(this.#tables ?? [], base, await this.#snapshot());
+    }
+    /** Make `changes()` report only what happens from now on. */
+    async checkpoint() {
+        this.#checkpoint = await this.#snapshot();
+    }
+    /** Changes since the scenario started, regardless of checkpoints. Used for failure output. */
+    async changesSinceStart() {
+        return diff(this.#tables ?? [], this.#start, await this.#snapshot());
+    }
+    /** Every tracked table's rows, in one round trip. */
+    async #snapshot() {
+        const tables = (this.#tables ??= await this.#listTables());
+        const snap = new Map();
+        const order = (t) => (t.key.length ? ` ORDER BY ${t.key.map((c) => this.#driver.column(c)).join(", ")}` : "");
+        const results = await this.#driver.queryAll(tables.map((t) => `SELECT * FROM ${t.quoted}${order(t)}`));
+        tables.forEach((t, i) => snap.set(t.name, results[i]));
+        return snap;
     }
     /**
      * Tables to empty: ordinary tables in the configured schemas, minus migration
@@ -121,46 +128,107 @@ export class Db {
      * 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)}`);
+        return this.#driver.listTables(this.opts.schemas, [...MIGRATION_TABLES, ...this.opts.keep]);
+    }
+    /** `WHERE ...` for a filter: `null` is IS NULL, an array is IN (...), anything else `=`. */
+    #where(where) {
+        const d = this.#driver;
+        const conds = [];
+        const params = [];
+        for (const [col, value] of Object.entries(where)) {
+            if (value === null || value === undefined)
+                conds.push(`${d.ident(col)} IS NULL`);
+            else if (Array.isArray(value))
+                conds.push(d.inList(col, value, params));
+            else {
+                params.push(value);
+                conds.push(`${d.ident(col)} = ${d.param(params.length)}`);
+            }
+        }
+        return { clause: conds.length ? ` WHERE ${conds.join(" AND ")}` : "", params };
     }
     async close() {
-        await this.#client.end();
+        await this.#driver.close();
     }
 }
-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})`);
+function diff(tables, before, after) {
+    const out = {};
+    for (const table of tables) {
+        const a = before?.get(table.name) ?? [];
+        const b = after.get(table.name) ?? [];
+        const changes = table.key.length > 0 ? diffByKey(a, b, table.key) : diffAsBags(a, b);
+        if (changes.inserted.length || changes.updated.length || changes.deleted.length)
+            out[table.name] = changes;
+    }
+    return out;
+}
+function diffByKey(before, after, key) {
+    const keyOf = (r) => serialize(key.map((k) => r[k]));
+    const old = new Map(before.map((r) => [keyOf(r), r]));
+    const changes = { inserted: [], updated: [], deleted: [] };
+    for (const row of after) {
+        const k = keyOf(row);
+        const prev = old.get(k);
+        old.delete(k);
+        if (!prev) {
+            changes.inserted.push(row);
+            continue;
         }
-        else {
-            params.push(value);
-            conds.push(`${ident(col)} = $${params.length}`);
+        const changed = [...new Set([...Object.keys(prev), ...Object.keys(row)])].filter((c) => serialize(prev[c]) !== serialize(row[c]));
+        if (changed.length)
+            changes.updated.push({ key: Object.fromEntries(key.map((k) => [k, row[k]])), before: prev, after: row, changed });
+    }
+    changes.deleted.push(...old.values());
+    return changes;
+}
+/** Without a primary key, rows are compared as a multiset: an update shows up as a delete plus an insert. */
+function diffAsBags(before, after) {
+    const left = new Map();
+    for (const r of before) {
+        const k = serialize(r);
+        left.set(k, [...(left.get(k) ?? []), r]);
+    }
+    const inserted = [];
+    for (const r of after) {
+        const same = left.get(serialize(r));
+        if (same?.length)
+            same.pop();
+        else
+            inserted.push(r);
+    }
+    return { inserted, updated: [], deleted: [...left.values()].flat() };
+}
+function serialize(v) {
+    return JSON.stringify(v, (_, x) => (typeof x === "bigint" ? x.toString() : x));
+}
+/** Short summary of `changes()` for failure output. */
+export function formatChanges(changes, maxRows = 3) {
+    const lines = [];
+    const show = (sign, rows) => {
+        for (const r of rows.slice(0, maxRows))
+            lines.push(`    ${sign} ${truncate(serialize(r))}`);
+        if (rows.length > maxRows)
+            lines.push(`    ${sign} …and ${rows.length - maxRows} more`);
+    };
+    for (const [table, c] of Object.entries(changes)) {
+        const counts = [
+            c.inserted.length && `${c.inserted.length} inserted`,
+            c.updated.length && `${c.updated.length} updated`,
+            c.deleted.length && `${c.deleted.length} deleted`,
+        ].filter(Boolean);
+        lines.push(`  ${table}: ${counts.join(", ")}`);
+        show("+", c.inserted);
+        for (const u of c.updated.slice(0, maxRows)) {
+            const key = Object.entries(u.key).map(([k, v]) => `${k}=${serialize(v)}`).join(" ");
+            const cols = u.changed.map((col) => `${col}: ${serialize(u.before[col])} → ${serialize(u.after[col])}`).join(", ");
+            lines.push(`    ~ ${key}  ${truncate(cols)}`);
         }
+        if (c.updated.length > maxRows)
+            lines.push(`    ~ …and ${c.updated.length - maxRows} more`);
+        show("-", c.deleted);
     }
-    return { clause: conds.length ? ` WHERE ${conds.join(" AND ")}` : "", params };
+    return lines.join("\n");
 }
-/** Quote an identifier; `schema.table` is split on the dot. */
-function ident(name) {
-    return name
-        .split(".")
-        .map((part) => `"${part.replace(/"/g, '""')}"`)
-        .join(".");
+function truncate(s, max = 200) {
+    return s.length > max ? `${s.slice(0, max)}…` : s;
 }

package/dist/drivers/driver.d.ts

@@ -0,0 +1,65 @@
+/**
+ * What `Db` needs from a database engine. Everything dialect-specific
+ * (quoting, placeholders, catalog queries, how to empty tables) lives behind
+ * this interface so the rest of slicetest stays engine-agnostic.
+ */
+export interface Row {
+    [column: string]: unknown;
+}
+export interface Table {
+    /** Display name: `name` in the default schema, else `schema.name`. */
+    name: string;
+    quoted: string;
+    /** Primary-key columns, in order; empty when there is none. */
+    key: string[];
+}
+export interface Driver {
+    query<T extends Row = Row>(sql: string, params?: unknown[]): Promise<T[]>;
+    /** Several parameterless SELECTs in one round trip. */
+    queryAll(sqls: string[]): Promise<Row[][]>;
+    /** Run a script of several statements, e.g. a seed file. */
+    exec(script: string): Promise<void>;
+    /** Quote an identifier; `schema.table` is split on the dot. */
+    ident(name: string): string;
+    /** Quote a single column name, dots and all. */
+    column(name: string): string;
+    /** Bind placeholder for the n-th (1-based) parameter. */
+    param(n: number): string;
+    /** A `column IN (...)` condition for `values`, appending its parameters to `params`. */
+    inList(column: string, values: unknown[], params: unknown[]): string;
+    /** Data tables to reset, minus `keep` (bare or `schema.table`) and engine-owned tables. */
+    listTables(schemas: string[], keep: string[]): Promise<Table[]>;
+    /** Empty `tables` and restart their id sequences, without dropping the app's connections. */
+    truncate(tables: Table[]): Promise<void>;
+    /** Insert one row and return it as stored (defaults and generated ids filled in). */
+    insert(table: string, row: Row): Promise<Row[]>;
+    close(): Promise<void>;
+}
+/** Server-level operations: the databases slicetest creates for templates and workers. */
+export interface Admin {
+    /** Names of databases starting with `prefix`. */
+    databases(prefix: string): Promise<string[]>;
+    create(name: string): Promise<void>;
+    /** Create `name` as a copy of `template` (schema and data). */
+    clone(template: string, name: string): Promise<void>;
+    /** Drop `name`, disconnecting anyone still using it. */
+    drop(name: string): Promise<void>;
+    /** Run `fn` while holding a server-wide lock, so concurrent runs build a shared template once. */
+    withLock<T>(key: string, fn: () => Promise<T>): Promise<T>;
+    /** Connection URL for database `name` on this server. */
+    urlFor(name: string): string;
+    close(): Promise<void>;
+}
+export interface Engine {
+    name: string;
+    /** Container image used when no `db.url` is given. */
+    defaultImage: string;
+    startContainer(image: string, reuse: boolean): Promise<{
+        url: string;
+        stop(): Promise<unknown>;
+    }>;
+    admin(url: string): Promise<Admin>;
+    driver(url: string): Promise<Driver>;
+    /** The URL to hand Atlas for database `url`. */
+    atlasUrl(url: string): string;
+}

package/dist/drivers/driver.js

@@ -0,0 +1,6 @@
+/**
+ * What `Db` needs from a database engine. Everything dialect-specific
+ * (quoting, placeholders, catalog queries, how to empty tables) lives behind
+ * this interface so the rest of slicetest stays engine-agnostic.
+ */
+export {};

package/dist/drivers/index.d.ts

@@ -0,0 +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. 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

@@ -0,0 +1,14 @@
+import { postgres } from "./postgres.js";
+/** 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;
+    }
+    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;