mx-tester 0.1.2

A tool to help test Matrix bots and Synapse modules.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75

# 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:


```sh
# 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:

```yaml
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.
```