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:
-
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__ = ()¶
-
client:
- 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.