Neptune Mutual前端测试体系：Jest + Testing Library保障DApp质量的完整实践

Neptune Mutual前端测试体系：Jest + Testing Library保障DApp质量的完整实践

【免费下载链接】app.neptunemutual.com🔱 An open source interface for the Neptune Mutual App项目地址: https://gitcode.com/gh_mirrors/ap/app.neptunemutual.com

Neptune Mutual 是一个开源的去中心化再保险协议（DApp）前端应用，其测试体系基于Jest 28 + React Testing Library + jsdom构建，覆盖页面、组件、Hook 三大层级，并针对 Web3 场景做了钱包、路由、API 的全面 Mock 方案，是 DApp 前端测试的一个完整可参考实践。

一、为什么 DApp 前端测试更难？

普通 Web 应用测试已经不容易，DApp 还要额外面对三类"浏览器外依赖"：

• 钱包连接：MetaMask 注入的window.ethereum对象；
• 区块链路由：Next.js 的useRouter；
• 链上数据 API：Subgraph、协议节点返回的异步数据。

Neptune Mutual 的做法是把这三类依赖统一收口到src/utils/unit-tests/工具目录，让业务测试文件保持干净。

二、Jest 配置：一份 next/jest 解决所有编译问题

📄 核心配置文件：jest.config.js

关键设计点如下：

配置项	值	作用
testEnvironment	jsdom	模拟浏览器 DOM 环境
transform	babel-jest + next/babel	正确转译 JSX 与 Next.js 语法
setupFilesAfterEach	jest.setup.js	注入 jest-dom 断言扩展
moduleNameMapper	@/common、@/modules等	与 Next.js 别名保持一致

其中moduleNameMapper把样式文件与图片统一重定向到 Mock：

css/sass/scss → __mocks__/styleMock.js png/jpg/svg... → __mocks__/fileMock.js

配合__mocks__/@lingui/macro.js对国际化宏的 Mock，i18n 代码在测试中不再报错。

📄 全局初始化只有两行，位于 jest.setup.js：

import '@testing-library/jest-dom/extend-expect' jest.setTimeout(90 * 1000)

jest-dom提供了toBeInTheDocument()这类自然语言断言；90 秒超时则是为了容忍异步链上数据 Mock 的等待。

三、测试目录：镜像源码的"影子结构"

测试代码位于独立的__tests__/目录，按src/pages的页面路由结构镜像组织：

__tests__/src/pages/ ├── covers/ # 保险标的（Cover）相关页面 ├── my-liquidity/ # 我的流动性 ├── my-policies/ # 我的保单（含理赔 claim 流程） ├── pools/ # 流动性池、质押 ├── reports/ # 事故报告与争议流程 └── index.test.js # 首页

以首页测试__tests__/src/pages/index.test.js为例，它只关心"页面能渲染出首页容器"这一件事，复杂的 home 模块被jest.mock替换为一个静态data-testid节点——这正是 Testing Library"测试行为而非实现"的典型用法。

四、DApp 专属 Mock 层：测试体系的核心亮点

📄 全局环境 Mock：src/utils/unit-tests/test-utils.jsx

这个文件一次性补齐了 jsdom 缺失的 DApp 运行时环境：

• window.ethereum：Mock 了enable、request、eth_chainId、eth_requestAccounts等 MetaMask 方法，返回固定的测试地址；
• localStorage：用内存对象替换，避免 jsdom 持久化副作用；
• Provider 封装：withProviders/withDataProviders把I18nProvider、Web3ReactProvider、ToastProvider、NetworkProvider、TxPosterProvider等应用级 Context 打包成现成的包装器，测试一行代码即可获得完整应用上下文。

📄 数据与 Hook Mock：src/utils/unit-tests/mock-hooks-and-methods.js

该文件集中导出了useAuth、usePurchasePolicy、useReportIncident、useSubgraphFetch等几十个业务 Hook 的 Mock 函数。测试时只需：

mockHooksOrMethods.useRouter()

即可将对应 Hook 替换为可控返回值，从而把"链上状态"变成确定性的测试输入。再配合createMockData.js、test-data.js中的固定数据集，保证每次运行结果一致。

📄 渲染入口：src/utils/unit-tests/helpers.js

initiateTest(Component)返回initialRender/rerenderFn，内部自动完成三件事：清理上一轮 DOM、激活英文语言包（i18n.activate('en')）、按 Testing Library 规范渲染组件。所有测试因此共享同一套渲染协议。

五、如何运行测试

📄 脚本定义在 package.json 的 scripts 中：

命令	用途
yarn test	完整运行并输出覆盖率报告（jest --coverage）
yarn test:watch	开发时监听模式（jest --watch）

Node/Yarn 版本由volta字段锁定为 Node 18.12.0 / Yarn 1.22.19，克隆仓库后本地环境完全一致：

git clone https://gitcode.com/gh_mirrors/ap/app.neptunemutual.com cd app.neptunemutual.com yarn install yarn test

六、这套体系给 DApp 开发者的 5 点启示

1. 用 next/jest 起步，让 JSX、CSS Modules、资源导入零配置可用；
2. 全局环境补丁集中管理（ethereum、localStorage、crypto），避免每个测试重复打补丁；
3. Provider 包装器把 React Context 依赖封装成一行调用，是测试复杂应用上下文的关键技巧；
4. Mock 数据与 Hook 分离存放，业务测试只写断言，可读性接近普通 Web 项目；
5. 镜像式目录 + 页面级冒烟测试，能在路由重构时第一时间发现断链。

📁 相关模块入口：src/utils/unit-tests/（测试工具）、__mocks__/（全局 Mock）、__tests__/src/（全部测试用例）

---

Neptune Mutual 的这套 Jest + Testing Library 实践证明：即使面对钱包、链上数据等强外部依赖，DApp 前端依然可以建立一套确定性、可重复、易读的自动化测试体系。对正在构建 DApp 的开发者来说，上述目录结构、Mock 分层与 Provider 封装方案，可以直接作为模板落地。

【免费下载链接】app.neptunemutual.com🔱 An open source interface for the Neptune Mutual App项目地址: https://gitcode.com/gh_mirrors/ap/app.neptunemutual.com