slicetest 0.4.0 → 0.6.0

package/dist/global-setup.js

@@ -8,13 +8,42 @@ import { annotation, appendSummary, failureAnnotations, failureSummary, onGitHub
 import { configureContainerRuntime } from "./container-runtime.js";
 import { engineFor } from "./drivers/index.js";
 import { coverageCacheFile } from "./gen.js";
-import { formatCoverage, OpenApiSpec } from "./openapi.js";
+import { appSpecFile, 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;
+    // Builds don't need the database, so they run while it starts.
+    const builds = buildAll(opts);
+    builds.catch(() => { });
+    // No database (`db: false`): nothing to start or migrate, only the builds to wait for.
+    const database = opts.db.none ? (await builds, undefined) : await startDatabase(opts, builds);
+    // Each worker writes the documented responses it saw here; they are merged when the run ends.
+    const coverageDir = opts.openapi.app || opts.openapi.fromApp ? await mkdtemp(path.join(os.tmpdir(), "slicetest-coverage-")) : undefined;
+    // 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: database?.adminUrl ?? "", template: database?.template ?? "", prefix: database?.prefix ?? "", coverageDir, recordDir, ciDir });
+    return async () => {
+        try {
+            await database?.teardown();
+        }
+        finally {
+            if (coverageDir)
+                await reportCoverage(opts, coverageDir);
+            if (recordDir)
+                await saveRecordings(opts, recordDir);
+            if (ciDir)
+                await reportToGitHub(ciDir);
+        }
+    };
+}
+/** Start (or reuse) the database server and migrate a template database for the workers to clone. */
+async function startDatabase(opts, builds) {
     const engine = await engineFor(opts);
     let adminUrl;
     let stopContainer;
@@ -40,6 +69,7 @@ export default async function setup(project) {
             await dropStale(admin);
         const key = opts.db.reuse ? await migrationKey(opts) : undefined;
         template = key ? await cachedTemplate(admin, engine, opts, key) : await freshTemplate(admin, engine, opts, prefix);
+        await builds;
     }
     catch (e) {
         await admin?.close().catch(() => { });
@@ -47,32 +77,23 @@ export default async function setup(project) {
         throw e;
     }
     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;
-    // 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) {
-                // Shared server: drop only the databases this run created.
-                for (const name of await server.databases(`${prefix}_`))
-                    await server.drop(name);
+    return {
+        adminUrl,
+        template,
+        prefix,
+        async teardown() {
+            try {
+                if (!stopContainer) {
+                    // Shared server: drop only the databases this run created.
+                    for (const name of await server.databases(`${prefix}_`))
+                        await server.drop(name);
+                }
             }
-        }
-        finally {
-            await server.close();
-            await stopContainer?.();
-            if (coverageDir)
-                await reportCoverage(opts, coverageDir);
-            if (recordDir)
-                await saveRecordings(opts, recordDir);
-            if (ciDir)
-                await reportToGitHub(ciDir);
-        }
+            finally {
+                await server.close();
+                await stopContainer?.();
+            }
+        },
     };
 }
 async function reportCoverage(opts, dir) {
@@ -85,7 +106,8 @@ async function reportCoverage(opts, dir) {
         // No scenario ran (e.g. everything filtered out): nothing to report.
         if (hits.size === 0)
             return;
-        const spec = await OpenApiSpec.load(path.resolve(opts.root, opts.openapi.app), opts.openapi.app);
+        // A spec served by the app was saved next to the coverage files by the first worker that fetched it.
+        const spec = opts.openapi.fromApp ? await OpenApiSpec.load(appSpecFile(dir), `GET ${opts.openapi.fromApp}`) : 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);
@@ -97,13 +119,14 @@ async function reportCoverage(opts, dir) {
             // Not thrown: Vitest reports teardown errors as a crash. The failing exit code is what CI needs.
             const message = `OpenAPI coverage ${report.percent}% is below openapi.minCoverage (${min}%)`;
             console.error(`slicetest: ${message}\n`);
-            if (onGitHub())
+            if (onGitHub() && opts.openapi.app)
                 console.log(annotation("error", message, { file: repoPath(path.resolve(opts.root, opts.openapi.app)), title: "slicetest: OpenAPI coverage" }));
             process.exitCode = 1;
         }
     }
     finally {
         await rm(dir, { recursive: true, force: true });
+        await rm(appSpecFile(dir), { force: true });
     }
 }
 async function reportToGitHub(dir) {
@@ -211,9 +234,24 @@ async function migrate(opts, engine, url) {
     const m = opts.db.migrate;
     if (!m)
         return;
+    const output = await applyMigrations(opts, engine, url, m);
+    // Some tools exit 0 when they couldn't connect (drizzle-kit push through a driver that can't reach
+    // the server): an empty database after migrating means they did nothing.
+    const driver = await engine.driver(url);
+    try {
+        if ((await driver.listTables(opts.db.schemas, [])).length > 0)
+            return;
+    }
+    finally {
+        await driver.close();
+    }
+    const tail = output.trim().split("\n").slice(-15).join("\n");
+    throw new Error(`slicetest: db.migrate finished without error but created no tables${engine.name === "sqlite" ? "" : ` in ${opts.db.schemas.join(", ")}`}. Check that it reaches the database at DATABASE_URL.${tail ? `\nIts output:\n${tail}` : ""}`);
+}
+async function applyMigrations(opts, engine, url, m) {
     if ("atlas" in m) {
         const dir = atlasDirUrl(m.atlas.dir, opts.root);
-        await run("atlas", ["migrate", "apply", "--url", engine.atlasUrl(url), "--dir", dir], opts.root);
+        return run("atlas", ["migrate", "apply", "--url", engine.atlasUrl(url), "--dir", dir], opts.root);
     }
     else if ("sql" in m) {
         const target = path.resolve(opts.root, m.sql);
@@ -228,11 +266,10 @@ async function migrate(opts, engine, url) {
         finally {
             await driver.close();
         }
+        return "";
     }
-    else {
-        // Through the platform shell (sh or cmd.exe), like app.command.
-        await run(m.command, [], opts.root, { DATABASE_URL: url }, true);
-    }
+    // Through the platform shell (sh or cmd.exe), like app.command.
+    return run(m.command, [], opts.root, { DATABASE_URL: url }, true);
 }
 /**
  * Atlas wants `file://<path>` with forward slashes. Absolute paths (including
@@ -244,9 +281,28 @@ export function atlasDirUrl(dir, root) {
     const rel = path.isAbsolute(dir) || /^[a-zA-Z]:[\\/]/.test(dir) ? path.relative(root, dir) : dir;
     return `file://${rel.replace(/\\/g, "/")}`;
 }
+export async function buildAll(opts) {
+    const processes = [["app", opts.app], ...Object.entries(opts.services).map(([n, s]) => [`service ${n}`, s])];
+    await Promise.all(processes
+        .filter(([, p]) => p.build)
+        .map(async ([label, p]) => {
+        try {
+            // The process's literal settings apply to its build too: Next.js inlines NEXT_PUBLIC_* at build
+            // time. Values with placeholders ({{db.url}}, …) don't exist yet and are left out.
+            const literal = Object.fromEntries(Object.entries(p.env ?? {}).filter(([, v]) => !v.includes("{{")));
+            await exec(p.build, [], { cwd: path.resolve(opts.root, p.cwd ?? "."), env: { ...process.env, ...literal }, shell: true, windowsHide: true, maxBuffer: 64 * 1024 * 1024 });
+        }
+        catch (e) {
+            const err = e;
+            const output = `${err.stdout ?? ""}${err.stderr ?? ""}`.trim().split("\n").slice(-40).join("\n");
+            throw new Error(`slicetest: ${label} build failed: ${p.build}\n${output || err.message}`);
+        }
+    }));
+}
 async function run(cmd, args, cwd, env = {}, shell = false) {
     try {
-        await exec(cmd, args, { cwd, env: { ...process.env, ...env }, shell, windowsHide: true });
+        const { stdout, stderr } = await exec(cmd, args, { cwd, env: { ...process.env, ...env }, shell, windowsHide: true, maxBuffer: 64 * 1024 * 1024 });
+        return `${stdout}${stderr}`;
     }
     catch (e) {
         const err = e;

package/dist/http.d.ts

@@ -1,3 +1,5 @@
+import { type SubmitOptions } from "./form.js";
+import { type WebhookOptions } from "./webhook.js";
 export interface HttpResponse {
     method: string;
     url: string;
@@ -17,6 +19,8 @@ export interface RequestOptions {
 }
 /** Per-scenario state shared by a client and every client derived from it with `with()`. */
 declare class Session {
+    /** Stub base URLs of intercepted hosts, which redirects may lead to (an OAuth provider's login page). */
+    external: Map<string, string>;
     cookies: Map<string, string>;
     history: HttpResponse[];
     listeners: ((res: HttpResponse) => void)[];
@@ -37,16 +41,35 @@ 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>;
+    /**
+     * Submit a form of `page` (a response from the app) as a browser with JavaScript off would:
+     * hidden fields such as CSRF tokens or a Next.js server action's id are sent along,
+     * plus the pressed button and the values you type.
+     * `http.submit(await http.get("/signup"), { button: "Sign up", fields: { email: "a@b.test" } })`.
+     */
+    submit(page: HttpResponse, opts?: SubmitOptions & RequestOptions): Promise<HttpResponse>;
+    /**
+     * POST `payload` to the app as `provider` would deliver it, signed with `secret`:
+     * `http.webhook("/webhooks/stripe", event, { provider: "stripe", secret: "whsec_test" })`.
+     * `{ invalidSignature: true }` and `{ stale: true }` make deliveries the app must refuse.
+     */
+    webhook(path: string, payload: unknown, opts: WebhookOptions): 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. */
+    /**
+     * Strings, URLSearchParams, FormData, Blob and byte arrays are sent as-is; anything else is sent as JSON.
+     * With `follow`, redirects are followed here rather than by fetch, so cookies set along the way are kept
+     * (a login answering 302 + Set-Cookie) and nothing is sent outside the app: a redirect elsewhere is returned.
+     */
     request(method: string, path: string, body?: unknown, options?: RequestOptions): Promise<HttpResponse>;
     /** Call `fn` with every response this client (or one derived with `with()`) receives. */
     onResponse(fn: (res: HttpResponse) => void): void;
+    /** Let redirects to `host` continue to the stub at `stubUrl`, as they would to the real host in a browser. */
+    intercept(host: string, stubUrl: string): void;
     /** Cookies the app has set during this scenario. Mutations are sent with later requests. */
     get cookies(): Map<string, string>;
     clearCookies(): void;

package/dist/http.js

@@ -1,10 +1,22 @@
+import { formRequest } from "./form.js";
+import { lookupHost } from "./intercept.js";
+import { signWebhook, webhookBody } from "./webhook.js";
 /** Per-scenario state shared by a client and every client derived from it with `with()`. */
 class Session {
+    /** Stub base URLs of intercepted hosts, which redirects may lead to (an OAuth provider's login page). */
+    external = new Map();
     cookies = new Map();
     history = [];
     listeners = [];
 }
 const HISTORY = 20;
+const REDIRECTS = new Set([301, 302, 303, 307, 308]);
+/** A redirected request that lost its body must not keep claiming a content type. */
+function withoutContentType(headers, body) {
+    if (body !== undefined || !headers)
+        return headers;
+    return Object.fromEntries(Object.entries(headers).filter(([k]) => k.toLowerCase() !== "content-type"));
+}
 /** HTTP client bound to the app under test. Keeps cookies for the duration of a scenario. */
 export class HttpClient {
     baseUrl;
@@ -41,6 +53,37 @@ export class HttpClient {
     patch(path, body, opts) {
         return this.request("PATCH", path, body, opts);
     }
+    /**
+     * Submit a form of `page` (a response from the app) as a browser with JavaScript off would:
+     * hidden fields such as CSRF tokens or a Next.js server action's id are sent along,
+     * plus the pressed button and the values you type.
+     * `http.submit(await http.get("/signup"), { button: "Sign up", fields: { email: "a@b.test" } })`.
+     */
+    async submit(page, opts = {}) {
+        const { button, form, fields, ...request } = opts;
+        let built;
+        try {
+            built = formRequest(page.text, { button, form, fields });
+        }
+        catch (e) {
+            // A redirect or an error page is the usual reason there is no such form.
+            e.message += `\n(the page: ${page.method} ${page.url} → ${page.status}${REDIRECTS.has(page.status) ? `, a redirect to ${page.headers.get("location")}; request it with follow: true` : ""})`;
+            throw e;
+        }
+        const { method, action, body } = built;
+        const target = new URL(action, new URL(page.url, this.baseUrl));
+        target.hash = "";
+        return this.request(method, target.pathname + target.search, body, request);
+    }
+    /**
+     * POST `payload` to the app as `provider` would deliver it, signed with `secret`:
+     * `http.webhook("/webhooks/stripe", event, { provider: "stripe", secret: "whsec_test" })`.
+     * `{ invalidSignature: true }` and `{ stale: true }` make deliveries the app must refuse.
+     */
+    webhook(path, payload, opts) {
+        const { body, type } = webhookBody(payload);
+        return this.request("POST", path, body, { headers: { "content-type": type, ...signWebhook(body, opts), ...opts.headers } });
+    }
     /**
      * 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 })`
@@ -55,18 +98,45 @@ export class HttpClient {
         release();
         return all;
     }
-    /** Strings, URLSearchParams, FormData, Blob and byte arrays are sent as-is; anything else is sent as JSON. */
+    /**
+     * Strings, URLSearchParams, FormData, Blob and byte arrays are sent as-is; anything else is sent as JSON.
+     * With `follow`, redirects are followed here rather than by fetch, so cookies set along the way are kept
+     * (a login answering 302 + Set-Cookie) and nothing is sent outside the app: a redirect elsewhere is returned.
+     */
     async request(method, path, body, options = {}) {
         const opts = merge(this.defaults, options);
-        const url = new URL(path, this.baseUrl);
+        let url = new URL(path, this.baseUrl);
         if (url.origin !== new URL(this.baseUrl).origin) {
             throw new Error(`slicetest: http only talks to the app under test; "${path}" resolves to ${url.origin}`);
         }
         for (const [k, v] of Object.entries(opts.query ?? {}))
             if (v !== undefined)
                 url.searchParams.set(k, String(v));
+        let res = await this.#send(method, url, body, opts);
+        for (let hops = 0; opts.follow && REDIRECTS.has(res.status) && hops < 20; hops++) {
+            const location = res.headers.get("location");
+            if (!location)
+                break;
+            const next = new URL(location, url);
+            // Like a browser: on to the app, or to a host a stub stands in for; anywhere else is returned.
+            if (next.origin !== new URL(this.baseUrl).origin && lookupHost(this.#session.external, next.hostname) === undefined)
+                break;
+            // 307/308 repeat the request as it was; the others turn it into a GET without a body, like browsers do.
+            if (res.status !== 307 && res.status !== 308 && method !== "HEAD") {
+                method = "GET";
+                body = undefined;
+            }
+            url = next;
+            res = await this.#send(method, url, body, { ...opts, headers: withoutContentType(opts.headers, body) });
+        }
+        return res;
+    }
+    async #send(method, url, body, opts) {
         const headers = new Headers(opts.headers);
-        if (this.#session.cookies.size > 0 && !headers.has("cookie")) {
+        const stub = url.origin === new URL(this.baseUrl).origin ? undefined : lookupHost(this.#session.external, url.hostname);
+        // The app's cookies stay with the app; the stub is reached at its own address.
+        const target = stub ? new URL(url.pathname + url.search, stub) : url;
+        if (!stub && this.#session.cookies.size > 0 && !headers.has("cookie")) {
             headers.set("cookie", [...this.#session.cookies].map(([k, v]) => `${k}=${v}`).join("; "));
         }
         let payload;
@@ -86,15 +156,16 @@ export class HttpClient {
         const started = performance.now();
         let res;
         try {
-            res = await fetch(url, { method, headers, body: payload, redirect: opts.follow ? "follow" : "manual" });
+            res = await fetch(target, { method, headers, body: payload, redirect: "manual" });
         }
         catch (e) {
             const cause = e.cause?.code;
             this.#record({ method, url: url.pathname + url.search, status: 0, headers: new Headers(), text: `${e}${cause ? ` (${cause})` : ""}`, json: undefined, durationMs: Math.round(performance.now() - started) });
             throw e;
         }
-        for (const cookie of res.headers.getSetCookie())
-            this.#storeCookie(cookie);
+        if (!stub)
+            for (const cookie of res.headers.getSetCookie())
+                this.#storeCookie(cookie);
         const text = await res.text();
         let json;
         try {
@@ -103,7 +174,7 @@ export class HttpClient {
         catch { }
         const out = {
             method,
-            url: url.pathname + url.search,
+            url: stub ? url.href : url.pathname + url.search,
             status: res.status,
             headers: res.headers,
             text,
@@ -111,8 +182,10 @@ export class HttpClient {
             durationMs: Math.round(performance.now() - started),
         };
         this.#record(out);
-        for (const listener of this.#session.listeners)
-            listener(out);
+        // Listeners (contract checks, coverage) are about the app's responses only.
+        if (!stub)
+            for (const listener of this.#session.listeners)
+                listener(out);
         return out;
     }
     /** Call `fn` with every response this client (or one derived with `with()`) receives. */
@@ -124,6 +197,10 @@ export class HttpClient {
         if (this.#session.history.length > HISTORY)
             this.#session.history.shift();
     }
+    /** Let redirects to `host` continue to the stub at `stubUrl`, as they would to the real host in a browser. */
+    intercept(host, stubUrl) {
+        this.#session.external.set(host.toLowerCase(), stubUrl);
+    }
     /** Cookies the app has set during this scenario. Mutations are sent with later requests. */
     get cookies() {
         return this.#session.cookies;

package/dist/index.d.ts

@@ -3,10 +3,15 @@ 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 { Stub, RecordedCall, StubResponse, Responder, MatchOptions, RouteBuilder, ChaosOptions, ServerSentEvent } from "./stub.js";
+export { sse } from "./stub.js";
 export type { HttpClient, HttpResponse, RequestOptions } from "./http.js";
+export type { SubmitOptions } from "./form.js";
 export type { App } from "./app.js";
 export type { Dependency } from "./containers.js";
 export type { Mailbox, Mail, MailFilter } from "./mail.js";
+export type { Issuer, TokenOptions, AuthOptions } from "./auth.js";
+export { normalizeSql, type Query, type QueryList } from "./query-log.js";
+export { signWebhook, type WebhookOptions, type WebhookProvider, type HmacScheme } from "./webhook.js";
 export type { SlicetestOptions, ContainerOptions } from "./config.js";
 export type {} from "./matchers.js";

package/dist/index.js

@@ -1,2 +1,5 @@
 export { scenario } from "./scenario.js";
 export { mask } from "./trace.js";
+export { sse } from "./stub.js";
+export { normalizeSql } from "./query-log.js";
+export { signWebhook } from "./webhook.js";