slicetest 0.6.0 → 0.7.0

package/dist/diagram.js

@@ -0,0 +1,89 @@
+import { describeGraphQL } from "./graphql.js";
+import { timeline } from "./timeline.js";
+/**
+ * A Mermaid sequence diagram of what a scenario did: each request to the app,
+ * the stub calls the app made while answering it, the mail it sent and the
+ * database tables it changed. GitHub, GitLab and most Markdown viewers render it.
+ */
+export function sequenceDiagram(history, stubs, changes, mailbox) {
+    const events = [];
+    const participants = new Map();
+    const id = (name, label) => {
+        const key = `s_${name.replace(/[^A-Za-z0-9_]/g, "_")}`;
+        if (!participants.has(key))
+            participants.set(key, label);
+        return key;
+    };
+    let order = 0;
+    const add = (at, line) => events.push({ at, order: order++, line });
+    for (const res of history) {
+        const t = timeline.get(res) ?? { start: Infinity, end: Infinity };
+        const external = /^https?:/.test(res.url);
+        const target = external ? id(`ext_${new URL(res.url).host}`, new URL(res.url).host) : "app";
+        const path = external ? new URL(res.url).pathname : res.url;
+        add(t.start, `test->>+${target}: ${text(`${res.method} ${path}`)}`);
+        add(t.end ?? t.start, `${target}-->>-test: ${res.status || "failed"}${summary(res)}`);
+    }
+    for (const stub of stubs) {
+        for (const call of stub.calls()) {
+            const t = timeline.get(call) ?? { start: Infinity };
+            const s = id(stub.name, `${stub.name} (stub)`);
+            add(t.start, `app->>+${s}: ${text(describeCall(call))}`);
+            const reply = call.fault === "reset" ? "connection dropped" : call.response ? `${call.response.status}${call.fault ? " (chaos)" : ""}` : call.matched ? "no answer" : "501 no stub";
+            add(t.end ?? t.start, `${s}-->>-app: ${reply}`);
+        }
+    }
+    events.sort((a, b) => a.at - b.at || a.order - b.order);
+    const lines = ["sequenceDiagram", "  participant test as scenario", "  participant app"];
+    for (const [key, label] of participants)
+        lines.push(`  participant ${key} as ${text(label)}`);
+    if (mailbox && mailbox.messages().length)
+        lines.push("  participant mail");
+    const tables = Object.entries(changes ?? {}).filter(([, c]) => c.inserted.length || c.updated.length || c.deleted.length);
+    if (tables.length)
+        lines.push("  participant db as database");
+    for (const e of events)
+        lines.push(`  ${e.line}`);
+    for (const m of mailbox?.messages() ?? [])
+        lines.push(`  app->>mail: ${text(`${m.subject} to ${m.to.join(", ")}`)}`);
+    if (tables.length) {
+        const counts = tables.map(([table, c]) => `${table} ${[c.inserted.length && `+${c.inserted.length}`, c.updated.length && `~${c.updated.length}`, c.deleted.length && `-${c.deleted.length}`].filter(Boolean).join(" ")}`);
+        lines.push(`  Note over app,db: ${text(counts.join(", "))}`);
+    }
+    return lines.join("\n");
+}
+function describeCall(call) {
+    if (call.graphql)
+        return describeGraphQL(call.graphql);
+    return `${call.method} ${call.path}`;
+}
+/** A short hint of the response: a JSON error message or the id it created. */
+function summary(res) {
+    const j = res.json;
+    if (j && typeof j === "object" && !Array.isArray(j)) {
+        for (const key of ["error", "message", "id"]) {
+            const v = j[key];
+            if (typeof v === "string" || typeof v === "number")
+                return ` ${text(`${key}: ${v}`)}`;
+        }
+    }
+    return "";
+}
+/** Mermaid ends a message at `;` and reads `#…;` as an entity, so both are escaped; long text is cut. */
+function text(s, max = 70) {
+    const cut = s.length > max ? `${s.slice(0, max - 1)}…` : s;
+    return cut.replace(/[\r\n]+/g, " ").replace(/[#;]/g, (c) => (c === "#" ? "#35;" : "#59;"));
+}
+/** Scenario diagrams per test file, for `SLICETEST_DIAGRAMS` / `--diagrams`: one Markdown page per file, in run order. */
+const pages = new Map();
+export function diagramPage(file, title, scenario, diagram, failed) {
+    const page = pages.get(file) ?? { title, sections: new Map() };
+    pages.set(file, page);
+    page.sections.set(scenario, [`## ${scenario}${failed ? " (failed)" : ""}`, "", "```mermaid", diagram, "```", ""].join("\n"));
+    return [`# ${page.title}`, "", `Sequence diagrams of the scenarios in \`${page.title}\`, written by slicetest. Regenerated on every run.`, "", ...page.sections.values()].join("\n");
+}
+/** A collapsed section for the GitHub Actions job summary. */
+export function failureDiagram(where, scenario, diagram) {
+    const name = scenario.replace(/[<>&]/g, (c) => ({ "<": "&lt;", ">": "&gt;", "&": "&amp;" })[c]);
+    return [`<details><summary>✗ ${name} <code>${where}</code>: what happened</summary>`, "", "```mermaid", diagram, "```", "", "</details>", ""].join("\n");
+}

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

@@ -22,6 +22,8 @@ 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>;
+    /** The Path each cookie was set for; a cookie without one (added by hand) goes everywhere. */
+    cookiePaths: Map<string, string>;
     history: HttpResponse[];
     listeners: ((res: HttpResponse) => void)[];
 }
@@ -54,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,11 +1,14 @@
 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 {
     /** Stub base URLs of intercepted hosts, which redirects may lead to (an OAuth provider's login page). */
     external = new Map();
     cookies = new Map();
+    /** The Path each cookie was set for; a cookie without one (added by hand) goes everywhere. */
+    cookiePaths = new Map();
     history = [];
     listeners = [];
 }
@@ -84,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 })`
@@ -136,8 +149,10 @@ export class HttpClient {
         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("; "));
+        if (!stub && !headers.has("cookie")) {
+            const cookie = this.#cookieHeader(url.pathname);
+            if (cookie)
+                headers.set("cookie", cookie);
         }
         let payload;
         if (body === undefined ||
@@ -160,12 +175,14 @@ 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)
             for (const cookie of res.headers.getSetCookie())
-                this.#storeCookie(cookie);
+                this.#storeCookie(cookie, url.pathname);
         const text = await res.text();
         let json;
         try {
@@ -181,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)
@@ -207,6 +225,7 @@ export class HttpClient {
     }
     clearCookies() {
         this.#session.cookies.clear();
+        this.#session.cookiePaths.clear();
     }
     /** Requests made during the current scenario, oldest first (last 20). */
     get history() {
@@ -214,29 +233,65 @@ export class HttpClient {
     }
     /** Start a new scenario: forget cookies and history. */
     reset() {
-        this.#session.cookies.clear();
+        this.clearCookies();
         this.#session.history = [];
     }
-    #storeCookie(header) {
+    /** Cookies whose Path covers `requestPath`, longest Path first as browsers send them (RFC 6265 5.4). */
+    #cookieHeader(requestPath) {
+        const { cookies, cookiePaths } = this.#session;
+        return [...cookies]
+            .map(([name, value]) => ({ name, value, path: cookiePaths.get(name) ?? "/" }))
+            .filter((c) => pathMatches(requestPath, c.path))
+            .sort((a, b) => b.path.length - a.path.length)
+            .map((c) => `${c.name}=${c.value}`)
+            .join("; ");
+    }
+    #storeCookie(header, requestPath) {
         const [pair, ...attrs] = header.split(";");
         const eq = pair.indexOf("=");
         if (eq <= 0)
             return;
         const name = pair.slice(0, eq).trim();
-        const expired = attrs.some((a) => {
-            const [k, v = ""] = a.split("=").map((s) => s.trim());
-            if (k.toLowerCase() === "max-age")
-                return Number(v) <= 0;
-            if (k.toLowerCase() === "expires")
-                return Date.parse(v) <= Date.now();
-            return false;
-        });
-        if (expired)
+        let maxAge;
+        let expires;
+        let cookiePath;
+        for (const a of attrs) {
+            const i = a.indexOf("=");
+            const k = (i < 0 ? a : a.slice(0, i)).trim().toLowerCase();
+            const v = i < 0 ? "" : a.slice(i + 1).trim();
+            if (k === "max-age")
+                maxAge = Number(v);
+            else if (k === "expires")
+                expires = Date.parse(v);
+            else if (k === "path" && v.startsWith("/"))
+                cookiePath = v;
+        }
+        // Max-Age wins over Expires whichever comes first.
+        const expired = maxAge !== undefined && !Number.isNaN(maxAge) ? maxAge <= 0 : expires !== undefined && expires <= Date.now();
+        // Keyed by name alone: a second cookie of the same name under another Path replaces the first.
+        if (expired) {
             this.#session.cookies.delete(name);
-        else
+            this.#session.cookiePaths.delete(name);
+        }
+        else {
             this.#session.cookies.set(name, pair.slice(eq + 1).trim());
+            this.#session.cookiePaths.set(name, cookiePath ?? defaultCookiePath(requestPath));
+        }
     }
 }
+/** RFC 6265 5.1.4: the request path's directory, e.g. "/auth" for "/auth/login". */
+function defaultCookiePath(requestPath) {
+    const slash = requestPath.lastIndexOf("/");
+    return slash <= 0 ? "/" : requestPath.slice(0, slash);
+}
+/** RFC 6265 5.1.4: "/api" covers "/api" and "/api/x" but not "/apix". */
+function pathMatches(requestPath, cookiePath) {
+    if (requestPath === cookiePath)
+        return true;
+    if (!requestPath.startsWith(cookiePath))
+        return false;
+    return cookiePath.endsWith("/") || requestPath[cookiePath.length] === "/";
+}
 function merge(a, b) {
     return {
         ...a,

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";