Behavior-Driven Testing
Start from user behavior, not code structure. Every user-reachable path must be tested—no branch left uncovered, no edge case assumed.
Core Principles
- 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
Workflow Overview
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
Quick Reference: Must-Test Branches
| 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 |
The Whitespace Trap (Most Common Bug)
// ❌ WRONG - whitespace " " is truthy!
if (!text) throw new Error('Required');
// ✅ CORRECT
if (!text?.trim()) throw new Error('Required');
Common Mistakes
| 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 |
Branch Matrix Template
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 | ❌ Failed
Detailed References
Load 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)
Pre-Release Checklist
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
Related Skills
- test-driven-development - Write tests first, then implementation
- systematic-debugging - Debug issues methodically
1---2name: behavior-driven-testing3description: 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.4license: MIT5---6
7# Behavior-Driven Testing
8
9Start from user behavior, not code structure. Every user-reachable path must be tested—no branch left uncovered, no edge case assumed.
10
11## Core Principles
12
131. **Behavior over Implementation** - Test what users see, not how code works
142. **Exhaustive Coverage** - Every branch, every condition, every edge case
153. **Context Awareness** - Every test must define its preconditions explicitly
164. **Real Environment Validation** - Mocks are tools, not destinations
17
18## Workflow Overview
19
20Testing follows three phases. Follow them in order:
21
22```
23Analysis → Design → Execution → Verify Coverage → Ship (or loop back)
24```
25
26**Analysis Phase:**
271. Requirements Definition - Define "correct" behavior with Gherkin specs
282. Code Change Tracking - Know exactly what changed
293. State Machine Analysis - Map all UI states and transitions
304. Branch Mapping - Create the branch matrix (core artifact)
31
32**Design Phase:**
335. Test Case Design - Apply equivalence partitioning, boundary analysis
346. Impact Analysis - Ensure new code doesn't break existing behavior
357. Test Prioritization - P0 (every commit) → P3 (periodic)
36
37**Execution Phase:**
388. Test Data Preparation - Create fixtures, mocks, factories
399. Test Implementation - Write unit, integration, E2E tests
4010. Test Execution - Run tests in phases (local → CI → staging)
4111. Coverage Verification - Verify branch matrix completion
42
43## Quick Reference: Must-Test Branches
44
45| Category | Test Cases | Priority |
46|----------|------------|:--------:|
47| **Empty values** | null, undefined, "", " " (whitespace), [], {} | P0 |
48| **Boundaries** | min-1, min, min+1, max-1, max, max+1 | P1 |
49| **Auth states** | logged in, logged out, loading, session expired | P0 |
50| **API responses** | 200+data, 200+empty, 400, 401, 403, 404, 500, timeout, offline | P0 |
51| **User chaos** | double-click, rapid navigation, refresh mid-action, back button | P1 |
52
53### The Whitespace Trap (Most Common Bug)
54
55```javascript
56// ❌ WRONG - whitespace " " is truthy!
57if (!text) throw new Error('Required');
58
59// ✅ CORRECT
60if (!text?.trim()) throw new Error('Required');
61```
62
63## Common Mistakes
64
65| Mistake | Why It's Bad | Fix |
66|---------|--------------|-----|
67| Only happy path | Error paths are 50% of code | Test ALL branches |
68| Skip empty value tests | Most common production bugs | Test null, undefined, "", whitespace separately |
69| Mock everything | Mocks hide real problems | Add integration + E2E tests |
70| "Tested manually" | Not repeatable, not reliable | Automate it |
71| Ignore loading states | Users interact during load | Test loading behavior |
72| Skip double-click test | Users double-click everything | Test rapid interactions |
73
74## Branch Matrix Template
75
76For each code change, create a branch matrix:
77
78```markdown
79| ID | Condition | True Behavior | False Behavior | Priority | Status |
80|----|-----------|---------------|----------------|:--------:|:------:|
81| B01 | user.isPremium | Skip credit check | Check credits | P0 | ⬜ |
82| B02 | credits >= required | Proceed | Show error | P0 | ⬜ |
83| B03 | credits == required | Boundary: Proceed | - | P1 | ⬜ |
84
85Status: ⬜ Pending | ✅ Passed | ❌ Failed
86```
87
88## Detailed References
89
90Load these files only when you need detailed guidance:
91
92- **Analysis details**: See [references/analysis-phase.md](references/analysis-phase.md)
93 - Gherkin specification format
94 - State machine diagrams
95 - Complete branch mapping methodology
96
97- **Test templates**: See [references/test-templates.md](references/test-templates.md)
98 - Unit test structure (Vitest/Jest)
99 - Integration test patterns
100 - E2E test examples (Playwright)
101
102- **Branch matrices**: See [references/branch-matrices.md](references/branch-matrices.md)
103 - Entry point branches
104 - Authentication branches
105 - API response branches
106 - Input validation branches
107
108- **Testing principles**: See [references/testing-principles.md](references/testing-principles.md)
109 - Mock vs Real testing
110 - Creating test conditions you don't have
111 - Progressive testing strategy (Day 1-4)
112
113## Pre-Release Checklist
114
115Before shipping, verify:
116
117```markdown
118## Mock Tests (CI)
119- [ ] All unit tests pass
120- [ ] All integration tests pass
121- [ ] Coverage thresholds met
122
123## Real Tests (Before release)
124- [ ] E2E tests pass on staging
125- [ ] Manual smoke test on staging
126- [ ] Core paths verified in real environment
127
128## Branch Matrix
129- [ ] All P0 branches tested
130- [ ] All P1 branches tested
131- [ ] No untested edge cases
132
133## Production (After deploy)
134- [ ] Smoke test passes
135- [ ] Error rate monitoring normal
136```
137
138## Related Skills
139
140- test-driven-development - Write tests first, then implementation
141- systematic-debugging - Debug issues methodically
majiayu000