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

code

┌──────────────────────────────────┐
│  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):

bash

just test-mocks        # Unit tests without database

Integration Tests (with database):

bash

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:

bash

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:

bash

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:

bash

# 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)

code

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)

bash

# 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

bash

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

bash

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

bash

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

bash

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

typescript

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

✅ DO: Test user interactions

typescript

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

❌ DON'T: MSW double-wrapping

typescript

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

✅ DO: Return unwrapped data

typescript

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

E2E

❌ DON'T: Write E2E before unit tests

typescript

// No unit test → straight to E2E ❌

✅ DO: Follow the pyramid

bash

# Unit → API → Component → E2E ✅

❌ DON'T: Multiple concerns in one test

typescript

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

✅ DO: One concern per test

typescript

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

❌ DON'T: Arbitrary timeouts

typescript

await page.waitForTimeout(3000)  // ❌ Flaky

✅ DO: Explicit waits

typescript

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:

•testing-pyramid.md - Understand the approach
•backend-testing.md OR frontend-testing.md - Your domain
•test-fixtures.md - Set up test data
•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 ✅