Interface¶

This is the most important class in the library for you, as it contains all the assertions and tools you need to interface with the library. Generally broken down into a few overall types:

Message (i.e. assert_message_contains): Does not send it’s own message, so it require a Message to be passed in.
Reply (i.e. assert_reply_contains): Sends a message containing the text in contents and analyzes messages sent after that.
- Use get_delayed_reply to wait an amount of time before checking for a reply
Embed (i.e. assert_embed_equals): Sends a message then checks the embed of the response against a list of attributes
Other Tests (i.e. ask_human): Some tests do weird things and don’t have a clear category.
Interface Functions (i.e. connect, send_message): Help other tests but also can be useful in making custom tests out of the other tests.

class distest.TestInterface(client, channel, target)[source]¶

All the tests, and some supporting functions. Tests are designed to be run by the tester and mixed together in order to actually test the bot.

Note

In addition to the tests failing due to their own reasons, all tests will also fail if they timeout. This period is specified when the bot is run.

Note

Some functions (send_message and edit_message) are helper functions rather than tests and serve to bring some of the functionality of the discord library onto the same level as the tests.

Note

assert_reply_* tests will send a message with the passed content, while assert_message_* tests require a Message to be passed to them. This allows for more flexibility when you need it and an easier option when you don’t.

Parameters:	client (DiscordCliInterface) – The discord client of the tester. channel (discord.TextChannel) – The discord channel in which to run the tests. target (discord.Member) – The bot we’re testing.

ask_human(query)¶

Ask a human for an opinion on a question using reactions.

Currently, only yes-no questions are supported. If the human answers ‘no’, the test will be failed. Do not use if avoidable, since this test is not really automateable. Will fail if the reaction is wrong or takes too long to arrive

Parameters:	query (str) – The question for the human.
Raises:	HumanResponseTimeout, HumanResponseFailure

static assert_embed_equals(message: discord.message.Message, matches: discord.embeds.Embed, attributes_to_prove: list = None)¶

If matches doesn’t match the embed of message, fail the test.

Checks only the attributes from attributes_to_prove.

Parameters:	message – original message matches – embed object to compare to attributes_to_prove – a string list with the attributes of the embed, which are to compare This are all the Attributes you can prove: “title”, “description”, “url”, “color”, “author”, “video”, “image” and “thumbnail”.
Returns:	message
Return type:	discord.Message

assert_guild_channel_created(channel_name, timeout=None)¶

Assert that the next channel created matches the name given

Parameters:	channel_name (str) – The name of the channel to check for timeout (float) – The num of seconds to wait, defaults to the timeout provided at the start
Returns:	The channel that was created
Return type:	discord.abc.GuildChannel
Raises:	NoResponseError

assert_guild_channel_deleted(channel_name, timeout=None)¶

Assert that the next channel deleted matches the name given

TODO: check what the deleted channel actually returns

Parameters:	channel_name (str) – The name of the channel to check for timeout (float) – The num of seconds to wait, defaults to the timeout provided at the start
Returns:	The channel that was deleted
Return type:	discord.abc.GuildChannel
Raises:	NoResponseError

static assert_message_contains(message, substring)¶

If message does not contain the given substring, fail the test.

Parameters:	message (discord.Message) – The message to test. substring (str) – The string to test message against.
Returns:	message
Return type:	discord.Message
Raises:	ResponseDidNotMatchError

static assert_message_equals(message, matches)¶

If message does not match a string exactly, fail the test.

Parameters:	message (discord.Message) – The message to test. matches (str) – The string to test message against.
Returns:	message
Return type:	discord.Message
Raises:	ResponseDidNotMatchError

static assert_message_has_image(message)¶

Assert message has an attachment. If not, fail the test.

Parameters:	message (discord.Message) – The message to test.
Returns:	message
Return type:	discord.Message
Raises:	UnexpectedResponseError

static assert_message_matches(message, regex)¶

If message does not match a regex, fail the test.

Requires a properly formatted Python regex ready to be used in the re functions.

Parameters:	message (discord.Message) – The message to test. regex (str) – The regular expression to test message against.
Returns:	message
Return type:	discord.Message
Raises:	ResponseDidNotMatchError

assert_reaction_equals(contents, emoji)¶

Send a message and ensure that the reaction is equal to emoji. If not, fail the test.

Parameters:	contents (str) – The content of the trigger message. (A command) emoji (discord.Emoji) – The emoji that the reaction must equal.
Returns:	The resultant reaction object.
Return type:	discord.Reaction
Raises:	ReactionDidNotMatchError

assert_reply_contains(contents, substring)¶

Send a message and wait for a response. If the response does not contain the given substring, fail the test.

Parameters:	contents (str) – The content of the trigger message. (A command) substring (str) – The string to test against.
Returns:	The reply.
Return type:	discord.Message
Raises:	ResponseDidNotMatchError

assert_reply_equals(contents, matches)¶

Send a message and wait for a response. If the response does not match the string exactly, fail the test.

Parameters:	contents (str) – The content of the trigger message. (A command) matches (str) – The string to test against.
Returns:	The reply.
Return type:	discord.Message
Raises:	ResponseDidNotMatchError

assert_reply_has_image(contents)¶

Send a message consisting of contents and wait for a reply.

Check that the reply contains a discord.Attachment. If not, fail the test.

Parameters:	contents (str) – The content of the trigger message. (A command)
Returns:	The reply.
Return type:	discord.Message
Raises:	ResponseDidNotMatchError, NoResponseError

assert_reply_matches(contents: str, regex)¶

Send a message and wait for a response. If the response does not match a regex, fail the test.

Requires a properly formatted Python regex ready to be used in the re functions.

Parameters:	contents (str) – The content of the trigger message. (A command) regex (str) – The regular expression to test against.
Returns:	The reply.
Return type:	discord.Message
Raises:	ResponseDidNotMatchError

connect(channel)¶: Connect to a given VoiceChannel :param channel: The VoiceChannel to connect to. :return:

disconnect()¶: Disconnect from the VoiceChannel; Doesn’t work if the Bot isn’t connected. :return:

static edit_message(message, new_content)¶

Modify a message. Most tests and send_message return the discord.Message they sent, which can be used here. Helper Function

Parameters:	message (discord.Message) – The target message. Must be a `discord.Message` new_content (str) – The text to change message to.
Returns:	message after modification.
Return type:	discord.Message

ensure_silence()¶

Assert that the bot does not post any messages for some number of seconds.

Raises:	UnexpectedResponseError, TimeoutError

get_delayed_reply(seconds_to_wait, test_function, *args)¶

Get the last reply after a specific time and check it against a given test.

Parameters:	seconds_to_wait (float) – Time to wait in s test_function (method) – The function to call afterwards, without parenthesis (assert_message_equals, not assert_message_equals()!) args – The arguments to pass to the test, requires the same number of args as the test function. Make sur to pass in all args, including kwargs with defaults. NOTE: this policy may change if it becomes kinda stupid down the road.
Return type:	Method
Raises:	SyntaxError –
Returns:	The instance of the test requested

send_message(content)¶

Send a message to the channel the test is being run in. Helper Function

Parameters:	content (str) – Text to send in the message
Returns:	The message that was sent
Return type:	discord.Message

wait_for_event(event: str, check: Optional[Callable[[...], bool]] = None, timeout: float = None)¶

A wrapper for the discord.py function wait_for, tuned to be useful for distest.

See https://discordpy.readthedocs.io/en/latest/api.html#event-reference for a list of events.

Parameters:	event – The discord.py event, as a string and with the `on_` removed from the beginning. check (Callable[..,bool]) – A check function that all events of the type are ran against. Should return true when the desired event occurs, takes the event’s params as it’s params timeout (float) – How many seconds to wait for the event to occur.
Returns:	The parameters of the event requested
Raises:	NoResponseError

wait_for_message()¶

Wait for the bot the send any message. Will fail on timeout, but will ignore messages sent by anything other that the target.

Returns:	The message we’ve been waiting for.
Return type:	discord.Message
Raises:	NoResponseError

wait_for_message_in_channel(content, channel_id)¶

Send a message with content and returns the next message that the targeted bot sends. Used in many other tests.

Parameters:	content (str) – The text of the trigger message. channel_id (int) – The id of the channel that the message is sent in.
Returns:	The message we’ve been waiting for.
Return type:	discord.Message
Raises:	NoResponseError

wait_for_reaction(message)¶

Assert that message is reacted to with any reaction.

Parameters:	message (discord.Message) – The message to test with
Returns:	The reaction object.
Return type:	discord.Reaction
Raises:	NoReactionError –

wait_for_reply(content)¶

Send a message with content and returns the next message that the targeted bot sends. Used in many other tests.

Parameters:	content (str) – The text of the trigger message.
Returns:	The message we’ve been waiting for.
Return type:	discord.Message
Raises:	NoResponseError

class distest.TestInterface.Test(name, func, needs_human=False)[source]¶

Holds data about a specific test.

Parameters:	name (str) – The name of the test, checks this against the valid test names func (function) – The function in the tester bot that makes up this test needs_human (bool) – Weather or not this test will require human interaction to complete
Raises:	ValueError

Distest

Navigation

Interface¶