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

See also:

discord.ext.test.verify

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

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

client: Client

Alias for field number 0

guilds: List[Guild]

Alias for field number 1

channels: List[GuildChannel]

Alias for field number 2

members: List[Member]

Alias for field number 3

__slots__ = ()
require_config(func: Callable[[...], T]) → Callable[[...], 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.

get_message(peek: bool = False) → 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

get_embed(peek: bool = False) → 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 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: TextChannel | CategoryChannel | GuildChannel | PrivateChannel | int = 0, member: Member | int = 0, attachments: List[Path | str] = None) → 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: User | Role, channel: GuildChannel, overrides: PermissionOverwrite | None = 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: Member, role: 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: Member, role: 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

add_reaction(user: BaseUser | User, message: Message, emoji: str) → None

Add a reaction to a message, as if added by another user

Parameters:

  • user – User who reacted

  • message – Message they reacted to

  • emoji – Emoji that was used

remove_reaction(user: BaseUser | User, message: Message, emoji: str) → None

Remove a reaction from a message, as if done by another user

Parameters:

  • user – User who removed their react

  • message – Message they removed react from

  • emoji – Emoji that was removed

member_join(guild: Guild | int = 0, user: User | None = None, *, name: str = None, discrim: str | int = None) → 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() → RunnerConfig

Get the current runner configuration

Returns:

Current runner config

configure(client: Client, guilds: int | List[str] = 1, text_channels: int | List[str] = 1, voice_channels: int | List[str] = 1, members: int | List[str] = 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.

  • guilds – Number or list of names of guilds to start the configuration with. Default is 1

  • text_channels – Number or list of names of text channels in each guild to start with. Default is 1

  • voice_channels – Number or list of names of voice channels in each guild to start with. Default is 1.

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