Testing Patterns

Purpose

Comprehensive guide to testing in ActionPhase, covering the testing pyramid, TDD workflow, and patterns for backend (Go), frontend (React/TypeScript), and E2E (Playwright) testing.

When to Use This Skill

• Writing any type of test (unit, component, E2E)
• Debugging test failures
• Understanding the testing pyramid
• Implementing TDD workflow
• Fixing bugs (regression testing)
• Setting up test fixtures
• Understanding E2E testing rules

---

Testing Philosophy

"Tests are MANDATORY for all new features and bug fixes"

THE GOLDEN RULE: E2E tests are the LAST step, NEVER the first!

---

The Testing Pyramid

┌──────────────────────────────────┐
│  4. E2E Tests (Playwright)       │ ← Slow (20-30s each), expensive, LAST
│     ~30 tests                    │    Write ONLY after lower levels pass
├──────────────────────────────────┤
│  3. Component Tests (React)      │ ← Medium speed (~15-20s total)
│     1,022 tests                  │    Test user interactions
├──────────────────────────────────┤
│  2. API Integration Tests        │ ← Fast verification
│     (curl verification)          │    Verify endpoints work
├──────────────────────────────────┤
│  1. Unit Tests (Go/TypeScript)   │ ← Fastest (~300ms for mocks)
│     467 backend tests            │    Write FIRST, test behavior
└──────────────────────────────────┘

Total: 1,489 passing tests (100% pass rate)

See: testing-pyramid.md for detailed explanation

---

Quick Reference

Backend Testing (Go)

Unit Tests (FAST - ~300ms):

just test-mocks        # Unit tests without database

Integration Tests (with database):

just test              # All tests (unit + integration)
just test-integration  # Integration tests only

Patterns:

• Table-driven tests with subtests
• Test database with automatic cleanup
• Mock interfaces for fast tests
• testify/assert and testify/require

See: backend-testing.md

Frontend Testing (React)

Component Tests:

just test-frontend           # Run all tests
just test-fe watch           # Watch mode
npm test -- Component.test.tsx  # Specific file

Patterns:

• React Testing Library (screen queries)
• MSW v2 for API mocking
• renderWithProviders() wrapper
• Test user interactions, not implementation

See: frontend-testing.md

E2E Testing (Playwright)

Run Tests:

just e2e               # Headless (auto-loads fixtures)
just e2e-test headed   # Visible browser
just e2e-test ui       # Interactive UI mode
just e2e-test debug    # Debug mode

CRITICAL: E2E tests are the LAST step!

See: e2e-testing.md

---

E2E Testing - Mandatory Checklist

⚠️ BEFORE writing ANY E2E test, ALL four must pass:

# 1. ✅ Backend unit test MUST pass
SKIP_DB_TESTS=true go test ./pkg/db/services -run TestFeature -v

# 2. ✅ API endpoint MUST return correct data
curl -X POST http://localhost:3000/api/v1/endpoint \
  -H "Authorization: Bearer $(cat /tmp/api-token.txt)" \
  -d '...' | jq '.expected_field'

# 3. ✅ Frontend component test MUST pass
npm test -- ComponentName.test.tsx

# 4. ✅ System verification MUST complete
curl -sf http://localhost:3000/health  # Backend running
curl -sf http://localhost:5173         # Frontend running

ONLY after all four pass → Write E2E test

See: e2e-testing.md for complete E2E guide

---

Testing Workflow

For New Features (TDD Approach)

1. Write unit test (should FAIL)
   ↓
2. Implement feature
   ↓
3. Unit test passes
   ↓
4. Test API with curl (verify endpoint)
   ↓
5. Write component test (if UI feature)
   ↓
6. Component test passes
   ↓
7. Verify system running
   ↓
8. Write E2E test (LAST STEP)

See: testing-pyramid.md

For Bug Fixes (Mandatory Regression Testing)

# 1. Write test that reproduces bug (should FAIL)
go test ./pkg/db/services -run TestBugFix -v
# Output: FAIL ❌

# 2. Fix the bug in code
# (make changes)

# 3. Verify test passes
go test ./pkg/db/services -run TestBugFix -v
# Output: PASS ✅

# 4. Commit test and fix together

See: bug-fix-workflow.md

---

Key Commands

Backend

just test              # All tests (467 tests)
just test-mocks        # Fast unit tests (~300ms)
just test-integration  # Database integration tests
just test-coverage     # Generate coverage report
just test-race         # Race condition detection
just test-run pattern  # Run specific test by name
just ci-test           # Full CI suite (lint + test + race)

Frontend

just test-frontend     # All frontend tests (1,022 tests)
just test-fe watch     # Watch mode for development
just test-fe coverage  # With coverage report
npm test -- Component.test.tsx  # Specific file

E2E

just e2e               # Run E2E tests (headless)
just e2e-test headed   # Visible browser
just e2e-test ui       # Interactive UI mode
just e2e-test debug    # Debug specific test
just e2e-test report   # View HTML report
just load-e2e          # Load E2E test fixtures

See: test-commands.md for complete reference

---

Test Data & Fixtures

Test Users

All passwords: testpassword123 Important: Usernames are case-sensitive (PascalCase!)

• GM: TestGM / test_gm@example.com
• Player 1: TestPlayer1 / test_player1@example.com
• Player 2: TestPlayer2 / test_player2@example.com
• Player 3-5: TestPlayer3, TestPlayer4, TestPlayer5
• Audience: TestAudience / test_audience@example.com

Test Games

10 games with various states (recruiting, running, paused, completed)

Key Test Games:

• Game 1: Shadows Over Innsmouth (common room phase)
• Game 2: The Heist at Goldstone Bank (action submissions)
• Game 6: Chronicles of Westmarch (pagination testing - 11 phases)

Fixture Commands

just test-fixtures     # Apply all fixtures
just load-e2e          # Load E2E fixtures (6 workers)
just test-data reload  # Reset and reload

See: test-fixtures.md for complete fixture documentation

---

Common Anti-Patterns

Backend

❌ DON'T: Hardcode test data

userID := 123  // Hardcoded

✅ DO: Use fixtures

user := testDB.CreateTestUser(t, "testuser", "test@example.com")

❌ DON'T: Skip cleanup

// Test creates data but doesn't clean up

✅ DO: Use defer cleanup

defer testDB.CleanupTables(t, "users", "games")

Frontend

❌ DON'T: Test implementation details

expect(component.state.count).toBe(1)  // Testing internal state

✅ DO: Test user interactions

expect(screen.getByText('Count: 1')).toBeInTheDocument()

❌ DON'T: MSW double-wrapping

http.get('/api/endpoint', () => {
  return HttpResponse.json({ data: mockData })  // ❌ axios wraps again
})

✅ DO: Return unwrapped data

http.get('/api/endpoint', () => {
  return HttpResponse.json(mockData)  // ✅ axios wraps automatically
})

E2E

❌ DON'T: Write E2E before unit tests

// No unit test → straight to E2E ❌

✅ DO: Follow the pyramid

# Unit → API → Component → E2E ✅

❌ DON'T: Multiple concerns in one test

test('feature works', async () => {
  // Tests autocomplete + submission + rendering + validation ❌
})

✅ DO: One concern per test

test('autocomplete appears when typing @', async () => {
  // Only tests autocomplete ✅
})

❌ DON'T: Arbitrary timeouts

await page.waitForTimeout(3000)  // ❌ Flaky

✅ DO: Explicit waits

await page.waitForSelector('[data-testid="element"]')  // ✅ Reliable

See: anti-patterns.md for complete list

---

Coverage Targets

Current Status

• Backend: 75.0% coverage (467 tests) - Target: 80%
• Frontend: ~60% coverage (1,022 tests) - Target: 60% ✅ MET
• E2E: 30 test files covering critical user journeys
• Pass Rate: 100% ✅

Quality Gates

• ✅ 100% pass rate on main
• ✅ All critical paths covered
• ✅ Regression tests for all known bugs
• ✅ Test execution < 5 minutes

See: coverage-targets.md

---

Real Code Examples

Code Examples

Backend - Table-driven tests with testDB fixtures Frontend - Component tests with RTL + MSW E2E - Playwright tests with auth helpers

See: real-examples.md for more examples

---

Navigation Guide

Need to...	Read this
Understand testing pyramid and workflow	testing-pyramid.md
Write backend unit/integration tests	backend-testing.md
Write frontend component/hook tests	frontend-testing.md
Write E2E tests with Playwright	e2e-testing.md
Use test fixtures and test data	test-fixtures.md
Find testing commands	test-commands.md
Avoid common mistakes	anti-patterns.md
Check coverage targets	coverage-targets.md
Fix bugs with TDD	bug-fix-workflow.md
See real code examples	real-examples.md

---

Related Skills & Context

Skills

• backend-dev-guidelines - Backend implementation patterns
• frontend-dev-guidelines - Frontend component patterns
• route-tester - API endpoint testing with curl
• game-domain - Game state testing scenarios
• test-fixtures - Test data management

Context Files

• .claude/context/TESTING.md - Primary testing reference (comprehensive)
• .claude/context/TEST_DATA.md - Test fixtures overview
• /docs/testing/COVERAGE_STATUS.md - Current coverage metrics
• /docs/testing/E2E_QUICK_START.md - E2E quick reference
• /docs/adrs/007-testing-strategy.md - Testing strategy decisions

---

Quick Start

New to testing in ActionPhase? Read in this order:

1. testing-pyramid.md - Understand the approach
2. backend-testing.md OR frontend-testing.md - Your domain
3. test-fixtures.md - Set up test data
4. e2e-testing.md - E2E patterns (read BEFORE writing E2E tests!)

Writing tests?

• test-commands.md - Find the right command
• real-examples.md - Copy patterns from working code

Debugging?

• anti-patterns.md - Check common mistakes
• bug-fix-workflow.md - TDD approach to bugs

---

Skill Status: COMPLETE ✅ Line Count: < 500 ✅ Progressive Disclosure: 10 resource files ✅ Coverage: Complete testing pyramid, all test types, TDD workflow ✅