深入解析 Truffle Dashboard Message Bus 端到端测试包:@truffle/dashboard-message-bus-e2e-test 架构与实践
深入解析 Truffle Dashboard Message Bus 端到端测试包:@truffle/dashboard-message-bus-e2e-test 架构与实践
导读
@truffle/dashboard-message-bus-e2e-test 是 Truffle monorepo 中一个**不对外发布(private)**的测试专用包,它的使命是在真实进程环境中端到端(e2e)验证 @truffle/dashboard-message-bus(消息总线)与 @truffle/dashboard-message-bus-client(消息总线客户端)的完整通信链路——从发布消息、订阅消费、回复响应,到结合 Ganache 与 ethers.js / web3.js 的 Dashboard RPC 代理场景。阅读本文后,你将理解:为什么官方要单独抽出一个私有包来跑 e2e 测试(而不是放在被测试包内部)、该包的测试基建与运行方式、三类核心测试各自验证了什么,以及消息总线底层基于双 WebSocket 服务器的发布/订阅机制是如何被这些测试逐一覆盖的。
为什么需要独立的私有 e2e 测试包
循环依赖问题
在 Truffle 的包结构中,@truffle/dashboard-message-bus 负责管理 Dashboard 与其他 Truffle 组件之间的通信(通过专门的代理 RPC 服务器),而 @truffle/dashboard-message-bus-client 则是连接这条消息总线的客户端库,二者是"服务端 ↔ 客户端"的耦合关系。如果直接在其中一个包内部编写针对另一个包的测试,就会形成包之间的循环依赖,这在 monorepo 的发布与依赖解析中会引入不必要的复杂性。
包 README 明确说明了设计动机:
This is a private package that's used to run e2e tests of
@truffle/dashboard-message-busand@truffle/dashboard-message-bus-client. Having these tests in a separate (unpublished) package makes it so that we can test both the message bus and client without having a circular dependency.
即:把测试放到一个独立的、不发布的包中,让消息总线和客户端可以被放在一起测试,同时避免循环依赖。这正是 monorepo 中针对"相互依赖的两个模块"做集成/端到端测试的经典做法。
包定位与依赖关系
从 package.json 可以看到它的关键元信息:
name:@truffle/dashboard-message-bus-e2e-test,且"private": true,不会发布到 npm;scripts.test:jest --verbose——所有测试统一通过 Jest 驱动,并以 verbose 模式输出;- 核心 devDependencies 包括:
@truffle/dashboard、@truffle/dashboard-message-bus、@truffle/dashboard-message-bus-client、@truffle/dashboard-message-bus-common、ganache、ethers、web3、jest、ts-jest等; engines要求node ^16.20 || ^18.16 || >=20。
可见该测试包把消息总线、消息总线客户端、公共消息类型、以及真正的 Dashboard 服务端全部作为 devDependencies 引入,从而可以在一个独立的"测试沙箱"里模拟真实的使用场景。而 jest --verbose 配合 jest.setTimeout 的长超时设置,说明这些测试会真实地启动 WebSocket 服务与本地以太坊节点,属于名副其实的端到端测试。
测试基建:Jest 与 TypeScript 配置
Jest 配置
jest.config.js 定义了测试的运行环境与匹配规则:
module.exports = {
moduleFileExtensions: ["js", "json", "node", "ts"],
testEnvironment: "node",
globals: {
"ts-jest": {
tsconfig: "<rootDir>/tsconfig.json",
diagnostics: true
}
},
testMatch: [
"<rootDir>/@(lib|test)/**/*.@(test|spec).@(ts|js)",
"<rootDir>/@(lib|test)/**/test/*.@(ts|js)"
],
preset: "ts-jest"
};
几个值得注意的要点:
testEnvironment: "node":这些测试运行在 Node.js 环境(而非 jsdom),因为要真实创建 WebSocket 服务器、HTTP 服务与以太坊 provider;preset: "ts-jest"+diagnostics: true:测试代码以 TypeScript 编写并即时编译,且开启了类型诊断;testMatch:测试文件位于test目录下,命名遵循*.test.ts约定。
TypeScript 配置
tsconfig.json 中 rootDir 指向 test,include 仅包含 ./test/**/*.ts,types 只包含 jest 与 node,说明整个包就是纯粹为测试服务的:源码即测试,测试即源码。
运行方式
按 README 与 package.json 的说明,所有测试集中在 test 目录,运行命令非常简单:
yarn test
(等价于执行 jest --verbose。)
e2e 测试一:消息总线的发布/订阅/响应核心链路
测试骨架:真实启动总线与客户端
test/DashboardMessageBus.test.ts 是整个包中最核心的测试。它的 beforeEach 会真实地完成以下动作:
messageBus = new DashboardMessageBus(publishPort, subscribePort);
await messageBus.start();
client = new DashboardMessageBusClient({
host: "localhost",
subscribePort,
publishPort,
retryDelayMsec: 10
});
- 使用固定的
publishPort = 12345、subscribePort = 23456启动一个真实的DashboardMessageBus实例; - 创建一个指向该总线的
DashboardMessageBusClient,并设置retryDelayMsec: 10(连接失败后仅延迟 10ms 就重试,让测试更快收敛); afterEach中调用client.close()与messageBus.terminate()做清理。值得注意的是其中一行被注释掉的//await client.waitForOutstandingTasks();,以及文件顶部jest.setTimeout(2000000)(200 万毫秒)的超长超时——这暗示消息总线相关的连接与清理可能存在异步滞留,官方测试用极长超时兜底。
核心断言链路:一次完整的请求/响应往返
主测试用例 "should send a message between a publisher and subscriber" 完整演示了消息总线的核心语义:
- 等待客户端就绪:
await client.ready(),确保发布与订阅两条 WebSocket 连接都已建立; - 发布消息(模拟 publisher):
客户端将const publishLifecycle = await client.publish({ type: "test", payload: "request" });{ type: "test", payload: "request" }编码并通过发布连接发送到总线; - 订阅消息(模拟 subscriber):
client.subscribe({ type: "test" })创建按类型过滤的订阅,并等待"message"事件拿到ReceivedMessageLifecycle; - 校验收到的消息:断言
consumedMessage具有id、type === "test"、payload === "request"三个属性——其中id由@truffle/dashboard-message-bus-common的createMessage生成,用于关联请求与响应; - 订阅者回复:
await subscribeLifecycle.respond({ payload: "response" }); - 发布者拿到响应:
const response = await publishLifecycle.response;,并断言响应id与请求消息id一致、不包含type字段、payload === "response"。
这条测试链路完整覆盖了 @truffle/dashboard-message-bus-client 文档 中描述的发布消息生命周期(PublishedMessageLifecycle):发布一条消息后,可以通过 publishLifecycle.response 这个 Promise 等待对应响应;消息生命周期有三种终止方式——收到对应响应、消息被 invalidate(取消)、或调用 abandon 放弃。文档还特别强调:如果 fire-and-forget 消息不调用 abandon,进程退出时会永远挂起等待一个永远不会到来的响应。这正是测试中注释掉 waitForOutstandingTasks 的原因所在。
待办用例(todo)
该测试文件还以 it.todo 形式列出了尚未完成的后续用例,这些描述本身就是消息总线设计意图的注释:
should send a message to multiple subscribers(广播给多个订阅者);should send unfulfilled requests to new subscribers(新订阅者接入时补发未完成请求);should clear publisher's unfulfilled requests when publisher disconnects(发布者断开时清理其未完成请求)。
这些"未完成"的测试点,恰恰对应了消息总线源码中的既有行为(见下文),说明该测试文件在持续追赶实现能力。
消息总线底层机制:这些 e2e 用例在测什么
为了让上面的 e2e 断言"为什么能成立"更清晰,需要回到被测试对象的源码。核心实现在 packages/dashboard-message-bus/lib/DashboardMessageBus.ts:
双 WebSocket 服务器架构
DashboardMessageBus 启动时会开启两个独立的 WebSocket 服务器(见 start(),源码 L44-L71):
- publishServer:供 publisher(如 Truffle 命令行、ethers/web3 provider 等)连接并发送请求;
- subscribeServer:供 subscriber(如 Dashboard 前端)连接并接收请求、回发响应。
订阅者连接后必须先发送一条消息才会被正式加入订阅者列表(newSubscriber.once("message", () => this.addSubscriber(newSubscriber))),这是一个有趣的握手约定。
请求转发与"首个响应胜出"
processRequest(源码 L95-L137)的处理流程为:
- 把发布者的请求存入
unfulfilledRequestsMap(key 为原始数据,value 记录{ publisher, data }); - 通过
broadcastAndAwaitFirst(subscribers, message)把消息广播给所有订阅者,并等待第一个响应(见 lib/utils.ts 的Promise.any实现); - 拿到响应后把响应回发给对应 publisher,并从未完成请求表中删除该项;
- 向所有订阅者广播一条
invalidate消息(invalidateMessage),宣告该请求已完成、不再有效。
未完成请求的补发与生命周期管理
addSubscriber在新增订阅者时,会把当前所有unfulfilledRequests逐个processRequest重新发给新订阅者——这就是 README 中"当新订阅者连接时,任何未完成请求也会被发送给新订阅者"的实现;removePublisher会调用clearRequestsForPublisher清理该发布者的全部未完成请求;terminateIfNoConnections:当 publisher 和 subscriber 全部断开时,消息总线自动关闭;readygetter 返回一个在"出现第一个订阅者"时 resolve 的 Promise,发布者的请求会等待ready后才真正广播。
e2e 测试一中"先发布、后订阅也能成功"(以及测试二中"请求先发出、Dashboard 后连接也能成功")之所以成立,正是因为有 unfulfilledRequests 补发机制 + ready 等待逻辑在底层兜底。
e2e 测试二:DashboardServer + Ganache + ethers.js / web3.js
测试目标
test/DashboardServer.test.ts 把 e2e 的层级提升到了"完整 Dashboard":它真实启动 @truffle/dashboard 的 DashboardServer(端口 8546,HTTP RPC 端点为 http://localhost:8546/rpc),并用 Ganache 启动一个本地以太坊节点,然后用 ethers.js 与 web3.js 两套库分别发起 RPC 请求。文件头部的注释说明这些用例是从 browser-provider 的测试复制而来,并标记了去重(DRY)的待办。
测试基建
beforeAll中创建安静的 Ganache provider(logging: { quiet: true }),afterAll中disconnect;beforeEach中启动DashboardServer(autoOpen: false,避免测试时弹出浏览器窗口),并通过dashboardServer.subscribePort/dashboardServer.publishPort组装客户端连接选项,再创建MockDashboard;afterEach中依次断开 MockDashboard 并停止 DashboardServer。
三个关键场景(每套库各跑一遍)
- 获取已解锁账户:
ethersProvider.listAccounts()/web3.eth.getAccounts()——验证通过消息总线代理的 JSON-RPC 请求能到达 Dashboard 并被正确处理; - 请求先于 Dashboard 连接发出:先把
listAccounts()的 Promise 发出去,再await mockDashboard.connect(clientOptions),最后才 await 结果——直接验证消息总线的"未完成请求补发"能力(对应测试一的 todo 用例should send unfulfilled requests to new subscribers); - 发送 ETH 交易:
signer.sendTransaction(...)/web3.eth.sendTransaction(...)转账 0.1 ETH,断言返回对象带有hash/transactionHash——验证完整写路径(交易签名、广播、回执)。
ethers.js 场景的一个细节
测试中创建 ethers provider 时特别强调第二个参数不能省略:
ethersProvider = new providers.JsonRpcProvider(rpcUrl, {
name: "ganache",
chainId: 1337
});
注释指出如果丢掉这个参数,测试套件在退出时会挂起(有时长达两分钟以上)。这是一个很有价值的实践提示:e2e 测试中 provider 的网络/chainId 元数据会影响进程能否干净退出。
MockDashboard:用消息总线客户端模拟真实仪表盘
test/MockDashboard.ts 是一个精炼的"模拟订阅者"实现,它演示了 @truffle/dashboard-message-bus-client 作为消息消费方的完整用法:
connect(options)创建一个DashboardMessageBusClient,调用client.ready()建立双连接;- 以
dashboardProviderMessageType(来自@truffle/dashboard-message-bus-common的 provider 消息类型)调用client.subscribe(...),注册"message"事件监听; - 收到消息后,
handleIncomingMessage把消息负载里的 JSON-RPC payload 通过forwardDashboardProviderRequest转发给真实的 Ganache provider; - 调用
messageLifecycle.respond({ payload: responsePayload })把 RPC 结果(或错误)回发给请求方。
forwardDashboardProviderRequest 中构造的 reply 遵循 JSON-RPC 结构(jsonrpc、id、result 或 error),出错时也会以 JSON-RPC 错误对象返回而非抛异常——这模拟了真实钱包(如 MetaMask)注入的 web3 provider 行为。
值得注意的源码细节与总结
一个来自源码的观察
在看 packages/dashboard/lib/DashboardServer.ts 时可以发现一个有趣细节:get publishPort() 与 get subscribePort() 返回的都是 this.messageBus?.subscribePort(L61-L67)。从源码结构看,这疑似复制粘贴笔误(publishPort 应当返回 messageBus.publishPort)。当前仓库中的测试与实现以仓库实际代码为准,阅读源码时值得留意这一点。
测试包的实践价值
@truffle/dashboard-message-bus-e2e-test 虽然 README 只有寥寥数行,但它浓缩了三个可复用的工程实践:
- 用独立私有包打破测试循环依赖:当 A、B 两包互相依赖又需要联调测试时,抽一个"测试专用包"把两者都作为 devDependencies 引入,是最干净的解法;
- 真实进程级 e2e:测试真实启动双 WebSocket 服务器、HTTP Dashboard 服务与 Ganache 节点,覆盖发布/订阅/响应、未完成请求补发、RPC 代理、交易发送等完整链路,并针对进程挂起问题设置了长超时与 provider 元数据等兜底;
- Mock 与真实现分层:
MockDashboard用真实的 message-bus-client 扮演订阅者,而 RPC 处理转发给真实的 Ganache,实现"通信链路全真、业务逻辑可控"的测试组合。
如果你正在阅读 packages/dashboard-message-bus/lib/DashboardMessageBus.ts、packages/dashboard-message-bus/lib/utils.ts 或 packages/dashboard-message-bus-client/lib/client.ts 来理解 Dashboard 的消息体系,那么这个测试包(test 目录)就是最好的"可运行的行为说明书"。