Flows 应用测试覆盖率不足 80% 时如何定位并补齐测试

当 Flows 应用因行覆盖率未达 80% 硬性门槛而无法通过审批时，按步骤配置覆盖率工具、补齐缺失测试、覆盖未测路径并重构代码以提升可测性。

适用场景

解决思路

1. 验证测试框架与覆盖率工具：用 grep -E "(vitest|jest)" package.json 检查是否安装 Vitest 或 Jest，并读取 vitest.config.ts/js 或 jest.config.ts/js 确认存在 coverage 配置段（如 vitest 的 coverage: { provider: 'v8', ... }）以及至少配置了 text 和 lcov 或 json-summary 报告器。
2. 若未配置覆盖率工具，执行 pnpm add -D @vitest/coverage-v8 安装 provider，并在 vitest.config.ts 的 test 段内加入 coverage 配置：provider 为 'v8'，reporter 为 ['text','text-summary','lcov']，include 为 ['src/**/*.{ts,tsx}']，exclude 为测试文件、vite-env.d.ts 和 main.tsx；若不存在配置文件则创建带 defineConfig 包装的完整文件。
3. 校验覆盖率范围：用 grep -A 20 "exclude" vitest.config.ts 或 grep -A 10 "coveragePathIgnorePatterns|collectCoverageFrom" jest.config.ts 检查排除项，确保 80% 阈值适用于 src/ 下所有 .ts/.tsx 文件，仅排除测试文件、类型声明文件和入口 main.tsx。
4. 若配置排除了生产代码，重写 exclude 数组只保留 'src/**/*.test.{ts,tsx}'、'src/**/*.spec.{ts,tsx}'、'src/**/vite-env.d.ts'、'src/main.tsx'，移除对 src/pages/、src/components/、src/hooks/、具体功能文件或 src/**/*.tsx 的排除。
5. 运行测试并收集覆盖率：执行 npx vitest run --coverage 或 npx jest --coverage 或 npm test -- --coverage，记录 Statements、Branches、Functions、Lines 四项百分比，确认行覆盖率至少 80%。
6. 若测试运行失败则修复：缺失导入就补 import 语句；mock 损坏就按被 mock 模块当前 API 修正；快照过期就运行 npx vitest run --update 并审查 diff；缺依赖就 pnpm add -D <missing-package>；配置错误就修正语法或选项；每次修复后重跑直到全部通过。
7. 查找缺失的测试文件：用 find 遍历 src 下所有 .ts/.tsx 生产文件，对每个文件检查同目录或 __tests__ 目录下是否存在 .test. 或 .spec. 对应文件，输出所有 NO TEST 的文件。
8. 对缺失测试的文件分类：Services、hooks、utils、contexts、ViewModel hooks 必须立即编写测试；无逻辑的纯展示组件、仅重导出的 barrel 文件（index.ts）、仅含类型导出的文件标记为 N/A 无需测试。
9. 为每个缺失测试的文件编写完整测试：先读取源文件了解导出、依赖和逻辑，在同目录创建 .test.ts 或 .test.tsx，覆盖 happy path、error path、空状态和边界情况。
10. 按文件类型使用对应测试模式：hooks 用 @testing-library/react 的 renderHook 并包裹 QueryClientProvider 等 provider，测试初始、loading、success、error 状态；services/utils 直接调用函数并 mock CDF SDK 响应，测试返回值、副作用和抛错；含逻辑组件用 render 和 userEvent 测试 loading/error/data 状态及用户交互。
11. 依赖 mock 优先使用 context 注入而非 vi.mock；若生产代码使用硬编码导入无法注入，则用 vi.mock 并加注释说明原因（如 // vi.mock required: useDataSource uses direct import, not context injection）；mock 必须类型安全，禁止 as unknown as T 强转，需定义满足接口的 mock 对象。
12. 每写完一个测试文件运行 npx vitest run <test-file> 验证通过。
13. 修复低覆盖率文件：用 node 解析 coverage/coverage-summary.json 列出所有行覆盖率低于 80% 的文件，从 coverage/ 目录的 lcov 或 html 报告读取未覆盖行，阅读源文件理解这些行逻辑，然后补充测试用例。
14. 针对未覆盖路径补测试：错误路径通过触发网络失败、无效输入、null 值、权限错误或 mock 依赖抛错来覆盖；分支路径为每个 if/else 补测未覆盖的分支；未覆盖函数为每个导出函数补调用并验证返回值和副作用；catch 块通过 mock 上游 reject/throw 验证行为。
15. 补测后运行 npx vitest run --coverage <test-file> 确认该文件达到 80%，重复直到每个文件达标或所有可行路径已覆盖。
16. 评估并修复可测性问题：用 grep 检查 src/hooks/ 和 src/contexts/ 中的 useContext/createContext、src/ 中的 vi.mock、测试文件中的 as unknown as、src/ 中的 implements 关键字。
17. 按问题类型重构生产代码并同步更新测试：hook 直接导入依赖改为通过 createContext 提供默认依赖并用 useContext 获取，测试通过 provider 注入 mock；服务无接口则提取 TypeScript 接口并让实现类 implements，测试针对接口 mock；页面混合数据获取与渲染则抽取 use*ViewModel hook，页面调用该 hook 渲染，分别用 renderHook 和 mock ViewModel 测试；测试用 vi.mock 的改为 context 注入并移除 vi.mock 加注释；测试用 as unknown as T 的改为定义满足接口的正确类型 mock，接口过大时写返回部分 mock 的辅助函数。
18. 每个重构文件完成后运行 npx vitest run <test-file> 确认测试仍通过。
19. 重新运行完整测试套件 npx vitest run --coverage 获取最终数字，输出修复前后 Lines/Branches/Functions/Statements 对比表、PASS/FAIL 判定、已修复项清单（工具配置、排除项清理、失败测试修复数、新测试文件数、扩展测试文件数、重构文件数）以及需人工审查的剩余缺口（需领域知识的复杂业务逻辑、需真实凭证的集成测试、需重大架构改动才能达 80% 的文件）。

适用边界 · 注意事项

• 非 Flows 应用或没有 80% 行覆盖率硬性门槛的项目
• 项目未使用 Vitest 或 Jest 作为测试框架
• 需要真实 API 凭证或环境配置才能运行的集成测试场景