ECC 测试工程实践指南：80% 覆盖率红线、TDD 强制工作流与 tdd-guide Agent 协作-平芜编程栈

ECC 测试工程实践指南：80% 覆盖率红线、TDD 强制工作流与 tdd-guide Agent 协作

【免费下载链接】ECCThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.项目地址: https://gitcode.com/GitHub_Trending/ev/ECC

导读

本文围绕 ECC 仓库中统一测试规范 rules/common/testing.md（及其日文译本 docs/ja-JP/rules/common/testing.md）展开，系统说明 ECC 对测试的最低要求（覆盖率 ≥ 80%）、三种必须的测试类型（单元 / 集成 / E2E）、强制性的 Red-Green-Improve TDD 工作流，以及如何借助tdd-guideAgent 在编写新功能时自动执行"测试先行"。读完本文，你将掌握一套可以直接复制到任意语言项目中的 TDD 实战流程，并了解 ECC 仓库自身如何用覆盖率配置、测试命令与测试用例来落地这套规范。

一、测试基线：为什么是 80% 覆盖率

ECC 的测试规范把覆盖率红线定为80%，这是所有代码改动进入合入流程前必须达到的硬性门槛。规范原文（rules/common/testing.md）明确要求测试覆盖三个层级，且三者全部必须存在：

测试类型	覆盖对象	说明
单元测试（Unit Tests）	单个函数、工具方法、组件	隔离验证最小逻辑单元
集成测试（Integration Tests）	API 端点、数据库操作	验证模块间真实协作
E2E 测试	关键用户流程	框架按语言自行选择

"关键用户流程"通常指登录、下单、搜索等完整业务链路，E2E 是最后一道防线，用来发现单元与集成测试都覆盖不到的端到端缺陷。

仓库自身的配置可以作为 80% 红线的直接证据：

在 package.json 中，覆盖率命令通过c8强制检查：--lines 80 --functions 80 --branches 79 --statements 80，任何一项低于阈值即判定构建失败；
在 pyproject.toml 中，Python 侧配置了pytest-cov，source = ["src/llm"]限定统计范围、branch = true开启分支覆盖率统计，并用exclude_lines排除pragma: no cover、if TYPE_CHECKING:等无需覆盖的代码。

也就是说，80% 不是一句口号，而是仓库里真实生效的 CI 门槛：覆盖率不足时测试命令本身就会以非零状态退出。

二、强制 TDD 工作流：Red → Green → Improve

规范第二部分定义了必须遵守（MANDATORY）的测试驱动开发工作流，共六个步骤（rules/common/testing.md）：

先写测试（RED）——先描述期望行为，此时实现尚不存在；
运行测试——应当失败——确认失败且失败原因正确；
编写最小实现（GREEN）——只写让测试通过所需的最少代码；
运行测试——应当通过——确认由红转绿；
重构（IMPROVE）——消除重复、改善命名、优化性能，测试保持绿色；
确认覆盖率（80%+）——不达标则回到步骤 1 补齐用例。

这套流程在 agents/tdd-guide.md 中进一步细化为带命令的版本：npm test验证 RED、npm run test:coverage验证覆盖率，且明确覆盖率必须覆盖branches（分支）、functions（函数）、lines（行）、statements（语句）四个维度，而不只是行覆盖率。

在 skills/tdd-workflow/SKILL.md 中，工作流还补充了一个关键前置步骤Step 0：检测测试运行器。规范强调不要假设项目一定用npm test——仓库提供了包管理器探测器：

node scripts/setup-package-manager.js --detect

它按CLAUDE_PACKAGE_MANAGER→.claude/package-manager.json→package.json的packageManager字段 → lockfile → 全局配置的顺序解析包管理器（npm / pnpm / yarn / bun）。更重要的是要区分包管理器与测试运行器：例如项目用 Bun 装依赖，却可能仍用 Jest 或 Vitest 跑测试；反之若测试文件import { test, expect } from "bun:test"，则应使用 Bun 原生运行器bun test，而不是bun run test。选错运行器是测试基础设施中最常见的失败原因之一。

Git 检查点：把 TDD 证据固化进提交历史

skills/tdd-workflow/SKILL.md 进一步要求：在 Git 仓库中，每个 TDD 阶段后创建检查点提交，且不得在流程结束前改写这些提交。推荐的紧凑工作流是：

RED 验证后提交：test: add reproducer for <feature or bug>
GREEN 验证后提交：fix: <feature or bug>
重构完成后可选提交：refactor: clean up after <feature or bug> implementation

判定检查点有效的前提是：提交存在于当前活动分支、可从当前HEAD可达、且属于当前任务序列。若后续使用 squash 合并，必须先把 RED/GREEN/重构摘要复制进 PR 描述或 TDD 证据报告中，否则审查者将无法回答"到底验证了什么、如何验证的"。

三、故障排查：测试失败时的四条纪律

规范给出了测试失败时的标准排查顺序（rules/common/testing.md）：

使用 tdd-guide Agent——先让专职 Agent 介入分析；
确认测试隔离——检查是否存在共享状态、测试间相互依赖；
验证 Mock 正确性——外部依赖（数据库、API、缓存）是否被正确模拟；
修复实现，而不是修改测试——唯一例外是测试本身确实写错了。

这条"修实现、不修测试"的原则非常重要：测试是行为的契约，当测试失败时，默认假设是生产代码有缺陷，而不是降低测试标准去迎合实现。

四、Agent 支持：tdd-guide 的职责边界

规范的 Agent 支持章节（rules/common/testing.md）明确要求：新功能要主动（PROACTIVELY）使用 tdd-guide Agent，强制测试先行。

agents/tdd-guide.md 给出了该 Agent 的完整定义：它被描述为"强制测试先行的 TDD 专家"，拥有 Read / Write / Edit / Bash / Grep 工具，并在写新功能、修 Bug、重构三种场景下都应主动介入，核心职责包括：

强制 tests-before-code 方法论；
引导 Red-Green-Refactor 循环；
保证 80%+ 覆盖率；
编写单元 / 集成 / E2E 完整测试套件；
在实现之前捕获边缘用例。

该 Agent 还内置了"必须测试的 8 类边缘用例"清单（agents/tdd-guide.md）：null/undefined 输入、空数组/空字符串、非法类型、边界值（min/max）、错误路径（网络失败、数据库错误）、竞态条件（并发操作）、大数据量（10k+ 条目的性能）、特殊字符（Unicode、emoji、SQL 字符）。

同时它列出了必须避免的测试反模式（agents/tdd-guide.md）：

测试实现细节（内部状态）而非行为；
测试相互依赖（共享状态）；
断言过少（测试通过却没验证任何东西）；
不 Mock 外部依赖（Supabase、Redis、OpenAI 等）。

v1.8 评估驱动 TDD 增补

agents/tdd-guide.md 还记录了 v1.8 引入的 Eval-Driven TDD 增补：在实现前先定义能力评估与回归评估，运行基线并捕获失败签名，实现最小通过变更后重跑测试与评估并报告 pass@1 / pass@3。发布关键路径在合入前应以 pass^3 稳定性为目标——这是把"测试驱动"进一步升级为"评估驱动"的进阶实践。

五、测试结构规范：AAA 模式与行为化命名

规范后半部分补充了两条结构约定（英文源文档 rules/common/testing.md）。

AAA（Arrange-Act-Assert）模式

测试应遵循"准备-执行-断言"三段式结构，让每个测试的意图一目了然：

test('calculates similarity correctly', () => { // Arrange const vector1 = [1, 0, 0] const vector2 = [0, 1, 0] // Act const similarity = calculateCosineSimilarity(vector1, vector2) // Assert expect(similarity).toBe(0) })

描述性命名：解释被测行为

测试名应当描述"被测行为"而非"被测方法"，这样失败信息本身就能说明问题：

test('returns empty array when no markets match query', () => {}) test('throws error when API key is missing', () => {}) test('falls back to substring search when Redis is unavailable', () => {})

六、仓库落地：覆盖率工具链与按语言检测

ECC 仓库用一套命令工具把上述规范落地为可执行步骤，核心入口是 commands/test-coverage.md。

第一步：按语言检测测试框架

覆盖率命令因框架而异，该命令给出了识别矩阵：

框架指示器	覆盖率命令
`jest.config.*`或 package.json 含 jest	`npx jest --coverage --coverageReporters=json-summary`
`vitest.config.*`	`npx vitest run --coverage`
`pytest.ini`/ pyproject.toml 含 pytest	`pytest --cov=src --cov-report=json`
`Cargo.toml`	`cargo llvm-cov --json`
`pom.xml`含 JaCoCo	`mvn test jacoco:report`
`go.mod`	`go test -coverprofile=coverage.out ./...`

第二步到第五步：分析缺口 → 补测试 → 复验 → 报告

覆盖率报告生成后，按"从差到好"排序列出低于 80% 的文件，识别未测试函数、缺失的分支覆盖（if/else、switch、错误路径）以及推高分母的死代码。补测试按优先级执行：happy path → 错误处理 → 边缘用例（空数组、null/undefined、0 / -1 / MAX_INT 边界）→ 分支覆盖。每条测试生成规则都强调与源码相邻放置（foo.ts→foo.test.ts）、沿用项目既有测试风格、Mock 外部依赖、测试之间零共享可变状态、使用描述性命名（如test_create_user_with_duplicate_email_returns_409）。

最终报告应给出前后对比，例如：

Coverage Report ────────────────────────────── File Before After src/services/auth.ts 45% 88% src/utils/validation.ts 32% 82% ────────────────────────────── Overall: 67% 84% PASS:

各语言 TDD 命令：以 C++ 为例

针对特定语言，仓库还提供了专属 TDD 命令，例如 commands/cpp-test.md 定义了 C++ 侧的完整循环：先用 GoogleTest 写 RED 测试 →cmake --build build && ctest --test-dir build --output-on-failure验证失败 → 最小实现转 GREEN → 用gcov/lcov验证覆盖率。该命令还给出了分级的覆盖率目标：核心业务逻辑 100%、公共 API 90%+、一般代码 80%+、生成代码排除统计。类似的命令还包括python-review、go-test、rust-test、react-test等，均可在 commands 目录下查阅。

与质量门禁的衔接

测试只是质量保障的一部分。格式层面的质量门禁由post:quality-gatePostToolUse Hook（scripts/hooks/quality-gate.js，注册于 hooks/hooks.json）驱动，手动触发入口见 commands/quality-gate.md：对.ts/.tsx/.js/.jsx/.json/.md使用 Biome 或 Prettier，对.go使用 gofmt，对.py使用 ruff format。lint 与类型检查不在该门禁内，需通过verification-loop技能或各语言验证技能完成——测试、lint、类型检查构成完整的三道防线。

七、可复制的实战速查

七步 TDD 循环（含命令占位符）

Step 1 从 plan.md 提取用户旅程（user journeys）与验收标准 Step 2 为每个旅程生成测试用例（AAA 结构、行为化命名） Step 3 运行 <test> —— 必须失败（RED 门禁，未编译未执行不算 RED） Step 4 编写最小实现 Step 5 重跑 <test> —— 必须通过（GREEN 门禁） Step 6 重构，保持绿色 Step 7 运行 <coverage> —— 确认 80%+ Step 8 编写 TDD 证据报告（docs/testing/<task>.tdd.md），保留任务→测试→RED/GREEN 证据映射

其中<test>、<test-watch>、<coverage>按项目实际运行器替换：npm / pnpm / yarn 对应npm test/pnpm test/yarn test，Bun 原生运行器则用bun test、bun test --watch、bun test --coverage。

覆盖率阈值配置示例

{ "jest": { "coverageThresholds": { "global": { "branches": 80, "functions": 80, "lines": 80, "statements": 80 } } } }

成功度量标准

覆盖率 ≥ 80%（branches / functions / lines / statements 全维度）；
全部测试通过（绿色）；
无跳过或禁用的测试；
单元测试执行快速（全套 < 30s，单测 < 50ms/个）；
E2E 覆盖关键用户流程；
测试能在进入生产前捕获缺陷。

延伸阅读：完整的 TDD 工作流、Mock 模式（Supabase / Redis / OpenAI）、测试文件组织规范与常见错误示例，可深入阅读 skills/tdd-workflow/SKILL.md；覆盖率缺口分析与补测流程见 commands/test-coverage.md；TDD 专家的完整角色定义与质量清单见 agents/tdd-guide.md。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考