Contributing

Setup your environment

We recommend using venv to keep your development environment isolated from your base Python environment. It is part of Python by default.

1. Clone the mmpy_bot repository, setup your virtual environment and install the requirements:

   $ git clone https://github.com/attzonko/mmpy_bot.git
   $ cd mmpy_bot
   $ python3 -m venv venv
   $ source venv/bin/activate
   $ pip install -e ".[dev]"
   

2. Spin up the Mattermost container (Podman or Docker required):

   $ podman-compose -f tests/integration_tests/docker-compose.yml up -d
   

3. In order to run the bot, it is advised to use an entrypoint Python file which defines your Mattermost server and bot account settings, as well as importing any custom plugins you may create. See the provided entrypoint.py as a reference. To run your bot inside a docker container (not necessary, you can also just run python entrypoint.py) you can use the provided docker-compose file.

Testing

mmpy_bot develops all tests based on pytest. If you need to add your own tests and run tests, please install the dev requirements.

$ pip install -r dev-requirements.txt

All the tests are put in mmpy_bot\tests. There are two test packages: unit_tests and integration_tests.

Tests which can be performed by a single bot without requiring a server or interaction with other bots should be kept in the unit_tests package. Tests that require interactions between bots on a mattermost server belong to the integration_tests package.

Adding unit tests

There are multiple test modules inside unit_tests package, one for each module in the code. The naming convention of these modules is modulename_test. Inside each module, there will be several test functions with naming convention test_methodname, grouped into classes for each corresponding class in the code. If you need to add more unit tests, please consider following these conventions.

Running the unit tests

To run the unit tests (in parallel), simply execute:

$ pytest -n auto tests\unit_tests

Adding integration tests

The integration tests are run on the jneeven:mattermost-bot-test docker image, for which dockerfiles are provided in the tests/intergration_tests folder. The tests are defined as interactions between a bot (the responder) and a driver (the one sending test messages), which live inside the docker image. Their respective tokens are available in tests/integration_tests/utils.py, and the two bots are available as pytest fixtures so they can be easily re-used. Note that while the bot is also a fixture, it should not be used in any functions. It will simply be started whenever the integration tests are executed.

An integration test might look like this (also have a look at the actual code in tests/integration_tests/test_example_plugin.py):

from tests.integration_tests.utils import start_bot  # noqa, only imported so that the bot is started
from tests.integration_tests.utils import MAIN_BOT_ID, OFF_TOPIC_ID, RESPONSE_TIMEOUT, TEAM_ID
from tests.integration_tests.utils import driver as driver_fixture
from tests.integration_tests.utils import expect_reply

# Hacky workaround to import the fixture without linting errors
driver = driver_fixture

# Verifies that the bot is running and listening to this non-targeted message
def test_start(driver):
    post = driver.create_post(OFF_TOPIC_ID, "starting integration tests!")
    # Checks whether the bot has sent us the expected reply
    assert expect_reply(driver, post)["message"] == "Bring it on!"

In this test, the driver sends a message in the “off-topic” channel, and waits for the bot to reply ‘Bring it on!’. If no reply occurs within a default response timeout (15 seconds by default, but this can be passed as an argument to expect_reply), an exception will be raised. The driver fixture is imported from the utils and can be re-used in every test function simply by adding it as a function argument.

Running the integration_tests

Running the integration_tests is easy: simply cd into tests/integration_tests, and run docker-compose up -d to start a local mattermost server. Then run pytest -n auto . to start the tests! For more info about the integration tests an the docker server, have a look at tests/integration_tests/README.md.

Test coverage:

Install pytest-cov:

$ pip install pytest-cov

Set necessary configuration as described above, and run:

$ py.test --cov=mmpy_bot tests\

It automatically runs tests and measures code coverage of modules under mmpy_bot root dir. Using “–cov-report” parameter to write report into “cov_html” folder by html format.

py.test --cov-report html:logs\cov_html --cov=mmpy_bot tests\