matrixdotorg/sytest-dendrite

SyTest

概述

SyTest是Matrix homeserver实现的集成测试系统，目前主要针对Synapse服务器。它采用"黑盒"测试方式，通过启动多个homeserver实例，并使用常规HTTP交互（类似其他Matrix客户端）测试实例间的交互。测试结果可输出到交互式终端或TAP风格报告，适用于Jenkins等持续集成工具。

核心功能和特性

• 黑盒测试：无需了解homeserver内部实现，通过外部HTTP交互验证功能
• 多实例测试：支持启动多个homeserver实例，测试实例间的交互场景
• 灵活的结果输出：可输出到交互式终端或生成TAP风格报告，适配CI/CD流程
• 插件支持：允许通过插件扩展功能，支持自定义Homeserver和Output实现
• Postgres优化：支持使用模板数据库加速测试数据库创建

使用场景和适用范围

• 测试Matrix homeserver实现（尤其是Synapse）的功能正确性
• 验证homeserver在多实例环境下的交互行为
• 集成到持续集成流程中，自动化验证代码变更对homeserver的影响

安装与配置

系统依赖

在Ubuntu/Debian系统上，需安装以下原生依赖：

bash
sudo apt install libpq-dev build-essential

Perl环境配置

SyTest依赖Perl模块，需先配置Perl环境（非root用户）：

1. 编辑.profile文件，添加以下环境变量：

   bash
   export PERL5LIB=$HOME/lib/perl5
   export PERL_MB_OPT=--install_base=$HOME
   export PERL_MM_OPT=INSTALL_BASE=$HOME
   

2. 使配置生效：

   bash
   source ~/.profile
   

3. 首次运行cpan进行初始化配置：

   bash
   cpan
   

   提示配置时选择"yes"进行自动配置，完成后输入exit退出。

获取源码与安装依赖

1. 获取SyTest源码并安装依赖：

   bash
   git clone https://github.com/matrix-org/sytest
   cd sytest
   ./install-deps.pl
   cd ..
   

2. 获取Synapse源码（默认期望在同级目录synapse中）：

   bash
   pip install pynacl --user  # 解决pynacl目录排序问题
   git clone https://github.com/matrix-org/synapse
   cd synapse
   git checkout develop
   python setup.py develop --user
   python setup.py test
   cd ..
   

   注意：Synapse无需安装，SyTest将直接从源码目录运行

macOS系统安装注意事项

1. 使用Homebrew安装libsodium：

   bash
   brew install libsodium
   

2. 验证libsodium是否被正确识别：

   bash
   pkg-config --libs libsodium
   

   预期输出类似：-L/usr/local/Cellar/libsodium/1.0.8/lib -lsodium

3. 强制安装Perl模块：

   bash
   cpan
   cpan> force install Crypt::NaCl::Sodium
   cpan> force install Shell::Guess
   

4. 手动安装DBI后再安装DBD::Pg，避免依赖错误：

   bash
   cpan> install DBI
   cpan> install DBD::Pg
   

5. 运行依赖安装脚本：

   bash
   ./install-deps.pl
   

使用方法

基本运行

默认配置下，直接运行测试脚本：

bash
cd sytest
./run-tests.pl

指定Synapse目录

若Synapse源码不在同级目录，使用--synapse-directory指定路径：

bash
./run-tests.pl --synapse-directory /home/synapse/synapse

指定Python解释器

如需使用特定Python环境（如虚拟环境），通过--python指定：

bash
./run-tests.pl --python ../synapse/env/bin/python

注意：若运行时出现ModuleNotFoundError: No module named 'synapse'，需激活Synapse虚拟环境：

bash
source ../synapse/env/bin/Activate

日志与调试

• 打印HTTP请求和响应（-C为简写）：

  bash
  ./run-tests.pl --client-log
  # 或
  ./run-tests.pl -C
  

• 打印Synapse服务器错误日志（-S为简写）：

  bash
  ./run-tests.pl --server-log
  # 或
  ./run-tests.pl -S
  

运行指定测试文件

仅运行特定测试文件中的用例，将文件路径作为参数：

bash
./run-tests.pl tests/20profile-events.pl

日志配置

创建符合dictConfig格式的YAML日志配置文件（可从运行中的Synapse复制），命名为log.config，放置于homeserver配置目录（localhost-<port>）。

测试黑名单

使用黑名单文件标记预期失败的测试（失败不会导致整个测试套件失败），通过-B指定：

bash
./run-tests.pl -B synapse/sytest-blacklist

插件扩展

SyTest支持通过插件扩展功能，插件需遵循与SyTest相同的项目结构，包含以下目录：

• lib/SyTest/HomeserverFactory
• lib/SyTest/Homeserver
• lib/SyTest/Output

默认插件目录为sytest/plugins，可通过SYTEST_PLUGINS环境变量指定自定义路径。示例插件：https://github.com/valkum/sytest_conduit

开发指南

有关SyTest本身的开发（维护或编写新测试），请参考源码中的DEVELOP.rst文件。

Postgres模板数据库优化

使用Postgres测试时，SyTest会检查是否存在sytest_template数据库，若存在则以此为模板创建测试数据库，大幅减少数据库创建时间。

创建模板数据库的简易方法：启动一个指向该数据库的homeserver，待数据库创建完成后停止服务。