@zudojs/testing 1.1.2 → 1.2.2

package/dist/httpTestClient/httpTestRequest/httpTestRequest.core.js

@@ -0,0 +1,97 @@
+/**
+ * @zudojs/testing — fluent HTTP test request.
+ */
+import { expectHeader, expectJson, expectStatus, expectText, } from "../httpTestResponse/index.js";
+import { appendQuery, basicAuthorization, normalizePath, } from "./httpTestRequest.encode.js";
+import { executeHttpTestRequest } from "./httpTestRequest.execute.js";
+/**
+ * Creates a request bound to a client context. Nothing is sent until the
+ * request is awaited.
+ */
+export function createHttpTestRequest(context, method, path) {
+    const headers = new Headers(context.headers);
+    const expectations = [];
+    let target = normalizePath(path);
+    let body;
+    let hasBody = false;
+    let timeoutMs = context.timeout;
+    let sent;
+    const mutable = () => {
+        if (sent) {
+            throw new TypeError(`${method} ${target} has already been sent; build a new request.`);
+        }
+    };
+    const execute = () => executeHttpTestRequest(context, {
+        method,
+        target,
+        headers,
+        body,
+        hasBody,
+        timeoutMs,
+        expectations,
+    });
+    const register = (check) => {
+        mutable();
+        expectations.push({ check, site: new Error("expectation") });
+        return request;
+    };
+    const request = {
+        set(nameOrHeaders, value) {
+            mutable();
+            const entries = typeof nameOrHeaders === "string"
+                ? [[nameOrHeaders, value ?? ""]]
+                : Object.entries(nameOrHeaders);
+            for (const [name, entry] of entries)
+                headers.set(name, entry);
+            return request;
+        },
+        query(values) {
+            mutable();
+            target = appendQuery(target, values);
+            return request;
+        },
+        send(value) {
+            mutable();
+            body = value;
+            hasBody = value !== undefined;
+            return request;
+        },
+        auth(tokenOrUser, password) {
+            mutable();
+            headers.set("authorization", password === undefined
+                ? `Bearer ${tokenOrUser}`
+                : basicAuthorization(tokenOrUser, password));
+            return request;
+        },
+        timeout(ms) {
+            mutable();
+            if (!Number.isFinite(ms) || ms <= 0) {
+                throw new RangeError(`Request timeout must be a positive number of milliseconds; got ${ms}.`);
+            }
+            timeoutMs = ms;
+            return request;
+        },
+        expect(first, value) {
+            if (typeof first === "number")
+                return register(expectStatus(first));
+            if (typeof first === "function")
+                return register(first);
+            if (value === undefined) {
+                throw new TypeError(`.expect("${first}") needs the header value or pattern to compare with.`);
+            }
+            return register(expectHeader(first, value));
+        },
+        expectJson: (expected) => register(expectJson(expected)),
+        expectText: (expected) => register(expectText(expected)),
+        then(onFulfilled, onRejected) {
+            sent ??= execute();
+            return sent.then(onFulfilled, onRejected);
+        },
+        catch(onRejected) {
+            sent ??= execute();
+            return sent.catch(onRejected);
+        },
+    };
+    return request;
+}
+//# sourceMappingURL=httpTestRequest.core.js.map

package/dist/httpTestClient/httpTestRequest/httpTestRequest.encode.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @zudojs/testing — request target and body encoding.
+ *
+ * Bodies are encoded as they travel on the wire, so JSON is plain
+ * `JSON.stringify` output (no serialization envelope).
+ */
+import type { HttpTestBody, HttpTestQuery } from "./httpTestRequest.type.js";
+/** An encoded body and the content type it implies. */
+export interface EncodedBody {
+    readonly bytes: Uint8Array;
+    readonly contentType: string;
+}
+/** Encodes a `.send()` body. */
+export declare function encodeBody(body: HttpTestBody): EncodedBody;
+/**
+ * Checks and normalises a request path. It must be origin-relative: the
+ * target is chosen when the client is created, not per request.
+ */
+export declare function normalizePath(path: string): string;
+/** Substitutes `:name` segments with URI-encoded `params`. */
+export declare function substituteParams(path: string, params: Readonly<Record<string, string>>): string;
+/** Appends query parameters to a path that may already carry a query. */
+export declare function appendQuery(path: string, query: HttpTestQuery): string;
+/** Builds a Basic `Authorization` header value. */
+export declare function basicAuthorization(user: string, password: string): string;
+//# sourceMappingURL=httpTestRequest.encode.d.ts.map

package/dist/httpTestClient/httpTestRequest/httpTestRequest.encode.js

@@ -0,0 +1,73 @@
+/**
+ * @zudojs/testing — request target and body encoding.
+ *
+ * Bodies are encoded as they travel on the wire, so JSON is plain
+ * `JSON.stringify` output (no serialization envelope).
+ */
+/** Encodes a `.send()` body. */
+export function encodeBody(body) {
+    const encoder = new TextEncoder();
+    if (typeof body === "string") {
+        return {
+            bytes: encoder.encode(body),
+            contentType: "text/plain; charset=utf-8",
+        };
+    }
+    if (body instanceof Uint8Array) {
+        return { bytes: body, contentType: "application/octet-stream" };
+    }
+    if (body instanceof ArrayBuffer) {
+        return {
+            bytes: new Uint8Array(body),
+            contentType: "application/octet-stream",
+        };
+    }
+    if (body instanceof URLSearchParams) {
+        return {
+            bytes: encoder.encode(body.toString()),
+            contentType: "application/x-www-form-urlencoded; charset=utf-8",
+        };
+    }
+    return {
+        bytes: encoder.encode(JSON.stringify(body)),
+        contentType: "application/json",
+    };
+}
+/**
+ * Checks and normalises a request path. It must be origin-relative: the
+ * target is chosen when the client is created, not per request.
+ */
+export function normalizePath(path) {
+    if (/^[a-z][a-z\d+.-]*:/i.test(path) || path.startsWith("//")) {
+        throw new TypeError(`HTTP test client paths are origin-relative; got "${path}". Point createHttpTestClient() at the other origin instead.`);
+    }
+    return path.startsWith("/") ? path : `/${path}`;
+}
+/** Substitutes `:name` segments with URI-encoded `params`. */
+export function substituteParams(path, params) {
+    return path.replace(/:([A-Za-z_$][\w$]*)/g, (segment, name) => Object.hasOwn(params, name)
+        ? encodeURIComponent(params[name])
+        : segment);
+}
+/** Appends query parameters to a path that may already carry a query. */
+export function appendQuery(path, query) {
+    const hash = path.indexOf("#");
+    const bare = hash === -1 ? path : path.slice(0, hash);
+    const split = bare.indexOf("?");
+    const pathname = split === -1 ? bare : bare.slice(0, split);
+    const search = new URLSearchParams(split === -1 ? "" : bare.slice(split + 1));
+    for (const [name, value] of Object.entries(query)) {
+        if (value === null || value === undefined)
+            continue;
+        const values = Array.isArray(value) ? value : [value];
+        for (const item of values)
+            search.append(name, String(item));
+    }
+    const encoded = search.toString();
+    return encoded ? `${pathname}?${encoded}` : pathname;
+}
+/** Builds a Basic `Authorization` header value. */
+export function basicAuthorization(user, password) {
+    return `Basic ${Buffer.from(`${user}:${password}`, "utf8").toString("base64")}`;
+}
+//# sourceMappingURL=httpTestRequest.encode.js.map

package/dist/httpTestClient/httpTestRequest/httpTestRequest.execute.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @zudojs/testing — sends a built test request and runs its expectations.
+ */
+import type { HttpTestExpectation, HttpTestResponse } from "../httpTestResponse/index.js";
+import type { HttpTestBody, HttpTestRequestContext } from "./httpTestRequest.type.js";
+/** An expectation plus where it was registered, for failure stacks. */
+export interface RegisteredExpectation {
+    readonly check: HttpTestExpectation;
+    readonly site: Error;
+}
+/** Everything a request accumulated before it was sent. */
+export interface HttpTestRequestState {
+    readonly method: string;
+    readonly target: string;
+    readonly headers: Headers;
+    readonly body: HttpTestBody | undefined;
+    readonly hasBody: boolean;
+    readonly timeoutMs: number;
+    readonly expectations: readonly RegisteredExpectation[];
+}
+/**
+ * Sends the request, stores returned cookies, then runs each expectation in
+ * order.
+ */
+export declare function executeHttpTestRequest(context: HttpTestRequestContext, state: HttpTestRequestState): Promise<HttpTestResponse>;
+//# sourceMappingURL=httpTestRequest.execute.d.ts.map

package/dist/httpTestClient/httpTestRequest/httpTestRequest.execute.js

@@ -0,0 +1,58 @@
+/**
+ * @zudojs/testing — sends a built test request and runs its expectations.
+ */
+import { createHttpTestResponse } from "../httpTestResponse/index.js";
+import { encodeBody } from "./httpTestRequest.encode.js";
+/**
+ * Largest delay a Node timer honours; anything longer fires after 1 ms, so
+ * a generous timeout would otherwise fail every request at once.
+ */
+const MAX_TIMER_DELAY_MS = 2_147_483_647;
+/** Points a failure's stack at the `.expect…()` call that registered it. */
+function relocate(error, site) {
+    if (error instanceof Error && site.stack) {
+        const frames = site.stack.split("\n").slice(2).join("\n");
+        error.stack = `${error.name}: ${error.message}\n${frames}`;
+    }
+    return error;
+}
+/**
+ * Sends the request, stores returned cookies, then runs each expectation in
+ * order.
+ */
+export async function executeHttpTestRequest(context, state) {
+    const { method, target, headers } = state;
+    if (state.hasBody && (method === "GET" || method === "HEAD")) {
+        throw new TypeError(`${method} ${target}: a ${method} request cannot carry a body.`);
+    }
+    const encoded = state.hasBody
+        ? encodeBody(state.body)
+        : undefined;
+    if (encoded && !headers.has("content-type")) {
+        headers.set("content-type", encoded.contentType);
+    }
+    const transport = await context.transport();
+    const sentPath = `${transport.pathPrefix ?? ""}${target}`;
+    const cookie = context.jar?.headerFor(sentPath);
+    if (cookie !== undefined && !headers.has("cookie"))
+        headers.set("cookie", cookie);
+    const raw = await transport.send({
+        method,
+        target,
+        headers,
+        body: encoded?.bytes,
+        timeoutMs: Math.min(state.timeoutMs, MAX_TIMER_DELAY_MS),
+    });
+    const response = createHttpTestResponse(raw, { method, path: target });
+    context.jar?.store(response.setCookies, sentPath);
+    for (const { check, site } of state.expectations) {
+        try {
+            await check(response);
+        }
+        catch (error) {
+            throw relocate(error, site);
+        }
+    }
+    return response;
+}
+//# sourceMappingURL=httpTestRequest.execute.js.map

package/dist/httpTestClient/httpTestRequest/httpTestRequest.type.d.ts

@@ -0,0 +1,53 @@
+/**
+ * @zudojs/testing — fluent HTTP test request types.
+ */
+import type { HttpTestCookieJar } from "../httpTestClient.cookieJar.js";
+import type { HttpTestExpectation, HttpTestResponse } from "../httpTestResponse/index.js";
+import type { HttpTestTransport } from "../httpTestTransport/index.js";
+/** A query-string value; arrays repeat the name, `null`/`undefined` are skipped. */
+export type HttpTestQueryValue = string | number | boolean | null | undefined | readonly (string | number | boolean)[];
+/** Query parameters for `.query()`. */
+export type HttpTestQuery = Readonly<Record<string, HttpTestQueryValue>>;
+/**
+ * A request body for `.send()`: a string is sent as text, bytes as
+ * `application/octet-stream`, `URLSearchParams` as a form, and anything else
+ * as JSON. An explicit `Content-Type` header always wins.
+ */
+export type HttpTestBody = string | Uint8Array | ArrayBuffer | URLSearchParams | object | number | boolean | null;
+/** What a request needs from the client that created it. */
+export interface HttpTestRequestContext {
+    readonly transport: () => Promise<HttpTestTransport>;
+    readonly jar: HttpTestCookieJar | undefined;
+    readonly headers: Readonly<Record<string, string>>;
+    readonly timeout: number;
+}
+/**
+ * A request being built. Await it (or call `.then`) to send it; it is sent
+ * once, however many times it is awaited. Expectations run in the order they
+ * were added, and the first failure rejects with an `AssertionError` whose
+ * stack points at the `.expect…()` call.
+ */
+export interface HttpTestRequest extends PromiseLike<HttpTestResponse> {
+    /** Sets one header, or several from a record. */
+    set(name: string, value: string): HttpTestRequest;
+    set(headers: Readonly<Record<string, string>>): HttpTestRequest;
+    /** Adds query parameters (merged with any already in the path). */
+    query(values: HttpTestQuery): HttpTestRequest;
+    /** Sets the body. See {@link HttpTestBody}. */
+    send(body: HttpTestBody): HttpTestRequest;
+    /** `Authorization: Bearer <token>`, or Basic with a user and password. */
+    auth(token: string): HttpTestRequest;
+    auth(user: string, password: string): HttpTestRequest;
+    /** Overrides the client's timeout for this request. */
+    timeout(ms: number): HttpTestRequest;
+    /** Expects a status code, a header value/pattern, or runs a custom check. */
+    expect(status: number): HttpTestRequest;
+    expect(header: string, value: string | RegExp): HttpTestRequest;
+    expect(check: HttpTestExpectation): HttpTestRequest;
+    /** Expects a JSON body containing `expected` (partial object match). */
+    expectJson(expected: unknown): HttpTestRequest;
+    /** Expects the body text to equal a string or match a pattern. */
+    expectText(expected: string | RegExp): HttpTestRequest;
+    catch<T = never>(onRejected?: ((reason: unknown) => T | PromiseLike<T>) | null): Promise<HttpTestResponse | T>;
+}
+//# sourceMappingURL=httpTestRequest.type.d.ts.map

package/dist/httpTestClient/httpTestRequest/httpTestRequest.type.js

@@ -0,0 +1,5 @@
+/**
+ * @zudojs/testing — fluent HTTP test request types.
+ */
+export {};
+//# sourceMappingURL=httpTestRequest.type.js.map

package/dist/httpTestClient/httpTestRequest/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @zudojs/testing — fluent HTTP test requests.
+ *
+ * The awaitable request builder returned by `client.get()` and friends, and
+ * the helpers that encode its path, query and body.
+ */
+export { createHttpTestRequest } from "./httpTestRequest.core.js";
+export { executeHttpTestRequest } from "./httpTestRequest.execute.js";
+export type { HttpTestRequestState, RegisteredExpectation, } from "./httpTestRequest.execute.js";
+export { appendQuery, basicAuthorization, encodeBody, normalizePath, substituteParams, } from "./httpTestRequest.encode.js";
+export type { EncodedBody } from "./httpTestRequest.encode.js";
+export type { HttpTestBody, HttpTestQuery, HttpTestQueryValue, HttpTestRequest, HttpTestRequestContext, } from "./httpTestRequest.type.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/httpTestClient/httpTestRequest/index.js

@@ -0,0 +1,10 @@
+/**
+ * @zudojs/testing — fluent HTTP test requests.
+ *
+ * The awaitable request builder returned by `client.get()` and friends, and
+ * the helpers that encode its path, query and body.
+ */
+export { createHttpTestRequest } from "./httpTestRequest.core.js";
+export { executeHttpTestRequest } from "./httpTestRequest.execute.js";
+export { appendQuery, basicAuthorization, encodeBody, normalizePath, substituteParams, } from "./httpTestRequest.encode.js";
+//# sourceMappingURL=index.js.map

package/dist/httpTestClient/httpTestResponse/httpTestResponse.core.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @zudojs/testing — builds `HttpTestResponse` objects from raw responses.
+ */
+import type { RawHttpResponse } from "../httpTestTransport/index.js";
+import type { HttpTestRequestSummary, HttpTestResponse } from "./httpTestResponse.type.js";
+/** A short, single-line preview of a body for failure messages. */
+export declare function previewBody(text: string): string;
+/**
+ * Wraps a raw response.
+ *
+ * @param raw - The response as received.
+ * @param request - The method and path that produced it.
+ */
+export declare function createHttpTestResponse(raw: RawHttpResponse, request: HttpTestRequestSummary): HttpTestResponse;
+//# sourceMappingURL=httpTestResponse.core.d.ts.map

package/dist/httpTestClient/httpTestResponse/httpTestResponse.core.js

@@ -0,0 +1,71 @@
+/**
+ * @zudojs/testing — builds `HttpTestResponse` objects from raw responses.
+ */
+const MAX_PREVIEW = 500;
+function mediaType(headers) {
+    const value = headers.get("content-type");
+    return value ? value.split(";")[0]?.trim().toLowerCase() : undefined;
+}
+function isJsonType(type) {
+    return type === "application/json" || (type?.endsWith("+json") ?? false);
+}
+function tryParse(text) {
+    try {
+        return { ok: true, value: JSON.parse(text) };
+    }
+    catch {
+        return { ok: false, value: undefined };
+    }
+}
+/** A short, single-line preview of a body for failure messages. */
+export function previewBody(text) {
+    if (text.length === 0)
+        return "(empty)";
+    const flat = text.replace(/\s+/g, " ");
+    return flat.length > MAX_PREVIEW ? `${flat.slice(0, MAX_PREVIEW)}…` : flat;
+}
+function cookiesOf(setCookies) {
+    const cookies = {};
+    for (const header of setCookies) {
+        const pair = header.split(";")[0] ?? "";
+        const equals = pair.indexOf("=");
+        if (equals > 0)
+            cookies[pair.slice(0, equals).trim()] = pair.slice(equals + 1).trim();
+    }
+    return Object.freeze(cookies);
+}
+/**
+ * Wraps a raw response.
+ *
+ * @param raw - The response as received.
+ * @param request - The method and path that produced it.
+ */
+export function createHttpTestResponse(raw, request) {
+    const text = new TextDecoder().decode(raw.body);
+    const type = mediaType(raw.headers);
+    const parsed = text.length > 0 && isJsonType(type) ? tryParse(text) : undefined;
+    const setCookies = Object.freeze([...raw.headers.getSetCookie()]);
+    return Object.freeze({
+        status: raw.status,
+        statusText: raw.statusText,
+        ok: raw.status >= 200 && raw.status < 300,
+        headers: raw.headers,
+        type,
+        text,
+        bytes: raw.body,
+        body: parsed?.ok ? parsed.value : text.length > 0 ? text : undefined,
+        sent: true,
+        setCookies,
+        cookies: cookiesOf(setCookies),
+        request: Object.freeze({ ...request }),
+        header: (name) => raw.headers.get(name) ?? undefined,
+        json: () => {
+            const result = tryParse(text);
+            if (!result.ok) {
+                throw new SyntaxError(`${request.method} ${request.path} answered ${raw.status} with a body that is not JSON (content-type: ${type ?? "none"}): ${previewBody(text)}`);
+            }
+            return result.value;
+        },
+    });
+}
+//# sourceMappingURL=httpTestResponse.core.js.map

package/dist/httpTestClient/httpTestResponse/httpTestResponse.expect.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @zudojs/testing — expectations run against a test client response.
+ *
+ * Failures are `AssertionError`s (from `node:assert`) carrying `actual` and
+ * `expected`, so test runners show a diff, and their message always names
+ * the request and previews the response body.
+ */
+import type { HttpTestResponse } from "./httpTestResponse.type.js";
+/** A check run once the response arrives. Throw to fail. */
+export type HttpTestExpectation = (response: HttpTestResponse) => void | Promise<void>;
+/** Expects an exact status code. */
+export declare function expectStatus(expected: number): HttpTestExpectation;
+/** Expects a header to equal a string or match a pattern. */
+export declare function expectHeader(name: string, expected: string | RegExp): HttpTestExpectation;
+/** Expects a JSON body containing `expected` (extra object keys are allowed). */
+export declare function expectJson(expected: unknown): HttpTestExpectation;
+/** Expects the text body to equal a string or match a pattern. */
+export declare function expectText(expected: string | RegExp): HttpTestExpectation;
+//# sourceMappingURL=httpTestResponse.expect.d.ts.map

package/dist/httpTestClient/httpTestResponse/httpTestResponse.expect.js

@@ -0,0 +1,74 @@
+/**
+ * @zudojs/testing — expectations run against a test client response.
+ *
+ * Failures are `AssertionError`s (from `node:assert`) carrying `actual` and
+ * `expected`, so test runners show a diff, and their message always names
+ * the request and previews the response body.
+ */
+import { AssertionError } from "node:assert";
+import { previewBody } from "./httpTestResponse.core.js";
+import { findPartialDifference } from "./httpTestResponse.match.js";
+function fail(response, message, actual, expected) {
+    const { method, path } = response.request;
+    throw new AssertionError({
+        message: `${message}\n  request:  ${method} ${path}\n  response: ${response.status} ${response.statusText}\n  body:     ${previewBody(response.text)}`,
+        actual,
+        expected,
+        operator: "strictEqual",
+    });
+}
+/** Expects an exact status code. */
+export function expectStatus(expected) {
+    return (response) => {
+        if (response.status !== expected) {
+            fail(response, `Expected status ${expected}, got ${response.status}.`, response.status, expected);
+        }
+    };
+}
+function matches(actual, expected) {
+    if (typeof expected === "string")
+        return actual === expected;
+    return new RegExp(expected.source, expected.flags.replace(/[gy]/g, "")).test(actual);
+}
+function describeExpected(expected, verb) {
+    return typeof expected === "string"
+        ? `${verb} ${JSON.stringify(expected)}`
+        : `match ${String(expected)}`;
+}
+/** Expects a header to equal a string or match a pattern. */
+export function expectHeader(name, expected) {
+    return (response) => {
+        const actual = response.header(name);
+        if (actual === undefined || !matches(actual, expected)) {
+            const shown = actual === undefined
+                ? "it was absent"
+                : `got ${JSON.stringify(actual)}`;
+            fail(response, `Expected header "${name}" to ${describeExpected(expected, "be")}, ${shown}.`, actual, expected);
+        }
+    };
+}
+/** Expects a JSON body containing `expected` (extra object keys are allowed). */
+export function expectJson(expected) {
+    return (response) => {
+        let body;
+        try {
+            body = response.json();
+        }
+        catch {
+            fail(response, `Expected a JSON body (content-type: ${response.type ?? "none"}).`, response.text, expected);
+        }
+        const difference = findPartialDifference(body, expected);
+        if (difference) {
+            fail(response, `JSON body mismatch at ${difference.path}: ${difference.reason}.`, body, expected);
+        }
+    };
+}
+/** Expects the text body to equal a string or match a pattern. */
+export function expectText(expected) {
+    return (response) => {
+        if (!matches(response.text, expected)) {
+            fail(response, `Expected body text to ${describeExpected(expected, "equal")}.`, response.text, expected);
+        }
+    };
+}
+//# sourceMappingURL=httpTestResponse.expect.js.map

package/dist/httpTestClient/httpTestResponse/httpTestResponse.match.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @zudojs/testing — partial structural matching for response bodies.
+ *
+ * Plain objects match when every expected key matches (extra keys in the
+ * actual value are ignored), arrays match element-wise with equal length,
+ * and everything else is compared with the package's structural equality.
+ */
+import type { Difference } from "../../assertions/index.js";
+/**
+ * Finds the first place `actual` fails to contain `expected`.
+ *
+ * @returns The mismatch, or `undefined` when `actual` matches.
+ */
+export declare function findPartialDifference(actual: unknown, expected: unknown, path?: string): Difference | undefined;
+//# sourceMappingURL=httpTestResponse.match.d.ts.map

package/dist/httpTestClient/httpTestResponse/httpTestResponse.match.js

@@ -0,0 +1,52 @@
+/**
+ * @zudojs/testing — partial structural matching for response bodies.
+ *
+ * Plain objects match when every expected key matches (extra keys in the
+ * actual value are ignored), arrays match element-wise with equal length,
+ * and everything else is compared with the package's structural equality.
+ */
+import { isPlainObject } from "@zudojs/types";
+import { describeValue, findDifference } from "../../assertions/index.js";
+function matchArray(actual, expected, path) {
+    if (!Array.isArray(actual)) {
+        return { path, reason: `expected an array, got ${describeValue(actual)}` };
+    }
+    if (actual.length !== expected.length) {
+        return {
+            path,
+            reason: `expected ${expected.length} items, got ${actual.length}`,
+        };
+    }
+    for (let index = 0; index < expected.length; index++) {
+        const found = findPartialDifference(actual[index], expected[index], `${path}[${index}]`);
+        if (found)
+            return found;
+    }
+    return undefined;
+}
+/**
+ * Finds the first place `actual` fails to contain `expected`.
+ *
+ * @returns The mismatch, or `undefined` when `actual` matches.
+ */
+export function findPartialDifference(actual, expected, path = "body") {
+    if (Array.isArray(expected)) {
+        return matchArray(actual, expected, path);
+    }
+    if (!isPlainObject(expected)) {
+        return findDifference(actual, expected, path);
+    }
+    if (!isPlainObject(actual)) {
+        return { path, reason: `expected an object, got ${describeValue(actual)}` };
+    }
+    for (const [key, value] of Object.entries(expected)) {
+        if (!(key in actual) && value !== undefined) {
+            return { path: `${path}.${key}`, reason: "missing" };
+        }
+        const found = findPartialDifference(actual[key], value, `${path}.${key}`);
+        if (found)
+            return found;
+    }
+    return undefined;
+}
+//# sourceMappingURL=httpTestResponse.match.js.map

package/dist/httpTestClient/httpTestResponse/httpTestResponse.type.d.ts

@@ -0,0 +1,44 @@
+/**
+ * @zudojs/testing — HTTP test client response type.
+ */
+import type { TestHTTPResponse } from "../../httpTesting/index.js";
+/** What was sent, kept on the response for failure messages. */
+export interface HttpTestRequestSummary {
+    readonly method: string;
+    readonly path: string;
+}
+/**
+ * A response received by the test client.
+ *
+ * It is a `TestHTTPResponse`, so `assertResponseStatus`, `assertResponseBody`
+ * and the other response assertions accept it directly.
+ */
+export interface HttpTestResponse extends TestHTTPResponse {
+    readonly status: number;
+    readonly statusText: string;
+    /** True for 2xx statuses. */
+    readonly ok: boolean;
+    readonly headers: Headers;
+    /** Media type without parameters, e.g. `application/json`. */
+    readonly type: string | undefined;
+    /** Body decoded as UTF-8. */
+    readonly text: string;
+    /** Raw body bytes. */
+    readonly bytes: Uint8Array;
+    /**
+     * Parsed JSON for `application/json` and `+json` responses, the text for
+     * any other non-empty body, `undefined` for an empty one.
+     */
+    readonly body: unknown;
+    readonly sent: true;
+    /** Raw `Set-Cookie` values from this response. */
+    readonly setCookies: readonly string[];
+    /** Cookies this response set, as `name → value`. */
+    readonly cookies: Readonly<Record<string, string>>;
+    readonly request: HttpTestRequestSummary;
+    /** A header value, or `undefined` when absent. */
+    header(name: string): string | undefined;
+    /** Parses the body as JSON; throws a readable error when it is not JSON. */
+    json<T = unknown>(): T;
+}
+//# sourceMappingURL=httpTestResponse.type.d.ts.map