Factories

Test factories: they create objects for testing purposes.

Added in version 7.0.

Important

These factories are documented to help plugin authors to use them. However Sopel recommends the usage of pytest and provides a set of fixtures to get properly configurated factories in sopel.tests.pytest_plugin, instead of trying to instanciate the factories manually.

class sopel.tests.factories.BotFactory

Factory to create bots.

An instance of this factory can be used as a callable to create an instance of Sopel with a fake connection backend. It requires an instance of Config, which can be obtained through the ConfigFactory.

See also

The botfactory() fixture can be used to instantiate this factory.

See also

The created instance will use the MockIRCBackend which does not generate network activity and stores messages sent by the bot in-memory.

Note

The created instance does not connect to an external server: it uses a fake backend (MockIRCBackend), that implements the same interface but stores the messages in-memory instead of sending them through the wire. This allows plugin authors to inspect messages sent by the bot.

__call__(settings: Config) → Sopel

Create a test bot with a fake backend without any plugins.

Parameters:

settings – test settings used by the test bot

Returns:

an instance of Sopel ready for use in tests

This factory creates an instance of Sopel using the settings provided and a fake backend which collects all messages sent by the bot.

See also

The created instance will use the MockIRCBackend which does not generate network activity and stores messages sent by the bot in-memory.

preloaded(
settings: config.Config,
preloads: Iterable[str] | None = None,
) → bot.Sopel

Create a test bot with a fake backend and preload its plugins.

Parameters:

  • settings – Sopel’s configuration for testing purposes

  • preloads – list of plugins to preload, setup, and register

Returns:

a test instance of the bot

This method will create an instance of Sopel using the settings provided and a fake backend which collects all messages sent by the bot.

This will automatically load the coretasks plugin, and every other plugin from preloads:

factory = BotFactory()
bot = factory.preloaded(settings, ['emoticons', 'remind'])

See also

The created instance will use the MockIRCBackend which does not generate network activity and stores messages sent by the bot in-memory.

Note

This will automatically setup plugins: be careful with plugins that require access to external services or network connectivity during setup.

You may also need to manually call shutdown routines for the loaded plugins once the tests are concluded.

class sopel.tests.factories.ConfigFactory(tmpdir: pathlib.Path)

Factory to create settings.

Parameters:

tmpdir – a test folder to store documentation files

An instance of this factory can be used as a callable to create an instance of Config.

Changed in version 8.1: This factory used to depend on pytest’s fixture tmpdir, but is now using Python’s standard pathlib.Path instead.

See also

The configfactory() fixture can be used to instantiate this factory.

__call__(name: str, data: str) → Config

Call the factory with the settings to create.

Parameters:

  • name – filename of the configuration file; should end with the .cfg file extension

  • data – settings content as per Sopel’s configuration file format

Returns:

an instance of test configuration

class sopel.tests.factories.IRCFactory

Factory to create mock IRC servers.

An instance of this factory can be used as a callable to create an instance of sopel.tests.mocks.MockIRCServer. It requires an instance of Sopel, which can be obtained through the BotFactory.

See also

The ircfactory() fixture can be used to create this factory.

__call__(
mockbot: Sopel,
join_threads: bool = True,
) → MockIRCServer

Call the factory with a test bot to return a test server.

Parameters:

  • mockbot – a test instance of Sopel

  • join_threads – an optional flag to wait on running triggers (defaults to True)

Returns:

an instance of a test server

class sopel.tests.factories.TriggerFactory

Factory to create triggers.

An instance of this factory can be used as a callable to create an instance of sopel.trigger.Trigger. It requires an instance of Sopel, which can be obtained through the BotFactory, as well as the trigger’s content.

See also

The triggerfactory() fixture can be used to instantiate this factory.

__call__(
mockbot: Sopel,
raw: str,
pattern: str | None = None,
) → Trigger

Call the factory with a test bot to return a test trigger message.

Parameters:

  • mockbot – a test instance of Sopel

  • raw – the raw trigger’s content

  • pattern – an optional regex pattern (default to .*)

Returns:

an instance of a test trigger

wrapper(
mockbot: Sopel,
raw: str,
pattern: str | None = None,
) → SopelWrapper

Create a trigger and return a wrapped instance of Sopel.

Parameters:

  • mockbot – a test instance of Sopel

  • raw – the raw trigger’s content

  • pattern – an optional regex pattern (default to .*)

Returns:

a wrapped instance of Sopel with the created trigger

This method is a shortcut over calling the factory to create a trigger and get an instance of SopelWrapper with it.

class sopel.tests.factories.UserFactory

Factory to create mock users.

An instance of this factory can be used as a callable to create an instance of sopel.tests.mocks.MockUser. It requires the information of the test user such as its nick, account, and hostname.

See also

The userfactory() fixture can be used to create this factory.

__call__(
nick: str | None = None,
user: str | None = None,
host: str | None = None,
) → MockUser

Call the factory with a nick to create a test user.

Parameters:

  • nick – a user’s nick

  • user – a user’s account

  • host – a user’s hostname

Returns:

an instance of a test user