@neontechspace/fluxerly 1000.0.0-nightly.12

package/src/internal/testing/http.ts

@@ -0,0 +1,395 @@
+/**
+ * In-memory HTTP transport for test clients: Instance discovery, registered REST responses and the request record.
+ * Invariant: No request leaves the process. The hosted discovery bootstrap is answered directly, every other request is
+ * recorded without its Authorization header or webhook token and answered by the newest matching registration. An
+ * unmatched message send or edit receives an echoed bot message, and any other unmatched request receives a
+ * Fluxer-shaped 404 together with a Warn record. Cancellation settles a pending handler's request at once with the
+ * signal's reason.
+ * Implements [SDK contracts: Delivery, requests and caches](/docs/SDK-CONTRACTS.md#delivery-requests-and-caches)
+ */
+import { ClientClosedError, ConfigurationError } from "#sdk/errors"
+import type { LogRecord } from "#sdk/logging"
+import { hostedDiscoveryDocument, hostedDiscoveryUrl } from "./discovery.js"
+import { fixtureTimestamp, type Fixtures, type WireMessage, type WireUser } from "./fixtures.js"
+import type {
+    TestRequest,
+    TestRequestFile,
+    TestRequestMatcher,
+    TestResponder,
+    TestResponse,
+    TestRest,
+    TestRoute,
+    TestWaitOptions,
+} from "./types.js"
+import { timedWait, waitTimeout } from "./wait.js"
+
+interface Route {
+    readonly matches: (request: TestRequest) => boolean
+    readonly response: TestResponse | TestResponder
+    readonly answered: TestRequest[]
+    /** How many answered requests next already returned */
+    taken: number
+    /** Pending next calls, oldest first */
+    readonly waiters: Set<(request: TestRequest) => void>
+    active: boolean
+}
+
+/** A registered route with the abort signal the native entry point passes to next for interruption */
+export interface InternalTestRoute extends TestRoute {
+    next(options?: TestWaitOptions, signal?: AbortSignal): Promise<TestRequest>
+}
+
+const apiBase = `${hostedDiscoveryDocument.endpoints.api_public}/v1`
+/** Hosted discovery with presigned uploads off, so an attachment upload arrives as one recorded multipart request */
+const testDiscoveryDocument = Object.freeze({
+    ...hostedDiscoveryDocument,
+    features: Object.freeze({ presigned_attachment_uploads: false }),
+})
+const nullBodyStatuses = new Set([204, 205, 304])
+
+function redactWebhookToken(text: string): string {
+    return text.replace(/(\/webhooks\/\d+\/)[^/?#]+/g, "$1[redacted]")
+}
+
+/** The fixtures and bot account that automatic message replies are built from */
+export interface TestReplies {
+    readonly fixtures: Fixtures
+    readonly author: WireUser
+}
+
+const isMessageSend = (request: Pick<TestRequest, "method" | "path">) =>
+    request.method === "POST" && pathPattern("/channels/:channel/messages")(request.path)
+const isMessageEdit = (request: Pick<TestRequest, "method" | "path">) =>
+    request.method === "PATCH" && pathPattern("/channels/:channel/messages/:message")(request.path)
+
+/** Turn a request embed into the response shape, which adds the rich type, media flags and field inline defaults */
+function echoedEmbed(embed: unknown): unknown {
+    if (typeof embed !== "object" || embed === null) return embed
+    const object = (value: unknown, defaults: object) =>
+        typeof value === "object" && value !== null ? { ...defaults, ...value } : value
+    const { image, thumbnail, fields, ...rest } = embed as Record<string, unknown>
+    return {
+        type: "rich",
+        ...rest,
+        ...(image === undefined ? {} : { image: object(image, { flags: 0 }) }),
+        ...(thumbnail === undefined ? {} : { thumbnail: object(thumbnail, { flags: 0 }) }),
+        ...(Array.isArray(fields) ? { fields: fields.map((field) => object(field, { inline: false })) } : {}),
+    }
+}
+
+/** Build the message a send or edit request describes, echoing the fields a bot usually sets */
+function echoedMessage(replies: TestReplies, request: TestRequest, edit: boolean): WireMessage {
+    const [, , channelId, , messageId] = request.path.split("/")
+    const body =
+        typeof request.body === "object" && request.body !== null ? (request.body as Record<string, unknown>) : {}
+    const { guild_id: _, ...message } = replies.fixtures.message({
+        id: edit ? messageId! : replies.fixtures.nextId(),
+        channel_id: channelId!,
+        author: replies.author,
+        content: typeof body.content === "string" ? body.content : "",
+        embeds: Array.isArray(body.embeds) ? body.embeds.map(echoedEmbed) : [],
+        flags: typeof body.flags === "number" ? body.flags : 0,
+        tts: body.tts === true,
+        edited_timestamp: edit ? fixtureTimestamp : null,
+    })
+    return Object.freeze(message)
+}
+
+/** Compile a string path pattern, where :name matches one segment */
+function pathPattern(pattern: string): (path: string) => boolean {
+    if (/^https?:\/\//.test(pattern)) return (path) => path === pattern
+    if (!pattern.startsWith("/"))
+        throw new ConfigurationError("configuration", "Test request paths must start with / or be absolute http URLs")
+    const expected = pattern.split("/")
+    return (path) => {
+        const actual = path.split("/")
+        return (
+            actual.length === expected.length &&
+            expected.every((segment, index) =>
+                segment.startsWith(":") && segment.length > 1 ? actual[index] !== "" : segment === actual[index],
+            )
+        )
+    }
+}
+
+function methodPattern(method: unknown): ((request: TestRequest) => boolean) | undefined {
+    if (method === undefined) return undefined
+    if (typeof method !== "string" || !/^[A-Za-z]+$/.test(method))
+        throw new ConfigurationError("configuration", "Test request methods must be HTTP method names such as GET")
+    const expected = method.toUpperCase()
+    return (request) => request.method === expected
+}
+
+function compileMatcher(matcher: TestRequestMatcher): (request: TestRequest) => boolean {
+    if (typeof matcher === "function") return (request) => matcher(request) === true
+    if (matcher instanceof RegExp) return (request) => new RegExp(matcher.source, matcher.flags).test(request.path)
+    let method: unknown
+    let path: unknown
+    if (typeof matcher === "string") {
+        const parts = matcher.trim().split(/\s+/)
+        if (parts.length > 2 || parts[0] === "")
+            throw new ConfigurationError("configuration", 'Test request matchers must read "METHOD /path" or "/path"')
+        ;[method, path] = parts.length === 2 ? parts : [undefined, parts[0]]
+    } else if (typeof matcher === "object" && matcher !== null) {
+        method = matcher.method
+        path = matcher.path
+    } else
+        throw new ConfigurationError(
+            "configuration",
+            "Test request matchers must be a string, RegExp, { method, path } object or function",
+        )
+    const methodMatches = methodPattern(method)
+    const pathMatches =
+        path instanceof RegExp
+            ? (value: string) => new RegExp(path.source, path.flags).test(value)
+            : typeof path === "string"
+              ? pathPattern(path)
+              : undefined
+    if (!pathMatches)
+        throw new ConfigurationError("configuration", "Test request matcher paths must be strings or RegExps")
+    return (request) => (methodMatches?.(request) ?? true) && pathMatches(request.path)
+}
+
+function validateResponse(response: unknown): void {
+    if (typeof response === "function") return
+    if (response instanceof Response) {
+        if (response.bodyUsed)
+            throw new ConfigurationError("configuration", "A registered test Response must not have a consumed body")
+        return
+    }
+    if (typeof response !== "object" || response === null)
+        throw new ConfigurationError(
+            "configuration",
+            "Test responses must be an object, a Response or a handler function",
+        )
+    checkDescription(response as Exclude<TestResponse, Response>)
+}
+
+function checkDescription(response: Exclude<TestResponse, Response>): void {
+    const { status, headers, body } = response
+    if (status !== undefined && (!Number.isSafeInteger(status) || status < 200 || status > 599))
+        throw new ConfigurationError("configuration", "Test response status must be an integer from 200 through 599")
+    if (status !== undefined && nullBodyStatuses.has(status) && body !== undefined)
+        throw new ConfigurationError("configuration", `Test response status ${status} cannot have a body`)
+    if (
+        headers !== undefined &&
+        (typeof headers !== "object" ||
+            headers === null ||
+            Object.values(headers).some((value) => typeof value !== "string"))
+    )
+        throw new ConfigurationError("configuration", "Test response headers must be an object of strings")
+}
+
+function toResponse(response: TestResponse): Response {
+    if (response instanceof Response) return response
+    if (typeof response !== "object" || response === null)
+        throw new TypeError("A test response handler must return a response object or a Response")
+    checkDescription(response)
+    const { body, headers } = response
+    const status = response.status ?? (body === undefined ? 204 : 200)
+    return new Response(body === undefined ? null : JSON.stringify(body), {
+        status,
+        headers: body === undefined ? { ...headers } : { "content-type": "application/json", ...headers },
+    })
+}
+
+/** Read the recorded body and attachment parts of one request, consuming any streamed body */
+async function readBody(request: Request): Promise<{ body: unknown; files: TestRequestFile[] }> {
+    if (request.body === null) return { body: undefined, files: [] }
+    const type = request.headers.get("content-type") ?? ""
+    if (type.startsWith("multipart/form-data")) {
+        const form = await request.formData()
+        let body: unknown
+        const files: TestRequestFile[] = []
+        for (const [field, value] of form) {
+            if (typeof value === "string") {
+                if (field === "payload_json") body = parseJson(value)
+            } else files.push({ field, filename: value.name, contentType: value.type, size: value.size })
+        }
+        return { body, files }
+    }
+    const text = await request.text()
+    if (text === "") return { body: undefined, files: [] }
+    return { body: type.includes("json") ? parseJson(text) : text, files: [] }
+}
+
+function parseJson(text: string): unknown {
+    try {
+        return JSON.parse(text) as unknown
+    } catch {
+        // allow-silent: A body that is not valid JSON stays visible to the test as its text
+        return text
+    }
+}
+
+function aborted(signal: AbortSignal | null | undefined): Promise<never> | undefined {
+    if (!signal) return undefined
+    return new Promise<never>((_resolve, reject) => {
+        if (signal.aborted) reject(signal.reason)
+        else signal.addEventListener("abort", () => reject(signal.reason), { once: true })
+    })
+}
+
+/** The fake HTTP side of one test client */
+export class TestHttp implements TestRest {
+    readonly #routes: Route[] = []
+    readonly #requests: TestRequest[] = []
+    /** Pending next calls of every route, failed with ClientClosedError when the transport closes */
+    readonly #waits = new Set<(error: unknown) => void>()
+    /** Messages described by recorded sends, built once when the automatic reply or sentMessages first needs them */
+    readonly #sent = new WeakMap<TestRequest, WireMessage>()
+    #inFlight = 0
+    #closed = false
+
+    constructor(
+        private readonly record: (record: Omit<LogRecord, "time">) => void,
+        private readonly replies: TestReplies,
+    ) {}
+
+    /** Requests received but not yet answered, including ones whose response handler is still running */
+    get inFlight() {
+        return this.#inFlight
+    }
+
+    respond(matcher: TestRequestMatcher, response: TestResponse | TestResponder): InternalTestRoute {
+        const matches = compileMatcher(matcher)
+        validateResponse(response)
+        const route: Route = { matches, response, answered: [], taken: 0, waiters: new Set(), active: true }
+        this.#routes.push(route)
+        return Object.freeze({
+            requests: () => Object.freeze([...route.answered]),
+            next: (options?: TestWaitOptions, signal?: AbortSignal) => {
+                const timeoutMs = waitTimeout(options)
+                if (route.taken < route.answered.length) return Promise.resolve(route.answered[route.taken++]!)
+                if (this.#closed) return Promise.reject(new ClientClosedError())
+                return timedWait<TestRequest>("next", timeoutMs, signal, (settle) => {
+                    const deliver = (request: TestRequest) => settle({ value: request })
+                    const fail = (error: unknown) => settle({ error })
+                    route.waiters.add(deliver)
+                    this.#waits.add(fail)
+                    return () => {
+                        route.waiters.delete(deliver)
+                        this.#waits.delete(fail)
+                    }
+                })
+            },
+            remove: () => {
+                route.active = false
+            },
+        })
+    }
+
+    /** Requests received so far, in order, excluding the discovery bootstrap */
+    requests(): readonly TestRequest[] {
+        return Object.freeze([...this.#requests])
+    }
+
+    /** The messages described by the message sends among these requests, in order */
+    sentMessages(requests: readonly TestRequest[]): readonly WireMessage[] {
+        return Object.freeze(requests.filter(isMessageSend).map((request) => this.#sentMessage(request)))
+    }
+
+    #sentMessage(request: TestRequest): WireMessage {
+        let message = this.#sent.get(request)
+        if (!message) this.#sent.set(request, (message = echoedMessage(this.replies, request, false)))
+        return message
+    }
+
+    /** The fetch-compatible function passed to the client's transport option */
+    readonly fetch = async (url: string, init: RequestInit): Promise<Response> => {
+        this.#inFlight++
+        try {
+            return await this.#answer(url, init)
+        } finally {
+            this.#inFlight--
+        }
+    }
+
+    readonly #answer = async (url: string, init: RequestInit): Promise<Response> => {
+        if (this.#closed) throw new Error("The test client has shut down, so its transport accepts no requests")
+        const cancelled = aborted(init.signal)
+        // A cancelled request must settle even while a handler or body read is still pending
+        const settle = <A>(work: Promise<A>) => (cancelled ? Promise.race([work, cancelled]) : work)
+        cancelled?.catch(() => {
+            // allow-silent: The same rejection is observed through the race below when cancellation wins
+        })
+        if (url === hostedDiscoveryUrl) return Response.json(testDiscoveryDocument)
+        const request = new Request(url, init)
+        const { body, files } = await settle(readBody(request))
+        const target = new URL(url)
+        const headers: Record<string, string> = {}
+        request.headers.forEach((value, name) => {
+            if (name !== "authorization") headers[name] = value
+        })
+        const withoutQuery = `${target.origin}${target.pathname}`
+        const recordedUrl = redactWebhookToken(url)
+        const path = redactWebhookToken(
+            withoutQuery.startsWith(`${apiBase}/`) ? withoutQuery.slice(apiBase.length) : withoutQuery,
+        )
+        const base = {
+            method: request.method.toUpperCase(),
+            url: recordedUrl,
+            path,
+            query: Object.freeze(Object.fromEntries(target.searchParams)),
+            headers: Object.freeze(headers),
+            body,
+            files: Object.freeze(files),
+        }
+        const route = this.#routes.findLast(
+            (candidate) => candidate.active && candidate.matches({ ...base, matched: true }),
+        )
+        const recorded: TestRequest = Object.freeze({ ...base, matched: route !== undefined })
+        this.#requests.push(recorded)
+        if (!route && isMessageSend(recorded)) return Response.json(this.#sentMessage(recorded))
+        if (!route && isMessageEdit(recorded)) return Response.json(echoedMessage(this.replies, recorded, true))
+        if (!route) {
+            this.record({
+                level: "warn",
+                category: "rest",
+                code: "testing.unmatchedRequest",
+                message: `No test response matches ${recorded.method} ${recorded.path}, so the request received HTTP 404. Register a matching response with rest.respond`,
+                status: 404,
+                fields: { method: recorded.method, path: recorded.path },
+            })
+            return Response.json(
+                { code: "NOT_FOUND", message: `No test response matches ${recorded.method} ${recorded.path}` },
+                { status: 404 },
+            )
+        }
+        route.answered.push(recorded)
+        const waiter = route.waiters.values().next().value
+        if (waiter) {
+            route.taken++
+            waiter(recorded)
+        }
+        const { response } = route
+        // A registered Response answers every match, so each request receives its own unread copy
+        if (typeof response !== "function")
+            return response instanceof Response ? response.clone() : toResponse(response)
+        try {
+            return toResponse(await settle(Promise.resolve(response(recorded))))
+        } catch (error) {
+            if (init.signal?.aborted && error === init.signal.reason) throw error
+            this.record({
+                level: "error",
+                category: "rest",
+                code: "testing.responderFailed",
+                message: `The test response handler for ${recorded.method} ${recorded.path} failed, so the request failed as a network error`,
+                fields: { method: recorded.method, path: recorded.path },
+                error: {
+                    origin: "application",
+                    name: error instanceof Error ? error.name : "Error",
+                    message: error instanceof Error ? error.message : String(error),
+                    ...(error instanceof Error && error.stack !== undefined ? { stack: error.stack } : {}),
+                },
+            })
+            throw error
+        }
+    }
+
+    /** Refuse later requests and fail pending next calls with ClientClosedError */
+    close() {
+        this.#closed = true
+        for (const fail of this.#waits) fail(new ClientClosedError())
+    }
+}

package/src/internal/testing/types.ts

@@ -0,0 +1,240 @@
+/**
+ * Public types of the testing entry points, shared by the default and native test clients.
+ * Invariant: This module declares types only and imports nothing that needs Node.js or Effect declarations, so both
+ * testing entry points compile in consumers that lack those type packages, as their main entry points do.
+ * Implements [SDK contracts: Delivery, requests and caches](/docs/SDK-CONTRACTS.md#delivery-requests-and-caches)
+ */
+import type { WireMessage, WireOverrides, WireUser } from "./fixtures.js"
+
+/**
+ * Settings that only test clients accept, alongside the usual client options
+ *
+ * @category Testing
+ */
+export interface TestSettings {
+    /** Token passed to the client, default the fixture token. The fake transport never sends it anywhere */
+    readonly token?: string
+    /** Bot account the test gateway reports in READY, default the test client's fixtures.botUser() */
+    readonly user?: WireUser
+    /**
+     * Heartbeat interval in milliseconds sent in HELLO, default 41,250 as on hosted Fluxer.
+     * The client heartbeats on its own timer, which shutdown stops
+     */
+    readonly heartbeatIntervalMs?: number
+}
+
+/**
+ * Choose the shard that receives an emitted dispatch
+ *
+ * @category Testing
+ */
+export interface TestEmitOptions {
+    /**
+     * Local shard ID that receives the dispatch.
+     * By default a payload with a guild_id goes to the shard Fluxer routes that community to, (guild_id >> 22) % totalShards,
+     * and any other payload goes to shard 0, which receives direct-message traffic
+     */
+    readonly shardId?: number
+}
+
+/**
+ * Choose how the test gateway ends one shard's connection
+ *
+ * @category Testing
+ */
+export interface TestDisconnectOptions {
+    /** Local shard ID whose connection closes, default 0 */
+    readonly shardId?: number
+    /**
+     * WebSocket or gateway close code the client receives, default 4000 (unknown error), after which the SDK reconnects
+     * and resumes. A fatal code such as 4004 ends the client's connection lifetime instead
+     */
+    readonly code?: number
+}
+
+/**
+ * One gateway command a client sent to the test gateway, in send order.
+ * Identify and Resume carry "[redacted]" in place of the token
+ *
+ * @category Testing
+ */
+export interface TestGatewayCommand {
+    /** Shard that sent the command, or null when it came before the socket identified or resumed */
+    readonly shardId: number | null
+    /** Gateway opcode, such as 2 for Identify, 3 for Presence Update or 8 for Request Guild Members */
+    readonly op: number
+    /** Command data as sent, parsed from JSON */
+    readonly d: unknown
+}
+
+/**
+ * One attachment part of a recorded multipart request
+ *
+ * @category Testing
+ */
+export interface TestRequestFile {
+    /** Form field name, such as files[0] */
+    readonly field: string
+    /** Uploaded file name */
+    readonly filename: string
+    /** Declared content type */
+    readonly contentType: string
+    /** Size in bytes */
+    readonly size: number
+}
+
+/**
+ * One HTTP request a test client sent, as recorded by the test transport and passed to response handlers.
+ * The record never contains the Authorization header, and a webhook token in the path reads "[redacted]"
+ *
+ * @category Testing
+ */
+export interface TestRequest {
+    /** Upper-case HTTP method */
+    readonly method: string
+    /** Absolute request URL, including the query string */
+    readonly url: string
+    /**
+     * Fluxer API path after the /v1 prefix and without the query string, such as /channels/1/messages.
+     * Requests to other origins, such as media downloads, use the absolute URL without its query string
+     */
+    readonly path: string
+    /** Query parameters. A repeated parameter keeps its last value */
+    readonly query: Readonly<Record<string, string>>
+    /** Request headers with lower-case names, without authorization */
+    readonly headers: Readonly<Record<string, string>>
+    /**
+     * Request body: Parsed JSON for JSON requests, the parsed payload_json part of a multipart upload, the text of any
+     * other body, or undefined when the request has none
+     */
+    readonly body: unknown
+    /** Attachment parts of a multipart upload, empty for other requests */
+    readonly files: readonly TestRequestFile[]
+    /**
+     * Whether a registered response answered the request. False means the test transport answered it itself, with the
+     * automatic reply to a message send or edit, or otherwise with the default 404
+     */
+    readonly matched: boolean
+}
+
+/**
+ * Select the requests a registered response answers.
+ * A string is "METHOD /path" or "/path" for any method, where a :name segment matches any single path segment, such as
+ * "POST /channels/:id/messages". A string starting with http matches an absolute URL on another origin.
+ * A RegExp is tested against the path. An object combines an optional method with a string or RegExp path,
+ * and a function decides from the whole request
+ *
+ * @category Testing
+ */
+export type TestRequestMatcher =
+    | string
+    | RegExp
+    | {
+          /** HTTP method to match, case-insensitive. Omit it to match every method */
+          readonly method?: string
+          /** Path pattern with the string or RegExp rules above */
+          readonly path: string | RegExp
+      }
+    | ((request: TestRequest) => boolean)
+
+/**
+ * A response description. Omitted fields default to status 200 with a JSON body, or status 204 when body is omitted.
+ * A Response object is used unchanged for bodies that are not JSON
+ *
+ * @category Testing
+ */
+export type TestResponse =
+    | {
+          /** HTTP status from 200 through 599 */
+          readonly status?: number
+          /** Response headers, such as Retry-After or X-RateLimit-Bucket */
+          readonly headers?: Readonly<Record<string, string>>
+          /** Value sent as the JSON response body, usually a wire fixture. Omit it for an empty body */
+          readonly body?: unknown
+      }
+    | Response
+
+/**
+ * Compute a response from the recorded request. A returned promise may settle later, and a handler that throws or
+ * rejects makes the request fail as a network error, which the client reports like any transport failure
+ *
+ * @category Testing
+ */
+export type TestResponder = (request: TestRequest) => TestResponse | Promise<TestResponse>
+
+/**
+ * One registered response. Registrations are searched newest first, so a later registration overrides an earlier one
+ * for the requests both match
+ *
+ * @category Testing
+ */
+export interface TestRoute {
+    /** Requests this registration answered so far, in order */
+    requests(): readonly TestRequest[]
+    /**
+     * Resolve with the next request this registration answers. Each call returns a different request, in order, so
+     * a request that arrived before the call is returned at once.
+     * Without timeoutMs the wait has no SDK deadline, so the test runner's own timeout ends a test whose request never
+     * arrives. With timeoutMs the promise rejects with TestTimeoutError when no request arrives in time.
+     * It rejects with ClientClosedError when the test client shuts down first. Invalid options throw ConfigurationError
+     */
+    next(options?: TestWaitOptions): Promise<TestRequest>
+    /** Stop answering requests. Earlier matching registrations and the default 404 apply again */
+    remove(): void
+}
+
+/**
+ * Limit how long a test wait, such as TestRoute.next, idle or say, may take
+ *
+ * @category Testing
+ */
+export interface TestWaitOptions {
+    /**
+     * Milliseconds before the wait fails with TestTimeoutError, an integer from 1 through 2,147,483,647.
+     * Omit it to wait without an SDK deadline, so the test runner's own timeout bounds a wait that never settles.
+     * The timeout uses real timers, so it still fires when a test fakes timers
+     */
+    readonly timeoutMs?: number
+}
+
+/**
+ * Choose the message a test bot's say delivers and how long say waits for the bot to settle
+ *
+ * @category Testing
+ */
+export interface TestSayOptions extends TestWaitOptions {
+    /**
+     * Wire fields that replace the defaults of the delivered MESSAGE_CREATE payload, as in fixtures.message.
+     * By default the message comes from the fixture set's human author in its default channel and community
+     */
+    readonly message?: WireOverrides<WireMessage>
+}
+
+/**
+ * Register fake Fluxer HTTP API responses for a test client.
+ * Without a registration, message sends (POST /channels/:id/messages) and edits (PATCH /channels/:id/messages/:id)
+ * receive an automatic reply: A message by the bot account that echoes the request's content, embeds, flags and tts,
+ * with a new fixture ID for a send and the edited ID for an edit. Other unmatched requests receive a Fluxer-shaped 404
+ *
+ * @category Testing
+ */
+export interface TestRest {
+    /**
+     * Answer matching requests with a fixed response or a handler's response until the registration is removed.
+     * The newest matching registration wins, including over the automatic message replies.
+     * Invalid matchers or responses throw ConfigurationError
+     *
+     * @example
+     * ```ts
+     * import { createTestClient } from "@neontechspace/fluxerly/testing"
+     * export function respondExample() {
+     *     const test = createTestClient()
+     *     test.rest.respond("GET /users/@me", { body: test.fixtures.botUser() })
+     *     return test.rest.respond("POST /channels/:id/messages", (request) => ({
+     *         body: test.fixtures.message({ content: String((request.body as { content?: unknown }).content) }),
+     *     }))
+     * }
+     * ```
+     */
+    respond(matcher: TestRequestMatcher, response: TestResponse | TestResponder): TestRoute
+}