chapterjs 0.2.3 → 0.3.0

package/dist/testing/harness.d.ts

@@ -0,0 +1,387 @@
+import type { PermissionName } from '../discord/permissions.js';
+import type { Locale } from '../discord/types/common.js';
+import { type RawEmbed } from '../discord/types/message.js';
+import type { CommandDeclaration, CommandOption, CommandOptions, CommandWhere } from '../commands/command.js';
+import type { ButtonDeclaration } from '../components/button.js';
+import { type ButtonComponent, type ModalComponent, type SelectComponent } from '../components/instance.js';
+import type { CheckboxesField, CheckboxField, EntityField, FilesField, ModalDeclaration, ModalField, ModalFields, NoteField, RadioField, SelectField, TextField } from '../components/modal.js';
+import type { OptionValue } from '../components/options.js';
+import type { SelectDeclaration } from '../components/select.js';
+import type { Bot } from '../core/bot.js';
+import type { Project, ProjectObserver } from '../cli/project.js';
+import type { Log } from '../cli/log.js';
+import type { TaskDeclaration } from '../tasks/task.js';
+import { type Camelize } from '../util/case.js';
+import { World } from './world.js';
+/** A person in the test server. */
+export interface TestMember {
+    /** The id of the person. */
+    readonly id: string;
+    /** The username of the person: what `bot.member()` was given. */
+    readonly name: string;
+    /** The nickname in the server, or `null` without one. */
+    readonly nickname: string | null;
+    /** The names of the roles of the person. */
+    readonly roles: readonly string[];
+    /** The permissions of the person in the server. */
+    readonly permissions: readonly PermissionName[];
+    /** Whether the person is in the server right now. */
+    readonly inServer: boolean;
+    /** Whether the person is banned from the server. */
+    readonly banned: boolean;
+    /** Whether the person is timed out right now. */
+    readonly timedOut: boolean;
+    /** The messages the bot sent to the person in private, oldest first. */
+    readonly privateMessages: readonly TestMessage[];
+    /** Whether the person may do that in the server. */
+    can(permission: PermissionName): boolean;
+    /** Whether the person has that role. */
+    hasRole(role: string | TestRole): boolean;
+}
+/** A role of the test server. */
+export interface TestRole {
+    readonly id: string;
+    readonly name: string;
+    /** What the role allows. */
+    readonly permissions: readonly PermissionName[];
+    /** Whether the role still exists. */
+    readonly exists: boolean;
+}
+/** The kinds of channels a test can make. */
+export type TestChannelType = 'text' | 'announcement' | 'voice' | 'category' | 'forum';
+/** A channel of the test server, a thread, or a private conversation. */
+export interface TestChannel {
+    readonly id: string;
+    readonly name: string;
+    /** What kind of channel it is: `'text'`, `'voice'`, `'thread'`, `'dm'`... */
+    readonly type: string;
+    /** The topic, or `null`. */
+    readonly topic: string | null;
+    /** The seconds between two messages of one person (slowmode); `0` for none. */
+    readonly slowmode: number;
+    /** Whether the channel still exists. */
+    readonly exists: boolean;
+    /** Every message in it that everyone sees, oldest first (deleted and ephemeral ones left out). */
+    readonly messages: readonly TestMessage[];
+    /** The newest message, or `null`. */
+    readonly last: TestMessage | null;
+    /** The threads opened in it. */
+    readonly threads: readonly TestChannel[];
+    /** For a thread: who is in it. */
+    readonly members: readonly TestMember[];
+    /** For a thread: whether it is archived. */
+    readonly archived: boolean;
+    /** For a thread: whether it is locked. */
+    readonly locked: boolean;
+    /** Whether a member may do that in the channel (its overwrites counted). */
+    allows(member: TestMember | TestRole, permission: PermissionName): boolean;
+}
+/** A button on a message the bot sent. */
+export interface TestButton {
+    /** The text on the button, or `null` for an emoji alone. */
+    readonly label: string | null;
+    /** `'primary'`, `'secondary'`, `'success'`, `'danger'`, `'link'` or `'premium'`. */
+    readonly style: string;
+    readonly disabled: boolean;
+    /** The id the framework wrote in it. */
+    readonly customId: string | null;
+}
+/** A select menu on a message the bot sent. */
+export interface TestMenu {
+    /** `'string'`, `'user'`, `'role'`, `'mentionable'` or `'channel'`. */
+    readonly type: string;
+    readonly placeholder: string | null;
+    readonly disabled: boolean;
+    /** For a menu of texts: its options. */
+    readonly options: readonly {
+        label: string;
+        value: string;
+    }[];
+    /** The id the framework wrote in it. */
+    readonly customId: string;
+}
+/** A form the bot opened. */
+export interface TestForm {
+    readonly title: string;
+    /** The names of its fields, in order. */
+    readonly fields: readonly string[];
+    /** The id the framework wrote in it. */
+    readonly customId: string;
+}
+/** A suggestion the bot gave while someone typed in an option. */
+export interface TestSuggestion {
+    readonly name: string;
+    readonly value: string | number;
+}
+/** A file someone attaches to a command or a form. */
+export interface TestFile {
+    /** The name of the file, with its extension: `photo.png`. */
+    name: string;
+    /** Its content, as text. */
+    content?: string;
+    /** Its media type: guessed from the name by default. */
+    type?: string;
+}
+/** What is checked of a message or an answer. */
+export interface TestAssertions<Self> {
+    /** Checks that the text contains `text` (or matches it). */
+    says(text: string | RegExp): Self;
+    /** Checks that the text is exactly `text`. */
+    saysExactly(text: string): Self;
+    /** Checks that only the person who asked sees it. */
+    isEphemeral(): Self;
+    /** Checks that everyone sees it. */
+    isPublic(): Self;
+    /** Checks that there is a button with this label. */
+    hasButton(label: string): Self;
+    /** Checks that there is an embed, with this title when given. */
+    hasEmbed(title?: string): Self;
+    /** Checks that there is no embed. */
+    hasNoEmbed(): Self;
+    /** Checks that there is no button and no menu. */
+    hasNoComponent(): Self;
+}
+/** A message in the test server. */
+export interface TestMessage extends TestAssertions<TestMessage> {
+    readonly id: string;
+    /** The text of the message. */
+    readonly content: string;
+    /** Who wrote it; `null` for someone who is not in the world any more. */
+    readonly author: TestMember | null;
+    /** Whether the bot wrote it. */
+    readonly fromBot: boolean;
+    /** The embeds, as the bot sent them. */
+    readonly embeds: readonly Camelize<RawEmbed>[];
+    /** The buttons on it, in order. */
+    readonly buttons: readonly TestButton[];
+    /** The select menus on it, in order. */
+    readonly menus: readonly TestMenu[];
+    /** Whether only one person sees it. */
+    readonly ephemeral: boolean;
+    readonly pinned: boolean;
+    /** The channel it is in. */
+    readonly channel: TestChannel;
+    /** Whether the message was deleted since. */
+    readonly deleted: boolean;
+    /** The button with this label: to click it. Fails when there is none. */
+    button(label: string): TestButton;
+    /** The menu, or the one with this placeholder. Fails when there is none. */
+    menu(placeholder?: string): TestMenu;
+}
+/** What the bot answered to a command, a button, a menu or a form. */
+export interface TestReply extends TestAssertions<TestReply> {
+    /** The message the bot answered with (or changed), or `null` without one. */
+    readonly message: TestMessage | null;
+    /** The text of the answer; `''` without a message. */
+    readonly content: string;
+    readonly embeds: readonly Camelize<RawEmbed>[];
+    readonly buttons: readonly TestButton[];
+    readonly menus: readonly TestMenu[];
+    /** The messages sent after the first answer, in order. */
+    readonly followUps: readonly TestMessage[];
+    /** The form the bot opened, or `null`. */
+    readonly form: TestForm | null;
+    /** Whether the bot said the answer was coming before answering. */
+    readonly deferred: boolean;
+    /** Whether the answer changed the message of the component. */
+    readonly updated: boolean;
+    readonly ephemeral: boolean;
+    /** Checks that the bot said the answer was coming ("thinking…"). */
+    isDeferred(): TestReply;
+    /** Checks that the bot changed the message of the button or menu. */
+    updatesMessage(): TestReply;
+    /** Checks that the bot opened a form, this one when given. */
+    opensForm(form?: ModalDeclaration<ModalFields, never> | TestForm): TestReply;
+    /** Checks that the bot answered with nothing visible (a deferred update). */
+    changesNothing(): TestReply;
+    /** The button with this label, to click it. Fails when there is none. */
+    button(label: string): TestButton;
+    /** The menu, or the one with this placeholder. Fails when there is none. */
+    menu(placeholder?: string): TestMenu;
+}
+/** How to make a person for a test. */
+export interface TestMemberOptions {
+    /** The roles of the person, by name or as `bot.role()` gave them. */
+    roles?: readonly (string | TestRole)[];
+    /** Permissions given through a role of their own. */
+    permissions?: readonly PermissionName[];
+    nickname?: string;
+    /** Whether the person is a bot. */
+    bot?: boolean;
+    /** The language of the person: what `t` answers them in. Default: `'en-US'`. */
+    locale?: Locale;
+}
+export interface TestRoleOptions {
+    permissions?: readonly PermissionName[];
+}
+export interface TestChannelOptions {
+    /** Default: `'text'`. */
+    type?: TestChannelType;
+    /** The category it is in. */
+    parent?: TestChannel;
+    topic?: string;
+}
+/** Who does something, and where. */
+export interface TestWhere {
+    /** Who does it. Default: `bot.someone`. */
+    by?: TestMember;
+    /** Where: a channel, or `'dm'` for a private message with the bot. Default: `#general`. */
+    in?: TestChannel | 'dm';
+    /** For a button or a menu: the message it is on. Default: a message of the bot. */
+    on?: TestMessage | TestReply;
+}
+/** What a test gives for an option, by its kind. */
+type OptionInput<Option extends CommandOption> = Option extends {
+    choices: readonly (infer Choice)[];
+} ? Choice : Option extends {
+    choices: Readonly<Record<string, infer Choice>>;
+} ? Choice : Option['type'] extends 'string' ? string : Option['type'] extends 'integer' | 'number' ? number : Option['type'] extends 'boolean' ? boolean : Option['type'] extends 'user' ? TestMember : Option['type'] extends 'role' ? TestRole : Option['type'] extends 'channel' ? TestChannel : Option['type'] extends 'mentionable' ? TestMember | TestRole : TestFile;
+/** The options of a command as a test fills them in. */
+export type OptionInputsOf<Options extends CommandOptions> = {
+    [Name in keyof Options as Options[Name] extends {
+        required: true;
+    } ? Name : never]: OptionInput<Options[Name]>;
+} & {
+    [Name in keyof Options as Options[Name] extends {
+        required: true;
+    } ? never : Name]?: OptionInput<Options[Name]>;
+};
+/** What a test gives for a field of a form, by its kind. */
+type FieldInput<Field extends ModalField> = Field extends TextField ? string : Field extends SelectField<infer Options> ? readonly OptionValue<Options>[] : Field extends EntityField ? Field['type'] extends 'user' ? readonly TestMember[] : Field['type'] extends 'role' ? readonly TestRole[] : Field['type'] extends 'channel' ? readonly TestChannel[] : readonly (TestMember | TestRole)[] : Field extends FilesField ? readonly TestFile[] : Field extends RadioField<infer Options> ? OptionValue<Options> : Field extends CheckboxesField<infer Options> ? readonly OptionValue<Options>[] : Field extends CheckboxField ? boolean : never;
+/** The fields of a form as a test fills them in: a field left out stays empty. */
+export type FieldInputsOf<Fields extends ModalFields> = {
+    [Name in keyof Fields as Fields[Name] extends NoteField ? never : Name]?: FieldInput<Fields[Name]>;
+};
+/** What a test picks in a menu: texts, or people, roles and channels. */
+export type SelectInput = string | TestMember | TestRole | TestChannel;
+/** A button, as a test names it: the declaration, an instance, or one found on a message. */
+export type ButtonTarget = ButtonDeclaration<never> | ButtonComponent | TestButton;
+export type SelectTarget = SelectDeclaration<never> | SelectComponent | TestMenu;
+export type FormTarget<Fields extends ModalFields = ModalFields> = ModalDeclaration<Fields, never> | ModalComponent | TestForm;
+/** The arguments of `bot.use()`: the options may be left out when none is required. */
+type UseArgs<Options extends CommandOptions> = {} extends OptionInputsOf<Options> ? [options?: OptionInputsOf<Options>, where?: TestWhere] : [options: OptionInputsOf<Options>, where?: TestWhere];
+/**
+ * The bot of the project, running in a Discord in memory: one server, a few
+ * people, and everything the bot does kept where the test can read it.
+ */
+export interface TestBot {
+    /** The test server. */
+    readonly guild: {
+        readonly id: string;
+        readonly name: string;
+    };
+    /** The bot itself, as a member of the server. */
+    readonly me: TestMember;
+    /** The owner of the server. */
+    readonly owner: TestMember;
+    /** A person with no special rights: who does things when nobody is named. */
+    readonly someone: TestMember;
+    /** Every request the bot sent to Discord so far. */
+    readonly requests: readonly {
+        method: string;
+        path: string;
+        body: unknown;
+    }[];
+    /**
+     * A person of the server, made the first time the name is given. The
+     * options only count the first time.
+     */
+    member(name: string, options?: TestMemberOptions): TestMember;
+    /** A role of the server, made the first time the name is given. */
+    role(name: string, options?: TestRoleOptions): TestRole;
+    /** A channel of the server, made the first time the name is given. `#general` exists. */
+    channel(name: string, options?: TestChannelOptions): TestChannel;
+    /** Uses a slash command, as a person would. Resolves once the bot answered. */
+    use<Options extends CommandOptions, Where extends CommandWhere>(command: CommandDeclaration<Options, Where>, ...args: UseArgs<Options>): Promise<TestReply>;
+    /** Clicks a button. Resolves once the bot answered. */
+    click(button: ButtonTarget, where?: TestWhere): Promise<TestReply>;
+    /** Picks values in a select menu. Resolves once the bot answered. */
+    select(menu: SelectTarget, values: readonly SelectInput[], where?: TestWhere): Promise<TestReply>;
+    /** Fills in and sends a form. Resolves once the bot answered. */
+    submit<Fields extends ModalFields>(form: FormTarget<Fields>, fields?: FieldInputsOf<Fields>, where?: TestWhere): Promise<TestReply>;
+    /** Types in an option with suggestions, and gets what the bot suggests. */
+    suggest<Options extends CommandOptions, Where extends CommandWhere>(command: CommandDeclaration<Options, Where>, option: keyof Options & string, typed: string, where?: TestWhere): Promise<TestSuggestion[]>;
+    /** Sends a message as a person. Resolves once the bot handled it. */
+    say(content: string, where?: TestWhere): Promise<TestMessage>;
+    /** Reacts to a message as a person. Resolves once the bot handled it. */
+    react(message: TestMessage, emoji: string, where?: Pick<TestWhere, 'by'>): Promise<void>;
+    /** Makes a person join the server. Resolves once the bot handled it. */
+    join(member: string | TestMember, options?: TestMemberOptions): Promise<TestMember>;
+    /** Makes a person leave the server. Resolves once the bot handled it. */
+    leave(member: TestMember): Promise<void>;
+    /** Runs a task now, as if its time had come. Resolves once it is done. */
+    run(task: TaskDeclaration, at?: Date): Promise<void>;
+    /** Waits for everything the bot started to be done. */
+    settle(): Promise<void>;
+}
+/** What the test runner reads of what the bot said to the developer. */
+export interface Captured {
+    errors: string[];
+    warnings: string[];
+    infos: string[];
+}
+/** A `Log` that keeps what is written, for the runner to show per check. */
+export declare function captureLog(): {
+    log: Log;
+    take(): Captured;
+};
+/** Watches what the bot does with the files, to wait for it. */
+export declare class Observer {
+    #private;
+    readonly observe: ProjectObserver;
+    /** Forgets the interactions seen so far: a new world starts. */
+    reset(): void;
+    /** Resolves once the files are done with the interaction `id`. */
+    interaction(id: string, timeout: number): Promise<void>;
+    /** Resolves once the files are done with the next event that matches. */
+    event(match: (event: string, data: unknown) => boolean, timeout: number): Promise<void>;
+    /** Resolves once nothing the files started is still running. */
+    settle(): Promise<void>;
+}
+/** The bot in its world, with the handles a test works with. */
+export declare class Session implements TestBot {
+    #private;
+    readonly world: World;
+    readonly project: Project;
+    readonly bot: Bot;
+    constructor(world: World, project: Project, bot: Bot, observer: Observer, options?: {
+        timeout?: number;
+    });
+    get guild(): {
+        id: string;
+        name: string;
+    };
+    get me(): TestMember;
+    get owner(): TestMember;
+    get someone(): TestMember;
+    get requests(): {
+        method: string;
+        path: string;
+        body: unknown;
+    }[];
+    member(name: string, options?: TestMemberOptions): TestMember;
+    role(name: string, options?: TestRoleOptions): TestRole;
+    channel(name: string, options?: TestChannelOptions): TestChannel;
+    use<Options extends CommandOptions, Where extends CommandWhere>(command: CommandDeclaration<Options, Where>, ...args: UseArgs<Options>): Promise<TestReply>;
+    suggest<Options extends CommandOptions, Where extends CommandWhere>(command: CommandDeclaration<Options, Where>, option: keyof Options & string, typed: string, where?: TestWhere): Promise<TestSuggestion[]>;
+    click(button: ButtonTarget, where?: TestWhere): Promise<TestReply>;
+    select(menu: SelectTarget, values: readonly SelectInput[], where?: TestWhere): Promise<TestReply>;
+    submit<Fields extends ModalFields>(form: FormTarget<Fields>, fields?: FieldInputsOf<Fields>, where?: TestWhere): Promise<TestReply>;
+    say(content: string, where?: TestWhere): Promise<TestMessage>;
+    react(message: TestMessage, emoji: string, where?: Pick<TestWhere, 'by'>): Promise<void>;
+    join(member: string | TestMember, options?: TestMemberOptions): Promise<TestMember>;
+    leave(member: TestMember): Promise<void>;
+    run(task: TaskDeclaration, at?: Date): Promise<void>;
+    settle(): Promise<void>;
+    /**
+     * Sends a gateway event to the bot and waits for the files to be done
+     * with it. For the checks of `chapterjs test`, not for scenarios.
+     */
+    emit(type: string, data: unknown): Promise<void>;
+    /**
+     * Runs `act`, which makes the world send the event `type`, and waits for
+     * the files to be done with it.
+     */
+    expectEvent(type: string, act: () => void): Promise<void>;
+}
+export {};