About

mx-tester is a WIP tool to help test Matrix bots and Synapse modules.

What mx-tester does

The flow of mx-tester is the following:

1. mx-tester build Create a Docker image for Synapse. If you need your Synapse to be setup with custom modules, you add scripts to this step to install the modules.
2. mx-tester up Launch Synapse on port 9999.
3. mx-tester run Launch your test script.
4. mx-tester down Stop Synapse.

You may customize each of these steps by inserting scripts.

If you are using mx-tester to launch tests on a project that has already been setup, your flow is probably simply:

# Setup and launch Synapse, modules, bots, ...
$ mx-tester build
$ mx-tester up
# Launch the tests. Repeat as many times as needed, as you fix tests or your code.
$ mx-tester run
# Once you're done testing
$ mx-tester down

Setting up mx-tester.

mx-tester requires a configuration file, typically called mx-tester.yml.

It has the following structure:

name: A name for this test suite
homeserver_config:
  # A yaml subtree specifying configuration options for Synapse.
  #
  # This uses the exact same syntax as homeserver.yaml.
  #
  # If you make use of modules, it MUST contain an entry `modules`,
  # as per https://github.com/matrix-org/synapse/blob/develop/docs/modules.md
modules:
  - name: Name of a module you wish to setup
    build: # A script to setup the module.
      - # This script MUST copy the source code of the module
      - # to directory $MX_TEST_MODULE_DIR
      - # ...
      - # env: MX_TEST_MODULE_DIR -- where the module should be copied
      - # env: MX_TEST_SYNAPSE_DIR -- where Synapse source lies
      - # env: MX_TEST_SCRIPT_TMPDIR -- a temporary directory where the test can
      - #   write data. Note that `mx-tester` will NOT clear this directory.
      - # env: MX_TEST_CWD -- the directory in which the test was launched.
  - # Other modules, if necessary.
up: # Optionally, a script to be executed at the end of `mx-tester up`
  - # Use this script e.g. to setup additional components, such as bots.
  -
  - # env: MX_TEST_SCRIPT_TMPDIR -- a temporary directory where the test can
  - #   write data. Note that `mx-tester` will NOT clear this directory.
  - # env: MX_TEST_CWD -- the directory in which the test was launched.
run: # Optionally, a script to be executed as `mx-tester run`
  - # Use this script e.g. to start your tests.
  - # env: MX_TEST_SCRIPT_TMPDIR -- a temporary directory where the test can
  - #   write data. Note that `mx-tester` will NOT clear this directory.
  - # env: MX_TEST_CWD -- the directory in which the test was launched.
down: # Optionally, a script to be executed at the start of `mx-tester down`
      # Use this script e.g. to teardown additional components, such as bots.
    success: # Optionally, a script to be executed if `run` was a success. -- NOT IMPLEMENTED YET
    failure: # Optionally, a script to be executed if `run` was a failure. -- NOT IMPLEMENTED YET
    finally: # Optionally, a script to be executed regardless of the result of `run`.
      - # env: MX_TEST_SCRIPT_TMPDIR -- a temporary directory where the test can
      - #   write data. Note that `mx-tester` will NOT clear this directory.
      - # env: MX_TEST_CWD -- the directory in which the test was launched.