| name | behavior-driven-testing | ||||||
|---|---|---|---|---|---|---|---|
| description | Systematic testing methodology for exhaustive branch coverage, edge case identification, and production bug prevention. Use when PR review reveals incomplete test coverage, when tests pass but users report bugs, when code changes break existing features, when verifying all branches and edge cases before merge, when analyzing "it works on my machine" issues, when planning test strategy for new features, or when debugging flaky tests and race conditions. | ||||||
| license | MIT | ||||||
| metadata |
|
Start from user behavior, not code structure. Every user-reachable path must be tested—no branch left uncovered, no edge case assumed.
- Behavior over Implementation - Test what users see, not how code works
- Exhaustive Coverage - Every branch, every condition, every edge case
- Context Awareness - Every test must define its preconditions explicitly
- Real Environment Validation - Mocks are tools, not destinations
Testing follows three phases. Follow them in order:
Analysis → Design → Execution → Verify Coverage → Ship (or loop back)
Analysis Phase:
- Requirements Definition - Define "correct" behavior with Gherkin specs
- Code Change Tracking - Know exactly what changed
- State Machine Analysis - Map all UI states and transitions
- Branch Mapping - Create the branch matrix (core artifact)
Design Phase: 5. Test Case Design - Apply equivalence partitioning, boundary analysis 6. Impact Analysis - Ensure new code doesn't break existing behavior 7. Test Prioritization - P0 (every commit) → P3 (periodic)
Execution Phase: 8. Test Data Preparation - Create fixtures, mocks, factories 9. Test Implementation - Write unit, integration, E2E tests 10. Test Execution - Run tests in phases (local → CI → staging) 11. Coverage Verification - Verify branch matrix completion
| Category | Test Cases | Priority |
|---|---|---|
| Empty values | null, undefined, "", " " (whitespace), [], {} | P0 |
| Boundaries | min-1, min, min+1, max-1, max, max+1 | P1 |
| Auth states | logged in, logged out, loading, session expired | P0 |
| API responses | 200+data, 200+empty, 400, 401, 403, 404, 500, timeout, offline | P0 |
| User chaos | double-click, rapid navigation, refresh mid-action, back button | P1 |
// ❌ WRONG - whitespace " " is truthy!
if (!text) throw new Error('Required');
// ✅ CORRECT
if (!text?.trim()) throw new Error('Required');| Mistake | Why It's Bad | Fix |
|---|---|---|
| Only happy path | Error paths are 50% of code | Test ALL branches |
| Skip empty value tests | Most common production bugs | Test null, undefined, "", whitespace separately |
| Mock everything | Mocks hide real problems | Add integration + E2E tests |
| "Tested manually" | Not repeatable, not reliable | Automate it |
| Ignore loading states | Users interact during load | Test loading behavior |
| Skip double-click test | Users double-click everything | Test rapid interactions |
For each code change, create a branch matrix:
| ID | Condition | True Behavior | False Behavior | Priority | Status |
|----|-----------|---------------|----------------|:--------:|:------:|
| B01 | user.isPremium | Skip credit check | Check credits | P0 | ⬜ |
| B02 | credits >= required | Proceed | Show error | P0 | ⬜ |
| B03 | credits == required | Boundary: Proceed | - | P1 | ⬜ |
Status: ⬜ Pending | ✅ Passed | ❌ FailedLoad these files only when you need detailed guidance:
-
Analysis details: See references/analysis-phase.md
- Gherkin specification format
- State machine diagrams
- Complete branch mapping methodology
-
Test templates: See references/test-templates.md
- Unit test structure (Vitest/Jest)
- Integration test patterns
- E2E test examples (Playwright)
-
Branch matrices: See references/branch-matrices.md
- Entry point branches
- Authentication branches
- API response branches
- Input validation branches
-
Testing principles: See references/testing-principles.md
- Mock vs Real testing
- Creating test conditions you don't have
- Progressive testing strategy (Day 1-4)
Before shipping, verify:
## Mock Tests (CI)
- [ ] All unit tests pass
- [ ] All integration tests pass
- [ ] Coverage thresholds met
## Real Tests (Before release)
- [ ] E2E tests pass on staging
- [ ] Manual smoke test on staging
- [ ] Core paths verified in real environment
## Branch Matrix
- [ ] All P0 branches tested
- [ ] All P1 branches tested
- [ ] No untested edge cases
## Production (After deploy)
- [ ] Smoke test passes
- [ ] Error rate monitoring normal- test-driven-development - Write tests first, then implementation
- systematic-debugging - Debug issues methodically