关于

mx-tester 是一个正在开发中的工具，用于帮助测试Matrix机器人和Synapse模块。

mx-tester 做了以下事情

mx-tester 的工作流程如下

1. mx-tester build 为Synapse创建Docker镜像。如果您需要将自定义模块设置到Synapse中，您可以在这一步添加脚本以安装模块。
2. mx-tester up 在端口9999上启动Synapse。
3. mx-tester run 启动您的测试脚本。
4. mx-tester down 停止Synapse。

您可以通过插入脚本来自定义这些步骤中的每一个。

如果您使用 mx-tester 在已经设置好的项目上启动测试，您的工作流程可能只是

# 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

或者在单步中

$ mx-tester build up run down

设置 mx-tester。

mx-tester 需要一个配置文件，通常称为 mx-tester.yml。

它具有以下结构

name: A name for this test suite

# --- Configuring external components

up:
  # Optional. A script to be executed to prepare additional components
  # as part of `mx-tester up`.
  before:
    - # Optional. Script to be executed before bringinng up the image.
    - # Use this script e.g. to setup databases, etc.
  after:
    - # Optional. Script to be executed after bringing up the image.
    - # Use this script e.g. to setup bots.

down:
  # Optional. A script to be executed to clean up the environment,
  # typically to teardown components that were setup with `up`. This
  # script will be executed at the end of `mx-tester down`.
  success:
    - # Optional. A script to be executed only if `run` was a success.
    - # This script will ONLY be executed if `mx-tester` is called to
    - # execute both run and down, e.g. `mx-tester up run down`.
  failure:
    - # Optional. A script to be executed only if `run` was a failure.
    - # This script will ONLY be executed if `mx-tester` is called to
    - # execute both run and down, e.g. `mx-tester up run down`.
  finally:
    - # Optional. A script to be executed regardless of the result of `run`.
    - # This script will ALWAYS be executed if `mx-tester down` is called.

directories:
  # Optional. Directories to use for the test.
  root:
    # Optional. The root directory for this test.
    # All temporary files and logs are created as subdirectories of this directory.
    # Default: `mx-tester` in the platform's temporary directory.
    # May be overridden from the command-line with parameter `--root`.
    #
    # IMPORTANT: Some CI environments (e.g. Docker-in-docker aka dind) do not play
    # well with the platform's temporary directory. If you are running `mx-tester`
    # in such an environment, you should probably specify your root directory to
    # be in your (environment-specific) home-style directory (which may be your
    # build directory, etc.).
    #
    # Example: On GitLab CI, you should probably use `/builds/$CI_PROJECT_PATH`.

# --- Configuring the test

run:
  - # Optional. A script to be executed as `mx-tester run`.
  - # Use this e.g. to launch integration tests.

users:
  - # Optional. A list of users to create for the test.
  - # These users are created during `mx-tester up`.
  - # If the users already exist, they are not recreated.
  - localname:
    # Required. A name for the user.
    admin:
    # Optional. If `true`, the users should be an admin for the server.
    # Default: `false`.
    password:
    # Optional. If specified, a password for the user.
    # Default: "password".
    rate_limit:
    # Optional. If `unlimited`, remove rate limits for this user.
    # Default: Use the global setting for rate limits.
    rooms:
    - # Optional. A list of rooms to create.
    - public:
      # Optional. If `true`, the room should be public.
      # Default: `false`.
      name:
      # Optional. A name for the room.
      # Default: No name.
      alias:
      # Optional. An alias for the room.
      # Default: No alias.
      # If there is already a room with the same alias, the old alias will
      # be unregistered (we assume that this was caused by a previous call
      # to `mx-tester up`).
      # It several rooms define the same `alias` in the same mx-tester.yml,
      # this is an error.
      topic:
      # Optional. A topic for the room.
      # Default: No topic.
      members:
      # Optional. A list of users (created by `users`) to invite to the room.
      # mx-tester will ensure that these users join the room.
      # Default: No invites.


# --- Configuring the homeserver. Optional.

synapse:
  # Optionally, a version of Synapse.
  # If unspecified, pick the latest version available on Docker Hub.
  docker:
    # Required: A docker tag, e.g. "matrixdotorg/synapse:latest"

modules:
  # Optionally, a list of modules to install.
  - name: Name of a module you wish to setup
    build:
      # Required: A script to setup the module.
      # This may be as simple as copying the module from its directory
      # to $MX_TEST_MODULE_DIR.
      - # 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.
    install:
      # Optional. A script to install dependencies.
      # Typically, this will be something along the lines of
      # `pypi -r module_name/requirements.txt`
    config:
      # Required. Additional configuration information
      # to copy into homeserver.yaml.
      # This typically looks like
      # module: python_module_name
      # config:
      #   key: value
      #   key: value
      #   ...
  - # Other modules, if necessary.

homeserver:
  # Optional. Additional configuration for the homeserver.
  # Each of these fields will be copied into homeserver.yaml.
  # For more detail on the fields, see the documentation for homeserver.yaml.
  server_name:
    # Optional. The name of a homeserver.
    # By default, `localhost:9999`.
  public_baseurl:
    # Optional. The URL to communicate to the server with.
    # By default, `http://127.0.0.1:9999`.
  registration_shared_secret:
    # Optional. The registration shared secret.
    # By default, "MX_TESTER_REGISTRATION_DEFAULT".
  ...
    # Any other field to be copied in homeserver.yaml.

appservices:
  # Optional. Define Matrix Application Services to be connected
  # with your homeserver. For more details on AppServices, see
  # https://spec.matrix.org/v1.2/application-service-api .
  host:
    # Optional. Application Services whose process is running on
    # the host.
    name:
      # String. The name of the AppService. Each AppService on this
      # homeserver should have a distinct name.
    url:
      # String. The (local) URL at which to communicate with the AppService,
      # including a port number, e.g. "http://127.0.0.1:8765".
      # Note that the host is actually IGNORED.
    as_token:
      # Optional. String. If specified, a token used by the homeserver
      # when sending messages to the AppService.
      # By default, generate a random token automatically during `build`.
      # See the generated appservice file to determine its value.
    hs_token:
      # Optional. String. If specified, a token used by the AppService
      # when sending messages to the homeserver.
      # By default, generate a random token automatically during `build`.
      # See the generated appservice file to determine its value.
    sender_localpart:
      # String. The localpart of the userid of the user that will be
      # used when this AppService sends messages.
    namespaces:
      # The namespaces controlled or monitored by this AppService.
      users:
        # Optional. Empty by default.
        - regex:
            # A set of users to control or monitor.
            # Regex are matched against the full user id, including sigil
            # and homeserver name.
          exclusive:
            # Optional. Boolean. False by default.
            # If `true`, the AppService is in charge of all users whose
            # id matches the regex. Otherwise, the AppService will only
            # be informed of the actions of these users.
      rooms:
        # Optional. Empty by default.
        - regex:
            # A set of rooms to control or monitor.
            # Regex are matched against the full room id, including sigil
            # and homeserver name.
          exclusive:
            # Optional. Boolean. False by default.
            # If `true`, the AppService is in charge of all rooms whose
            # id matches the regex. Otherwise, the AppService will only
            # be informed of the actions in these rooms.
      aliases:
        # Optional. Empty by default.
        - regex:
            # A set of room alises to control or monitor.
            # Regex are matched against the full alias, including sigil
            # and homeserver name.
          exclusive:
            # Optional. Boolean. False by default.
            # If `true`, the AppService is in charge of all rooms whose
            # alias matches the regex. Otherwise, the AppService will only
            # be informed of the actions in these aliases.
  guest:
    # Optional. Application Services whose process is running on the guest.
    # Same fields as `host`.

# --- Additional resources. Optional.

copy:
  # Optional. Additional resources to copy.
  # Paths on the guest are relative to the guest root.
  # Paths on the host are relative to the directory from which mx-tester
  # is launched.
  # As of this writing, only individual files are copied, no globs or
  # subdirectories.
  # Guest directories are created if necessary.
  "/path/on/the/guest": "path/on/the/host"
  # ...

# --- Docker configuration. Optional.

docker:
  # Optional. Additional configuration for Docker.
  hostname:
    # Optional. The hostname to give to the Synapse container on the docker
    # network.
    # By default, "synapse".
  port_mapping:
    - # Optional. The docker port mapping configuration to use for the
    - # synapse container.
    - # By default:
    - # - host: 9999
    - # - guest: 8008

credentials:
  # Optional. Credentials to connect to a Docker registry,
  # as per `docker login`.
  # Typically useful to adapt mx-tester to your CI.
  username:
  # Optional. Specify a username to connect to the registry.
  # Default: No username.
  # May be overridden from the command-line with parameter `--username`/`-u`.
  password:
  # Optional. Specify a password to connect to the registry.
  # Default: No password.
  # May be overridden from the command-line with parameter `--password`/`-p`.
  serveraddress:
  # Optional. Specify a server to connect to the registry.
  # Default: No server.
  # May be overridden from the command-line with parameter `--server`.

# --- Worker configuration. Optional. CURRENTLY IGNORED.
workers:
  enabled:
  # A boolean. Specify `true` to launch Synapse with workers.
  # Default: No workers.
  # May be overridden from the command-line with parameter `--workers`.

调试

默认情况下，mx-tester 的输出非常少。

mx-tester 需要处理许多工具，每个工具都有自己的日志。为了帮助您调试，mx-tester 将所有这些日志存储在 /tmp/mx-tester/$(YOUR_PROJECT)/logs（或您平台上的等效目录）中。不要犹豫，查看它们吧：）

结构大致如下

• logs/
  • mx-tester/ 存储在 mx-tester.yml 中提供的脚本的日志
    • up.out、up.log up 脚本的日志。
    • run.out、run.log run 脚本的日志。
    • modules/ modules 中提供的 mx-tester.yml 中包含的 build 脚本的日志。
  • nginx/ 如果使用工作进程，则nginx负载均衡器的日志。
  • workers/ 如果使用工作进程，则每个工作进程的日志。
  • docker/ Docker中运行的所有内容的日志。
    • build.out、build.log 在 mx-tester build 步骤期间在虚拟机中执行的所有操作的日志。
    • up-run-down.out、up-run-down.log 在 mx-tester up、mx-tester run 和 mx-tester down 步骤期间在虚拟机中执行的所有操作的日志。

如果您希望在执行期间查看这些工具的所有输出，可以将 mx-tester 的调用前缀如下

$ RUST_LOG=debug,bollard=error mx-tester run # and/or build, up, down...

Docker 注意事项

所有操作都在 Docker 中执行，具有相同的限制和抽象泄漏。

主机 host.docker.internal 应在所有平台上配置，这样虚拟机 Synapse（以及模块）就可以访问主机，如果需要用于测试。

虚拟机容器运行在名为 mx-tester-synapse-$(TAG) 的网络上，其中 TAG 是 Synapse 运行版本的 Docker 标签。默认情况下，这是 matrixdotorg/synapse:latest。

Synapse 注意事项

速率限制

从版本 0.3.3 开始，默认情况下，mx-tester 大幅扩展了 Synapse 的速率限制。我们假设这是许多测试的首选行为。

如果您不想扩展速率限制，需要在 mx-tester.yml 的 homeserver 部分中覆盖它们，例如

homeserver:
  # ...
  rc_login: synapse-default # Restores the Synapse default