Skip to main content
scenario() declares a test of your bot, from a *.test.ts file of src/, and chapterjs test runs it against a Discord in memory. Everything on this page is imported from chapterjs/test.
src/checks/hello.test.ts
src/checks/hello.ts
How to test a bot, what is checked without a scenario and what the test server has is in the guide. This page lists what exists.

scenario()

Declares a test of your bot. Export the result from a *.test.ts file of src/: chapterjs test runs it against a Discord in memory, where the bot is in a server with a few people in it. bot is the bot in its test server: bot.use() runs a command, bot.click() presses a button, bot.say() sends a message as someone, and what comes back says what the bot answered. A file may export several scenarios, in a list too. The label is what the report shows: it can not be empty, and 120 characters is the most.

ScenarioDeclaration

What scenario() returns: a declaration the runner finds in the exports of a file.
{ label: string; run: (bot: TestBot) => unknown }
What the file gave to scenario(), not checked yet.

TestBot

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.
{ id: string; name: string }
required
The test server.
TestMember
required
The bot itself, as a member of the server.
TestMember
required
The owner of the server.
TestMember
required
A person with no special rights: who does things when nobody is named.
{ method: string; path: string; body: unknown }[]
required
Every request the bot sent to Discord so far.

member()

A person of the server, made the first time the name is given. The options only count the first time.

role()

A role of the server, made the first time the name is given.

channel()

A channel of the server, made the first time the name is given. #general exists.

use()

Uses a command, as a person would: a slash command with its options, or a menu command on what it is used on ({ on: message }, { on: member }; a message menu is used in the channel of its message). Resolves once the bot answered. options is typed from the options of the command (OptionInputsOf): a text, a number, true or false, one of the choices, a TestMember for a user option, a TestRole for a role one, a TestChannel for a channel one, a TestFile for an attachment one. It may be left out when the command requires none. What Discord would not let a person send (a required option missing, a number out of its range, a text too long, a value that is not one of the choices) fails the scenario before the bot hears of it.

click()

Clicks a button. Resolves once the bot answered. A button found on a message (reply.button('Confirm')) is clicked on that message, as a person would.

select()

Picks values in a select menu. Resolves once the bot answered. values are texts for a menu of texts (its option values), people, roles or channels for the others; the min and max of the menu are enforced.

submit()

Fills in and sends a form. Resolves once the bot answered. fields is typed from the fields of the form (FieldInputsOf): a text for a text field, a list of option values for a select or checkboxes one, one option value for a radio one, true or false for a checkbox, people, roles or channels for the others, files for a files field. A field left out stays empty; a required one left out fails the scenario, as the Discord app would refuse to send the form.

suggest()

Types in an option with suggestions, and gets what the bot suggests.

say()

Sends a message as a person. Resolves once the bot handled it.

react()

Reacts to a message as a person. Resolves once the bot handled it.

join()

Makes a person join the server. Resolves once the bot handled it.

leave()

Makes a person leave the server. Resolves once the bot handled it.

run()

Runs a task now, as if its time had come. Resolves once it is done.

settle()

Waits for everything the bot started to be done. Everything but what waits for the test to act: a function waiting for a message, a click or a reaction (waitForMessage()…) is left waiting, and use(), say(), click()… resolve meanwhile.

endWaits()

Ends everything the bot waits for (waitForMessage(), waitForClick()…) as if its time was up: time does not pass in the test server. Resolves once the bot handled it.

TestWhere

Who does something, and where.
TestMember
Who does it. Default: bot.someone.
TestChannel | 'dm'
Where: a channel, or 'dm' for a private message with the bot. Default: #general.
TestMessage | TestReply
For a button or a menu: the message it is on. Default: a message of the bot.

TestMemberOptions

How to make a person for a test.
(string | TestRole)[]
The roles of the person, by name or as bot.role() gave them.
PermissionName[]
Permissions given through a role of their own.
string
The nickname in the server.
boolean
Whether the person is a bot.
Locale
The language of the person: what t answers them in. Default: 'en-US'.

TestRoleOptions

PermissionName[]
What the role allows.

TestChannelOptions

TestChannelType
'text', 'announcement', 'voice', 'category' or 'forum'. Default: 'text'.
TestChannel
The category it is in.
string
The topic of the channel.

TestFile

A file someone attaches to a command or a form.
string
required
The name of the file, with its extension: photo.png.
string
Its content, as text.
string
Its media type: guessed from the name by default.

TestReply

What the bot answered to a command, a button, a menu or a form. It has every check of TestAssertions, and:
TestMessage | null
required
The message the bot answered with (or changed), or null without one.
string
required
The text of the answer; '' without a message.
Embed[]
required
The embeds, as the bot sent them.
TestButton[]
required
The buttons on it, in order.
TestMenu[]
required
The select menus on it, in order.
TestMessage[]
required
The messages sent after the first answer, in order.
TestForm | null
required
The form the bot opened, or null.
boolean
required
Whether the bot said the answer was coming before answering.
boolean
required
Whether the answer changed the message of the component.
boolean
required
Whether only one person sees it.

isDeferred()

Checks that the bot said the answer was coming (“thinking…“).

updatesMessage()

Checks that the bot changed the message of the button or menu.

opensForm()

Checks that the bot opened a form, this one when given: its export (whatever data it carries), the form called with its data, or one found on an answer.

changesNothing()

Checks that the bot answered with nothing visible (a deferred update).

button()

The button with this label, to click it. Fails when there is none.
The menu, or the one with this placeholder. Fails when there is none.

TestAssertions

What is checked of a message or an answer. Each check throws a TestFailure with a plain sentence when it fails, and returns what it checked otherwise, so checks chain.

says()

Checks that the text contains text (or matches it).

saysExactly()

Checks that the text is exactly text.

isEphemeral()

Checks that only the person who asked sees it.

isPublic()

Checks that everyone sees it.

hasButton()

Checks that there is a button with this label.

hasEmbed()

Checks that there is an embed, with this title when given.

hasNoEmbed()

Checks that there is no embed.

hasNoComponent()

Checks that there is no button and no menu.

TestMessage

A message in the test server. It has every check of TestAssertions, and:
string
required
The id of the message.
string
required
The text of the message.
TestMember | null
required
Who wrote it; null for someone who is not in the world any more.
boolean
required
Whether the bot wrote it.
Embed[]
required
The embeds, as the bot sent them.
TestButton[]
required
The buttons on it, in order.
TestMenu[]
required
The select menus on it, in order.
boolean
required
Whether only one person sees it.
boolean
required
Whether the message is pinned.
TestChannel
required
The channel it is in.
boolean
required
Whether the message was deleted since.

button()

The button with this label: to click it. Fails when there is none.
The menu, or the one with this placeholder. Fails when there is none.

TestMember

A person in the test server.
string
required
The id of the person.
string
required
The username of the person: what bot.member() was given.
string | null
required
The nickname in the server, or null without one.
string[]
required
The names of the roles of the person.
PermissionName[]
required
The permissions of the person in the server.
boolean
required
Whether the person is in the server right now.
boolean
required
Whether the person is banned from the server.
boolean
required
Whether the person is timed out right now.
TestMessage[]
required
The messages the bot sent to the person in private, oldest first.

can()

Whether the person may do that in the server.

hasRole()

Whether the person has that role.

TestRole

A role of the test server.
string
required
The id of the role.
string
required
The name of the role.
PermissionName[]
required
What the role allows.
boolean
required
Whether the role still exists.

TestChannel

A channel of the test server, a thread, or a private conversation.
string
required
The id of the channel.
string
required
The name of the channel.
string
required
What kind of channel it is: 'text', 'voice', 'thread', 'dm'…
string | null
required
The topic, or null.
number
required
The seconds between two messages of one person (slowmode); 0 for none.
boolean
required
Whether the channel still exists.
TestMessage[]
required
Every message in it that everyone sees, oldest first (deleted and ephemeral ones left out).
TestMessage | null
required
The newest message, or null.
TestChannel[]
required
The threads opened in it.
TestMember[]
required
For a thread: who is in it.
boolean
required
For a thread: whether it is archived.
boolean
required
For a thread: whether it is locked.

allows()

Whether a member may do that in the channel (its overwrites counted).

TestButton

A button on a message the bot sent.
string | null
required
The text on the button, or null for an emoji alone.
string
required
'primary', 'secondary', 'success', 'danger', 'link' or 'premium'.
boolean
required
Whether the button is disabled.
string | null
required
The id the framework wrote in it.

TestMenu

A select menu on a message the bot sent.
string
required
'string', 'user', 'role', 'mentionable' or 'channel'.
string | null
required
The text shown when nothing is picked.
boolean
required
Whether the menu is disabled.
{ label: string; value: string }[]
required
For a menu of texts: its options.
string
required
The id the framework wrote in it.

TestForm

A form the bot opened.
string
required
The title of the form.
string[]
required
The names of its fields, in order.
string
required
The id the framework wrote in it.

TestSuggestion

A suggestion the bot gave while someone typed in an option.
string
required
What the person sees.
string | number
required
What the bot receives.

Types

  • OptionInputsOf<Options>: the options of a command as a test fills them in. A required option can not be left out.
  • FieldInputsOf<Fields>: the fields of a form as a test fills them in: a field left out stays empty.
  • SelectInput: what a test picks in a menu: texts, or people, roles and channels.
  • TestMenuTarget<Type>: what a menu command is used on in a test: { on }, a TestMember for a 'user' menu, a TestMessage for a 'message' menu.
  • ButtonTarget: a button, as a test names it: the declaration, an instance, or one found on a message (reply.button('Confirm')).
  • SelectTarget: a menu, the same way (reply.menu()).
  • FormTarget<Fields>: a form, the same way (reply.form).
  • TestChannelType: 'text' | 'announcement' | 'voice' | 'category' | 'forum'.
  • TestFailure: an expectation of a test that the bot did not meet. What every check throws, with a plain sentence: the report shows it with the line of the scenario.