@nubisjs/testing 0.0.0-stage → 0.1.0-next.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 EYTAK LIMITED
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,17 @@
-# Temporary Holding Version
+# @nubisjs/testing
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Test [Nubis](https://eytak.com/nubis) bots without Discord. Also available as `nubis/testing`.
+
+```ts
+import { fake, testCommand } from "nubis/testing";
+
+const result = await testCommand(ban)
+	.as({ permissions: PermissionFlagsBits.BanMembers })
+	.run({ user: fake.user("alice") });
+
+expect(result.replies).toEqual(["Ban alice?"]);
+```
+
+`testCommand`, `testComponent` (click, select, raw custom_ids), `testModal` and `testMenu`, with fake users, roles, channels and messages.
+
+MIT. Built by [Eytak](https://eytak.com).

package/dist/fake-api.d.ts

@@ -0,0 +1,21 @@
+import type { NubisApi } from "@nubisjs/core";
+export interface ApiCall {
+    /** "channels.createMessage", "guilds.banUser", … */
+    readonly method: string;
+    readonly args: readonly unknown[];
+}
+export type FakeApi = NubisApi & {
+    /** Every call, in order. */
+    readonly calls: ApiCall[];
+    /** The calls to one method. */
+    callsTo(method: string): ApiCall[];
+};
+/**
+ * An `api` that records calls instead of making them. Pass it with
+ * `.with({ api })`; methods resolve to `{}` unless `responses` says otherwise:
+ *
+ *     const api = fakeApi({ "guilds.get": { id: "g1", name: "Test" } });
+ *     await testCommand(ban).with({ api }).run({ user });
+ *     expect(api.callsTo("guilds.banUser")).toHaveLength(1);
+ */
+export declare function fakeApi(responses?: Readonly<Record<string, unknown | ((...args: unknown[]) => unknown)>>): FakeApi;

package/dist/fake.d.ts

@@ -0,0 +1,13 @@
+import { type APIInteractionDataResolvedChannel, type APIMessage, type APIRole, type APIUser } from "discord-api-types/v10";
+/** Snowflake-shaped ids, unique within a test run. */
+export declare const fakeId: () => string;
+/**
+ * Fake Discord objects for tests. Only the fields bots commonly read are
+ * filled in; pass `overrides` for anything else.
+ */
+export declare const fake: {
+    user(name?: string, overrides?: Partial<APIUser>): APIUser;
+    role(name?: string, overrides?: Partial<APIRole>): APIRole;
+    channel(name?: string, overrides?: Partial<APIInteractionDataResolvedChannel>): APIInteractionDataResolvedChannel;
+    message(content?: string, overrides?: Partial<APIMessage>): APIMessage;
+};

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { fake, fakeId } from "./fake";
+export type { ApiCall, FakeApi } from "./fake-api";
+export { fakeApi } from "./fake-api";
+export type { Recording, TransportCall } from "./recorder";
+export { manualClock, recordingTransport } from "./recorder";
+export type { Actor, CommandTester, ComponentTester, MenuTester, ModalTester, TestOptions, TestResult, } from "./testers";
+export { testCommand, testComponent, testMenu, testModal } from "./testers";

package/dist/index.js

@@ -0,0 +1,379 @@
+// src/fake.ts
+import {
+  ChannelType
+} from "discord-api-types/v10";
+var next = 100000000000000000n;
+var fakeId = () => String(next++);
+var fake = {
+  user(name = "tester", overrides = {}) {
+    return {
+      id: fakeId(),
+      username: name,
+      global_name: name,
+      discriminator: "0",
+      avatar: null,
+      ...overrides
+    };
+  },
+  role(name = "role", overrides = {}) {
+    return {
+      id: fakeId(),
+      name,
+      color: 0,
+      colors: { primary_color: 0, secondary_color: null, tertiary_color: null },
+      hoist: false,
+      position: 1,
+      permissions: "0",
+      managed: false,
+      mentionable: false,
+      flags: 0,
+      ...overrides
+    };
+  },
+  channel(name = "general", overrides = {}) {
+    return {
+      id: fakeId(),
+      name,
+      type: ChannelType.GuildText,
+      permissions: "0",
+      ...overrides
+    };
+  },
+  message(content = "", overrides = {}) {
+    return {
+      id: fakeId(),
+      channel_id: fakeId(),
+      author: fake.user("author"),
+      content,
+      timestamp: new Date(0).toISOString(),
+      edited_timestamp: null,
+      tts: false,
+      mention_everyone: false,
+      mentions: [],
+      mention_roles: [],
+      attachments: [],
+      embeds: [],
+      pinned: false,
+      type: 0,
+      ...overrides
+    };
+  }
+};
+// src/fake-api.ts
+function fakeApi(responses = {}) {
+  const calls = [];
+  const namespaces = new Map;
+  const namespace = (name) => new Proxy({}, {
+    get(_target, key) {
+      if (typeof key === "symbol" || key === "then")
+        return;
+      const method = `${name}.${key}`;
+      return async (...args) => {
+        calls.push({ method, args });
+        const response = responses[method];
+        return typeof response === "function" ? response(...args) : response ?? {};
+      };
+    }
+  });
+  return new Proxy({}, {
+    get(_target, key) {
+      if (key === "calls")
+        return calls;
+      if (key === "callsTo") {
+        return (method) => calls.filter((call) => call.method === method);
+      }
+      if (typeof key === "symbol" || key === "then")
+        return;
+      if (!namespaces.has(key))
+        namespaces.set(key, namespace(key));
+      return namespaces.get(key);
+    }
+  });
+}
+// src/recorder.ts
+import {
+  InteractionResponseType
+} from "discord-api-types/v10";
+function recordingTransport() {
+  const recording = {
+    calls: [],
+    messages: [],
+    replies: [],
+    modals: [],
+    trace: [],
+    uploads: []
+  };
+  const record = (call, files) => {
+    recording.calls.push(call);
+    const label = call.type === "respond" ? `respond:${call.response.type}` : call.type;
+    recording.trace.push(label);
+    if (files?.length) {
+      recording.uploads.push({ call: label, files: files.map((f) => f.name) });
+    }
+    let body;
+    if (call.type === "editOriginal" || call.type === "followUp")
+      body = call.body;
+    else if (call.type === "respond") {
+      const { response } = call;
+      if (response.type === InteractionResponseType.ChannelMessageWithSource || response.type === InteractionResponseType.UpdateMessage) {
+        body = response.data ?? {};
+      } else if (response.type === InteractionResponseType.Modal) {
+        recording.modals.push(response.data);
+      }
+    }
+    if (body) {
+      recording.messages.push(body);
+      recording.replies.push(body.content ?? "");
+    }
+  };
+  const transport = {
+    respond: async (response, files) => record({ type: "respond", response }, files),
+    editOriginal: async (body, files) => record({ type: "editOriginal", body }, files),
+    deleteOriginal: async () => record({ type: "deleteOriginal" }),
+    followUp: async (body, files) => record({ type: "followUp", body }, files)
+  };
+  return { ...recording, transport };
+}
+function manualClock() {
+  const pending = [];
+  return {
+    schedule: (run) => {
+      const timer = { run, cancelled: false };
+      pending.push(timer);
+      return () => {
+        timer.cancelled = true;
+      };
+    },
+    fire() {
+      for (const timer of pending.splice(0))
+        if (!timer.cancelled)
+          timer.run();
+    }
+  };
+}
+// src/testers.ts
+import {
+  buildCommandTree,
+  createComponentRegistry,
+  dispatch,
+  dispatchComponent,
+  dispatchMenu,
+  dispatchModal
+} from "@nubisjs/core";
+import {
+  ApplicationCommandOptionType,
+  ApplicationCommandType,
+  ComponentType,
+  InteractionType
+} from "discord-api-types/v10";
+var EPHEMERAL = 1 << 6;
+function interactionBase(actor, type) {
+  const user = actor.user ?? fake.user();
+  const guild = actor.dm ? {} : {
+    guild_id: actor.guildId ?? "test-guild",
+    guild_locale: actor.guildLocale ?? "en-US",
+    member: {
+      user,
+      roles: [...actor.roles ?? []],
+      permissions: String(actor.permissions ?? 0n),
+      joined_at: new Date(0).toISOString(),
+      deaf: false,
+      mute: false,
+      flags: 0
+    }
+  };
+  return {
+    id: fakeId(),
+    application_id: "test-app",
+    token: "test-token",
+    version: 1,
+    type,
+    channel_id: actor.channelId ?? "test-channel",
+    app_permissions: String(actor.appPermissions ?? 0n),
+    locale: actor.locale ?? "en-US",
+    ...actor.dm ? { user } : guild,
+    ...actor.invoker ? {
+      message: {
+        id: fakeId(),
+        interaction_metadata: {
+          id: fakeId(),
+          type: InteractionType.ApplicationCommand,
+          user: actor.invoker
+        }
+      }
+    } : {}
+  };
+}
+async function finish(recording, result) {
+  const first = recording.messages[0];
+  return {
+    ...recording,
+    status: result.status,
+    ..."error" in result ? { error: result.error } : {},
+    ephemeral: ((first?.flags ?? 0) & EPHEMERAL) === EPHEMERAL
+  };
+}
+var defaults = { autoDeferMs: false };
+var OPTION_TYPES = {
+  string: ApplicationCommandOptionType.String,
+  integer: ApplicationCommandOptionType.Integer,
+  number: ApplicationCommandOptionType.Number,
+  boolean: ApplicationCommandOptionType.Boolean,
+  user: ApplicationCommandOptionType.User,
+  channel: ApplicationCommandOptionType.Channel,
+  role: ApplicationCommandOptionType.Role
+};
+function testCommand(definition, actor = {}, options = defaults) {
+  return {
+    as: (next) => testCommand(definition, { ...actor, ...next }, options),
+    with: (next) => testCommand(definition, actor, { ...options, ...next }),
+    async run(values) {
+      const given = [];
+      const resolved = {
+        users: {},
+        roles: {},
+        channels: {}
+      };
+      for (const [name, value] of Object.entries(values ?? {})) {
+        if (value === undefined)
+          continue;
+        const definitionOf = definition.options[name];
+        if (!definitionOf)
+          throw new Error(`The command has no option "${name}".`);
+        const kind = definitionOf.kind;
+        let sent = value;
+        if (kind === "user" || kind === "role" || kind === "channel") {
+          const entity = value;
+          resolved[`${kind}s`][entity.id] = value;
+          sent = entity.id;
+        }
+        given.push({ type: OPTION_TYPES[kind], name, value: sent });
+      }
+      const interaction = {
+        ...interactionBase(actor, InteractionType.ApplicationCommand),
+        data: {
+          id: fakeId(),
+          type: ApplicationCommandType.ChatInput,
+          name: "test",
+          options: given,
+          resolved
+        }
+      };
+      const recording = recordingTransport();
+      const result = await dispatch(buildCommandTree([{ path: ["test"], definition }]), interaction, recording.transport, options);
+      return finish(recording, result);
+    }
+  };
+}
+var COMPONENT_TYPES = {
+  button: ComponentType.Button,
+  "string-select": ComponentType.StringSelect,
+  "user-select": ComponentType.UserSelect,
+  "role-select": ComponentType.RoleSelect,
+  "mentionable-select": ComponentType.MentionableSelect,
+  "channel-select": ComponentType.ChannelSelect
+};
+function testComponent(definition, actor = {}, options = defaults) {
+  const kind = definition.kind;
+  const componentType = COMPONENT_TYPES[kind];
+  if (componentType === undefined) {
+    throw new Error(`testComponent can't run a ${kind}; use testModal for modals.`);
+  }
+  const customIdFor = (state) => definition(...state === undefined ? [] : [state]).custom_id;
+  const send = async (customId, values, resolved) => {
+    const interaction = {
+      ...interactionBase(actor, InteractionType.MessageComponent),
+      data: {
+        custom_id: customId,
+        component_type: componentType,
+        ...values ? { values: [...values] } : {},
+        ...resolved ? { resolved } : {}
+      }
+    };
+    const recording = recordingTransport();
+    const result = await dispatchComponent(createComponentRegistry([definition]), interaction, recording.transport, options);
+    return finish(recording, result);
+  };
+  return {
+    as: (next) => testComponent(definition, { ...actor, ...next }, options),
+    with: (next) => testComponent(definition, actor, { ...options, ...next }),
+    click: (state) => send(customIdFor(state)),
+    send: (customId, values) => send(customId, values),
+    select(values, state) {
+      const resolved = {
+        users: {},
+        roles: {},
+        channels: {}
+      };
+      const ids = values.map((value) => {
+        if (typeof value === "string")
+          return value;
+        const bucket = "username" in value ? "users" : ("color" in value) ? "roles" : "channels";
+        resolved[bucket][value.id] = value;
+        return value.id;
+      });
+      return send(customIdFor(state), ids, componentType === ComponentType.StringSelect ? undefined : resolved);
+    }
+  };
+}
+function testModal(definition, actor = {}, options = defaults) {
+  return {
+    as: (next) => testModal(definition, { ...actor, ...next }, options),
+    with: (next) => testModal(definition, actor, { ...options, ...next }),
+    async submit(values, state) {
+      const customId = definition(...state === undefined ? [] : [state]).custom_id;
+      const interaction = {
+        ...interactionBase(actor, InteractionType.ModalSubmit),
+        data: {
+          custom_id: customId,
+          components: Object.entries(values).map(([name, value]) => ({
+            type: ComponentType.Label,
+            id: 1,
+            component: {
+              type: ComponentType.TextInput,
+              id: 2,
+              custom_id: name,
+              value
+            }
+          }))
+        }
+      };
+      const recording = recordingTransport();
+      const result = await dispatchModal(createComponentRegistry([definition]), interaction, recording.transport, options);
+      return finish(recording, result);
+    }
+  };
+}
+function testMenu(definition, actor = {}, options = defaults) {
+  return {
+    as: (next) => testMenu(definition, { ...actor, ...next }, options),
+    with: (next) => testMenu(definition, actor, { ...options, ...next }),
+    async run(target) {
+      const isUser = definition.kind === "user";
+      const interaction = {
+        ...interactionBase(actor, InteractionType.ApplicationCommand),
+        data: {
+          id: fakeId(),
+          type: isUser ? ApplicationCommandType.User : ApplicationCommandType.Message,
+          name: definition.name,
+          target_id: target.id,
+          resolved: isUser ? { users: { [target.id]: target } } : { messages: { [target.id]: target } }
+        }
+      };
+      const recording = recordingTransport();
+      const result = await dispatchMenu([definition], interaction, recording.transport, options);
+      return finish(recording, result);
+    }
+  };
+}
+export {
+  fake,
+  fakeApi,
+  fakeId,
+  manualClock,
+  recordingTransport,
+  testCommand,
+  testComponent,
+  testMenu,
+  testModal
+};

package/dist/recorder.d.ts

@@ -0,0 +1,41 @@
+import type { Scheduler, Transport } from "@nubisjs/core";
+import { type APIInteractionResponse, type APIInteractionResponseCallbackData, type APIModalInteractionResponseCallbackData } from "discord-api-types/v10";
+export type TransportCall = {
+    readonly type: "respond";
+    readonly response: APIInteractionResponse;
+} | {
+    readonly type: "editOriginal";
+    readonly body: APIInteractionResponseCallbackData;
+} | {
+    readonly type: "deleteOriginal";
+} | {
+    readonly type: "followUp";
+    readonly body: APIInteractionResponseCallbackData;
+};
+/** What a handler sent to Discord, as a test sees it. */
+export interface Recording {
+    /** Every call, in order. */
+    readonly calls: TransportCall[];
+    /** Every message body sent, edited or followed up, in order. */
+    readonly messages: APIInteractionResponseCallbackData[];
+    /** The text of each of those messages. */
+    readonly replies: string[];
+    readonly modals: APIModalInteractionResponseCallbackData[];
+    /** Call types in order, e.g. ["respond:5", "editOriginal"]. */
+    readonly trace: string[];
+    /** File names uploaded with each call that had files. */
+    readonly uploads: {
+        readonly call: string;
+        readonly files: string[];
+    }[];
+}
+/** A transport that records instead of talking to Discord. */
+export declare function recordingTransport(): Recording & {
+    transport: Transport;
+};
+/** A scheduler driven by hand: auto-defer timers fire only when the test says. */
+export declare function manualClock(): {
+    readonly schedule: Scheduler;
+    /** Fires every pending timer. */
+    fire(): void;
+};

package/dist/testers.d.ts

@@ -0,0 +1,95 @@
+import { type CommandDefinition, type ComponentDefinition, type ComponentDispatchOptions, type DispatchOptions, type FieldMap, type MenuDefinition, type ModalDefinition, type OptionMap, type OptionValue } from "@nubisjs/core";
+import { type APIInteractionDataResolvedChannel, type APIRole, type APIUser } from "discord-api-types/v10";
+import { fake } from "./fake";
+import { type Recording } from "./recorder";
+/** Who is using the command or component. */
+export interface Actor {
+    /** Defaults to a fresh fake user. */
+    readonly user?: APIUser;
+    /** Run in DMs instead of a server. Servers are the default. */
+    readonly dm?: boolean;
+    readonly guildId?: string;
+    readonly channelId?: string;
+    /** Role ids the member has. */
+    readonly roles?: readonly string[];
+    /** The member's permission bits (`PermissionFlagsBits`). None by default. */
+    readonly permissions?: bigint;
+    /** The bot's permissions in the channel. None by default. */
+    readonly appPermissions?: bigint;
+    /** For components: who ran the command that sent the message. */
+    readonly invoker?: APIUser;
+    /** The user's Discord language, as `interaction.locale`. Defaults to "en-US". */
+    readonly locale?: string;
+    /** The server's language, as `interaction.guild_locale`. Defaults to "en-US". */
+    readonly guildLocale?: string;
+}
+export interface TestResult extends Recording {
+    /** The dispatch status: "handled", "denied", "stale", "error", … */
+    readonly status: string;
+    /** What the handler threw, when status is "error". */
+    readonly error?: unknown;
+    /** Whether the first message was only visible to the user. */
+    readonly ephemeral: boolean;
+}
+type Options = DispatchOptions & ComponentDispatchOptions;
+type RequiredKeys<T extends OptionMap> = {
+    [K in keyof T]: T[K]["required"] extends true ? K : never;
+}[keyof T];
+/** The options to run a command with: required ones required, values as handlers see them. */
+export type TestOptions<T extends OptionMap> = {
+    [K in RequiredKeys<T>]: NonNullable<OptionValue<T[K]>>;
+} & {
+    [K in Exclude<keyof T, RequiredKeys<T>>]?: OptionValue<T[K]>;
+};
+export interface CommandTester<T extends OptionMap> {
+    /** Runs as this user, member or DM. */
+    as(actor: Actor): CommandTester<T>;
+    /** Bot-wide guards, middleware or timing, as dispatch takes them. */
+    with(options: Options): CommandTester<T>;
+    run(...args: keyof T extends never ? [options?: TestOptions<T>] : [options: TestOptions<T>]): Promise<TestResult>;
+}
+/**
+ * Runs a command the way Discord would, without Discord:
+ *
+ *     const result = await testCommand(ban)
+ *       .as({ permissions: PermissionFlagsBits.BanMembers })
+ *       .run({ user: fake.user("alice") });
+ *     expect(result.replies).toEqual(["Banned alice"]);
+ */
+export declare function testCommand<T extends OptionMap>(definition: CommandDefinition<T>, actor?: Actor, options?: Options): CommandTester<T>;
+/** For entity selects: the picked users, roles or channels. */
+type Picked = string | APIUser | APIRole | APIInteractionDataResolvedChannel;
+export interface ComponentTester {
+    as(actor: Actor): ComponentTester;
+    with(options: Options): ComponentTester;
+    /** Clicks a button rendered with `state` (leave it out for buttons without state). */
+    click(state?: unknown): Promise<TestResult>;
+    /**
+     * Picks from a select: values for string selects, or users, roles and
+     * channels (fake ones work) for the others.
+     */
+    select(values: readonly Picked[], state?: unknown): Promise<TestResult>;
+    /** Sends a custom_id as-is, e.g. to test what tampered state does. */
+    send(customId: string, values?: readonly string[]): Promise<TestResult>;
+}
+/** Clicks buttons and picks from selects the way Discord would, without Discord. */
+export declare function testComponent(definition: ComponentDefinition, actor?: Actor, options?: Options): ComponentTester;
+export interface ModalTester<F extends FieldMap> {
+    as(actor: Actor): ModalTester<F>;
+    with(options: Options): ModalTester<F>;
+    /** Submits the form with these values (and the state it was opened with). */
+    submit(values: {
+        readonly [K in keyof F]?: string;
+    }, state?: unknown): Promise<TestResult>;
+}
+/** Submits a modal the way Discord would, without Discord. */
+export declare function testModal<F extends FieldMap>(definition: ModalDefinition<F, never>, actor?: Actor, options?: Options): ModalTester<F>;
+export interface MenuTester {
+    as(actor: Actor): MenuTester;
+    with(options: Options): MenuTester;
+    /** Right-clicks this user (user menus) or message (message menus). */
+    run(target: APIUser | ReturnType<typeof fake.message>): Promise<TestResult>;
+}
+/** Runs a right-click command the way Discord would, without Discord. */
+export declare function testMenu(definition: MenuDefinition, actor?: Actor, options?: Options): MenuTester;
+export {};

package/package.json

@@ -1,6 +1,41 @@
 {
-  "name": "@nubisjs/testing",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@nubisjs/testing",
+	"version": "0.1.0-next.1",
+	"description": "Test Nubis commands, components and modals without Discord.",
+	"license": "MIT",
+	"author": "Eytak",
+	"homepage": "https://eytak.com/nubis",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/Eytak-Technologies/nubis.git",
+		"directory": "packages/testing"
+	},
+	"bugs": "https://github.com/Eytak-Technologies/nubis/issues",
+	"type": "module",
+	"sideEffects": false,
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js"
+		}
+	},
+	"files": [
+		"dist"
+	],
+	"engines": {
+		"node": ">=20"
+	},
+	"scripts": {
+		"build": "bun build ./src/index.ts --outdir dist --target node --format esm --packages external && tsc -p tsconfig.build.json",
+		"check-types": "tsc --noEmit",
+		"test": "bun test",
+		"lint": "biome lint ."
+	},
+	"dependencies": {
+		"@nubisjs/core": "0.1.0-next.1",
+		"discord-api-types": "^0.38.59"
+	},
+	"devDependencies": {
+		"zod": "^4.6.7"
+	}
+}