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 aMessage
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
- Reply (i.e.
Embed (i.e.
assert_embed_equals
): Sends a message then checks the embed of the response against a list of attributesOther 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
andedit_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, whileassert_message_*
tests require aMessage
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.
-
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 ofmessage
, fail the test.Checks only the attributes from
attributes_to_prove
.- Parameters
message – original message
matches –
embed
object to compare toattributes_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
-
async static
assert_embed_regex
(message, patterns)¶ If regex patterns
patterns
cannot be found in the embed ofmessage
, 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
-
async
assert_guild_channel_created
(channel_name, timeout=None)¶ Assert that the next channel created matches the name given
- Parameters
- Returns
The channel that was created
- Return type
- 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
- Returns
The channel that was deleted
- Return type
- 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
- 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
- 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
- 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
- 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
- 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
- Returns
The reply.
- Return type
- 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 –
equals –
embed
object to compare toattributes_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
-
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
-
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
- Returns
The reply.
- Return type
- 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
- 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
- Returns
The reply.
- Return type
- 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 thediscord.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
-
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
- 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
-
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
- 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
- Returns
The message we’ve been waiting for.
- Return type
- 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
- Raises
NoReactionError –