深入解析 Truffle Dashboard Message Bus 端到端测试包:@truffle/dashboard-message-bus-e2e-test 架构与实践

原创2026-09-21 10:37:051,896 阅读
文章标签:区块链开发工具Web3

深入解析 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-bus and @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" 完整演示了消息总线的核心语义:

  1. 等待客户端就绪:await client.ready(),确保发布与订阅两条 WebSocket 连接都已建立;
  2. 发布消息(模拟 publisher):
    const publishLifecycle = await client.publish({
      type: "test",
      payload: "request"
    });
    
    客户端将 { type: "test", payload: "request" } 编码并通过发布连接发送到总线;
  3. 订阅消息(模拟 subscriber):client.subscribe({ type: "test" }) 创建按类型过滤的订阅,并等待 "message" 事件拿到 ReceivedMessageLifecycle;
  4. 校验收到的消息:断言 consumedMessage 具有 id、type === "test"、payload === "request" 三个属性——其中 id 由 @truffle/dashboard-message-bus-common 的 createMessage 生成,用于关联请求与响应;
  5. 订阅者回复:
    await subscribeLifecycle.respond({ payload: "response" });
    
  6. 发布者拿到响应: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)的处理流程为:

  1. 把发布者的请求存入 unfulfilledRequests Map(key 为原始数据,value 记录 { publisher, data });
  2. 通过 broadcastAndAwaitFirst(subscribers, message) 把消息广播给所有订阅者,并等待第一个响应(见 lib/utils.ts 的 Promise.any 实现);
  3. 拿到响应后把响应回发给对应 publisher,并从未完成请求表中删除该项;
  4. 向所有订阅者广播一条 invalidate 消息(invalidateMessage),宣告该请求已完成、不再有效。

未完成请求的补发与生命周期管理

  • addSubscriber 在新增订阅者时,会把当前所有 unfulfilledRequests 逐个 processRequest 重新发给新订阅者——这就是 README 中"当新订阅者连接时,任何未完成请求也会被发送给新订阅者"的实现;
  • removePublisher 会调用 clearRequestsForPublisher 清理该发布者的全部未完成请求;
  • terminateIfNoConnections:当 publisher 和 subscriber 全部断开时,消息总线自动关闭;
  • ready getter 返回一个在"出现第一个订阅者"时 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。

三个关键场景(每套库各跑一遍)

  1. 获取已解锁账户:ethersProvider.listAccounts() / web3.eth.getAccounts()——验证通过消息总线代理的 JSON-RPC 请求能到达 Dashboard 并被正确处理;
  2. 请求先于 Dashboard 连接发出:先把 listAccounts() 的 Promise 发出去,再 await mockDashboard.connect(clientOptions),最后才 await 结果——直接验证消息总线的"未完成请求补发"能力(对应测试一的 todo 用例 should send unfulfilled requests to new subscribers);
  3. 发送 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 作为消息消费方的完整用法:

  1. connect(options) 创建一个 DashboardMessageBusClient,调用 client.ready() 建立双连接;
  2. 以 dashboardProviderMessageType(来自 @truffle/dashboard-message-bus-common 的 provider 消息类型)调用 client.subscribe(...),注册 "message" 事件监听;
  3. 收到消息后,handleIncomingMessage 把消息负载里的 JSON-RPC payload 通过 forwardDashboardProviderRequest 转发给真实的 Ganache provider;
  4. 调用 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 只有寥寥数行,但它浓缩了三个可复用的工程实践:

  1. 用独立私有包打破测试循环依赖:当 A、B 两包互相依赖又需要联调测试时,抽一个"测试专用包"把两者都作为 devDependencies 引入,是最干净的解法;
  2. 真实进程级 e2e:测试真实启动双 WebSocket 服务器、HTTP Dashboard 服务与 Ganache 节点,覆盖发布/订阅/响应、未完成请求补发、RPC 代理、交易发送等完整链路,并针对进程挂起问题设置了长超时与 provider 元数据等兜底;
  3. 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 目录)就是最好的"可运行的行为说明书"。

登录后查看全文
truffle