Mocks#

Test mocks: they fake objects for testing.

New in version 7.0.

class sopel.tests.mocks.MockIRCBackend(*args, **kwargs)#

Fake IRC connection backend for testing purpose.

Parameters:

bot (sopel.bot.Sopel) – a Sopel instance

This backend doesn’t require an actual connection. Instead, it stores every message sent in the message_sent list.

You can use the rawlist() function to compare the messages easily, and the clear_message_sent() method to clear previous messages:

>>> from sopel.tests import rawlist, mocks
>>> backend = mocks.MockIRCBackend(bot=None)
>>> backend.irc_send(b'PRIVMSG #channel :Hi!\r\n')
>>> backend.message_sent == rawlist('PRIVMSG #channel :Hi!')
True
>>> backend.clear_message_sent()
[b'PRIVMSG #channel :Hi!\r\n']
>>> backend.message_sent
[]

See also

The parent class contains all the methods that can be used on this test backend.

clear_message_sent()#

Clear and return previous messages sent.

Returns:

a copy of the cleared messages sent

Return type:

list

New in version 7.1.

connected#

Convenient status flag.

Set to True to make the bot think it is connected.

irc_send(data)#

Store data into message_sent.

is_connected()#

Tell if the backend is connected or not.

message_sent#

List of raw messages sent by the bot.

This list will be populated each time the irc_send() method is used: it will contain the raw IRC lines the bot wanted to send.

You can clear this list with the clear_message_sent() method, or use the rawlist() function to compare it.

on_irc_error(pretrigger)#

Action to perform when the server sends an error event.

Parameters:

pretrigger – PreTrigger object with the error event

On IRC error, if bot.hasquit is set, the backend should close the connection so the bot can quit or reconnect as required.

run_forever()#

Run the backend forever (blocking call).

This method is responsible for initiating the connection to the server, and it must call bot.on_connect once connected, or bot.on_close if it fails to connect.

Upon successful connection, it must run forever, listening to the server and allowing the bot to use send_command() in a thread-safe way.

class sopel.tests.mocks.MockIRCServer(bot, join_threads=True)#

Fake IRC Server that can send messages to a test bot.

Parameters:

  • bot (sopel.bot.Sopel) – test bot instance to send messages to

  • join_threads (bool) – whether message functions should join running threads before returning (default: True)

This mock object helps developers when they want to simulate an IRC server sending messages to the bot.

The default join_threads behavior is suitable for testing most common plugin callables, and ensures that all callables dispatched by the bot in response to messages sent via this MockIRCServer are finished running before execution can continue. If set to False, the mock server will not wait for the bot to finish processing threaded callables before returning.

Note

You can override join_threads on a per-method-call basis with the blocking arguments to the instance methods below.

The IRCFactory factory can be used to create such mock object, either directly or by using pytest and the ircfactory() fixture.

New in version 7.1: The join_threads parameter.

channel_joined(channel, users=None, *, blocking=None)#

Send events as if the bot just joined a channel.

Parameters:

  • channel (str) – channel to send message for

  • users (list) – list (or tuple) of nicknames that will be present in the RPL_NAMREPLY event

  • blocking (bool) – whether to block until all triggered threads have finished (optional)

This will send 2 messages to the bot:

  • a RPL_NAMREPLY event (353), giving information about users present in channel

  • a RPL_ENDOFNAMES event (366) for completion

Use this to emulate when the bot joins a channel, and the server replies with the list of connected users:

factory.channel_joined('#test', ['Owner', '@ChanServ'])

In this example, the bot will know that there are 2 other users present in #test: “Owner” (a regular user) and “ChanServ” (which is a channel operator). Note that the bot itself will be added to the list of users automatically, and you should not pass it in the users parameter.

This is particularly useful to populate the bot’s memory of who is in a channel.

If blocking is True, this method will wait to join all running triggers’ threads before returning. Setting it to False will skip this step. If not specified, this MockIRCServer instance’s join_threads argument will be obeyed.

New in version 7.1: The blocking parameter.

See also

The join_threads argument to MockIRCServer.

Note

To add a user to a channel after using this method, you should use the join() method.

property chanserv#

ChanServ’s message prefix.

join(user, channel, *, blocking=None)#

Send a channel JOIN event from user.

Parameters:

  • user (MockUser) – factory for the user who joins the channel

  • channel (str) – channel the user joined

  • blocking (bool) – whether to block until all triggered threads have finished (optional)

This will send a JOIN message as if user just joined the channel:

factory.join(MockUser('NewUser'), '#test')

If blocking is True, this method will wait to join all running triggers’ threads before returning. Setting it to False will skip this step. If not specified, this MockIRCServer instance’s join_threads argument will be obeyed.

New in version 7.1: The blocking parameter.

See also

The join_threads argument to MockIRCServer.

See also

This function is a shortcut to call the bot with the result from the user factory’s join() method.

mode_set(channel, flags, users, *, blocking=None)#

Send a MODE event for a channel

Parameters:

  • channel (str) – channel receiving the MODE event

  • flags (str) – MODE flags set

  • users (list) – users getting the MODE flags

  • blocking (bool) – whether to block until all triggered threads have finished (optional)

This will send a MODE message as if ChanServ added/removed channel modes for a set of users. This method assumes the flags parameter follows the IRC specification for MODE:

factory.mode_set('#test', '+vo-v', ['UserV', UserOP', 'UserAnon'])

If blocking is True, this method will wait to join all running triggers’ threads before returning. Setting it to False will skip this step. If not specified, this MockIRCServer instance’s join_threads argument will be obeyed.

New in version 7.1: The blocking parameter.

See also

The join_threads argument to MockIRCServer.

pm(user, text, *, blocking=None)#

Send a PRIVMSG to the bot by a user.

Parameters:

  • user (MockUser) – factory for the user object who sends a message

  • text (str) – content of the message sent to the bot

  • blocking (bool) – whether to block until all triggered threads have finished (optional)

This will send a PRIVMSG message as forwarded by the server for a user sending it to the bot:

factory.pm(MockUser('NewUser'), 'A private word.')

If blocking is True, this method will wait to join all running triggers’ threads before returning. Setting it to False will skip this step. If not specified, this MockIRCServer instance’s join_threads argument will be obeyed.

New in version 7.1: The blocking parameter.

See also

The join_threads argument to MockIRCServer.

See also

This function is a shortcut to call the bot with the result from the user factory’s privmsg() method, using the bot’s nick as recipient.

say(user, channel, text, *, blocking=None)#

Send a PRIVMSG to channel by user.

Parameters:

  • user (MockUser) – factory for the user who sends a message to channel

  • channel (str) – recipient of the user’s PRIVMSG

  • text (str) – content of the message sent to the channel

  • blocking (bool) – whether to block until all triggered threads have finished (optional)

This will send a PRIVMSG message as if user sent it to the channel, and the server forwarded it to its clients:

factory.say(MockUser('NewUser'), '#test', '.shrug')

If blocking is True, this method will wait to join all running triggers’ threads before returning. Setting it to False will skip this step. If not specified, this MockIRCServer instance’s join_threads argument will be obeyed.

New in version 7.1: The blocking parameter.

See also

The join_threads argument to MockIRCServer.

See also

This function is a shortcut to call the bot with the result from the user’s privmsg() method.

class sopel.tests.mocks.MockUser(nick=None, user=None, host=None)#

Fake user that can generate messages to send to a bot.

Parameters:

  • nick (str) – nickname

  • user (str) – IRC username

  • host (str) – user’s host

The UserFactory factory can be used to create such mock object, either directly or by using pytest and the userfactory() fixture.

join(channel)#

Generate a JOIN command forwarded by the server for the user.

Parameters:

channel (str) – channel the user joined

Returns:

the JOIN command the server sends to its clients present in the same channel when the user joins it.

Return type:

str

property prefix#

User’s hostmask as seen by other users on the server.

When the server forwards a User’s command, it uses this prefix.

privmsg(recipient, text)#

Generate a PRIVMSG command forwarded by a server for the user.

Parameters:

  • recipient (str) – a channel name or the bot’s nick

  • text (str) – content of the message

Returns:

a PRIVMSG command forwarded by the server as if it originated from the user’s hostmask

Return type:

str