Rocket.Chat 联邦（Federation）端到端测试指南：基于 Playwright 的跨 Matrix 实例测试体系

本篇指南围绕仓库中 apps/meteor/tests/e2e/federation/README.md 展开，系统讲解 Rocket.Chat 联邦（Federation）能力所配套的 Playwright 端到端（E2E）测试体系：如何准备两个（甚至三个）相互隔离的 Rocket.Chat 实例与 Matrix 域名、如何通过一条环境变量命令拉起整套跨服务器测试，以及速率限制（Rate Limiter）等前置条件为什么必不可少。读完本文，你将能独立复现联邦场景下频道、私聊、消息、线程与管理后台的自动化验证流程，并理解其底层测试基建的实现原理。

一、背景：为什么需要"跨实例"的联邦 E2E 测试

Rocket.Chat 的联邦能力使其不同服务器之间能够基于 Matrix 协议互联互通，例如 A 服务器的用户可以直接与 B 服务器的用户私聊、拉人进频道。这类跨进程、跨域名的行为用单实例单元测试很难覆盖真实链路，因此仓库在 apps/meteor/tests/e2e/federation 目录下维护了一套独立的 Playwright E2E 套件，用真实浏览器驱动两个（或更多）Rocket.Chat 站点完成交互级验证。

围绕该功能，仓库还提供了配套的 Matrix 联邦测试编排脚手架（如 ee/packages/federation-matrix 下的 docker-compose.test.yml），E2E 用例假设测试环境已经存在可互通的联邦服务器与各自独立的 Matrix homeserver 域名。

二、测试套件全景：目录结构与运行入口

联邦 E2E 套件位于 apps/meteor/tests/e2e/federation，内部按职责划分清晰：

目录 / 文件	职责
config/global-setup.ts	Playwright 全局启动钩子，校验全部必需环境变量
config/constants.ts	把 RC_SERVER_* 环境变量解析为服务器配置对象
utils/test.ts	扩展 Playwright test，注入 apiServer1 / apiServer2 两个 REST API fixture，并提供 setupTesting / tearDownTesting 环境开关
utils/auth.ts	页面级登录助手 doLogin，支持保存登录态（storageState）
utils/register-user.ts	通过 REST 接口批量注册新用户
utils/format.ts	把用户名与域名格式化为 Matrix 完整 ID（@user:domain）
utils/channel.ts	频道创建与跨服邀请等复合操作
page-objects/	面向对象封装（admin.ts、channel.ts 及各 UI 区域 fragment）
tests/	按功能域组织的 spec 用例
files/	视频/音频/图片/PDF 等测试媒体素材

运行入口在 apps/meteor/package.json 中定义：

"test:e2e:federation": "playwright test --config=playwright-federation.config.ts"

即通过专门的 playwright-federation.config.ts 运行，而不是默认的 playwright.config.ts。

三、运行联邦 E2E 测试：环境变量与启动命令

原文档给出的核心启动方式是在仓库根目录（或 apps/meteor 下）为测试进程注入两组服务器配置，再调用 yarn run test:e2e:federation：

$ RC_SERVER_1=http://localhost:3000 RC_SERVER_1_ADMIN_USER=test RC_SERVER_1_ADMIN_PASSWORD=test RC_SERVER_1_MATRIX_SERVER_NAME=my.matrix.server \
RC_SERVER_2=http://localhost:3000 RC_SERVER_2_ADMIN_USER=test2 RC_SERVER_2_ADMIN_PASSWORD=test RC_SERVER_2_MATRIX_SERVER_NAME=my2.matrix.server \
yarn run test:e2e:federation

3.1 每个环境变量控制什么

对照 config/constants.ts 的映射逻辑，可以精确理解每条变量的语义：

环境变量	用途	备注
RC_SERVER_1 / RC_SERVER_2	两台 Rocket.Chat 实例的 HTTP 访问地址	代码中默认回退为 http://localhost:3000
RC_SERVER_1_ADMIN_USER	实例 1 的管理员账号	用于 REST 登录与后续管理操作
RC_SERVER_1_ADMIN_PASSWORD	实例 1 的管理员密码
RC_SERVER_1_MATRIX_SERVER_NAME	实例 1 所属 Matrix homeserver 域名	参与构造联邦用户完整 ID
RC_SERVER_2_ADMIN_USER / RC_SERVER_2_ADMIN_PASSWORD	实例 2 的管理员凭据
RC_SERVER_2_MATRIX_SERVER_NAME	实例 2 所属 Matrix 域名
RC_EXTRA_SERVER 及 RC_EXTRA_SERVER_ADMIN_USER/PASSWORD/MATRIX_SERVER_NAME	预留的第三个测试实例	供需要三实例才能覆盖的场景使用

MATRIX_SERVER_NAME 并非直接用于页面跳转，而是作为联邦域后缀：用例通过 utils/format.ts 将普通用户名拼装为 Matrix 全量用户名——formatUsernameAndDomainIntoMatrixFormat(username, domain) 产出 user:domain，formatIntoFullMatrixUsername 再补充 @ 前缀得到 @user:domain。例如实例 2 的用户 abc 在实例 1 侧会被表示为 @abc:my2.matrix.server。

3.2 环境变量校验：global-setup 会强制拦截

原文档示例只覆盖了两台服务器的 8 个变量，但当前的全局启动钩子 config/global-setup.ts 实际校验的变量多达 12 个——在示例之外还必须提供 RC_EXTRA_SERVER、RC_EXTRA_SERVER_ADMIN_USER、RC_EXTRA_SERVER_ADMIN_PASSWORD、RC_EXTRA_SERVER_MATRIX_SERVER_NAME。若任一缺失，Playwright 会在启动阶段抛出：

Missing required environment variables: ...

因此在实际执行时（尤其是用较新版本仓库跑用例），建议把示例命令补齐为同时携带 RC_EXTRA_SERVER 三件套的完整写法，避免 global-setup 直接终止运行。

四、被 README 特别标注的前置条件：注册接口速率限制

原文档以 "Important" 单独强调了一个高频踩坑点：

请在 管理（Admin）=> Rate Limiter（速率限制）=> Feature limiting（功能限制）中提高"用户注册接口"的速率限制上限。这是必须的，因为测试会用程序化方式批量注册新用户。

这条提示与源码中的实测逻辑完全吻合：utils/test.ts 的 setupTesting 会通过 REST 设置接口一次性关闭/放宽测试期间的各类限流，并在结束后用 tearDownTesting 恢复默认值：

• 关闭 API 级限流：API_Enable_Rate_Limiter=false，并将 Rate_Limiter_Limit_RegisterUser 调高到 10；
• 关闭 DDP 层的 IP / 用户 / 连接维度的限流开关（如 DDP_Rate_Limit_IP_Enabled=false）；
• 关闭 Accounts_ManuallyApproveNewUsers（新用户免人工审批），并把注册表单设为 Accounts_RegistrationForm='Public'，保证 /users.register 接口可被匿名调用；
• 测试结束后 tearDownTesting 会将上述开关逐一还原（注册限流回到 1、注册表单回到 Disabled、审批回到开启）。

由此可见，无论走后台界面手调，还是依赖用例内嵌的 setupTesting，"放开注册限流"都是联邦套件能跑起来的前提——大量用例都需要临时造出对方服务器上的全新用户。

五、测试基建如何运转：从配置到用例的完整链路

5.1 专用 Playwright 配置

与通用 E2E 不同，联邦套件使用 playwright-federation.config.ts，几个关键设计值得注意：

• globalSetup 指向联邦套件自带的 config/global-setup.ts，用于在用例开始前统一校验环境变量；
• testDir: 'tests/e2e/federation' 限定只执行联邦目录下的用例；
• workers: 1 串行执行，retries: 2 自动重试失败用例，timeout: 60 * 2000（即 120 秒/用例），充分照顾跨服务器同步的慢链路；
• headless: true + channel: 'chrome' 使用真实 Chrome（需本机装有 Chrome）；
• 启动参数中通过 --use-gl=egl 强制启用 GPU 加速（headless 下也生效），并通过 --use-file-for-fake-video-capture=tests/e2e/federation/files/video_mock_for_webcam.y4m 与 --use-file-for-fake-audio-capture=files/audio_mock.wav 注入伪造的摄像头/麦克风输入流——这正是 files 目录中媒体素材的用途；
• trace: 'retain-on-failure'、screenshot: 'only-on-failure'，失败产物输出到 outputDir: 'tests/e2e/.playwright'。

5.2 服务器配置对象

config/constants.ts 将环境变量封装为 RC_SERVER_1、RC_SERVER_2、RC_EXTRA_SERVER 三个配置对象，每个都含 url / username / password / matrixServerName 四个字段，供页面导航、REST 登录与联邦 ID 拼装三处共用。

5.3 REST 层 fixture：apiServer1 / apiServer2

utils/test.ts 基于 Playwright 的 request fixture 扩展出 apiServer1 / apiServer2：先用管理员账号向登录接口发起请求换取 data.authToken 与 data.userId，再封装出携带 X-Auth-Token、X-User-Id 请求头的 get/post/put/delete 方法。这样 spec 就能用"管理 API 直调 + 浏览器 UI 操作"双通道来搭建与断言跨服场景。

5.4 用户注册与登录

• utils/register-user.ts：用 faker 生成 UUID 用户名，POST 到 /users.register，邮箱形如 <uuid>@test-rc.com，返回新用户名——这就是 README 中"程序化注册新用户"的具体实现；
• utils/auth.ts：doLogin 打开 <url>/login，按 role=textbox[name=/username/i] 与 [name=password] 定位输入框完成登录；开启 storeState 时会把会话落盘为 <storageNamePrefix>-session.json，用于多页面复用登录态。

5.5 Page Object 封装

UI 操作被收敛进 page-object 层。以 page-objects/channel.ts 为例，FederationChannel 组合了内容区（content）、侧边栏（sidenav）、顶栏（navbar）、侧拉面板（tabs）等多个 fragment，并提供语义化动作如 createPublicChannelAndInviteUsersUsingCreationModal（创建联邦公共频道并邀请远端用户）、createPrivateGroupAndInviteUsersUsingCreationModal（私有群组）等；还能通过 [data-qa="federated-origin-server-name"] 读取当前房间所属的联邦来源服务器名。fragment 型 page object 放在 page-objects/fragments/ 下，与通用 E2E 套件复用。

六、测试覆盖范围：跨服功能用例一览

联邦用例按被测能力组织在 tests/ 下，可在 tests 目录逐一查阅：

用例目录	覆盖能力
channel/public.spec.ts	联邦公共频道的创建、跨服成员管理、订阅与访客场景
channel/private.spec.ts	私有群组/私有频道在联邦场景下的可见性与成员权限
channel/dm.spec.ts	直接消息：邀请"对方服务器尚不存在"的用户、跨服 DM 收发等（对 Matrix 域名的使用最密集）
messaging/public/private/dm.spec.ts	公共/私有/DM 房间内的跨服消息发送、编辑、删除与引用
messaging/threads.spec.ts	跨服务器环境下的消息线程（thread）行为
admin/rooms.spec.ts、admin/users.spec.ts	管理员视角对联邦房间与远程用户的统一管理
user-account/user.spec.ts	普通用户在联邦配置下的账号侧行为
ce-version/ce.spec.ts	社区版（Community Edition）下联邦能力的边界验证

以 tests/channel/dm.spec.ts 为例，可以看到一套典型的跨服用例模板：beforeAll 中先对两台服务器执行 setupTesting(apiServer1/apiServer2)，再各自 registerUser 注册远端用户，随后用 formatIntoFullMatrixUsername(user, matrixServerName) 拼出完整联邦 ID 并完成邀请前置；每个测试用例再通过 doLogin 与 page object 完成 UI 驱动；afterAll 统一调用 tearDownTesting 还原配置。这从用例层印证了前面 README 提到的限流与注册设置为何是关键前提。

七、失败排查与产物解读

套件为联邦类慢链路做了工程化兜底：

• 单用例失败会自动重试 2 次（retries: 2），降低跨服时序抖动导致的偶发失败；
• 失败时保留 Playwright trace（retain-on-failure）与页面截图，统一输出到 tests/e2e/.playwright 目录，可用 npx playwright show-trace 打开 trace 逐帧回放操作与网络请求；
• 全局 workers: 1 意味着多实例测试共享同一浏览器/服务器状态时不会互相抢占资源。

排查时优先核对三点：是否按 global-setup 要求补齐了全部 12 个环境变量；两套实例的 MATRIX_SERVER_NAME 是否与各自 Matrix homeserver 实际域名一致（否则拼出的 @user:domain 无法路由）；测试实例的注册接口限流是否已放开。

八、总结

这套联邦 E2E 体系的价值在于：用"双实例 + 真实浏览器 + REST 通道"完整复现了 Rocket.Chat 跨 Matrix 服务器的核心链路——建房间、邀请远端用户、跨服消息/线程、管理员治理。原文档虽短，但它的两条核心信息（多服务器环境变量启动方式、注册接口限流注意事项）分别对应着 global-setup 的强校验与 setupTesting/tearDownTesting 的配置自动切换。理解这层关系后，无论是本地复现、CI 接入还是扩展新的联邦用例，都能直接对照 apps/meteor/tests/e2e/federation 目录下的源码与 playwright-federation.config.ts 配置快速定位。