@chidchanun/bcp 0.2.13 → 0.2.15

package/packages/server/src/testing.ts

@@ -0,0 +1,1884 @@
+import {
+    randomUUID,
+} from "node:crypto";
+import {
+    isDeepStrictEqual,
+} from "node:util";
+
+import type {
+    AuthSessionStore,
+} from "./auth-session-store.js";
+import type {
+    AuthUser,
+} from "./auth.js";
+import type {
+    BackgroundJobQueue,
+    JobRecord,
+    JobState,
+} from "./jobs.js";
+import {
+    executeMiddlewarePipeline,
+    type MiddlewareExecutionInput,
+    type MiddlewareModule,
+} from "./middleware.js";
+import type {
+    OutboxDispatcher,
+    OutboxEventRecord,
+    OutboxEventState,
+    OutboxStats,
+    OutboxStore,
+} from "./events.js";
+import type {
+    RealtimeConnectOptions,
+    RealtimeConnection,
+    RealtimeEnvelope,
+    RealtimeHub,
+    RealtimeSocket,
+} from "./realtime.js";
+import {
+    createSessionToken,
+    type SessionTokenOptions,
+} from "./session.js";
+import type {
+    Workflow,
+    WorkflowRunRecord,
+    WorkflowRunState,
+} from "./workflow.js";
+import type {
+    TransactionDatabase,
+} from "../../client/src/database.js";
+
+export type TestRequestHandler = (
+    request: Request
+) => Response | Promise<Response>;
+
+export interface TestRequestOptions {
+    method?: string;
+    headers?: HeadersInit;
+    body?: BodyInit | null;
+    json?: unknown;
+    cookies?: Record<string, string>;
+    signal?: AbortSignal;
+}
+
+export interface TestAppOptions {
+    handler: TestRequestHandler;
+    baseUrl?: string;
+    headers?: HeadersInit;
+    cookies?: Record<string, string>;
+}
+
+export interface TestApp {
+    readonly baseUrl: string;
+    request(
+        path: string,
+        options?: TestRequestOptions
+    ): Promise<Response>;
+    get(
+        path: string,
+        options?: Omit<TestRequestOptions, "method">
+    ): Promise<Response>;
+    post(
+        path: string,
+        options?: Omit<TestRequestOptions, "method">
+    ): Promise<Response>;
+    put(
+        path: string,
+        options?: Omit<TestRequestOptions, "method">
+    ): Promise<Response>;
+    patch(
+        path: string,
+        options?: Omit<TestRequestOptions, "method">
+    ): Promise<Response>;
+    delete(
+        path: string,
+        options?: Omit<TestRequestOptions, "method">
+    ): Promise<Response>;
+    setCookie(name: string, value: string): void;
+    clearCookie(name: string): void;
+    cookies(): Record<string, string>;
+    setHeader(name: string, value: string): void;
+    deleteHeader(name: string): void;
+    headers(): Headers;
+    reset(): void;
+}
+
+export type TestRouteMethod =
+    | "GET"
+    | "POST"
+    | "PUT"
+    | "PATCH"
+    | "DELETE"
+    | "HEAD"
+    | "OPTIONS";
+
+export type TestRouteFunction = (
+    request: Request,
+    context?: unknown
+) => unknown | Promise<unknown>;
+
+export type TestRouteModule =
+    Partial<Record<TestRouteMethod, TestRouteFunction>>;
+
+export interface TestRouteHandlerOptions {
+    context?: (
+        request: Request
+    ) => unknown | Promise<unknown>;
+}
+
+export interface TestResponseExpectation {
+    readonly response: Response;
+    status(expected: number): TestResponseExpectation;
+    header(
+        name: string,
+        expected: string | RegExp
+    ): TestResponseExpectation;
+    text(expected: string | RegExp): Promise<TestResponseExpectation>;
+    json(expected: unknown): Promise<TestResponseExpectation>;
+    jsonMatches(
+        expected: Record<string, unknown>
+    ): Promise<TestResponseExpectation>;
+}
+
+export interface FakeClock {
+    now(): number;
+    value(): number;
+    set(value: number): number;
+    advance(milliseconds: number): number;
+    reset(): number;
+}
+
+export interface CreateTestAuthSessionOptions<TData extends object = Record<string, never>>
+extends SessionTokenOptions {
+    cookieName?: string;
+    sid?: string;
+    data?: TData;
+    store?: AuthSessionStore;
+    idFactory?: () => string;
+}
+
+export interface TestAuthSession<TUser extends AuthUser, TData extends object> {
+    sid: string;
+    user: TUser;
+    data?: TData;
+    token: string;
+    cookieName: string;
+    cookieHeader: string;
+    createdAt: number;
+    expiresAt: number;
+}
+
+export interface TestTransactionDatabase {
+    transaction<T>(
+        callback: (
+            database: TransactionDatabase
+        ) => Promise<T>
+    ): Promise<T>;
+}
+
+export interface JobTestHarness {
+    readonly queue: BackgroundJobQueue;
+    drain(options?: {
+        maxJobs?: number;
+        signal?: AbortSignal;
+    }): Promise<number>;
+    records(name?: string): Promise<JobRecord[]>;
+    count(options?: {
+        name?: string;
+        state?: JobState;
+    }): Promise<number>;
+    expectCount(
+        expected: number,
+        options?: {
+            name?: string;
+            state?: JobState;
+        }
+    ): Promise<void>;
+}
+
+export interface WorkflowTestHarness<TInput = unknown> {
+    readonly workflow: Workflow<TInput>;
+    startAndRun(
+        input: TInput,
+        options?: {
+            id?: string;
+            forceWaiting?: boolean;
+            maxPasses?: number;
+        }
+    ): Promise<WorkflowRunRecord<TInput>>;
+    runUntilIdle(
+        id: string,
+        options?: {
+            forceWaiting?: boolean;
+            maxPasses?: number;
+        }
+    ): Promise<WorkflowRunRecord<TInput>>;
+    expectState(
+        id: string,
+        expected: WorkflowRunState
+    ): Promise<WorkflowRunRecord<TInput>>;
+}
+
+export interface OutboxTestHarness {
+    readonly store: OutboxStore;
+    readonly dispatcher: OutboxDispatcher;
+    dispatchUntilIdle(
+        maxBatches?: number
+    ): Promise<number>;
+    events(type?: string): Promise<OutboxEventRecord[]>;
+    stats(): Promise<OutboxStats>;
+    expectState(
+        id: string,
+        expected: OutboxEventState
+    ): Promise<OutboxEventRecord>;
+}
+
+export interface RealtimeTestSocket
+extends RealtimeSocket {
+    readonly closed: boolean;
+    readonly closeCode: number | undefined;
+    readonly closeReason: string | undefined;
+    receive(
+        message: string | Record<string, unknown>
+    ): Promise<void>;
+    closeFromClient(
+        code?: number,
+        reason?: string
+    ): Promise<void>;
+    fail(error: unknown): Promise<void>;
+    sent(): string[];
+    messages<T = unknown>(): T[];
+    clear(): void;
+}
+
+export interface RealtimeTestConnection<TUser = unknown> {
+    socket: RealtimeTestSocket;
+    connection: RealtimeConnection<TUser>;
+}
+
+export interface RealtimeTestHarness<TUser = unknown> {
+    readonly hub: RealtimeHub<TUser>;
+    connect<TData = unknown>(
+        options?: Omit<
+            RealtimeConnectOptions<TUser, TData>,
+            "socket"
+        >
+    ): Promise<RealtimeTestConnection<TUser>>;
+    expectEvent<TPayload = unknown>(
+        socket: RealtimeTestSocket,
+        event: string,
+        channel?: string
+    ): RealtimeEnvelope<TPayload>;
+}
+
+export interface ParsedSseEvent<TData = unknown> {
+    id?: string;
+    event?: string;
+    data?: TData;
+    rawData?: string;
+}
+
+export function createTestApp(
+    options: TestAppOptions
+): TestApp {
+    if (
+        !options ||
+        typeof options.handler !== "function"
+    ) {
+        throw new TypeError(
+            "BCP Testing: createTestApp requires a request handler."
+        );
+    }
+
+    const baseUrl =
+        normalizeBaseUrl(
+            options.baseUrl ?? "http://bcp.test"
+        );
+    const initialHeaders =
+        new Headers(
+            options.headers
+        );
+    const defaultHeaders =
+        new Headers(
+            initialHeaders
+        );
+    const initialCookies = {
+        ...(options.cookies ?? {}),
+    };
+    const cookieJar =
+        new Map<string, string>(
+            Object.entries(initialCookies)
+        );
+
+    const app: TestApp = {
+        baseUrl,
+
+        async request(path, requestOptions = {}) {
+            const method =
+                normalizeMethod(
+                    requestOptions.method ?? "GET"
+                );
+            const headers =
+                new Headers(
+                    defaultHeaders
+                );
+
+            for (
+                const [name, value]
+                of new Headers(
+                    requestOptions.headers
+                )
+            ) {
+                headers.set(name, value);
+            }
+
+            const requestCookies =
+                new Map(cookieJar);
+
+            for (
+                const [name, value]
+                of Object.entries(
+                    requestOptions.cookies ?? {}
+                )
+            ) {
+                requestCookies.set(name, value);
+            }
+
+            if (requestCookies.size > 0) {
+                headers.set(
+                    "Cookie",
+                    serializeCookies(
+                        requestCookies
+                    )
+                );
+            }
+
+            let body =
+                requestOptions.body ?? null;
+
+            if (
+                requestOptions.json !== undefined
+            ) {
+                if (
+                    requestOptions.body !== undefined &&
+                    requestOptions.body !== null
+                ) {
+                    throw new TypeError(
+                        "BCP Testing: request cannot specify both body and json."
+                    );
+                }
+                body =
+                    JSON.stringify(
+                        requestOptions.json
+                    );
+                if (!headers.has("Content-Type")) {
+                    headers.set(
+                        "Content-Type",
+                        "application/json"
+                    );
+                }
+            }
+
+            if (
+                method === "GET" ||
+                method === "HEAD"
+            ) {
+                body = null;
+            }
+
+            const request =
+                new Request(
+                    resolveTestUrl(
+                        baseUrl,
+                        path
+                    ),
+                    {
+                        method,
+                        headers,
+                        body,
+                        signal:
+                            requestOptions.signal,
+                    }
+                );
+            const response =
+                await options.handler(
+                    request
+                );
+
+            if (!(response instanceof Response)) {
+                throw new TypeError(
+                    "BCP Testing: request handler must return a Response."
+                );
+            }
+
+            updateCookieJar(
+                cookieJar,
+                response.headers
+            );
+
+            return response;
+        },
+
+        get(path, requestOptions = {}) {
+            return app.request(
+                path,
+                {
+                    ...requestOptions,
+                    method: "GET",
+                }
+            );
+        },
+
+        post(path, requestOptions = {}) {
+            return app.request(
+                path,
+                {
+                    ...requestOptions,
+                    method: "POST",
+                }
+            );
+        },
+
+        put(path, requestOptions = {}) {
+            return app.request(
+                path,
+                {
+                    ...requestOptions,
+                    method: "PUT",
+                }
+            );
+        },
+
+        patch(path, requestOptions = {}) {
+            return app.request(
+                path,
+                {
+                    ...requestOptions,
+                    method: "PATCH",
+                }
+            );
+        },
+
+        delete(path, requestOptions = {}) {
+            return app.request(
+                path,
+                {
+                    ...requestOptions,
+                    method: "DELETE",
+                }
+            );
+        },
+
+        setCookie(name, value) {
+            cookieJar.set(
+                normalizeCookieName(name),
+                String(value)
+            );
+        },
+
+        clearCookie(name) {
+            cookieJar.delete(
+                normalizeCookieName(name)
+            );
+        },
+
+        cookies() {
+            return Object.fromEntries(
+                cookieJar
+            );
+        },
+
+        setHeader(name, value) {
+            defaultHeaders.set(
+                normalizeHeaderName(name),
+                String(value)
+            );
+        },
+
+        deleteHeader(name) {
+            defaultHeaders.delete(
+                normalizeHeaderName(name)
+            );
+        },
+
+        headers() {
+            return new Headers(
+                defaultHeaders
+            );
+        },
+
+        reset() {
+            cookieJar.clear();
+            for (
+                const [name, value]
+                of Object.entries(
+                    initialCookies
+                )
+            ) {
+                cookieJar.set(name, value);
+            }
+            for (const name of [...defaultHeaders.keys()]) {
+                defaultHeaders.delete(name);
+            }
+            for (const [name, value] of initialHeaders) {
+                defaultHeaders.set(name, value);
+            }
+        },
+    };
+
+    return app;
+}
+
+export function createRouteTestHandler(
+    routeModule: TestRouteModule,
+    options: TestRouteHandlerOptions = {}
+): TestRequestHandler {
+    if (!routeModule || typeof routeModule !== "object") {
+        throw new TypeError(
+            "BCP Testing: route module must be an object."
+        );
+    }
+
+    return async request => {
+        const method =
+            normalizeMethod(
+                request.method
+            ) as TestRouteMethod;
+        const handler =
+            routeModule[method] ??
+            (
+                method === "HEAD"
+                    ? routeModule.GET
+                    : undefined
+            );
+
+        if (!handler) {
+            const allow =
+                knownRouteMethods
+                    .filter(candidate =>
+                        typeof routeModule[candidate] ===
+                        "function"
+                    )
+                    .join(", ");
+            return new Response(
+                null,
+                {
+                    status: 405,
+                    headers:
+                        allow
+                            ? {
+                                Allow: allow,
+                            }
+                            : undefined,
+                }
+            );
+        }
+
+        const context =
+            options.context
+                ? await options.context(
+                    request
+                )
+                : undefined;
+        const value =
+            await handler(
+                request,
+                context
+            );
+
+        return normalizeRouteResponse(
+            value,
+            method
+        );
+    };
+}
+
+export function expectResponse(
+    response: Response
+): TestResponseExpectation {
+    if (!(response instanceof Response)) {
+        throw new TypeError(
+            "BCP Testing: expectResponse requires a Response."
+        );
+    }
+
+    const expectation:
+        TestResponseExpectation = {
+        response,
+
+        status(expected) {
+            if (response.status !== expected) {
+                throw new Error(
+                    `BCP Testing: expected response status ${expected}, received ${response.status}.`
+                );
+            }
+            return expectation;
+        },
+
+        header(name, expected) {
+            const actual =
+                response.headers.get(name);
+            if (
+                typeof expected === "string"
+                    ? actual !== expected
+                    : !expected.test(
+                        actual ?? ""
+                    )
+            ) {
+                throw new Error(
+                    `BCP Testing: response header "${name}" did not match. Received ${JSON.stringify(actual)}.`
+                );
+            }
+            return expectation;
+        },
+
+        async text(expected) {
+            const actual =
+                await response.clone().text();
+            if (
+                typeof expected === "string"
+                    ? actual !== expected
+                    : !expected.test(actual)
+            ) {
+                throw new Error(
+                    `BCP Testing: response text did not match. Received ${JSON.stringify(actual)}.`
+                );
+            }
+            return expectation;
+        },
+
+        async json(expected) {
+            const actual =
+                await response.clone().json();
+            if (!isDeepStrictEqual(actual, expected)) {
+                throw new Error(
+                    `BCP Testing: response JSON did not match. Expected ${safeJson(expected)}, received ${safeJson(actual)}.`
+                );
+            }
+            return expectation;
+        },
+
+        async jsonMatches(expected) {
+            const actual =
+                await response.clone().json();
+            if (
+                !actual ||
+                typeof actual !== "object" ||
+                Array.isArray(actual)
+            ) {
+                throw new Error(
+                    "BCP Testing: response JSON is not an object."
+                );
+            }
+            for (
+                const [key, value]
+                of Object.entries(expected)
+            ) {
+                if (
+                    !isDeepStrictEqual(
+                        (actual as Record<string, unknown>)[key],
+                        value
+                    )
+                ) {
+                    throw new Error(
+                        `BCP Testing: response JSON key "${key}" did not match.`
+                    );
+                }
+            }
+            return expectation;
+        },
+    };
+
+    return expectation;
+}
+
+export function createFakeClock(
+    initialValue = 0
+): FakeClock {
+    assertFinite(
+        initialValue,
+        "fake clock initial value"
+    );
+    let current =
+        initialValue;
+
+    return {
+        now() {
+            return current;
+        },
+        value() {
+            return current;
+        },
+        set(value) {
+            assertFinite(
+                value,
+                "fake clock value"
+            );
+            current = value;
+            return current;
+        },
+        advance(milliseconds) {
+            assertFinite(
+                milliseconds,
+                "fake clock advance"
+            );
+            current += milliseconds;
+            return current;
+        },
+        reset() {
+            current = initialValue;
+            return current;
+        },
+    };
+}
+
+export function createSequenceIdFactory(
+    prefix = "test",
+    start = 1
+): () => string {
+    const normalizedPrefix =
+        String(prefix).trim();
+    if (!normalizedPrefix) {
+        throw new TypeError(
+            "BCP Testing: id prefix must be a non-empty string."
+        );
+    }
+    if (!Number.isInteger(start) || start < 0) {
+        throw new TypeError(
+            "BCP Testing: id sequence start must be a non-negative integer."
+        );
+    }
+    let sequence = start;
+
+    return () =>
+        `${normalizedPrefix}-${sequence++}`;
+}
+
+export async function createTestAuthSession<
+    TUser extends AuthUser,
+    TData extends object = Record<string, never>
+>(
+    user: TUser,
+    options:
+        CreateTestAuthSessionOptions<TData> = {}
+): Promise<TestAuthSession<TUser, TData>> {
+    if (
+        !user ||
+        (
+            typeof user.id !== "string" &&
+            typeof user.id !== "number"
+        )
+    ) {
+        throw new TypeError(
+            "BCP Testing: auth user requires a string or number id."
+        );
+    }
+
+    const idFactory =
+        options.idFactory ?? randomUUID;
+    const sid =
+        normalizeNonEmpty(
+            options.sid ?? idFactory(),
+            "session id"
+        );
+    const cookieName =
+        normalizeCookieName(
+            options.cookieName ?? "bcp_session"
+        );
+    const expiresIn =
+        positiveInteger(
+            options.expiresIn ?? 60 * 60 * 12,
+            "session expiresIn"
+        );
+    const createdAt =
+        Math.floor(
+            Date.now() / 1000
+        );
+    const expiresAt =
+        createdAt + expiresIn;
+    const payload = {
+        sid,
+        user,
+        ...(options.data === undefined
+            ? {}
+            : {
+                data: options.data,
+            }),
+    };
+    const token =
+        await createSessionToken(
+            payload,
+            {
+                secret:
+                    options.secret,
+                expiresIn,
+                issuer:
+                    options.issuer,
+                audience:
+                    options.audience,
+            }
+        );
+
+    if (options.store) {
+        await options.store.set({
+            sid,
+            userId:
+                String(user.id),
+            createdAt,
+            expiresAt,
+            lastSeenAt:
+                createdAt,
+        });
+    }
+
+    return {
+        sid,
+        user,
+        ...(options.data === undefined
+            ? {}
+            : {
+                data: options.data,
+            }),
+        token,
+        cookieName,
+        cookieHeader:
+            `${cookieName}=${token}`,
+        createdAt,
+        expiresAt,
+    };
+}
+
+export async function withTestTransaction<T>(
+    database: TestTransactionDatabase,
+    callback: (
+        transaction: TransactionDatabase
+    ) => Promise<T>
+): Promise<T> {
+    if (
+        !database ||
+        typeof database.transaction !== "function"
+    ) {
+        throw new TypeError(
+            "BCP Testing: withTestTransaction requires a transactional database."
+        );
+    }
+    if (typeof callback !== "function") {
+        throw new TypeError(
+            "BCP Testing: transaction callback must be a function."
+        );
+    }
+
+    const marker =
+        Symbol("bcp-test-rollback");
+    let completed = false;
+    let value:
+        T | undefined;
+
+    try {
+        await database.transaction(
+            async transaction => {
+                value =
+                    await callback(
+                        transaction
+                    );
+                completed = true;
+                throw new TestRollbackSignal(
+                    marker
+                );
+            }
+        );
+    } catch (error) {
+        if (
+            !(error instanceof TestRollbackSignal) ||
+            error.marker !== marker
+        ) {
+            throw error;
+        }
+    }
+
+    if (!completed) {
+        throw new Error(
+            "BCP Testing: rollback transaction did not complete the test callback."
+        );
+    }
+
+    return value as T;
+}
+
+export async function runTestMiddleware(
+    module: MiddlewareModule | null | undefined,
+    input: MiddlewareExecutionInput,
+    downstream?: (
+        request: Request
+    ) => Response | Promise<Response>
+): Promise<Response> {
+    return executeMiddlewarePipeline(
+        module,
+        input,
+        async execution => {
+            const request =
+                new Request(
+                    execution.url,
+                    {
+                        method:
+                            execution.method ?? "GET",
+                        headers:
+                            execution.headers,
+                    }
+                );
+            return downstream
+                ? downstream(request)
+                : new Response(
+                    null,
+                    {
+                        status: 204,
+                    }
+                );
+        }
+    );
+}
+
+export function createJobTestHarness(
+    queue: BackgroundJobQueue
+): JobTestHarness {
+    if (!queue) {
+        throw new TypeError(
+            "BCP Testing: job harness requires a queue."
+        );
+    }
+
+    const harness: JobTestHarness = {
+        queue,
+
+        async drain(options = {}) {
+            const maxJobs =
+                positiveInteger(
+                    options.maxJobs ?? 1_000,
+                    "maxJobs"
+                );
+            let processed = 0;
+
+            while (
+                processed < maxJobs &&
+                !options.signal?.aborted
+            ) {
+                const didProcess =
+                    await queue.processNext(
+                        options.signal
+                    );
+                if (!didProcess) {
+                    break;
+                }
+                processed += 1;
+            }
+
+            return processed;
+        },
+
+        async records(name) {
+            const records =
+                await queue.list();
+            return name
+                ? records.filter(
+                    record =>
+                        record.name === name
+                )
+                : records;
+        },
+
+        async count(options = {}) {
+            const records =
+                await harness.records(
+                    options.name
+                );
+            return records.filter(
+                record =>
+                    !options.state ||
+                    record.state === options.state
+            ).length;
+        },
+
+        async expectCount(
+            expected,
+            options = {}
+        ) {
+            const actual =
+                await harness.count(options);
+            if (actual !== expected) {
+                throw new Error(
+                    `BCP Testing: expected ${expected} jobs, received ${actual}.`
+                );
+            }
+        },
+    };
+
+    return harness;
+}
+
+export function createWorkflowTestHarness<TInput>(
+    workflow: Workflow<TInput>
+): WorkflowTestHarness<TInput> {
+    if (!workflow) {
+        throw new TypeError(
+            "BCP Testing: workflow harness requires a workflow."
+        );
+    }
+
+    const harness:
+        WorkflowTestHarness<TInput> = {
+        workflow,
+
+        async startAndRun(
+            input,
+            options = {}
+        ) {
+            const run =
+                await workflow.start(
+                    input,
+                    {
+                        id: options.id,
+                    }
+                );
+            return harness.runUntilIdle(
+                run.id,
+                options
+            );
+        },
+
+        async runUntilIdle(
+            id,
+            options = {}
+        ) {
+            const maxPasses =
+                positiveInteger(
+                    options.maxPasses ?? 100,
+                    "workflow maxPasses"
+                );
+            let run =
+                await requireWorkflowRun(
+                    workflow,
+                    id
+                );
+
+            for (
+                let pass = 0;
+                pass < maxPasses;
+                pass += 1
+            ) {
+                if (isWorkflowTerminal(run.state)) {
+                    return run;
+                }
+
+                if (run.state === "waiting") {
+                    if (!options.forceWaiting) {
+                        return run;
+                    }
+                    run =
+                        await workflow.resume(
+                            id,
+                            {
+                                force: true,
+                            }
+                        );
+                    continue;
+                }
+
+                run =
+                    await workflow.run(id);
+            }
+
+            throw new Error(
+                `BCP Testing: workflow "${id}" did not become idle within ${maxPasses} passes.`
+            );
+        },
+
+        async expectState(
+            id,
+            expected
+        ) {
+            const run =
+                await requireWorkflowRun(
+                    workflow,
+                    id
+                );
+            if (run.state !== expected) {
+                throw new Error(
+                    `BCP Testing: expected workflow "${id}" state ${expected}, received ${run.state}.`
+                );
+            }
+            return run;
+        },
+    };
+
+    return harness;
+}
+
+export function createOutboxTestHarness(
+    store: OutboxStore,
+    dispatcher: OutboxDispatcher
+): OutboxTestHarness {
+    if (!store || !dispatcher) {
+        throw new TypeError(
+            "BCP Testing: outbox harness requires a store and dispatcher."
+        );
+    }
+
+    return {
+        store,
+        dispatcher,
+
+        async dispatchUntilIdle(
+            maxBatches = 100
+        ) {
+            const limit =
+                positiveInteger(
+                    maxBatches,
+                    "outbox maxBatches"
+                );
+            let published = 0;
+
+            for (
+                let batch = 0;
+                batch < limit;
+                batch += 1
+            ) {
+                const count =
+                    await dispatcher.dispatchBatch();
+                published += count;
+                if (count === 0) {
+                    return published;
+                }
+            }
+
+            return published;
+        },
+
+        async events(type) {
+            const events =
+                await store.list();
+            return type
+                ? events.filter(
+                    event =>
+                        event.type === type
+                )
+                : events;
+        },
+
+        stats() {
+            return store.stats();
+        },
+
+        async expectState(
+            id,
+            expected
+        ) {
+            const event =
+                await store.get(id);
+            if (!event) {
+                throw new Error(
+                    `BCP Testing: outbox event "${id}" does not exist.`
+                );
+            }
+            if (event.state !== expected) {
+                throw new Error(
+                    `BCP Testing: expected outbox event "${id}" state ${expected}, received ${event.state}.`
+                );
+            }
+            return event;
+        },
+    };
+}
+
+export function createRealtimeTestSocket():
+RealtimeTestSocket {
+    const sentMessages:
+        string[] = [];
+    const messageListeners =
+        new Set<(
+            data: string
+        ) => void | Promise<void>>();
+    const closeListeners =
+        new Set<() => void | Promise<void>>();
+    const errorListeners =
+        new Set<(
+            error: unknown
+        ) => void | Promise<void>>();
+    let closed = false;
+    let closeCode:
+        number | undefined;
+    let closeReason:
+        string | undefined;
+
+    const socket:
+        RealtimeTestSocket = {
+        get closed() {
+            return closed;
+        },
+        get closeCode() {
+            return closeCode;
+        },
+        get closeReason() {
+            return closeReason;
+        },
+
+        send(data) {
+            if (closed) {
+                throw new Error(
+                    "BCP Testing: realtime test socket is closed."
+                );
+            }
+            sentMessages.push(
+                String(data)
+            );
+        },
+
+        async close(
+            code = 1000,
+            reason = "server closed"
+        ) {
+            if (closed) {
+                return;
+            }
+            closed = true;
+            closeCode = code;
+            closeReason = reason;
+            await notify(
+                closeListeners,
+                listener => listener()
+            );
+        },
+
+        onMessage(listener) {
+            messageListeners.add(listener);
+            return () => {
+                messageListeners.delete(listener);
+            };
+        },
+
+        onClose(listener) {
+            closeListeners.add(listener);
+            return () => {
+                closeListeners.delete(listener);
+            };
+        },
+
+        onError(listener) {
+            errorListeners.add(listener);
+            return () => {
+                errorListeners.delete(listener);
+            };
+        },
+
+        async receive(message) {
+            if (closed) {
+                throw new Error(
+                    "BCP Testing: cannot receive on a closed realtime test socket."
+                );
+            }
+            const raw =
+                typeof message === "string"
+                    ? message
+                    : JSON.stringify(message);
+            await notify(
+                messageListeners,
+                listener =>
+                    listener(raw)
+            );
+        },
+
+        async closeFromClient(
+            code = 1000,
+            reason = "client closed"
+        ) {
+            if (closed) {
+                return;
+            }
+            closed = true;
+            closeCode = code;
+            closeReason = reason;
+            await notify(
+                closeListeners,
+                listener => listener()
+            );
+        },
+
+        async fail(error) {
+            await notify(
+                errorListeners,
+                listener =>
+                    listener(error)
+            );
+        },
+
+        sent() {
+            return [
+                ...sentMessages,
+            ];
+        },
+
+        messages<T = unknown>() {
+            return sentMessages.map(
+                message =>
+                    JSON.parse(message) as T
+            );
+        },
+
+        clear() {
+            sentMessages.length = 0;
+        },
+    };
+
+    return socket;
+}
+
+export function createRealtimeTestHarness<TUser = unknown>(
+    hub: RealtimeHub<TUser>
+): RealtimeTestHarness<TUser> {
+    if (!hub) {
+        throw new TypeError(
+            "BCP Testing: realtime harness requires a hub."
+        );
+    }
+
+    const harness:
+        RealtimeTestHarness<TUser> = {
+        hub,
+
+        async connect<TData = unknown>(
+            options: Omit<
+                RealtimeConnectOptions<TUser, TData>,
+                "socket"
+            > = {}
+        ): Promise<RealtimeTestConnection<TUser>> {
+            const socket =
+                createRealtimeTestSocket();
+            const connection =
+                await hub.attachSocket(
+                    socket,
+                    options
+                );
+            return {
+                socket,
+                connection,
+            };
+        },
+
+        expectEvent<TPayload = unknown>(
+            socket: RealtimeTestSocket,
+            event: string,
+            channel?: string
+        ): RealtimeEnvelope<TPayload> {
+            const normalizedEvent =
+                normalizeNonEmpty(
+                    event,
+                    "realtime event"
+                );
+            const messages =
+                socket.messages<
+                    {
+                        type?: string;
+                        id?: string;
+                        channel?: string;
+                        event?: string;
+                        payload?: unknown;
+                        timestamp?: number;
+                        sourceId?: string;
+                        excludeConnectionId?: string;
+                    }
+                >();
+            const found =
+                [...messages]
+                    .reverse()
+                    .find(message =>
+                        message.type === "event" &&
+                        message.event === normalizedEvent &&
+                        (
+                            channel === undefined ||
+                            message.channel === channel
+                        )
+                    );
+
+            if (
+                !found ||
+                !found.id ||
+                !found.channel ||
+                found.timestamp === undefined
+            ) {
+                throw new Error(
+                    `BCP Testing: realtime event "${normalizedEvent}" was not sent.`
+                );
+            }
+
+            return {
+                id: found.id,
+                channel: found.channel,
+                event: normalizedEvent,
+                payload:
+                    found.payload as TPayload,
+                timestamp: found.timestamp,
+                sourceId: found.sourceId,
+                excludeConnectionId:
+                    found.excludeConnectionId,
+            };
+        },
+    };
+
+    return harness;
+}
+
+export async function readSseEvents<TData = unknown>(
+    response: Response,
+    options: {
+        limit?: number;
+        timeoutMs?: number;
+    } = {}
+): Promise<ParsedSseEvent<TData>[]> {
+    if (!(response instanceof Response)) {
+        throw new TypeError(
+            "BCP Testing: readSseEvents requires a Response."
+        );
+    }
+    if (!response.body) {
+        return [];
+    }
+
+    const limit =
+        positiveInteger(
+            options.limit ?? 1,
+            "SSE event limit"
+        );
+    const timeoutMs =
+        positiveInteger(
+            options.timeoutMs ?? 1_000,
+            "SSE timeoutMs"
+        );
+    const reader =
+        response.body.getReader();
+    const decoder =
+        new TextDecoder();
+    const events:
+        ParsedSseEvent<TData>[] = [];
+    let buffer = "";
+
+    try {
+        while (events.length < limit) {
+            const result =
+                await readWithTimeout(
+                    reader,
+                    timeoutMs
+                );
+            if (result.done) {
+                break;
+            }
+            buffer +=
+                decoder.decode(
+                    result.value,
+                    {
+                        stream: true,
+                    }
+                );
+
+            let boundary =
+                buffer.indexOf("\n\n");
+            while (boundary >= 0) {
+                const frame =
+                    buffer.slice(
+                        0,
+                        boundary
+                    );
+                buffer =
+                    buffer.slice(
+                        boundary + 2
+                    );
+                const event =
+                    parseSseFrame<TData>(
+                        frame
+                    );
+                if (event) {
+                    events.push(event);
+                    if (events.length >= limit) {
+                        break;
+                    }
+                }
+                boundary =
+                    buffer.indexOf("\n\n");
+            }
+        }
+    } finally {
+        await reader.cancel().catch(
+            () => undefined
+        );
+    }
+
+    return events;
+}
+
+class TestRollbackSignal
+extends Error {
+    constructor(
+        readonly marker: symbol
+    ) {
+        super("BCP Testing rollback");
+        this.name =
+            "BcpTestRollbackSignal";
+    }
+}
+
+const knownRouteMethods:
+    TestRouteMethod[] = [
+    "GET",
+    "POST",
+    "PUT",
+    "PATCH",
+    "DELETE",
+    "HEAD",
+    "OPTIONS",
+];
+
+function normalizeRouteResponse(
+    value: unknown,
+    method: TestRouteMethod
+): Response {
+    if (value instanceof Response) {
+        if (method !== "HEAD") {
+            return value;
+        }
+        return new Response(
+            null,
+            {
+                status: value.status,
+                statusText:
+                    value.statusText,
+                headers:
+                    value.headers,
+            }
+        );
+    }
+    if (value === undefined || value === null) {
+        return new Response(
+            null,
+            {
+                status: 204,
+            }
+        );
+    }
+    if (typeof value === "string") {
+        return new Response(value);
+    }
+    return Response.json(value);
+}
+
+async function requireWorkflowRun<TInput>(
+    workflow: Workflow<TInput>,
+    id: string
+): Promise<WorkflowRunRecord<TInput>> {
+    const run =
+        await workflow.get(id);
+    if (!run) {
+        throw new Error(
+            `BCP Testing: workflow run "${id}" does not exist.`
+        );
+    }
+    return run;
+}
+
+function isWorkflowTerminal(
+    state: WorkflowRunState
+): boolean {
+    return state === "succeeded" ||
+        state === "failed" ||
+        state === "cancelled" ||
+        state === "compensated";
+}
+
+async function notify<T>(
+    listeners: Set<T>,
+    invoke: (
+        listener: T
+    ) => void | Promise<void>
+): Promise<void> {
+    for (const listener of [
+        ...listeners,
+    ]) {
+        await invoke(listener);
+    }
+}
+
+function parseSseFrame<TData>(
+    frame: string
+): ParsedSseEvent<TData> | null {
+    const lines =
+        frame.split(/\r?\n/);
+    let id:
+        string | undefined;
+    let event:
+        string | undefined;
+    const data:
+        string[] = [];
+
+    for (const line of lines) {
+        if (
+            !line ||
+            line.startsWith(":") ||
+            line.startsWith("retry:")
+        ) {
+            continue;
+        }
+        if (line.startsWith("id:")) {
+            id =
+                line.slice(3).trimStart();
+            continue;
+        }
+        if (line.startsWith("event:")) {
+            event =
+                line.slice(6).trimStart();
+            continue;
+        }
+        if (line.startsWith("data:")) {
+            data.push(
+                line.slice(5).trimStart()
+            );
+        }
+    }
+
+    if (
+        id === undefined &&
+        event === undefined &&
+        data.length === 0
+    ) {
+        return null;
+    }
+
+    const rawData =
+        data.join("\n");
+    let parsed:
+        TData | undefined;
+    if (rawData) {
+        try {
+            parsed =
+                JSON.parse(rawData) as TData;
+        } catch {
+            parsed =
+                rawData as unknown as TData;
+        }
+    }
+
+    return {
+        id,
+        event,
+        data: parsed,
+        rawData:
+            rawData || undefined,
+    };
+}
+
+function readWithTimeout(
+    reader:
+        ReadableStreamDefaultReader<Uint8Array>,
+    timeoutMs: number
+): Promise<ReadableStreamReadResult<Uint8Array>> {
+    return new Promise(
+        (resolve, reject) => {
+            const timer =
+                setTimeout(
+                    () => {
+                        reject(
+                            new Error(
+                                `BCP Testing: timed out waiting for SSE data after ${timeoutMs}ms.`
+                            )
+                        );
+                    },
+                    timeoutMs
+                );
+            reader.read().then(
+                value => {
+                    clearTimeout(timer);
+                    resolve(value);
+                },
+                error => {
+                    clearTimeout(timer);
+                    reject(error);
+                }
+            );
+        }
+    );
+}
+
+function updateCookieJar(
+    jar: Map<string, string>,
+    headers: Headers
+): void {
+    const extended =
+        headers as Headers & {
+            getSetCookie?: () => string[];
+        };
+    const values =
+        typeof extended.getSetCookie === "function"
+            ? extended.getSetCookie()
+            : (
+                headers.get("set-cookie")
+                    ? [
+                        headers.get("set-cookie") as string,
+                    ]
+                    : []
+            );
+
+    for (const value of values) {
+        const first =
+            value.split(";", 1)[0] ?? "";
+        const separator =
+            first.indexOf("=");
+        if (separator <= 0) {
+            continue;
+        }
+        const name =
+            first.slice(0, separator).trim();
+        const cookieValue =
+            first.slice(separator + 1).trim();
+        const lower =
+            value.toLowerCase();
+        if (
+            cookieValue === "" ||
+            lower.includes("max-age=0") ||
+            lower.includes("expires=thu, 01 jan 1970")
+        ) {
+            jar.delete(name);
+        } else {
+            jar.set(name, cookieValue);
+        }
+    }
+}
+
+function serializeCookies(
+    cookies: Map<string, string>
+): string {
+    return Array.from(
+        cookies,
+        ([name, value]) =>
+            `${name}=${value}`
+    ).join("; ");
+}
+
+function normalizeMethod(
+    value: string
+): string {
+    const method =
+        String(value).trim().toUpperCase();
+    if (!method) {
+        throw new TypeError(
+            "BCP Testing: request method must be a non-empty string."
+        );
+    }
+    return method;
+}
+
+function normalizeBaseUrl(
+    value: string
+): string {
+    let url:
+        URL;
+    try {
+        url = new URL(value);
+    } catch {
+        throw new TypeError(
+            "BCP Testing: baseUrl must be an absolute URL."
+        );
+    }
+    return url.href.endsWith("/")
+        ? url.href
+        : `${url.href}/`;
+}
+
+function resolveTestUrl(
+    baseUrl: string,
+    path: string
+): string {
+    const value =
+        String(path ?? "").trim();
+    if (!value) {
+        return baseUrl;
+    }
+    try {
+        return new URL(value).href;
+    } catch {
+        return new URL(
+            value.replace(/^\//, ""),
+            baseUrl
+        ).href;
+    }
+}
+
+function normalizeCookieName(
+    value: string
+): string {
+    const name =
+        normalizeNonEmpty(
+            value,
+            "cookie name"
+        );
+    if (!/^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/.test(name)) {
+        throw new TypeError(
+            "BCP Testing: cookie name contains invalid characters."
+        );
+    }
+    return name;
+}
+
+function normalizeHeaderName(
+    value: string
+): string {
+    return normalizeNonEmpty(
+        value,
+        "header name"
+    );
+}
+
+function normalizeNonEmpty(
+    value: unknown,
+    field: string
+): string {
+    const text =
+        String(value ?? "").trim();
+    if (!text) {
+        throw new TypeError(
+            `BCP Testing: ${field} must be a non-empty string.`
+        );
+    }
+    return text;
+}
+
+function positiveInteger(
+    value: number,
+    field: string
+): number {
+    if (
+        !Number.isInteger(value) ||
+        value <= 0
+    ) {
+        throw new TypeError(
+            `BCP Testing: ${field} must be a positive integer.`
+        );
+    }
+    return value;
+}
+
+function assertFinite(
+    value: number,
+    field: string
+): void {
+    if (!Number.isFinite(value)) {
+        throw new TypeError(
+            `BCP Testing: ${field} must be finite.`
+        );
+    }
+}
+
+function safeJson(
+    value: unknown
+): string {
+    try {
+        return JSON.stringify(value);
+    } catch {
+        return String(value);
+    }
+}