slicetest 0.6.1 → 0.7.0

package/dist/global-setup.js

@@ -5,10 +5,12 @@ import os from "node:os";
 import path from "node:path";
 import { promisify } from "node:util";
 import { annotation, appendSummary, failureAnnotations, failureSummary, onGitHub, repoPath, yamlFailures } from "./ci.js";
+import { interpolate } from "./app.js";
+import { connectionVars } from "./connection.js";
 import { configureContainerRuntime } from "./container-runtime.js";
 import { engineFor } from "./drivers/index.js";
 import { coverageCacheFile } from "./gen.js";
-import { appSpecFile, formatCoverage, OpenApiSpec } from "./openapi.js";
+import { appSpecFile, formatCoverage, formatUsage, OpenApiSpec } from "./openapi.js";
 import { mergeRecordings } from "./recording.js";
 import "./provided.js";
 const exec = promisify(execFile);
@@ -27,7 +29,9 @@ export default async function setup(project) {
     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 });
+    // Operations the app called on providers whose spec a stub has, reported at the end.
+    const usageDir = Object.keys(opts.openapi.stubs).length ? await mkdtemp(path.join(os.tmpdir(), "slicetest-usage-")) : undefined;
+    project.provide("slicetestDb", { adminUrl: database?.adminUrl ?? "", template: database?.template ?? "", prefix: database?.prefix ?? "", coverageDir, recordDir, ciDir, usageDir });
     return async () => {
         try {
             await database?.teardown();
@@ -35,6 +39,8 @@ export default async function setup(project) {
         finally {
             if (coverageDir)
                 await reportCoverage(opts, coverageDir);
+            if (usageDir)
+                await reportUsage(opts, usageDir);
             if (recordDir)
                 await saveRecordings(opts, recordDir);
             if (ciDir)
@@ -129,6 +135,36 @@ async function reportCoverage(opts, dir) {
         await rm(appSpecFile(dir), { force: true });
     }
 }
+async function reportUsage(opts, dir) {
+    try {
+        const used = new Map();
+        for (const file of await readdir(dir)) {
+            for (const [name, keys] of Object.entries(JSON.parse(await readFile(path.join(dir, file), "utf8")))) {
+                const set = used.get(name) ?? new Set();
+                for (const k of keys)
+                    set.add(k);
+                used.set(name, set);
+            }
+        }
+        for (const [name, file] of Object.entries(opts.openapi.stubs)) {
+            const keys = used.get(name);
+            if (!keys)
+                continue;
+            const report = formatUsage(name, await OpenApiSpec.load(path.resolve(opts.root, file), file), keys);
+            console.log(`\n${report.text}\n`);
+            await appendSummary(report.markdown);
+            if (onGitHub() && report.deprecated.length) {
+                console.log(annotation("warning", `The app calls operations ${file} marks deprecated: ${report.deprecated.join(", ")}`, { file: repoPath(path.resolve(opts.root, file)), title: `slicetest: deprecated ${name} API` }));
+            }
+        }
+    }
+    catch (e) {
+        console.error(`slicetest: couldn't report API usage: ${e.message}`);
+    }
+    finally {
+        await rm(dir, { recursive: true, force: true });
+    }
+}
 async function reportToGitHub(dir) {
     try {
         const failures = await yamlFailures(dir);
@@ -268,8 +304,13 @@ async function applyMigrations(opts, engine, url, m) {
         }
         return "";
     }
-    // Through the platform shell (sh or cmd.exe), like app.command.
-    return run(m.command, [], opts.root, { DATABASE_URL: url }, true);
+    // Through the platform shell (sh or cmd.exe), like app.command, with the same {{db.*}} placeholders.
+    const vars = { "db.url": url };
+    if (engine.name === "sqlite")
+        vars["db.path"] = (await import("./drivers/sqlite.js")).sqlitePath(url);
+    Object.assign(vars, connectionVars(engine.name, url, vars["db.path"]));
+    const env = Object.fromEntries(Object.entries(m.env ?? {}).map(([k, v]) => [k, interpolate(v, vars, `db.migrate.env.${k}`)]));
+    return run(interpolate(m.command, vars, "db.migrate.command"), [], opts.root, { DATABASE_URL: url, ...env }, true);
 }
 /**
  * Atlas wants `file://<path>` with forward slashes. Absolute paths (including

package/dist/graphql.d.ts

@@ -0,0 +1,34 @@
+/**
+ * GraphQL over HTTP, as clients send it (Apollo, urql, graphql-request, gql, …):
+ * a POST with `{ query, variables, operationName }`, or a GET with those as query
+ * parameters. Stubs match calls by operation, and the app's own GraphQL endpoint
+ * is called with `http.graphql()`.
+ */
+export interface GraphQLCall {
+    /** `operationName` from the request, else the name in the document (`query GetUser { … }`). Undefined for an anonymous operation. */
+    operation?: string;
+    type: "query" | "mutation" | "subscription";
+    query: string;
+    variables: Record<string, unknown>;
+}
+/** The operations a document defines, in order. Comments and strings don't count. */
+export declare function operations(document: string): {
+    type: GraphQLCall["type"];
+    name?: string;
+}[];
+/** The GraphQL request in an HTTP call, or undefined when it isn't one. */
+export declare function graphqlOf(call: {
+    method: string;
+    query: URLSearchParams;
+    json: any;
+}): GraphQLCall | undefined;
+/** A GraphQL error list from messages or full error objects. */
+export declare function graphqlErrors(errors: (string | {
+    message: string;
+    [k: string]: unknown;
+})[]): {
+    [k: string]: unknown;
+    message: string;
+}[];
+/** `GraphQL mutation CreateIssue`, for failure messages. */
+export declare function describeGraphQL(g: GraphQLCall): string;

package/dist/graphql.js

@@ -0,0 +1,56 @@
+/**
+ * GraphQL over HTTP, as clients send it (Apollo, urql, graphql-request, gql, …):
+ * a POST with `{ query, variables, operationName }`, or a GET with those as query
+ * parameters. Stubs match calls by operation, and the app's own GraphQL endpoint
+ * is called with `http.graphql()`.
+ */
+const OPERATION = /(?:^|[\s}])(query|mutation|subscription)\b\s*([_A-Za-z][_0-9A-Za-z]*)?/g;
+/** The operations a document defines, in order. Comments and strings don't count. */
+export function operations(document) {
+    const code = document.replace(/"""[\s\S]*?"""|"(?:[^"\\\n]|\\.)*"|#[^\n]*/g, " ");
+    const found = [];
+    for (const m of code.matchAll(OPERATION))
+        found.push({ type: m[1], name: m[2] });
+    // `{ viewer { id } }` without a keyword is an anonymous query.
+    if (found.length === 0 && /^\s*\{/.test(code))
+        found.push({ type: "query" });
+    return found;
+}
+/** The GraphQL request in an HTTP call, or undefined when it isn't one. */
+export function graphqlOf(call) {
+    let doc, name, variables;
+    if (call.method === "GET") {
+        doc = call.query.get("query") ?? undefined;
+        name = call.query.get("operationName") ?? undefined;
+        const v = call.query.get("variables");
+        try {
+            variables = v ? JSON.parse(v) : undefined;
+        }
+        catch {
+            variables = undefined;
+        }
+    }
+    else if (call.json && typeof call.json === "object" && !Array.isArray(call.json)) {
+        ({ query: doc, operationName: name, variables } = call.json);
+    }
+    if (typeof doc !== "string")
+        return undefined;
+    const ops = operations(doc);
+    const op = typeof name === "string" && name ? (ops.find((o) => o.name === name) ?? { type: "query", name }) : ops[0];
+    if (!op)
+        return undefined;
+    return {
+        operation: typeof name === "string" && name ? name : op.name,
+        type: op.type,
+        query: doc,
+        variables: variables && typeof variables === "object" ? variables : {},
+    };
+}
+/** A GraphQL error list from messages or full error objects. */
+export function graphqlErrors(errors) {
+    return errors.map((e) => (typeof e === "string" ? { message: e } : e));
+}
+/** `GraphQL mutation CreateIssue`, for failure messages. */
+export function describeGraphQL(g) {
+    return `GraphQL ${g.type} ${g.operation ?? "(anonymous)"}`;
+}

package/dist/har.d.ts

@@ -0,0 +1,49 @@
+import { type Recording } from "./recording.js";
+/**
+ * `slicetest import session.har`: turn a HAR file (saved from the browser's
+ * network panel, Charles, mitmproxy, Proxyman, Postman, …) into recordings a
+ * stub replays, without running the app against the real service first.
+ */
+interface HarEntry {
+    request: {
+        method: string;
+        url: string;
+        postData?: {
+            mimeType?: string;
+            text?: string;
+        };
+    };
+    response: {
+        status: number;
+        headers?: {
+            name: string;
+            value: string;
+        }[];
+        content?: {
+            mimeType?: string;
+            text?: string;
+            encoding?: string;
+        };
+    };
+}
+export interface HarTarget {
+    /** Stub name. */
+    name: string;
+    /** The real service's base URL; entries under it become recordings, with this prefix removed from their path. */
+    upstream: string;
+    /** Recordings file, absolute. */
+    file: string;
+}
+export declare function harEntries(har: unknown, file?: string): HarEntry[];
+/** The entry as a recording, if it is under `upstream` and replayable; otherwise why not. */
+export declare function toRecording(entry: HarEntry, upstream: string): Recording | "elsewhere" | "skipped";
+export declare function importHar(harFile: string, targets: HarTarget[]): Promise<{
+    written: {
+        name: string;
+        file: string;
+        count: number;
+    }[];
+    skipped: number;
+    others: [string, number][];
+}>;
+export {};

package/dist/har.js

@@ -0,0 +1,107 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { mergeRecordings } from "./recording.js";
+const KEPT_HEADERS = ["content-type", "location", "retry-after", "link", "etag"];
+const TEXTUAL = /json|text|xml|javascript|x-www-form-urlencoded|graphql/i;
+export function harEntries(har, file = "the HAR file") {
+    const entries = har?.log?.entries;
+    if (!Array.isArray(entries))
+        throw new Error(`slicetest import: ${file} is not a HAR file (no log.entries)`);
+    return entries;
+}
+/** The entry as a recording, if it is under `upstream` and replayable; otherwise why not. */
+export function toRecording(entry, upstream) {
+    const base = new URL(upstream);
+    let url;
+    try {
+        url = new URL(entry.request.url);
+    }
+    catch {
+        return "skipped";
+    }
+    const prefix = base.pathname.replace(/\/$/, "");
+    if (url.host !== base.host || !(url.pathname === prefix || url.pathname.startsWith(`${prefix}/`)))
+        return "elsewhere";
+    const method = entry.request.method.toUpperCase();
+    // Preflights are the browser's; aborted and blocked requests (status 0) have no answer to replay.
+    if (method === "OPTIONS" || !entry.response || !entry.response.status)
+        return "skipped";
+    const query = Object.fromEntries([...url.searchParams.entries()].sort(([a], [b]) => a.localeCompare(b)));
+    const sent = entry.request.postData?.text;
+    const json = parse(sent);
+    const request = {
+        method,
+        path: url.pathname.slice(prefix.length) || "/",
+        ...(Object.keys(query).length ? { query } : {}),
+        ...(json !== undefined ? { json } : sent ? { body: sent } : {}),
+    };
+    const content = entry.response.content ?? {};
+    let text = content.text ?? "";
+    if (content.encoding === "base64" && text) {
+        if (!TEXTUAL.test(content.mimeType ?? ""))
+            return "skipped";
+        text = Buffer.from(text, "base64").toString("utf8");
+    }
+    const headers = Object.fromEntries((entry.response.headers ?? []).flatMap((h) => (KEPT_HEADERS.includes(h.name.toLowerCase()) ? [[h.name.toLowerCase(), h.value]] : [])));
+    const body = parse(text);
+    return {
+        request,
+        response: {
+            status: entry.response.status,
+            ...(Object.keys(headers).length ? { headers } : {}),
+            ...(body !== undefined ? { json: body } : text ? { body: text } : {}),
+        },
+    };
+}
+export async function importHar(harFile, targets) {
+    const text = await readFile(harFile, "utf8");
+    let har;
+    try {
+        har = JSON.parse(text);
+    }
+    catch (e) {
+        throw new Error(`slicetest import: ${harFile} is not JSON: ${e.message}`);
+    }
+    const entries = harEntries(har, harFile);
+    const written = [];
+    const claimed = new Set();
+    let skipped = 0;
+    for (const t of targets) {
+        const recordings = [];
+        for (const e of entries) {
+            const r = toRecording(e, t.upstream);
+            if (r === "elsewhere")
+                continue;
+            claimed.add(e);
+            if (r === "skipped")
+                skipped++;
+            else
+                recordings.push(r);
+        }
+        if (recordings.length === 0)
+            continue;
+        await mergeRecordings(t.file, t.upstream, recordings, `Imported by slicetest from ${path.basename(harFile)} (${t.upstream})`);
+        written.push({ name: t.name, file: t.file, count: recordings.length });
+    }
+    const others = new Map();
+    for (const e of entries) {
+        if (claimed.has(e))
+            continue;
+        try {
+            const host = new URL(e.request.url).origin;
+            others.set(host, (others.get(host) ?? 0) + 1);
+        }
+        catch { }
+    }
+    return { written, skipped, others: [...others].sort((a, b) => b[1] - a[1]) };
+}
+function parse(text) {
+    if (!text)
+        return undefined;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/http.d.ts

@@ -56,6 +56,16 @@ export declare class HttpClient {
      * `{ invalidSignature: true }` and `{ stale: true }` make deliveries the app must refuse.
      */
     webhook(path: string, payload: unknown, opts: WebhookOptions): Promise<HttpResponse>;
+    /**
+     * Send a GraphQL operation to the app: `http.graphql("query { poll(id: 1) { title } }")`,
+     * `http.graphql(CREATE_POLL, { title: "Tea?" })`. Posts `{ query, variables, operationName }` to
+     * `/graphql` (`path` for another endpoint). Pair with `toHaveGraphQLData()`, since GraphQL
+     * servers answer errors with status 200.
+     */
+    graphql(query: string, variables?: Record<string, unknown>, opts?: RequestOptions & {
+        path?: string;
+        operationName?: string;
+    }): 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 })`

package/dist/http.js

@@ -1,5 +1,6 @@
 import { formRequest } from "./form.js";
 import { lookupHost } from "./intercept.js";
+import { timeline } from "./timeline.js";
 import { signWebhook, webhookBody } from "./webhook.js";
 /** Per-scenario state shared by a client and every client derived from it with `with()`. */
 class Session {
@@ -86,6 +87,16 @@ export class HttpClient {
         const { body, type } = webhookBody(payload);
         return this.request("POST", path, body, { headers: { "content-type": type, ...signWebhook(body, opts), ...opts.headers } });
     }
+    /**
+     * Send a GraphQL operation to the app: `http.graphql("query { poll(id: 1) { title } }")`,
+     * `http.graphql(CREATE_POLL, { title: "Tea?" })`. Posts `{ query, variables, operationName }` to
+     * `/graphql` (`path` for another endpoint). Pair with `toHaveGraphQLData()`, since GraphQL
+     * servers answer errors with status 200.
+     */
+    graphql(query, variables, opts = {}) {
+        const { path = "/graphql", operationName, ...request } = opts;
+        return this.request("POST", path, { query, ...(variables ? { variables } : {}), ...(operationName ? { operationName } : {}) }, request);
+    }
     /**
      * 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 })`
@@ -164,7 +175,9 @@ export class HttpClient {
         }
         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) });
+            const failed = { method, url: url.pathname + url.search, status: 0, headers: new Headers(), text: `${e}${cause ? ` (${cause})` : ""}`, json: undefined, durationMs: Math.round(performance.now() - started) };
+            timeline.set(failed, { start: started, end: performance.now() });
+            this.#record(failed);
             throw e;
         }
         if (!stub)
@@ -185,6 +198,7 @@ export class HttpClient {
             json,
             durationMs: Math.round(performance.now() - started),
         };
+        timeline.set(out, { start: started, end: performance.now() });
         this.#record(out);
         // Listeners (contract checks, coverage) are about the app's responses only.
         if (!stub)

package/dist/index.d.ts

@@ -3,7 +3,8 @@ 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, ChaosOptions, ServerSentEvent } from "./stub.js";
+export type { Stub, RecordedCall, StubResponse, Responder, MatchOptions, RouteBuilder, GraphQLRouteBuilder, ChaosOptions, ServerSentEvent } from "./stub.js";
+export type { GraphQLCall } from "./graphql.js";
 export { sse } from "./stub.js";
 export type { HttpClient, HttpResponse, RequestOptions } from "./http.js";
 export type { SubmitOptions } from "./form.js";