EthQL单元测试完全指南JSON-RPC录制Fixture与testGraphql方案深度解析【免费下载链接】ethqlA GraphQL interface to Ethereum :fire:项目地址: https://gitcode.com/gh_mirrors/et/ethqlEthQL 是 ConsenSys 开源的以太坊 GraphQL 接口让你用 GraphQL 查询区块、账户、交易和智能合约日志。它的单元测试方案非常值得借鉴通过JSON-RPC 录制 Fixture实现离线可复现测试配合testGraphql工具函数一步完成 GraphQL 查询验证。本文带你完整看懂这套测试体系。为什么链上项目单元测试这么难EthQL 的数据全部来自以太坊节点的 JSON-RPC 接口。如果每次测试都真实请求主网会遇到三个问题慢且不稳定网络波动、节点限流都会让测试时过时不过时有成本频繁请求公共 RPC 端点容易触发配额限制结果不可复现链上数据不断变化昨天的断言今天就可能失效EthQL 的解法是把真实主网的 JSON-RPC 响应录制成本地 JSON 文件测试时回放replay这些 Fixture从而做到离线、快速、100% 可复现。测试体系总览Jest Lerna 多包并行EthQL 是一个 Lerna monorepo测试基建集中在根目录基础配置[jest.config.base.js]使用 ts-jest 转换 TypeScript测试文件统一放在各包的src/__tests__/目录下全局设置jest.setup.js 把测试超时放宽到 15 秒链上查询需要留足余量运行方式根目录执行npm test实际是lerna link lerna run --parallel test让 core、erc20、ens、plugin 等所有包并行跑测试CI 场景还有test:ci限制 4 个 worker与test:watch两种变体每个业务包只需继承基础配置把自己的插件测试放进去即可例如 core 包的 16 个查询测试文件、erc20 包的批处理与日志解码测试。testGraphql一行代码搭好整个测试环境测试的核心工具是testGraphql定义在 packages/plugin/src/test-utils.ts 中。它做了三件麻烦事调用bootstrap把各插件的 schema、resolvers、服务实现合并成可执行 schema准备默认的测试上下文context返回一个execQuery函数直接执行 GraphQL 查询并拿到结果因此任何包的测试代码都只有固定三步——建 runner、写查询、断言结果例如 core 包的账户查询测试packages/core/src/tests/queries/account.test.tsconst { execQuery } testGraphql({ opts: { plugins: [CORE_PLUGIN] } }); test(account: select by address, async () { const result await execQuery(query); expect(result).toEqual(expected); });注意 ERC20 包的测试packages/erc20/src/tests/logs.test.ts只多传了一个插件参数[CORE_PLUGIN, ERC20_PLUGIN]就能同时验证核心 schema 插件扩展组合后的完整行为——插件架构让测试可以像拼积木一样自由组合。录制 Fixturerecord / replay 双模式testGraphql还支持通过环境变量ETHQL_TEST_MODE切换三种模式模式作用record真实请求主网 RPC把响应录制为 JSON 文件replay默认从本地 Fixture 文件回放响应完全离线passthrough直通不做任何拦截默认配置DEFAULT_TEST_RUNNER_OPTS指向主网 Infura 端点并开启批处理batching与缓存caching——这正好模拟了生产环境的行为也顺带把 web3 批处理代理 的 DataLoader 逻辑纳入了测试覆盖范围。Fixture 文件长什么样打开 packages/core/data/ 目录你会看到上百个 JSON 文件命名规则一目了然——方法名 参数 区块标签eth_getBalance_0x0000000000000000000000000000000000000000__latest.json —— 查零地址余额eth_getBlockByNumber_0x5265c0__true.json —— 查 5000000 号区块含交易eth_call_0x270fce69b8dd....json —— 智能合约 eth_call 调用eth_getLogs_0x3407b2b6....json —— 事件日志查询每个文件就是一份标准的 JSON-RPC 响应例如余额查询的 Fixture 内容只有三行{ jsonrpc: 2.0, id: 3, result: 0x189dc5360dd1e6ec9cf }这套数据是从真实主网录制的所以断言里能出现0x7d5a4369273c...5000000 号区块的 hash这样的固定值——回放模式下结果永远一致断言自然稳定。测试覆盖了哪些场景浏览 packages/core/src/tests/queries/ 目录可以总结出四类典型用例正常路径按地址查账户、查区块、区块内交易按角色/过滤条件筛选block.transactionsRoles.test.ts、block.transactionFilter.test.ts单位换算账户余额测试遍历 wei、gwei、ether 等全部单位验证换算精度错误处理非法地址0x1234应报Expected type Address!非法单位枚举值应给出拼写建议组合查询区块 → 交易 → 日志 → ERC20 解码事件的多层嵌套查询另外packages/core/src/tests/services/web3.test.ts 保留了少量真实端点测试HTTPS/WSS并用skipIfUndefined技巧让 HTTP/IPC 端点测试仅在配置了对应环境变量时才运行——离线 CI 不会被阻塞本地开发又能验证连通性。如何运行与扩展测试三步上手克隆仓库并安装依赖Lerna bootstrap 安装所有子包根目录运行npm test全量并行执行或进入单个包运行npm test新增测试时直接写execQuery(query)expect断言即可无需关心网络和插件装配想补充新的 Fixture 数据把环境变量设为 record 模式跑一遍工具会把缺失的 RPC 响应自动录制回 data 目录之后 replay 模式即可离线使用。这套方案的三个可复用亮点✅录制回放分离record 模式对接真实链replay 模式保证 CI 稳定二者共享同一套测试代码✅Fixture 即文档文件名即接口签名新人一眼看懂每条 RPC 调用的入参与返回✅插件化测试装配testGraphql 插件数组的组合方式让每个扩展包core / erc20 / ens的测试互不干扰又可自由叠加掌握这套 JSON-RPC 录制 Fixture testGraphql 的方案你不仅能读懂 EthQL 的测试还能把它移植到自己对接区块链 JSON-RPC 接口的项目中用极低成本获得离线、快速、可复现的单元测试。【免费下载链接】ethqlA GraphQL interface to Ethereum :fire:项目地址: https://gitcode.com/gh_mirrors/et/ethql创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考