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

1. Behavior over Implementation – Test what users see, not how code works
2. Exhaustive Coverage – Every branch, every condition, every edge case
3. Context Awareness – Every test must define its preconditions explicitly
4. 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:

1. Requirements Definition – Define “correct” behavior with Gherkin specs
2. Code Change Tracking – Know exactly what changed
3. State Machine Analysis – Map all UI states and transitions
4. 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

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

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