test-first-bugs

# Test-first bug fixing Enforce a disciplined bug-fixing workflow that prevents regression and parallelizes fix attempts. ## Core workflow When a bug is reported, follow these steps in order: ### Phase 1: Reproduce and document 1. **Understand the bug** — Gather details about expected vs actual behavior 2. **Identify the test location** — Determine where tests live in the project (check for `tests/`, `__tests__/`, `spec/`, `*.test.*`, `*.spec.*` patterns) 3. **Write a failing test** — Create a test that demonstrates the bug ### Phase 2: Fix with subagents 4. **Launch fix subagents** — Use the Task tool with `subagent_type=general-purpose` to attempt fixes 5. **Run the test** — Verify the fix by running the specific test 6. **Iterate if needed** — If test still fails, launch additional subagents with new approaches ### Phase 3: Verify and complete 7. **Run full test suite** — Ensure no regressions were introduced 8. **Report success** — Confirm the bug is fixed with passing test as proof ## Writing the failing test ### Test naming convention Name the test to describe the bug: ```python # Python (pytest) def test_user_login_fails_when_email_has_uppercase(): ... # Python (unittest) def test_should_handle_empty_input_without_crashing(self): ... ``` ```javascript // JavaScript (Jest/Vitest) it('should not crash when input array is empty', () => { ... }); test('handles special characters in username', () => { ... }); ``` ```typescript // TypeScript describe('UserService', () => { it('returns null when user not found instead of throwing', () => { ... }); }); ``` ### Test structure Every bug reproduction test follows this pattern: ```python 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 ``` ### Finding the right test file Check the project structure for existing test patterns: ```bash # 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 ``` ## Launching fix subagents Use the Task tool to parallelize fix attempts: ``` 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" ``` ### Parallel fix strategies Launch multiple subagents with different approaches: 1. **Direct fix agent** — Focus on the immediate code causing the bug 2. **Root cause agent** — Investigate deeper architectural issues 3. **Edge case agent** — Look for similar bugs in related code ## When projects lack tests If the project has no test infrastructure: 1. **Set up minimal test framework** first 2. **Create the test file** in a sensible location 3. **Document the test setup** for future use ### Quick test setup commands ```bash # 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 ``` ## Verifying the fix After subagent reports completion: ```bash # 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 ./... ``` ## Example workflow **User reports:** "The login function crashes when email has spaces" **Phase 1 — Write failing test:** ```python # 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() ``` **Run test to confirm it fails:** ```bash pytest tests/test_auth.py::test_login_handles_email_with_spaces -v # Expected: FAILED (demonstrates the bug) ``` **Phase 2 — Launch subagent:** ``` 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." ``` **Phase 3 — Verify:** ```bash # 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 ``` ## Integration with hooks The `bug-report-detector` hook in this plugin automatically: 1. Detects when a user reports a bug 2. Reminds Claude to follow the test-first workflow 3. Blocks Edit/Write tools until a test file has been created or modified ## Additional resources ### Reference files - **`references/test-frameworks.md`** — Framework-specific test patterns - **`references/common-bugs.md`** — Common bug patterns and test strategies ### Example files - **`examples/python-bug-test.py`** — Python pytest example - **`examples/js-bug-test.js`** — JavaScript Jest example ### Scripts - **`scripts/find-tests.sh`** — Locate test infrastructure in a project