@neontechspace/fluxerly 1000.0.0-nightly.12

package/dist/internal/testing/fixtures.js

@@ -0,0 +1,233 @@
+/**
+ * Testing fixtures: Deterministic Fluxer wire payloads for application tests and the documented fixture token.
+ * Invariant: Every builder returns a fresh plain JSON object in the Fluxer wire shape (snake_case), accepted by the SDK's
+ * real decoders without overrides, and one fixture set always produces the same IDs in the same call order.
+ * Implements [SDK contracts: Delivery, requests and caches](/docs/SDK-CONTRACTS.md#delivery-requests-and-caches)
+ */
+/**
+ * A token-shaped value used by test clients by default. It is not a credential, and the fake transport never sends it anywhere
+ *
+ * @category Testing
+ */
+export const fixtureToken = "fixture-only-not-a-credential";
+/** Fluxer's snowflake epoch, 2015-01-01T00:00:00.000Z */
+const snowflakeEpochMs = 1420070400000n;
+/** Creation time encoded in every fixture ID and used for fixture timestamps */
+const fixtureTimeMs = 1767225600000n;
+/** ISO 8601 form of the fixture creation time, 2026-01-01T00:00:00.000Z */
+export const fixtureTimestamp = new Date(Number(fixtureTimeMs)).toISOString();
+function merge(defaults, overrides) {
+    if (overrides === undefined)
+        return defaults;
+    if (typeof overrides !== "object" || overrides === null || Array.isArray(overrides))
+        throw new TypeError("Fixture overrides must be a plain object of wire fields");
+    return { ...defaults, ...overrides };
+}
+/**
+ * Create an independent fixture set whose ID sequence starts from the beginning.
+ * Use one set per test, or the fixtures property of a test client, when IDs must not depend on other tests
+ *
+ * @example
+ * ```ts
+ * import { createFixtures } from "@neontechspace/fluxerly/testing"
+ * const fixtures = createFixtures()
+ * export const command = fixtures.message({ content: "!ping" })
+ * ```
+ *
+ * @category Testing
+ */
+export function createFixtures() {
+    let sequence = 0n;
+    const nextId = () => String(((fixtureTimeMs - snowflakeEpochMs) << 22n) + ++sequence);
+    const ids = Object.freeze({ guild: nextId(), channel: nextId(), user: nextId(), bot: nextId() });
+    const user = (overrides) => merge({
+        id: ids.user,
+        username: "fixture-user",
+        discriminator: "0001",
+        global_name: null,
+        avatar: null,
+        avatar_color: null,
+        flags: 0,
+    }, overrides);
+    const botUser = (overrides) => merge(user({ id: ids.bot, username: "fixture-bot", discriminator: "0000", bot: true }), overrides);
+    const guild = (overrides) => merge({
+        id: ids.guild,
+        name: "Fixture Guild",
+        icon: null,
+        banner: null,
+        splash: null,
+        embed_splash: null,
+        splash_card_alignment: 0,
+        vanity_url_code: null,
+        owner_id: ids.user,
+        system_channel_id: ids.channel,
+        system_channel_flags: 0,
+        rules_channel_id: null,
+        afk_channel_id: null,
+        afk_timeout: 300,
+        features: [],
+        verification_level: 0,
+        mfa_level: 0,
+        nsfw_level: 0,
+        nsfw: false,
+        content_warning_level: 0,
+        content_warning_text: null,
+        explicit_content_filter: 0,
+        default_message_notifications: 0,
+        disabled_operations: 0,
+    }, overrides);
+    const channel = (overrides) => merge({
+        id: ids.channel,
+        guild_id: ids.guild,
+        type: 0,
+        name: "general",
+        topic: null,
+        position: 0,
+        parent_id: null,
+        nsfw: false,
+        rate_limit_per_user: 0,
+        last_message_id: null,
+        last_pin_timestamp: null,
+        permission_overwrites: [],
+    }, overrides);
+    const thread = (overrides) => {
+        const isPrivate = overrides?.type === 12;
+        return merge({
+            id: nextId(),
+            guild_id: ids.guild,
+            type: 11,
+            parent_id: ids.channel,
+            owner_id: ids.user,
+            name: "fixture-thread",
+            last_message_id: null,
+            last_pin_timestamp: null,
+            rate_limit_per_user: 0,
+            flags: 0,
+            thread_metadata: {
+                archived: false,
+                auto_archive_duration: 4320,
+                archive_timestamp: fixtureTimestamp,
+                locked: false,
+                ...(isPrivate ? { invitable: true } : {}),
+                create_timestamp: fixtureTimestamp,
+            },
+            message_count: 0,
+            total_message_sent: 0,
+            member_count: 1,
+        }, overrides);
+    };
+    const forumChannel = (overrides) => merge({
+        id: nextId(),
+        guild_id: ids.guild,
+        type: 15,
+        name: "fixture-forum",
+        topic: null,
+        position: 1,
+        parent_id: null,
+        nsfw: false,
+        rate_limit_per_user: 0,
+        last_message_id: null,
+        last_pin_timestamp: null,
+        permission_overwrites: [],
+        flags: 0,
+        available_tags: [],
+        default_reaction_emoji: null,
+        default_sort_order: null,
+        ...(overrides?.type === 16 ? {} : { default_forum_layout: 0 }),
+        default_tag_setting: "match_some",
+        default_auto_archive_duration: null,
+        default_thread_rate_limit_per_user: 0,
+    }, overrides);
+    const role = (overrides) => merge({
+        id: nextId(),
+        name: "fixture-role",
+        color: 0,
+        position: 1,
+        hoist_position: null,
+        permissions: "0",
+        hoist: false,
+        mentionable: false,
+        unicode_emoji: null,
+    }, overrides);
+    const member = (overrides) => merge({
+        guild_id: ids.guild,
+        user: user(),
+        nick: null,
+        avatar: null,
+        banner: null,
+        accent_color: null,
+        roles: [],
+        joined_at: fixtureTimestamp,
+        mute: false,
+        deaf: false,
+        communication_disabled_until: null,
+    }, overrides);
+    const guildCreate = (overrides) => {
+        const { guild: guildOverrides, ...body } = overrides ?? {};
+        const properties = guild(guildOverrides);
+        const { guild_id: _, ...botMember } = member({ guild_id: properties.id, user: botUser() });
+        return merge({
+            id: properties.id,
+            properties,
+            roles: [role({ id: properties.id, name: "@everyone", position: 0 })],
+            channels: [channel({ guild_id: properties.id })],
+            threads: [],
+            emojis: [],
+            stickers: [],
+            members: [botMember],
+            member_count: 2,
+            online_count: 1,
+            presences: [],
+            voice_states: [],
+            joined_at: fixtureTimestamp,
+            unavailable: false,
+        }, body);
+    };
+    const message = (overrides) => merge({
+        id: nextId(),
+        channel_id: ids.channel,
+        guild_id: ids.guild,
+        author: user(),
+        type: 0,
+        flags: 0,
+        content: "fixture message",
+        timestamp: fixtureTimestamp,
+        edited_timestamp: null,
+        pinned: false,
+        mention_everyone: false,
+        tts: false,
+        mentions: [],
+        mention_roles: [],
+        embeds: [],
+        attachments: [],
+        stickers: [],
+    }, overrides);
+    return Object.freeze({
+        ids,
+        nextId,
+        user,
+        botUser,
+        guild,
+        guildCreate,
+        channel,
+        thread,
+        forumChannel,
+        role,
+        member,
+        message,
+    });
+}
+/**
+ * A shared fixture set for quick payloads. Its ID sequence continues across every caller in the process, so prefer
+ * createFixtures or a test client's fixtures when a test compares exact message or role IDs
+ *
+ * @example
+ * ```ts
+ * import { fixtures } from "@neontechspace/fluxerly/testing"
+ * export const ping = fixtures.message({ content: "!ping" })
+ * ```
+ *
+ * @category Testing
+ */
+export const fixtures = createFixtures();
+//# sourceMappingURL=fixtures.js.map

package/dist/internal/testing/fixtures.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fixtures.js","sourceRoot":"","sources":["../../../src/internal/testing/fixtures.ts"],"names":[],"mappings":"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"}

package/dist/internal/testing/gateway.d.ts

@@ -0,0 +1,51 @@
+/**
+ * In-memory protocol-v1 gateway for test clients: Fake sockets shaped like ws sockets, the scripted handshake and dispatch delivery.
+ * Invariant: Every socket opens without I/O, receives HELLO after the SDK attaches its listeners, gets READY for Identify
+ * (with the requested shard pair) and RESUMED for Resume, and has every heartbeat acknowledged. Dispatches carry
+ * increasing sequence numbers per shard session. No timers run and closing the gateway closes every socket.
+ * Implements [SDK contracts: Connection and recovery](/docs/SDK-CONTRACTS.md#connection-and-recovery)
+ */
+import { EventEmitter } from "node:events";
+import type { WebSocketLike, WebSocketOptions } from "#sdk/rest";
+import type { WireUser } from "./fixtures.js";
+import type { TestDisconnectOptions, TestEmitOptions, TestGatewayCommand } from "./types.js";
+/** A ws-compatible socket whose server side is the test gateway */
+declare class FakeSocket extends EventEmitter {
+    #private;
+    private readonly gateway;
+    readyState: number;
+    shardId: number | null;
+    constructor(gateway: TestGateway);
+    send(data: string, callback: (error?: Error) => void): void;
+    close(code: number): void;
+    terminate(): void;
+    /** Deliver a frame synchronously, as one received text message */
+    deliver(frame: unknown): void;
+    /** End the connection from the server side */
+    serverClose(code: number): void;
+}
+/** The scripted gateway shared by one test client's shards */
+export declare class TestGateway {
+    #private;
+    private readonly settings;
+    constructor(settings: {
+        readonly user: WireUser;
+        readonly heartbeatIntervalMs: number;
+    });
+    /** The socket factory passed to the client's transport option */
+    readonly webSocket: (_url: string, _options: WebSocketOptions) => WebSocketLike;
+    /** Commands received so far, in order */
+    commands(): readonly TestGatewayCommand[];
+    /** Handle one command a client socket sent */
+    receive(socket: FakeSocket, data: string): void;
+    /** Forget a closing socket */
+    detach(socket: FakeSocket): void;
+    /** Deliver one dispatch synchronously to a connected shard with the next sequence number */
+    emit(type: unknown, payload: unknown, options: TestEmitOptions | undefined): void;
+    /** Close one shard's current connection from the server side with a close code */
+    disconnect(options: TestDisconnectOptions | undefined): void;
+    /** Close every remaining socket and refuse later connections. Returns how many sockets were still open */
+    close(): number;
+}
+export {};
+//# sourceMappingURL=gateway.d.ts.map

package/dist/internal/testing/gateway.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gateway.d.ts","sourceRoot":"","sources":["../../../src/internal/testing/gateway.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAE1C,OAAO,KAAK,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAA;AAGhE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAC7C,OAAO,KAAK,EAAE,qBAAqB,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAA;AAW5F,mEAAmE;AACnE,cAAM,UAAW,SAAQ,YAAY;;IAIrB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAHpC,UAAU,EAAE,MAAM,CAAmB;IACrC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAO;IAE7B,YAA6B,OAAO,EAAE,WAAW,EAEhD;IAED,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,KAAK,CAAC,EAAE,KAAK,KAAK,IAAI,QAOnD;IAED,KAAK,CAAC,IAAI,EAAE,MAAM,QAEjB;IAED,SAAS,SAER;IAED,kEAAkE;IAClE,OAAO,CAAC,KAAK,EAAE,OAAO,QAGrB;IAaD,8CAA8C;IAC9C,WAAW,CAAC,IAAI,EAAE,MAAM,QAEvB;CACJ;AAgCD,8DAA8D;AAC9D,qBAAa,WAAW;;IAShB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAD7B,YACqB,QAAQ,EAAE;QACvB,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;QACvB,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAA;KACvC,EACD;IAEJ,iEAAiE;IACjE,QAAQ,CAAC,SAAS,SAAU,MAAM,YAAY,gBAAgB,KAAG,aAAa,CAY7E;IAED,yCAAyC;IACzC,QAAQ,IAAI,SAAS,kBAAkB,EAAE,CAExC;IAED,8CAA8C;IAC9C,OAAO,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,QAcvC;IA2DD,8BAA8B;IAC9B,MAAM,CAAC,MAAM,EAAE,UAAU,QAOxB;IAgBD,4FAA4F;IAC5F,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,eAAe,GAAG,SAAS,QAyCzE;IAED,kFAAkF;IAClF,UAAU,CAAC,OAAO,EAAE,qBAAqB,GAAG,SAAS,QAapD;IAED,0GAA0G;IAC1G,KAAK,IAAI,MAAM,CAKd;CACJ"}

package/dist/internal/testing/gateway.js

@@ -0,0 +1,265 @@
+/**
+ * In-memory protocol-v1 gateway for test clients: Fake sockets shaped like ws sockets, the scripted handshake and dispatch delivery.
+ * Invariant: Every socket opens without I/O, receives HELLO after the SDK attaches its listeners, gets READY for Identify
+ * (with the requested shard pair) and RESUMED for Resume, and has every heartbeat acknowledged. Dispatches carry
+ * increasing sequence numbers per shard session. No timers run and closing the gateway closes every socket.
+ * Implements [SDK contracts: Connection and recovery](/docs/SDK-CONTRACTS.md#connection-and-recovery)
+ */
+import { EventEmitter } from "node:events";
+import { ClientClosedError, ConfigurationError } from "#sdk/errors";
+import { CloseCode, Opcode } from "../protocol/gateway.js";
+import { SocketState } from "../transport/index.js";
+/** A ws-compatible socket whose server side is the test gateway */
+class FakeSocket extends EventEmitter {
+    gateway;
+    readyState = SocketState.open;
+    shardId = null;
+    constructor(gateway) {
+        super();
+        this.gateway = gateway;
+    }
+    send(data, callback) {
+        if (this.readyState !== SocketState.open) {
+            queueMicrotask(() => callback(new Error("The test gateway socket is not open")));
+            return;
+        }
+        queueMicrotask(() => callback());
+        this.gateway.receive(this, data);
+    }
+    close(code) {
+        this.#close(code);
+    }
+    terminate() {
+        this.#close(CloseCode.abnormal);
+    }
+    /** Deliver a frame synchronously, as one received text message */
+    deliver(frame) {
+        if (this.readyState !== SocketState.open)
+            return;
+        this.emit("message", Buffer.from(JSON.stringify(frame)), false);
+    }
+    /** Close from either side. The close event follows in a microtask, exactly once */
+    #close(code) {
+        if (this.readyState === SocketState.closing || this.readyState === SocketState.closed)
+            return;
+        this.readyState = SocketState.closing;
+        this.gateway.detach(this);
+        queueMicrotask(() => {
+            this.readyState = SocketState.closed;
+            this.emit("close", code, Buffer.alloc(0));
+        });
+    }
+    /** End the connection from the server side */
+    serverClose(code) {
+        this.#close(code);
+    }
+}
+/** Redact the token in Identify and Resume data before recording */
+function recordedData(op, d) {
+    if ((op !== Opcode.identify && op !== Opcode.resume) || typeof d !== "object" || d === null)
+        return d;
+    return { ...d, token: "[redacted]" };
+}
+/**
+ * Fluxer exempts direct, here and everyone mentions from ignored MESSAGE_CREATE dispatches. Role-only mentions,
+ * own messages and DMs are not exempt in a production session. Pinned to session_dispatch:ignored_event_must_dispatch
+ * and session_passive:is_user_mentioned at fluxerapp/fluxer commit 841fb7af4174fc8fc025307776e87e7dba51a669
+ */
+function mentionedMessage(type, payload, userId) {
+    if (type !== "MESSAGE_CREATE" || typeof payload !== "object" || payload === null)
+        return false;
+    const message = payload;
+    return (message.mention_everyone === true ||
+        message.mention_here === true ||
+        (Array.isArray(message.mentions) &&
+            message.mentions.some((user) => typeof user === "object" && user !== null && user.id === userId)));
+}
+/** Fluxer's shard for a guild ID under a shard count */
+function guildShard(guildId, totalShards) {
+    return Number((BigInt(guildId) >> 22n) % BigInt(totalShards));
+}
+/** The scripted gateway shared by one test client's shards */
+export class TestGateway {
+    settings;
+    #sockets = new Set();
+    #shards = new Map();
+    #commands = [];
+    #totalShards = 1;
+    #sessions = 0;
+    #closed = false;
+    constructor(settings) {
+        this.settings = settings;
+    }
+    /** The socket factory passed to the client's transport option */
+    webSocket = (_url, _options) => {
+        const socket = new FakeSocket(this);
+        if (this.#closed) {
+            // A socket requested after cleanup closes like a refused connection instead of reaching any network
+            socket.serverClose(CloseCode.abnormal);
+            return socket;
+        }
+        this.#sockets.add(socket);
+        queueMicrotask(() => socket.deliver({ op: Opcode.hello, d: { heartbeat_interval: this.settings.heartbeatIntervalMs } }));
+        return socket;
+    };
+    /** Commands received so far, in order */
+    commands() {
+        return Object.freeze([...this.#commands]);
+    }
+    /** Handle one command a client socket sent */
+    receive(socket, data) {
+        let frame;
+        try {
+            frame = JSON.parse(data);
+        }
+        catch {
+            // allow-silent: A non-JSON command is an SDK defect the real gateway would answer with close code 4002
+            socket.serverClose(CloseCode.decodeError);
+            return;
+        }
+        const op = typeof frame.op === "number" ? frame.op : -1;
+        if (op === Opcode.identify)
+            this.#identify(socket, frame.d);
+        else if (op === Opcode.resume)
+            this.#resume(socket, frame.d);
+        this.#commands.push(Object.freeze({ shardId: socket.shardId, op, d: recordedData(op, frame.d) }));
+        if (op === Opcode.heartbeat)
+            queueMicrotask(() => socket.deliver({ op: Opcode.heartbeatAck }));
+    }
+    #identify(socket, d) {
+        const shard = d?.shard;
+        const pair = Array.isArray(shard) && shard.length === 2 && shard.every((value) => Number.isSafeInteger(value))
+            ? shard
+            : undefined;
+        const shardId = pair?.[0] ?? 0;
+        this.#totalShards = pair?.[1] ?? 1;
+        socket.shardId = shardId;
+        const session = {
+            socket,
+            ready: false,
+            sessionId: `fixture-session-${shardId}-${++this.#sessions}`,
+            sequence: 1,
+            ignoredEvents: new Set(d?.ignored_events ?? []),
+        };
+        this.#shards.set(shardId, session);
+        queueMicrotask(() => {
+            if (session.socket !== socket)
+                return;
+            // Ready first: The client can finish connecting and emit synchronously inside this delivery
+            session.ready = true;
+            socket.deliver({
+                op: Opcode.dispatch,
+                s: 1,
+                t: "READY",
+                d: {
+                    session_id: session.sessionId,
+                    version: 1,
+                    user: this.settings.user,
+                    // No guilds list: Tests add communities later, so the connected record reports no count and no invite warning
+                    private_channels: [],
+                    presences: [],
+                    users: [],
+                    ...(pair ? { shard: pair } : {}),
+                },
+            });
+        });
+    }
+    #resume(socket, d) {
+        const sessionId = d?.session_id;
+        const entry = [...this.#shards].find(([, session]) => session.sessionId === sessionId);
+        if (!entry) {
+            queueMicrotask(() => socket.deliver({ op: Opcode.invalidSession, d: false }));
+            return;
+        }
+        const [shardId, session] = entry;
+        socket.shardId = shardId;
+        session.socket = socket;
+        session.ready = false;
+        queueMicrotask(() => {
+            if (session.socket !== socket)
+                return;
+            session.ready = true;
+            socket.deliver({ op: Opcode.dispatch, s: ++session.sequence, t: "RESUMED", d: {} });
+        });
+    }
+    /** Forget a closing socket */
+    detach(socket) {
+        this.#sockets.delete(socket);
+        for (const session of this.#shards.values())
+            if (session.socket === socket) {
+                session.socket = undefined;
+                session.ready = false;
+            }
+    }
+    #connected(shardId, operation) {
+        if (this.#closed)
+            throw new ClientClosedError();
+        const session = this.#shards.get(shardId);
+        if (!session?.ready || session.socket?.readyState !== SocketState.open)
+            throw new ConfigurationError("shardIds", `Test gateway shard ${shardId} is not connected, so ${operation} cannot deliver to it`, {
+                hint: "Await ready() before emitting, and pass a shardId this client owns",
+            });
+        return session;
+    }
+    /** Deliver one dispatch synchronously to a connected shard with the next sequence number */
+    emit(type, payload, options) {
+        if (typeof type !== "string" || !/^[A-Z0-9_]+$/.test(type))
+            throw new ConfigurationError("event", "Emitted dispatch types must be upper-case Fluxer dispatch names, such as MESSAGE_CREATE");
+        if (type === "READY" || type === "RESUMED")
+            throw new ConfigurationError("event", `The test gateway sends ${type} itself during the handshake`, {
+                hint: "Await ready() to connect, or use disconnect() to exercise a resume",
+            });
+        if (options !== undefined && (typeof options !== "object" || options === null))
+            throw new ConfigurationError("event", "Emit options must be an object");
+        const requested = options?.shardId;
+        if (requested !== undefined && (!Number.isSafeInteger(requested) || requested < 0))
+            throw new ConfigurationError("shardIds", "Emit shardId must be a non-negative integer");
+        const guildId = payload?.guild_id;
+        const shardId = requested ??
+            (typeof guildId === "string" && /^[0-9]+$/.test(guildId) ? guildShard(guildId, this.#totalShards) : 0);
+        let text;
+        try {
+            text = JSON.stringify(payload);
+        }
+        catch (cause) {
+            throw new ConfigurationError("event", "Emitted payloads must be JSON-serializable wire data", { cause });
+        }
+        const session = this.#connected(shardId, `emit(${JSON.stringify(type)})`);
+        // MANY is generated from ADD after its ignored-event gate and bypasses filtering of the generated name
+        // (session_dispatch:flush_reaction_buffer and session_dispatch_voice:dispatch_reaction_add_many at the pinned commit)
+        const filteredType = type === "MESSAGE_REACTION_ADD_MANY" ? "MESSAGE_REACTION_ADD" : type;
+        if (session.ignoredEvents.has(filteredType) && !mentionedMessage(type, payload, this.settings.user.id))
+            throw new ConfigurationError("event", `Fluxer would not send ${type} to this test gateway session`, {
+                hint: `Register the event handler before ready() when gateway.ignoredEvents is "auto", or remove ${filteredType} from the explicit gateway.ignoredEvents list (use [] to disable suppression). Create a new test client to apply these changes, since Resume keeps the session's filtering`,
+            });
+        session.sequence += 1;
+        const frame = {
+            op: Opcode.dispatch,
+            s: session.sequence,
+            t: type,
+            ...(text === undefined ? {} : { d: payload }),
+        };
+        session.socket.deliver(frame);
+    }
+    /** Close one shard's current connection from the server side with a close code */
+    disconnect(options) {
+        if (options !== undefined && (typeof options !== "object" || options === null))
+            throw new ConfigurationError("connection", "Disconnect options must be an object");
+        const shardId = options?.shardId ?? 0;
+        const code = options?.code ?? CloseCode.unknownError;
+        if (!Number.isSafeInteger(shardId) || shardId < 0)
+            throw new ConfigurationError("shardIds", "Disconnect shardId must be a non-negative integer");
+        if (!Number.isSafeInteger(code) || code < 1000 || code > 4999)
+            throw new ConfigurationError("connection", "Disconnect code must be a WebSocket close code from 1000 through 4999");
+        this.#connected(shardId, "disconnect").socket.serverClose(code);
+    }
+    /** Close every remaining socket and refuse later connections. Returns how many sockets were still open */
+    close() {
+        this.#closed = true;
+        const open = [...this.#sockets];
+        for (const socket of open)
+            socket.serverClose(CloseCode.goingAway);
+        return open.length;
+    }
+}
+//# sourceMappingURL=gateway.js.map

package/dist/internal/testing/gateway.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gateway.js","sourceRoot":"","sources":["../../../src/internal/testing/gateway.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAC1C,OAAO,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA;AAEnE,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAA;AAC1D,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAanD,mEAAmE;AACnE,MAAM,UAAW,SAAQ,YAAY;IAIJ,OAAO;IAHpC,UAAU,GAAW,WAAW,CAAC,IAAI,CAAA;IACrC,OAAO,GAAkB,IAAI,CAAA;IAE7B,YAA6B,OAAoB;QAC7C,KAAK,EAAE,CAAA;uBADkB,OAAO;IAEpC,CAAC;IAED,IAAI,CAAC,IAAY,EAAE,QAAiC;QAChD,IAAI,IAAI,CAAC,UAAU,KAAK,WAAW,CAAC,IAAI,EAAE,CAAC;YACvC,cAAc,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,IAAI,KAAK,CAAC,qCAAqC,CAAC,CAAC,CAAC,CAAA;YAChF,OAAM;QACV,CAAC;QACD,cAAc,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,CAAA;QAChC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,CAAA;IACpC,CAAC;IAED,KAAK,CAAC,IAAY;QACd,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;IACrB,CAAC;IAED,SAAS;QACL,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAA;IACnC,CAAC;IAED,kEAAkE;IAClE,OAAO,CAAC,KAAc;QAClB,IAAI,IAAI,CAAC,UAAU,KAAK,WAAW,CAAC,IAAI;YAAE,OAAM;QAChD,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAA;IACnE,CAAC;IAED,mFAAmF;IACnF,MAAM,CAAC,IAAY;QACf,IAAI,IAAI,CAAC,UAAU,KAAK,WAAW,CAAC,OAAO,IAAI,IAAI,CAAC,UAAU,KAAK,WAAW,CAAC,MAAM;YAAE,OAAM;QAC7F,IAAI,CAAC,UAAU,GAAG,WAAW,CAAC,OAAO,CAAA;QACrC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;QACzB,cAAc,CAAC,GAAG,EAAE;YAChB,IAAI,CAAC,UAAU,GAAG,WAAW,CAAC,MAAM,CAAA;YACpC,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAA;QAC7C,CAAC,CAAC,CAAA;IACN,CAAC;IAED,8CAA8C;IAC9C,WAAW,CAAC,IAAY;QACpB,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;IACrB,CAAC;CACJ;AAED,oEAAoE;AACpE,SAAS,YAAY,CAAC,EAAU,EAAE,CAAU;IACxC,IAAI,CAAC,EAAE,KAAK,MAAM,CAAC,QAAQ,IAAI,EAAE,KAAK,MAAM,CAAC,MAAM,CAAC,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,IAAI;QAAE,OAAO,CAAC,CAAA;IACrG,OAAO,EAAE,GAAG,CAAC,EAAE,KAAK,EAAE,YAAY,EAAE,CAAA;AACxC,CAAC;AAED;;;;GAIG;AACH,SAAS,gBAAgB,CAAC,IAAY,EAAE,OAAgB,EAAE,MAAc;IACpE,IAAI,IAAI,KAAK,gBAAgB,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,IAAI;QAAE,OAAO,KAAK,CAAA;IAC9F,MAAM,OAAO,GAAG,OAAqF,CAAA;IACrG,OAAO,CACH,OAAO,CAAC,gBAAgB,KAAK,IAAI;QACjC,OAAO,CAAC,YAAY,KAAK,IAAI;QAC7B,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC;YAC5B,OAAO,CAAC,QAAQ,CAAC,IAAI,CACjB,CAAC,IAAa,EAAE,EAAE,CACd,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,IAAI,IAAK,IAAyB,CAAC,EAAE,KAAK,MAAM,CAC5F,CAAC,CACT,CAAA;AACL,CAAC;AAED,wDAAwD;AACxD,SAAS,UAAU,CAAC,OAAe,EAAE,WAAmB;IACpD,OAAO,MAAM,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,GAAG,CAAC,GAAG,MAAM,CAAC,WAAW,CAAC,CAAC,CAAA;AACjE,CAAC;AAED,8DAA8D;AAC9D,MAAM,OAAO,WAAW;IASC,QAAQ;IARpB,QAAQ,GAAG,IAAI,GAAG,EAAc,CAAA;IAChC,OAAO,GAAG,IAAI,GAAG,EAAwB,CAAA;IACzC,SAAS,GAAyB,EAAE,CAAA;IAC7C,YAAY,GAAG,CAAC,CAAA;IAChB,SAAS,GAAG,CAAC,CAAA;IACb,OAAO,GAAG,KAAK,CAAA;IAEf,YACqB,QAGhB;wBAHgB,QAAQ;IAI1B,CAAC;IAEJ,iEAAiE;IACxD,SAAS,GAAG,CAAC,IAAY,EAAE,QAA0B,EAAiB,EAAE;QAC7E,MAAM,MAAM,GAAG,IAAI,UAAU,CAAC,IAAI,CAAC,CAAA;QACnC,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YACf,oGAAoG;YACpG,MAAM,CAAC,WAAW,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAA;YACtC,OAAO,MAAM,CAAA;QACjB,CAAC;QACD,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,CAAA;QACzB,cAAc,CAAC,GAAG,EAAE,CAChB,MAAM,CAAC,OAAO,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC,EAAE,EAAE,kBAAkB,EAAE,IAAI,CAAC,QAAQ,CAAC,mBAAmB,EAAE,EAAE,CAAC,CACrG,CAAA;QACD,OAAO,MAAM,CAAA;IACjB,CAAC,CAAA;IAED,yCAAyC;IACzC,QAAQ;QACJ,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,CAAA;IAC7C,CAAC;IAED,8CAA8C;IAC9C,OAAO,CAAC,MAAkB,EAAE,IAAY;QACpC,IAAI,KAAoC,CAAA;QACxC,IAAI,CAAC;YACD,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAkC,CAAA;QAC7D,CAAC;QAAC,MAAM,CAAC;YACL,uGAAuG;YACvG,MAAM,CAAC,WAAW,CAAC,SAAS,CAAC,WAAW,CAAC,CAAA;YACzC,OAAM;QACV,CAAC;QACD,MAAM,EAAE,GAAG,OAAO,KAAK,CAAC,EAAE,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;QACvD,IAAI,EAAE,KAAK,MAAM,CAAC,QAAQ;YAAE,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC,CAAA;aACtD,IAAI,EAAE,KAAK,MAAM,CAAC,MAAM;YAAE,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC,CAAA;QAC5D,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,EAAE,EAAE,CAAC,EAAE,YAAY,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA;QACjG,IAAI,EAAE,KAAK,MAAM,CAAC,SAAS;YAAE,cAAc,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,YAAY,EAAE,CAAC,CAAC,CAAA;IAClG,CAAC;IAED,SAAS,CAAC,MAAkB,EAAE,CAAU;QACpC,MAAM,KAAK,GAAI,CAAgC,EAAE,KAAK,CAAA;QACtD,MAAM,IAAI,GACN,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,IAAI,KAAK,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC;YAC7F,CAAC,CAAE,KAA0B;YAC7B,CAAC,CAAC,SAAS,CAAA;QACnB,MAAM,OAAO,GAAG,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAA;QAC9B,IAAI,CAAC,YAAY,GAAG,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAA;QAClC,MAAM,CAAC,OAAO,GAAG,OAAO,CAAA;QACxB,MAAM,OAAO,GAAiB;YAC1B,MAAM;YACN,KAAK,EAAE,KAAK;YACZ,SAAS,EAAE,mBAAmB,OAAO,IAAI,EAAE,IAAI,CAAC,SAAS,EAAE;YAC3D,QAAQ,EAAE,CAAC;YACX,aAAa,EAAE,IAAI,GAAG,CAAE,CAAmD,EAAE,cAAc,IAAI,EAAE,CAAC;SACrG,CAAA;QACD,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,EAAE,OAAO,CAAC,CAAA;QAClC,cAAc,CAAC,GAAG,EAAE;YAChB,IAAI,OAAO,CAAC,MAAM,KAAK,MAAM;gBAAE,OAAM;YACrC,4FAA4F;YAC5F,OAAO,CAAC,KAAK,GAAG,IAAI,CAAA;YACpB,MAAM,CAAC,OAAO,CAAC;gBACX,EAAE,EAAE,MAAM,CAAC,QAAQ;gBACnB,CAAC,EAAE,CAAC;gBACJ,CAAC,EAAE,OAAO;gBACV,CAAC,EAAE;oBACC,UAAU,EAAE,OAAO,CAAC,SAAS;oBAC7B,OAAO,EAAE,CAAC;oBACV,IAAI,EAAE,IAAI,CAAC,QAAQ,CAAC,IAAI;oBACxB,8GAA8G;oBAC9G,gBAAgB,EAAE,EAAE;oBACpB,SAAS,EAAE,EAAE;oBACb,KAAK,EAAE,EAAE;oBACT,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;iBACnC;aACJ,CAAC,CAAA;QACN,CAAC,CAAC,CAAA;IACN,CAAC;IAED,OAAO,CAAC,MAAkB,EAAE,CAAU;QAClC,MAAM,SAAS,GAAI,CAAqC,EAAE,UAAU,CAAA;QACpE,MAAM,KAAK,GAAG,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,SAAS,KAAK,SAAS,CAAC,CAAA;QACtF,IAAI,CAAC,KAAK,EAAE,CAAC;YACT,cAAc,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,cAAc,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAA;YAC7E,OAAM;QACV,CAAC;QACD,MAAM,CAAC,OAAO,EAAE,OAAO,CAAC,GAAG,KAAK,CAAA;QAChC,MAAM,CAAC,OAAO,GAAG,OAAO,CAAA;QACxB,OAAO,CAAC,MAAM,GAAG,MAAM,CAAA;QACvB,OAAO,CAAC,KAAK,GAAG,KAAK,CAAA;QACrB,cAAc,CAAC,GAAG,EAAE;YAChB,IAAI,OAAO,CAAC,MAAM,KAAK,MAAM;gBAAE,OAAM;YACrC,OAAO,CAAC,KAAK,GAAG,IAAI,CAAA;YACpB,MAAM,CAAC,OAAO,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,QAAQ,EAAE,CAAC,EAAE,EAAE,OAAO,CAAC,QAAQ,EAAE,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,CAAA;QACvF,CAAC,CAAC,CAAA;IACN,CAAC;IAED,8BAA8B;IAC9B,MAAM,CAAC,MAAkB;QACrB,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;QAC5B,KAAK,MAAM,OAAO,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE;YACvC,IAAI,OAAO,CAAC,MAAM,KAAK,MAAM,EAAE,CAAC;gBAC5B,OAAO,CAAC,MAAM,GAAG,SAAS,CAAA;gBAC1B,OAAO,CAAC,KAAK,GAAG,KAAK,CAAA;YACzB,CAAC;IACT,CAAC;IAED,UAAU,CAAC,OAAe,EAAE,SAAiB;QACzC,IAAI,IAAI,CAAC,OAAO;YAAE,MAAM,IAAI,iBAAiB,EAAE,CAAA;QAC/C,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAA;QACzC,IAAI,CAAC,OAAO,EAAE,KAAK,IAAI,OAAO,CAAC,MAAM,EAAE,UAAU,KAAK,WAAW,CAAC,IAAI;YAClE,MAAM,IAAI,kBAAkB,CACxB,UAAU,EACV,sBAAsB,OAAO,yBAAyB,SAAS,uBAAuB,EACtF;gBACI,IAAI,EAAE,oEAAoE;aAC7E,CACJ,CAAA;QACL,OAAO,OAAgD,CAAA;IAC3D,CAAC;IAED,4FAA4F;IAC5F,IAAI,CAAC,IAAa,EAAE,OAAgB,EAAE,OAAoC;QACtE,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC;YACtD,MAAM,IAAI,kBAAkB,CACxB,OAAO,EACP,yFAAyF,CAC5F,CAAA;QACL,IAAI,IAAI,KAAK,OAAO,IAAI,IAAI,KAAK,SAAS;YACtC,MAAM,IAAI,kBAAkB,CAAC,OAAO,EAAE,0BAA0B,IAAI,8BAA8B,EAAE;gBAChG,IAAI,EAAE,oEAAoE;aAC7E,CAAC,CAAA;QACN,IAAI,OAAO,KAAK,SAAS,IAAI,CAAC,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,IAAI,CAAC;YAC1E,MAAM,IAAI,kBAAkB,CAAC,OAAO,EAAE,gCAAgC,CAAC,CAAA;QAC3E,MAAM,SAAS,GAAG,OAAO,EAAE,OAAO,CAAA;QAClC,IAAI,SAAS,KAAK,SAAS,IAAI,CAAC,CAAC,MAAM,CAAC,aAAa,CAAC,SAAS,CAAC,IAAI,SAAS,GAAG,CAAC,CAAC;YAC9E,MAAM,IAAI,kBAAkB,CAAC,UAAU,EAAE,6CAA6C,CAAC,CAAA;QAC3F,MAAM,OAAO,GAAI,OAAyC,EAAE,QAAQ,CAAA;QACpE,MAAM,OAAO,GACT,SAAS;YACT,CAAC,OAAO,OAAO,KAAK,QAAQ,IAAI,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,OAAO,EAAE,IAAI,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;QAC1G,IAAI,IAAwB,CAAA;QAC5B,IAAI,CAAC;YACD,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAA;QAClC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACb,MAAM,IAAI,kBAAkB,CAAC,OAAO,EAAE,sDAAsD,EAAE,EAAE,KAAK,EAAE,CAAC,CAAA;QAC5G,CAAC;QACD,MAAM,OAAO,GAAG,IAAI,CAAC,UAAU,CAAC,OAAO,EAAE,QAAQ,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;QACzE,uGAAuG;QACvG,sHAAsH;QACtH,MAAM,YAAY,GAAG,IAAI,KAAK,2BAA2B,CAAC,CAAC,CAAC,sBAAsB,CAAC,CAAC,CAAC,IAAI,CAAA;QACzF,IAAI,OAAO,CAAC,aAAa,CAAC,GAAG,CAAC,YAAY,CAAC,IAAI,CAAC,gBAAgB,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;YAClG,MAAM,IAAI,kBAAkB,CAAC,OAAO,EAAE,yBAAyB,IAAI,+BAA+B,EAAE;gBAChG,IAAI,EAAE,6FAA6F,YAAY,4KAA4K;aAC9R,CAAC,CAAA;QACN,OAAO,CAAC,QAAQ,IAAI,CAAC,CAAA;QACrB,MAAM,KAAK,GAAG;YACV,EAAE,EAAE,MAAM,CAAC,QAAQ;YACnB,CAAC,EAAE,OAAO,CAAC,QAAQ;YACnB,CAAC,EAAE,IAAI;YACP,GAAG,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC;SAChD,CAAA;QACD,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAA;IACjC,CAAC;IAED,kFAAkF;IAClF,UAAU,CAAC,OAA0C;QACjD,IAAI,OAAO,KAAK,SAAS,IAAI,CAAC,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,IAAI,CAAC;YAC1E,MAAM,IAAI,kBAAkB,CAAC,YAAY,EAAE,sCAAsC,CAAC,CAAA;QACtF,MAAM,OAAO,GAAG,OAAO,EAAE,OAAO,IAAI,CAAC,CAAA;QACrC,MAAM,IAAI,GAAG,OAAO,EAAE,IAAI,IAAI,SAAS,CAAC,YAAY,CAAA;QACpD,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,OAAO,CAAC,IAAI,OAAO,GAAG,CAAC;YAC7C,MAAM,IAAI,kBAAkB,CAAC,UAAU,EAAE,mDAAmD,CAAC,CAAA;QACjG,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,IAAI,CAAC,IAAI,IAAI,GAAG,IAAI,IAAI,IAAI,GAAG,IAAI;YACzD,MAAM,IAAI,kBAAkB,CACxB,YAAY,EACZ,uEAAuE,CAC1E,CAAA;QACL,IAAI,CAAC,UAAU,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC,CAAA;IACnE,CAAC;IAED,0GAA0G;IAC1G,KAAK;QACD,IAAI,CAAC,OAAO,GAAG,IAAI,CAAA;QACnB,MAAM,IAAI,GAAG,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,CAAA;QAC/B,KAAK,MAAM,MAAM,IAAI,IAAI;YAAE,MAAM,CAAC,WAAW,CAAC,SAAS,CAAC,SAAS,CAAC,CAAA;QAClE,OAAO,IAAI,CAAC,MAAM,CAAA;IACtB,CAAC;CACJ"}

package/dist/internal/testing/harness.d.ts

@@ -0,0 +1,60 @@
+import type { LogRecord } from "#sdk/logging";
+import type { TransportOptions } from "#sdk/rest";
+import type { ClientDiagnostics } from "#sdk/client";
+import { type Fixtures, type WireMessage } from "./fixtures.js";
+import { TestGateway } from "./gateway.js";
+import { TestHttp } from "./http.js";
+import type { TestSayOptions, TestWaitOptions } from "./types.js";
+/**
+ * The work in progress that idle waits for: The client's diagnostics, its scheduled task runs in progress and its
+ * handler invocations, including received events still waiting for a handler that has not started
+ */
+export interface TestClientWork {
+    readonly diagnostics: ClientDiagnostics;
+    readonly runningTasks: number;
+    readonly pendingHandlers: number;
+}
+/**
+ * Reject option keys that a test client does not accept, before any client exists. Transport and instance get their
+ * own explanation, because the test client owns them. Any other unknown key gets createClient's closest-name hint,
+ * listing the client keys a test client accepts, the test settings and extraKeys, such as the runBot keys of createTestBot
+ */
+export declare function checkTestOptionKeys(options: object, extraKeys?: readonly string[]): void;
+/** The in-memory transport, records and fixtures owned by one test client */
+export declare class TestHarness {
+    #private;
+    readonly fixtures: Fixtures;
+    readonly http: TestHttp;
+    readonly gateway: TestGateway;
+    constructor(options: object);
+    /** Client options with the fake transport, a default token and log capture added to the caller's settings */
+    clientOptions<O extends object>(options: O): O & {
+        readonly token: string;
+        readonly transport: TransportOptions;
+    };
+    /** Log records captured so far, in order */
+    logs(): readonly LogRecord[];
+    /**
+     * Record an Error or Fatal record of the client before its thresholds and deduplication. Each entry point sets
+     * this as the client logger's errorTap, so a quiet logging level cannot hide a failure from failures() or shutdown
+     */
+    readonly captureError: (record: LogRecord) => void;
+    /** Unhandled failure records so far, in order. Returning them marks them as observed by the test */
+    failures(): readonly LogRecord[];
+    /** Throw UnhandledTestFailuresError for unhandled failures the test has not observed, then mark them observed */
+    checkFailures(): void;
+    /**
+     * Resolve once the client has no running handler, scheduled task run, REST request or unanswered test request and
+     * produced no new log record, request or gateway command for several event loop turns. A scheduled task waiting for
+     * its time does not count, so a test advances its clock to run it
+     */
+    idle(work: () => TestClientWork, options: TestWaitOptions | undefined, signal?: AbortSignal): Promise<void>;
+    /**
+     * Deliver a MESSAGE_CREATE from a human author, wait until the client settles as idle does, then return the
+     * messages the client sent meanwhile. Misuse and emitting before ready throw synchronously, as idle and emit do
+     */
+    say(work: () => TestClientWork, content: string, options: TestSayOptions | undefined, signal?: AbortSignal): Promise<readonly WireMessage[]>;
+    /** Close the fake transport after the client shut down. Reports sockets the client left open */
+    close(): void;
+}
+//# sourceMappingURL=harness.d.ts.map

package/dist/internal/testing/harness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"harness.d.ts","sourceRoot":"","sources":["../../../src/internal/testing/harness.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAe,SAAS,EAAyC,MAAM,cAAc,CAAA;AACjG,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAA;AACjD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA;AAIpD,OAAO,EAAgC,KAAK,QAAQ,EAAE,KAAK,WAAW,EAAE,MAAM,eAAe,CAAA;AAC7F,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AAC1C,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAA;AAEpC,OAAO,KAAK,EAAE,cAAc,EAAgB,eAAe,EAAE,MAAM,YAAY,CAAA;AAQ/E;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC3B,QAAQ,CAAC,WAAW,EAAE,iBAAiB,CAAA;IACvC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAA;CACnC;AAwCD;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,GAAE,SAAS,MAAM,EAAO,GAAG,IAAI,CAoB5F;AAED,6EAA6E;AAC7E,qBAAa,WAAW;;IACpB,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAmB;IAC9C,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;IACvB,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAA;IAY7B,YAAY,OAAO,EAAE,MAAM,EAuB1B;IAED,6GAA6G;IAC7G,aAAa,CAAC,CAAC,SAAS,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,CAAC,GAAG;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,SAAS,EAAE,gBAAgB,CAAA;KAAE,CA6BhH;IAED,4CAA4C;IAC5C,IAAI,IAAI,SAAS,SAAS,EAAE,CAE3B;IAED;;;OAGG;IACH,QAAQ,CAAC,YAAY,WAAY,SAAS,UAEzC;IAED,oGAAoG;IACpG,QAAQ,IAAI,SAAS,SAAS,EAAE,CAI/B;IAED,iHAAiH;IACjH,aAAa,SAKZ;IAED;;;;OAIG;IACH,IAAI,CAAC,IAAI,EAAE,MAAM,cAAc,EAAE,OAAO,EAAE,eAAe,GAAG,SAAS,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CA0D1G;IAED;;;OAGG;IACH,GAAG,CACC,IAAI,EAAE,MAAM,cAAc,EAC1B,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,cAAc,GAAG,SAAS,EACnC,MAAM,CAAC,EAAE,WAAW,GACrB,OAAO,CAAC,SAAS,WAAW,EAAE,CAAC,CAcjC;IAiBD,gGAAgG;IAChG,KAAK,SAcJ;CACJ"}