slicetest 0.3.0 → 0.5.0

package/dist/openapi.js

@@ -157,9 +157,27 @@ export class OpenApiSpec {
                 json: json ?? undefined,
                 responses,
                 createdFields: okSchema?.properties ? Object.keys(okSchema.properties) : [],
+                bearer: this.#bearer(op.security ?? this.doc.security),
             };
         });
     }
+    #bearer(security) {
+        if (!Array.isArray(security) || security.length === 0)
+            return undefined;
+        // An empty requirement makes credentials optional.
+        if (security.some((req) => Object.keys(req ?? {}).length === 0))
+            return undefined;
+        const schemes = this.doc.components?.securitySchemes ?? {};
+        for (const req of security) {
+            for (const [name, scopes] of Object.entries(req)) {
+                const s = this.#deref(schemes[name]);
+                if (s && ((s.type === "http" && String(s.scheme).toLowerCase() === "bearer") || s.type === "oauth2" || s.type === "openIdConnect")) {
+                    return { scopes: Array.isArray(scopes) ? scopes : [] };
+                }
+            }
+        }
+        return undefined;
+    }
     /** A value that satisfies `schema` (as far as a simple walk can): examples, defaults, enums, then types. */
     #sample(schema, depth = 0) {
         const s = this.#deref(schema);
@@ -306,7 +324,17 @@ export function formatCoverage(spec, hits) {
     });
     const covered = keys.filter((k) => hits.has(k)).length;
     const percent = keys.length ? Math.round((covered / keys.length) * 100) : 100;
-    return { covered, total: keys.length, percent, text: `slicetest: OpenAPI coverage (${spec.file}): ${covered}/${keys.length} documented responses (${percent}%)\n${lines.join("\n")}` };
+    const markdown = [
+        `### slicetest: OpenAPI coverage ${percent}%`,
+        "",
+        `${covered} of ${keys.length} documented responses in \`${spec.file}\` were produced by a scenario.`,
+        "",
+        "| Operation | Responses |",
+        "|---|---|",
+        ...[...byOp].map(([op, statuses]) => `| \`${op}\` | ${statuses.map((s) => `${hits.has(`${op} ${s}`) ? "✅" : "❌"} ${s}`).join(" ")} |`),
+        "",
+    ].join("\n");
+    return { covered, total: keys.length, percent, markdown, text: `slicetest: OpenAPI coverage (${spec.file}): ${covered}/${keys.length} documented responses (${percent}%)\n${lines.join("\n")}` };
 }
 function isJson(media) {
     return /[/+]json$/i.test(media) || media === "*/*";

package/dist/provided.d.ts

@@ -8,6 +8,7 @@ declare module "vitest" {
             prefix: string;
             coverageDir?: string;
             recordDir?: string;
+            ciDir?: string;
         };
     }
 }

package/dist/query-log.d.ts

@@ -0,0 +1,49 @@
+export interface Query {
+    sql: string;
+    /** Milliseconds since the log started. */
+    at: number;
+}
+/** A list of queries, with helpers for spotting N+1 patterns. */
+export declare class QueryList extends Array<Query> {
+    /** Statements grouped by shape (literals and parameters replaced by `?`), most frequent first. */
+    shapes(): {
+        sql: string;
+        count: number;
+    }[];
+    /** Without transaction control and session statements (`BEGIN`, `COMMIT`, `SAVEPOINT`, `SET`, …), which some drivers add around every query. */
+    withoutTransactions(): QueryList;
+    /** Shapes run at least `min` times (default 3): the usual signature of an N+1. */
+    repeated(min?: number): {
+        sql: string;
+        count: number;
+    }[];
+}
+export declare function queryList(queries: Query[]): QueryList;
+/** `SELECT * FROM t WHERE id = 7 AND name = 'x'` → `SELECT * FROM t WHERE id = ? AND name = ?`. */
+export declare function normalizeSql(sql: string): string;
+type Engine = "postgres" | "mysql";
+/**
+ * A TCP proxy between the app and its database that reads the wire protocol
+ * and records every statement the app runs, whatever its language or driver.
+ * Postgres: simple queries and extended-protocol executions. MySQL: COM_QUERY
+ * and prepared-statement executions. Connections that switch to TLS are
+ * forwarded but not read.
+ */
+export declare class QueryLog {
+    #private;
+    private readonly server;
+    readonly port: number;
+    private constructor();
+    static start(engine: Engine, upstream: {
+        host: string;
+        port: number;
+    }): Promise<QueryLog>;
+    /** `url` with its host and port pointing at the proxy. */
+    proxyUrl(url: string): string;
+    /** Queries since the last `reset()`, or since `mark` (an index from `mark()`). */
+    queries(since?: number): QueryList;
+    mark(): number;
+    reset(): void;
+    close(): Promise<void>;
+}
+export {};

package/dist/query-log.js

@@ -0,0 +1,261 @@
+import net from "node:net";
+const TRANSACTION = /^\s*(BEGIN|START\s+TRANSACTION|COMMIT|END|ROLLBACK|SAVEPOINT|RELEASE|SET|SHOW|DISCARD|DEALLOCATE)\b/i;
+/** A list of queries, with helpers for spotting N+1 patterns. */
+export class QueryList extends Array {
+    /** Statements grouped by shape (literals and parameters replaced by `?`), most frequent first. */
+    shapes() {
+        const counts = new Map();
+        for (const q of this) {
+            const shape = normalizeSql(q.sql);
+            counts.set(shape, (counts.get(shape) ?? 0) + 1);
+        }
+        return [...counts].map(([sql, count]) => ({ sql, count })).sort((a, b) => b.count - a.count);
+    }
+    /** Without transaction control and session statements (`BEGIN`, `COMMIT`, `SAVEPOINT`, `SET`, …), which some drivers add around every query. */
+    withoutTransactions() {
+        return queryList(this.filter((q) => !TRANSACTION.test(q.sql)));
+    }
+    /** Shapes run at least `min` times (default 3): the usual signature of an N+1. */
+    repeated(min = 3) {
+        return this.shapes().filter((s) => s.count >= min);
+    }
+}
+export function queryList(queries) {
+    const list = new QueryList();
+    list.push(...queries);
+    return list;
+}
+/** `SELECT * FROM t WHERE id = 7 AND name = 'x'` → `SELECT * FROM t WHERE id = ? AND name = ?`. */
+export function normalizeSql(sql) {
+    return sql
+        .replace(/\s+/g, " ")
+        .trim()
+        .replace(/'(?:[^']|'')*'/g, "?")
+        .replace(/\$\d+/g, "?")
+        .replace(/(?<![\w"`.])-?\d+(\.\d+)?\b/g, "?")
+        .replace(/\(\s*\?(\s*,\s*\?)+\s*\)/g, "(?)");
+}
+/**
+ * A TCP proxy between the app and its database that reads the wire protocol
+ * and records every statement the app runs, whatever its language or driver.
+ * Postgres: simple queries and extended-protocol executions. MySQL: COM_QUERY
+ * and prepared-statement executions. Connections that switch to TLS are
+ * forwarded but not read.
+ */
+export class QueryLog {
+    server;
+    port;
+    #queries = [];
+    #started = performance.now();
+    #sockets = new Set();
+    constructor(server, port) {
+        this.server = server;
+        this.port = port;
+    }
+    static async start(engine, upstream) {
+        let log;
+        const server = net.createServer((client) => log.#connect(engine, client, upstream));
+        await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
+        log = new QueryLog(server, server.address().port);
+        return log;
+    }
+    /** `url` with its host and port pointing at the proxy. */
+    proxyUrl(url) {
+        const u = new URL(url);
+        u.hostname = "127.0.0.1";
+        u.port = String(this.port);
+        return u.toString();
+    }
+    /** Queries since the last `reset()`, or since `mark` (an index from `mark()`). */
+    queries(since = 0) {
+        return queryList(this.#queries.slice(since));
+    }
+    mark() {
+        return this.#queries.length;
+    }
+    reset() {
+        this.#queries = [];
+    }
+    #record(sql) {
+        this.#queries.push({ sql, at: Math.round(performance.now() - this.#started) });
+    }
+    #connect(engine, client, upstream) {
+        const server = net.connect(upstream.port, upstream.host);
+        this.#sockets.add(client).add(server);
+        const close = () => {
+            client.destroy();
+            server.destroy();
+            this.#sockets.delete(client);
+            this.#sockets.delete(server);
+        };
+        client.on("error", close).on("close", close);
+        server.on("error", close).on("close", close);
+        const reader = engine === "postgres" ? new PostgresReader((sql) => this.#record(sql)) : new MysqlReader((sql) => this.#record(sql));
+        client.on("data", (chunk) => {
+            try {
+                reader.fromClient(chunk);
+            }
+            catch {
+                reader.opaque = true;
+            }
+            server.write(chunk);
+        });
+        server.on("data", (chunk) => {
+            try {
+                reader.fromServer(chunk);
+            }
+            catch {
+                reader.opaque = true;
+            }
+            client.write(chunk);
+        });
+    }
+    async close() {
+        for (const s of this.#sockets)
+            s.destroy();
+        await new Promise((resolve) => this.server.close(resolve));
+    }
+}
+const cstring = (buf, start) => {
+    const end = buf.indexOf(0, start);
+    return [buf.toString("utf8", start, end), end + 1];
+};
+class PostgresReader {
+    record;
+    opaque = false;
+    #buf = Buffer.alloc(0);
+    #startup = true;
+    #awaitingSsl = false;
+    #statements = new Map();
+    #portals = new Map();
+    constructor(record) {
+        this.record = record;
+    }
+    fromServer(chunk) {
+        if (!this.#awaitingSsl)
+            return;
+        this.#awaitingSsl = false;
+        // 'S' (TLS) or 'G' (GSSAPI encryption): the rest is encrypted.
+        if (chunk[0] === 0x53 || chunk[0] === 0x47)
+            this.opaque = true;
+    }
+    fromClient(chunk) {
+        if (this.opaque)
+            return;
+        this.#buf = Buffer.concat([this.#buf, chunk]);
+        for (;;) {
+            if (this.#startup) {
+                if (this.#buf.length < 8)
+                    return;
+                const len = this.#buf.readInt32BE(0);
+                if (this.#buf.length < len)
+                    return;
+                const code = this.#buf.readInt32BE(4);
+                this.#buf = this.#buf.subarray(len);
+                if (code === 80877103 || code === 80877104)
+                    this.#awaitingSsl = true;
+                else if (code !== 80877102)
+                    this.#startup = false;
+                continue;
+            }
+            if (this.#buf.length < 5)
+                return;
+            const type = String.fromCharCode(this.#buf[0]);
+            const len = this.#buf.readInt32BE(1);
+            if (this.#buf.length < len + 1)
+                return;
+            const msg = this.#buf.subarray(5, len + 1);
+            this.#buf = this.#buf.subarray(len + 1);
+            this.#message(type, msg);
+        }
+    }
+    #message(type, msg) {
+        if (type === "Q") {
+            this.record(cstring(msg, 0)[0]);
+        }
+        else if (type === "P") {
+            const [name, next] = cstring(msg, 0);
+            this.#statements.set(name, cstring(msg, next)[0]);
+        }
+        else if (type === "B") {
+            const [portal, next] = cstring(msg, 0);
+            this.#portals.set(portal, this.#statements.get(cstring(msg, next)[0]) ?? "");
+        }
+        else if (type === "E") {
+            const sql = this.#portals.get(cstring(msg, 0)[0]);
+            if (sql)
+                this.record(sql);
+        }
+    }
+}
+const CLIENT_QUERY_ATTRIBUTES = 1 << 27;
+class MysqlReader {
+    record;
+    opaque = false;
+    #client = Buffer.alloc(0);
+    #server = Buffer.alloc(0);
+    #prepares = [];
+    #attributes = false;
+    #statements = new Map();
+    constructor(record) {
+        this.record = record;
+    }
+    #read(buf, each) {
+        while (buf.length >= 4) {
+            const len = buf.readUIntLE(0, 3);
+            if (buf.length < len + 4)
+                break;
+            each(buf[3], buf.subarray(4, len + 4));
+            buf = buf.subarray(len + 4);
+        }
+        return Buffer.from(buf);
+    }
+    fromClient(chunk) {
+        if (this.opaque)
+            return;
+        this.#client = this.#read(Buffer.concat([this.#client, chunk]), (seq, p) => {
+            // The handshake response asking for TLS is a short packet with CLIENT_SSL set.
+            if (seq === 1 && p.length === 32 && (p.readUInt32LE(0) & 0x800) !== 0)
+                this.opaque = true;
+            if (seq === 1 && p.length >= 4)
+                this.#attributes = (p.readUInt32LE(0) & CLIENT_QUERY_ATTRIBUTES) !== 0;
+            // Commands start a new sequence; handshake and auth packets don't.
+            if (seq !== 0 || p.length === 0)
+                return;
+            if (p[0] === 0x03)
+                this.record(this.#queryText(p));
+            else if (p[0] === 0x16)
+                this.#prepares.push(p.toString("utf8", 1));
+            else if (p[0] === 0x17 && p.length >= 5) {
+                const sql = this.#statements.get(p.readUInt32LE(1));
+                if (sql)
+                    this.record(sql);
+            }
+        });
+    }
+    /** COM_QUERY text; with query attributes it follows a parameter count, a set count and the attributes. */
+    #queryText(p) {
+        if (!this.#attributes)
+            return p.toString("utf8", 1);
+        const count = p[1];
+        // Drivers send no attributes (count 0, one set); anything else is read past heuristically.
+        if (count === 0)
+            return p.toString("utf8", 3);
+        const text = p.toString("utf8", 3);
+        const start = text.search(/\b(SELECT|INSERT|UPDATE|DELETE|WITH|REPLACE|CALL|SET|BEGIN|COMMIT|ROLLBACK|START)\b/i);
+        return start >= 0 ? text.slice(start) : text;
+    }
+    fromServer(chunk) {
+        if (this.opaque || this.#prepares.length === 0) {
+            this.#server = Buffer.alloc(0);
+            return;
+        }
+        this.#server = this.#read(Buffer.concat([this.#server, chunk]), (seq, p) => {
+            if (seq !== 1 || this.#prepares.length === 0)
+                return;
+            const sql = this.#prepares.shift();
+            if (p[0] === 0x00 && p.length >= 5)
+                this.#statements.set(p.readUInt32LE(1), sql);
+        });
+    }
+}

package/dist/record-cli.d.ts

@@ -0,0 +1,6 @@
+import { type SlicetestOptions } from "./config.js";
+/** The main-process side of `npx slicetest record`: run the session, tell the user where to send requests, stop on Enter. */
+export declare function record(configPath: string, options: SlicetestOptions, { out, port }: {
+    out?: string;
+    port?: number;
+}): Promise<void>;

package/dist/record-cli.js

@@ -0,0 +1,93 @@
+import { existsSync } from "node:fs";
+import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { createInterface } from "node:readline";
+import { fileURLToPath } from "node:url";
+import { resolveOptions } from "./config.js";
+import { SESSION_ENV } from "./record.js";
+const ext = path.extname(fileURLToPath(import.meta.url));
+const sessionFile = fileURLToPath(new URL(`./record-session${ext}`, import.meta.url));
+/** The main-process side of `npx slicetest record`: run the session, tell the user where to send requests, stop on Enter. */
+export async function record(configPath, options, { out, port = 0 }) {
+    const root = path.dirname(configPath);
+    const stamp = new Date().toISOString().replace(/[-:]/g, "").replace("T", "-").slice(0, 15);
+    const file = path.resolve(root, out ?? path.join("scenarios", `recorded-${stamp}.scenario.yaml`));
+    if (existsSync(file))
+        throw new Error(`slicetest record: ${path.relative(process.cwd(), file)} already exists. Pass --out <file>.`);
+    if (!Number.isInteger(port) || port < 0 || port > 65535)
+        throw new Error(`slicetest record: --port must be a port number, got ${port}`);
+    await mkdir(path.dirname(file), { recursive: true });
+    const dir = await mkdtemp(path.join(os.tmpdir(), "slicetest-record-"));
+    const session = {
+        stateFile: path.join(dir, "state.json"),
+        stopFile: path.join(dir, "stop"),
+        out: file,
+        port,
+        stubs: resolveOptions(options, root).stubs,
+    };
+    process.env[SESSION_ENV] = JSON.stringify(session);
+    const stop = () => void writeFile(session.stopFile, "").catch(() => { });
+    process.once("SIGINT", stop);
+    const { startVitest } = await import("vitest/node");
+    const { slicetest } = await import("./vitest.js");
+    const announce = watchState(session.stateFile, (state) => {
+        process.stdout.write(`\nRecording. Use the app through ${state.url} (it forwards to ${state.app}).\n` +
+            "Everything it does is captured: responses, calls to stubs, database changes.\n" +
+            "Press Enter (or Ctrl+C) to finish and write the scenario.\n\n");
+        const rl = createInterface({ input: process.stdin });
+        rl.once("line", () => {
+            rl.close();
+            stop();
+        });
+        process.stdin.once("end", stop);
+    });
+    try {
+        const vitest = await startVitest([], { config: false, root, include: [sessionFile.replace(/\\/g, "/")], exclude: [], watch: false, run: true, reporters: ["dot"] }, { plugins: [slicetest(options)] });
+        await vitest?.close();
+        const state = existsSync(session.stateFile) ? JSON.parse(await readFile(session.stateFile, "utf8")) : {};
+        if (!state.done || !state.summary) {
+            process.stderr.write("slicetest record: the session ended before anything was written (see the output above).\n");
+            process.exitCode = 1;
+            return;
+        }
+        // The session is written; a failure after it (e.g. an unmatched stub call) is reported in the file's header.
+        process.exitCode = 0;
+        const s = state.summary;
+        process.stdout.write(`\nWrote ${path.relative(process.cwd(), file)}: ${s.requests} request(s), ${s.stubs} stub route(s), changes in ${s.tables.length ? s.tables.join(", ") : "no tables"}.\n` +
+            (s.skippedAssets ? `Left out ${s.skippedAssets} request(s) for static files.\n` : "") +
+            (s.unanswered.length ? `Calls no stub answered (see the file's header): ${s.unanswered.join(", ")}\n` : "") +
+            `Replay it with: npx slicetest ${path.relative(root, file).replace(/\\/g, "/")}\n`);
+    }
+    finally {
+        announce.cancel();
+        process.off("SIGINT", stop);
+        // The Enter listener would otherwise keep the process alive.
+        process.stdin.destroy();
+        delete process.env[SESSION_ENV];
+        await rm(dir, { recursive: true, force: true });
+    }
+}
+function watchState(file, onReady) {
+    let cancelled = false;
+    void (async () => {
+        while (!cancelled) {
+            if (existsSync(file)) {
+                try {
+                    const state = JSON.parse(await readFile(file, "utf8"));
+                    if (state.url)
+                        return onReady(state);
+                }
+                catch {
+                    // Partly written; read it again.
+                }
+            }
+            await new Promise((r) => setTimeout(r, 100));
+        }
+    })();
+    return {
+        cancel: () => {
+            cancelled = true;
+        },
+    };
+}

package/dist/record-session.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/record-session.js

@@ -0,0 +1,10 @@
+/**
+ * The test file `npx slicetest record` runs: one scenario that lasts until the
+ * user is done, so the session gets the same app, database and stubs as tests.
+ */
+import { SESSION_ENV, runSession } from "./record.js";
+import { scenario } from "./scenario.js";
+const session = JSON.parse(process.env[SESSION_ENV] ?? "null");
+if (!session)
+    throw new Error("slicetest: this file is run by `npx slicetest record`");
+scenario("slicetest record", (ctx) => runSession(ctx, session), 24 * 60 * 60 * 1000);

package/dist/record.d.ts

@@ -0,0 +1,46 @@
+import type { Changes } from "./db.js";
+import type { ScenarioContext } from "./runtime.js";
+import type { RecordedCall } from "./stub.js";
+/**
+ * `npx slicetest record`: use the app for real (a browser, curl, a mobile
+ * client) through a proxy, and get the session back as a YAML scenario: the
+ * requests, the responses to expect, the stubbed services' replies and the
+ * database changes. The session runs as one long scenario, so the app, the
+ * database and the stubs are the same ones the tests use.
+ */
+/** Passed from the CLI to the session through the environment. */
+export interface RecordSession {
+    /** Written by the session: `{ "url": … }` once the proxy listens, `{ "done": … }` at the end. */
+    stateFile: string;
+    /** Created by the CLI when the user is done. */
+    stopFile: string;
+    out: string;
+    port: number;
+    stubs: string[];
+}
+export declare const SESSION_ENV = "SLICETEST_RECORD_SESSION";
+export interface Exchange {
+    method: string;
+    path: string;
+    contentType?: string;
+    body: string;
+    status: number;
+    responseType?: string;
+    response: string;
+}
+export declare function runSession(ctx: ScenarioContext, session: RecordSession): Promise<void>;
+export interface Summary {
+    requests: number;
+    skippedAssets: number;
+    stubs: number;
+    tables: string[];
+    unanswered: string[];
+}
+/** The recorded session as a YAML scenario, with a comment header of what to review. */
+export declare function buildScenario(exchanges: Exchange[], calls: Record<string, RecordedCall[]>, changes: Changes, { name, now }?: {
+    name?: string | undefined;
+    now?: Date | undefined;
+}): {
+    yaml: string;
+    summary: Summary;
+};