slicetest 0.6.1 → 0.8.0

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

@@ -11,11 +11,15 @@ export interface HttpResponse {
     /** Wall-clock time of the request in milliseconds. */
     durationMs: number;
 }
+type QueryValue = string | number | boolean;
 export interface RequestOptions {
     headers?: Record<string, string>;
-    query?: Record<string, string | number | boolean | undefined>;
+    /** A list repeats the parameter: `{ tag: ["a", "b"] }` is `?tag=a&tag=b`. */
+    query?: Record<string, QueryValue | QueryValue[] | undefined>;
     /** Follow redirects instead of returning the 3xx response. Default false. */
     follow?: boolean;
+    /** Fail the request when the app hasn't answered within this many ms, naming it, instead of the whole test timing out. */
+    timeout?: number;
 }
 /** Per-scenario state shared by a client and every client derived from it with `with()`. */
 declare class Session {
@@ -35,8 +39,12 @@ export declare class HttpClient {
     constructor(baseUrl: string, defaults?: RequestOptions, session?: Session);
     /** A client that adds `opts` (e.g. an auth header) to every request, sharing this one's cookies. */
     with(opts: RequestOptions): HttpClient;
-    /** Wrap fields to be sent as `application/x-www-form-urlencoded`. */
-    form(fields: Record<string, string | number | boolean>): URLSearchParams;
+    /**
+     * Wrap fields to be sent as `application/x-www-form-urlencoded`. A list repeats the key (`to=a&to=b`,
+     * as an HTML form sends it), and nested objects use bracket keys (`metadata[order]=7`,
+     * `items[0][price]=p_1`), as Rails, PHP and Stripe read them. `null` / `undefined` are left out.
+     */
+    form(fields: Record<string, unknown>): URLSearchParams;
     get(path: string, opts?: RequestOptions): Promise<HttpResponse>;
     head(path: string, opts?: RequestOptions): Promise<HttpResponse>;
     delete(path: string, opts?: RequestOptions): Promise<HttpResponse>;
@@ -56,6 +64,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 { encodeForm, 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 {
@@ -33,9 +34,13 @@ export class HttpClient {
     with(opts) {
         return new HttpClient(this.baseUrl, merge(this.defaults, opts), this.#session);
     }
-    /** Wrap fields to be sent as `application/x-www-form-urlencoded`. */
+    /**
+     * Wrap fields to be sent as `application/x-www-form-urlencoded`. A list repeats the key (`to=a&to=b`,
+     * as an HTML form sends it), and nested objects use bracket keys (`metadata[order]=7`,
+     * `items[0][price]=p_1`), as Rails, PHP and Stripe read them. `null` / `undefined` are left out.
+     */
     form(fields) {
-        return new URLSearchParams(Object.entries(fields).map(([k, v]) => [k, String(v)]));
+        return encodeForm(fields);
     }
     get(path, opts) {
         return this.request("GET", path, undefined, opts);
@@ -83,8 +88,19 @@ export class HttpClient {
      * `{ 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 } });
+        const { body, type } = webhookBody(payload, opts.provider);
+        const url = opts.url ?? new URL(path, this.baseUrl).href;
+        return this.request("POST", path, body, { headers: { "content-type": type, ...signWebhook(body, { ...opts, url }), ...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
@@ -111,9 +127,17 @@ export class HttpClient {
         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)
+        for (const [k, v] of Object.entries(opts.query ?? {})) {
+            if (v === undefined)
+                continue;
+            if (Array.isArray(v)) {
+                url.searchParams.delete(k);
+                for (const item of v)
+                    url.searchParams.append(k, String(item));
+            }
+            else
                 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");
@@ -160,12 +184,14 @@ export class HttpClient {
         const started = performance.now();
         let res;
         try {
-            res = await fetch(target, { method, headers, body: payload, redirect: "manual" });
+            res = await fetch(target, { method, headers, body: payload, redirect: "manual", signal: opts.timeout ? AbortSignal.timeout(opts.timeout) : undefined });
         }
         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;
+            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 new Error(`slicetest: ${method} ${failed.url}: ${requestFailure(e, cause, opts.timeout)}`, { cause: e });
         }
         if (!stub)
             for (const cookie of res.headers.getSetCookie())
@@ -185,6 +211,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)
@@ -278,6 +305,16 @@ function pathMatches(requestPath, cookiePath) {
         return false;
     return cookiePath.endsWith("/") || requestPath[cookiePath.length] === "/";
 }
+/** Why a request got no response, in terms of what to look at. */
+function requestFailure(e, code, timeout) {
+    if (e.name === "TimeoutError")
+        return `no response within ${timeout}ms (http timeout); the app may be waiting on a stub with a delay, a lock or a slow query`;
+    if (code === "ECONNREFUSED")
+        return "connection refused: the app isn't listening (it may have crashed; its output is below)";
+    if (code === "ECONNRESET" || code === "UND_ERR_SOCKET")
+        return "the app closed the connection without answering (did it crash or exit?)";
+    return `${e.message}${code ? ` (${code})` : ""}`;
+}
 function merge(a, b) {
     return {
         ...a,

package/dist/index.d.ts

@@ -1,9 +1,11 @@
 export { scenario } from "./scenario.js";
+export type { ScenarioOptions } from "./scenario.js";
 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 { Db, Row, Where, RowsOptions, Changes, TableChanges, ChangesOptions } from "./db.js";
+export type { Stub, RecordedCall, StubResponse, Responder, MatchOptions, RouteBuilder, GraphQLRouteBuilder, ChaosOptions, ServerSentEvent, UploadedFile } 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";
@@ -14,4 +16,4 @@ 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";
+export type { OrderedCall } from "./matchers.js";