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.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
async 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

async static assert_embed_equals(message, matches, attributes_to_prove=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

  • matchesembed 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

async static assert_embed_regex(message, patterns)

If regex patterns patterns cannot be found in the embed of message, fail the test.

Checks only the attributes from the dictionary keys of patterns.

Parameters
  • message – original message

  • patterns – a dict with keys of the attributes and regex values.

Returns

message

Return type

discord.Message

async 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

async 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

async 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

async 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

async 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

async 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

async 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

async 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

async assert_reply_embed_equals(message, equals, attributes_to_check=None)

Send a message and wait for an embed response. If the response does not match the given embed in the listed attributes, fail the test

See examples in example_target.py for examples of use.

Parameters
  • message

  • equalsembed object to compare to

  • attributes_to_check – 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

async assert_reply_embed_regex(message, patterns)
Send a message and wait for a response. If the response is not an embed or does not match the regex,

fail the test.

See examples in example_target.py for examples of use.

Parameters
  • message

  • patterns – A dict of the attributes to check. See assert_message_contains for more info on this.

Returns

message

Return type

discord.Message

async 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

async 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

async assert_reply_matches(contents, 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

async connect(channel)

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

async disconnect()

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

async 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

async ensure_silence()

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

Raises

UnexpectedResponseError, TimeoutError

async 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

async 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

async wait_for_event(event, check=None, timeout=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

async 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

async 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

async 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

async 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