test-first-bugs

测试先行的错误修复

执行严谨的错误修复工作流，防止回归并并行尝试修复方案。

核心工作流

报告错误后，请按顺序执行以下步骤：

阶段 1：复现并记录

1. 了解错误，收集预期行为与实际行为的详细信息
2. 确定测试位置，查找项目中的测试文件（检查 tests/、__tests__/、spec/、*.test.*、*.spec.* 等模式）
3. 编写失败测试，创建能够复现该错误的测试

阶段 2：借助子 Agent 修复

4. 启动修复子 Agent，使用 Task 工具并指定 subagent_type=general-purpose 来尝试修复
5. 运行测试，运行指定测试以验证修复
6. 根据需要迭代，如果测试仍然失败，则采用新方法启动更多子 Agent

阶段 3：验证并完成

7. 运行完整测试套件，确保没有引入回归
8. 报告成功，通过测试通过来确认错误已修复

编写失败测试

测试命名约定

测试名称应描述该错误：

# Python (pytest)
def test_user_login_fails_when_email_has_uppercase():
    ...

# Python (unittest)
def test_should_handle_empty_input_without_crashing(self):
    ...

// JavaScript (Jest/Vitest)
it('should not crash when input array is empty', () => { ... });
test('handles special characters in username', () => { ... });

// TypeScript
describe('UserService', () => {
  it('returns null when user not found instead of throwing', () => { ... });
});

测试结构

每个错误复现测试都遵循以下模式：

def test_bug_description():
    # 1. ARRANGE - Set up the conditions that trigger the bug
    input_data = create_problematic_input()

    # 2. ACT - Perform the action that causes the bug
    result = function_under_test(input_data)

    # 3. ASSERT - Verify the expected (correct) behavior
    assert result == expected_value  # This should FAIL initially

查找合适的测试文件

检查项目结构，了解现有的测试模式：

# Find test files
find . -name "*.test.*" -o -name "*.spec.*" -o -name "test_*.py" | head -20

# Find test directories
ls -la tests/ __tests__/ spec/ test/ 2>/dev/null

# Check package.json for test command
grep -A5 '"test"' package.json

启动修复子 Agent

使用 Task 工具并行尝试修复方案：

Task tool parameters:
- subagent_type: "general-purpose"
- description: "Fix [bug description]"
- prompt: Include:
  1. The bug description
  2. The failing test location and contents
  3. Suspected cause (if known)
  4. Constraint: "Run the test to verify your fix works"

并行修复策略

采用不同方法启动多个子 Agent：

1. 直接修复 Agent，重点修复导致错误的代码
2. 根本原因 Agent，调查更深层的架构问题
3. 边界情况 Agent，查找相关代码中的类似错误

项目没有测试时

如果项目没有测试基础设施：

1. 先搭建最精简的测试框架
2. 在合适的位置创建测试文件
3. 记录测试设置，便于今后使用

快速测试设置命令

# Python
pip install pytest
mkdir -p tests && touch tests/__init__.py

# JavaScript/TypeScript
npm install --save-dev jest
# or
npm install --save-dev vitest

# Go
# Tests are built-in, create *_test.go files

验证修复

子 Agent 报告完成后：

# Run the specific test
pytest tests/test_module.py::test_bug_description -v
npm test -- --grep "bug description"
go test -run TestBugDescription -v

# Run full suite to check for regressions
pytest
npm test
go test ./...

工作流示例

用户报告：“电子邮件中包含空格时，登录函数会崩溃”

阶段 1，编写失败测试：

# tests/test_auth.py
def test_login_handles_email_with_spaces():
    """Bug: Login crashes when email contains spaces"""
    auth = AuthService()

    # This should return an error, not crash
    result = auth.login("user @example.com", "password")

    assert result.success == False
    assert "invalid email" in result.error.lower()

运行测试以确认失败：

pytest tests/test_auth.py::test_login_handles_email_with_spaces -v
# Expected: FAILED (demonstrates the bug)

阶段 2，启动子 Agent：

Task tool:
- subagent_type: "general-purpose"
- description: "Fix email space crash"
- prompt: "Fix the login crash when email contains spaces.

  Bug: AuthService.login() crashes instead of returning error when email has spaces.

  Failing test: tests/test_auth.py::test_login_handles_email_with_spaces

  After fixing, run: pytest tests/test_auth.py::test_login_handles_email_with_spaces -v

  The test must pass to confirm the fix."

阶段 3，验证：

# Specific test passes
pytest tests/test_auth.py::test_login_handles_email_with_spaces -v
# PASSED

# No regressions
pytest tests/test_auth.py -v
# All tests pass

与钩子的集成

此插件中的 bug-report-detector 钩子会自动：

1. 检测用户何时报告错误
2. 提醒 Claude 遵循测试先行的工作流
3. 在创建或修改测试文件之前，阻止 Edit/Write 工具

其他资源

参考文件

• references/test-frameworks.md，特定框架的测试模式
• references/common-bugs.md，常见错误模式和测试策略

示例文件

• examples/python-bug-test.py，Python pytest 示例
• examples/js-bug-test.js，JavaScript Jest 示例

脚本

• scripts/find-tests.sh，在项目中查找测试基础设施