Runner

Main module for setting up and running tests using testcord. 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: 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

client: discord.Client

Alias for field number 0

guilds: List[discord.Guild]

Alias for field number 1

channels: List[discord.abc.GuildChannel]

Alias for field number 2

members: List[discord.Member]

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.

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

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

add_reaction(user: Union[discord.user.BaseUser, discord.abc.User], message: discord.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: Union[discord.user.BaseUser, discord.abc.User], message: discord.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: 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.