Runner

Main module for setting up and running tests using dpytest. Handles configuration of a bot, and setup of the discord environment.

All public functions in this module are re-exported at discord.ext.test, this is the primary entry point for users of the library and most of what they should interact with.

class RunnerConfig(client: discord.Client, guilds: List[discord.Guild], channels: List[discord.abc.GuildChannel], members: List[discord.Member])

Exposed discord test configuration Contains the current client, and lists of faked objects

property client

Alias for field number 0

property guilds

Alias for field number 1

property channels

Alias for field number 2

property members

Alias for field number 3

__slots__ = ()
require_config(func: Callable[[...], discord.ext.test._types.T]) → Callable[[...], discord.ext.test._types.T]

Decorator to enforce that configuration is completed before the decorated function is called.

Parameters

func – Function to decorate

Returns

Function with added check for configuration being setup

async run_all_events() → None

Ensure that all dpy related coroutines have completed or been cancelled. If any dpy coroutines are currently running, this will also wait for those.

async finish_on_command_error() → None

Ensure that all dpy related coroutines have completed or been cancelled. This will only wait for dpy related coroutines, not any other coroutines currently running.

verify_message(text: Optional[str] = None, equals: bool = True, contains: bool = False, peek: bool = False, assert_nothing: bool = False) → None

Assert that a message was sent with the given text, or that a message was sent that doesn’t match the given text

Parameters

  • text – Text to match, or None to match anything

  • equals – False to invert the assertion

  • contains – If true, checks whether message contains the text, otherwise checks if it exactly matches

  • peek – If true, message will not be removed from the queue

  • assert_nothing – Whether to assert that nothing was sent at all

get_message(peek: bool = False) → discord.Message

Allow the user to retrieve the most recent message sent by the bot

Parameters

peek – If true, message will not be removed from the queue

Returns

Most recent message from the queue

verify_embed(embed: Optional[discord.Embed] = None, allow_text: bool = False, equals: bool = True, peek: bool = False, assert_nothing: bool = False) → None

Assert that a message was sent containing an embed, or that a message was sent not containing an embed

Parameters

  • embed – Embed to compare against

  • allow_text – Whether non-embed text is allowed

  • equals – False to invert the assertion

  • peek – If true, message will not be removed from the queue

  • assert_nothing – Whether to assert that no message was sent

get_embed(peek: bool = False) → discord.Embed

Allow the user to retrieve an embed in a message sent by the bot

Parameters

peek – do not remove the message from the queue of messages

Returns

Embed of the most recent message in the queue

async verify_file(file: Optional[Union[str, pathlib.Path]] = None, allow_text: bool = False, equals: bool = True, assert_nothing: bool = False) → None

Assert that a message was sent containing and attached file, or that a message was not sent containing an attached file.

Parameters

  • file – Path to a file to check against. This file will be read and compared bytewise against the sent message’s attachment.

  • allow_text – Whether the message may contain content

  • equals – False to invert the assertion

  • assert_nothing – Whether to assert that no file was attached

verify_activity(activity: Optional[discord.Activity] = None, equals: bool = True) → None

Assert that the tested client’s activity was set to match the desired information.

Parameters

  • activity – Activity to compare against

  • equals – False to invert the assertion

async empty_queue() → None

Empty the current message queue. Waits for all events to complete to ensure queue is not immediately added to after running.

message(content: str, channel: Union[discord.TextChannel, discord.CategoryChannel, discord.abc.GuildChannel, discord.abc.PrivateChannel, int] = 0, member: Union[discord.Member, int] = 0, attachments: List[Union[pathlib.Path, str]] = None) → discord.Message

Fake a message being sent by some user to a channel.

Parameters

  • content – Content of the message

  • channel – Channel to send to, or index into the config list

  • member – Member sending the message, or index into the config list

  • attachments – Message attachments to include, as file paths.

Returns

New message that was sent

set_permission_overrides(target: Union[discord.User, discord.Role], channel: discord.abc.GuildChannel, overrides: Optional[discord.PermissionOverwrite] = None, **kwargs: Any) → None

Set the permission override for a channel, as if set by another user.

Parameters

  • target – User or Role the permissions override is being set for

  • channel – Channel the permissions are being set on

  • overrides – The permissions to use, as an object. Conflicts with using kwargs

  • kwargs – The permissions to use, as a set of keys and values. Conflicts with using overrides

add_role(member: discord.Member, role: discord.Role) → None

Add a role to a member, as if added by another user.

Parameters

  • member – Member to add the role to

  • role – Role to be added

remove_role(member: discord.Member, role: discord.Role) → None

Remove a role from a member, as if removed by another user.

Parameters

  • member – Member to remove the role from

  • role – Role to remove

async simulate_reaction(self: discord.Message, emoji: str, member: discord.Member)
member_join(guild: Union[discord.Guild, int] = 0, user: Optional[discord.User] = None, *, name: str = None, discrim: Union[str, int] = None) → discord.Member

Have a new member join a guild, either an existing or new user for the framework

Parameters

  • guild – Guild member is joining

  • user – User to join, or None to create a new user

  • name – If creating a new user, the name of the user. None to auto-generate

  • discrim – If creating a new user, the discrim of the user. None to auto-generate

get_config() → discord.ext.test.runner.RunnerConfig

Get the current runner configuration

Returns

Current runner config

configure(client: discord.Client, num_guilds: int = 1, num_channels: int = 1, num_members: int = 1) → None

Set up the runner configuration. This should be done before any tests are run.

Parameters

  • client – Client to configure with. Should be the bot/client that is going to be tested.

  • num_guilds – Number of guilds to start the configuration with. Default is 1

  • num_channels – Number of text channels in each guild to start with. Default is 1

  • num_members – Number of members in each guild (other than the client) to start with. Default is 1.