Testing Skill (Orchestrator)

This skill coordinates testing strategy across all test types. Tests are colocated with the code they test - when viewing a module, you see all its tests nearby.

Test Type Index

Testing
│
├── Static Analysis
│   └── Linting ─────────────────── ESLint syntax/import checks
│
├── Data Model Tests (Vitest)
│   ├── Pure Logic Tests ────────── Single functions, math, state transitions
│   └── Matrix Progression Tests ── 2D grid evolution over time (ASCII diagrams)
│
├── Component Tests (Vitest + Testing Library)
│   └── React Component Tests ───── Behavior, state, user interactions
│
├── Visual Regression (Playwright)
│   ├── Component Screenshots ───── React component pixel comparison
│   └── Canvas Filmstrip Tests ──── Matrix-to-canvas rendered progressions
│
└── Integration / E2E (Playwright)
    └── Smoke Tests ─────────────── App loads without JS errors

Test Types, Files, and Colocation

All tests are colocated with their source. When you open a folder, you see the code and all its tests together.

Data Model Tests

src/state/
  waveModel.ts              ← Source
  waveModel.test.ts         ← Logic test (colocated)

src/render/
  bathymetryProgressions.ts      ← Matrix definitions
  bathymetryProgressions.test.ts ← ASCII progression test (colocated)

Component Tests

src/ui/
  WaveControls.tsx          ← Component
  WaveControls.test.tsx     ← Behavior test (colocated)

Visual Regression Tests

stories/01-bathymetry/
  01-bathymetry.mdx              ← Story documentation
  01-bathymetry.visual.spec.ts   ← Visual test (colocated)
  strip-bathymetry-basic.png     ← Baseline screenshot (colocated)
  strip-bathymetry-features.png  ← Baseline screenshot (colocated)

Integration Tests

Choosing the Right Test Type

Test Order (Fastest First)

Run cheap tests first to catch issues early:

┌─────────────────────────────────────────────────────────────┐
│ 1. Lint                    ~1s    npm run lint              │
├─────────────────────────────────────────────────────────────┤
│ 2. Smoke                   ~3s    npx playwright test       │
│                                   tests/smoke.spec.js       │
├─────────────────────────────────────────────────────────────┤
│ 3. Logic/Progression      ~secs   npx vitest run <file>     │
├─────────────────────────────────────────────────────────────┤
│ 4. Component Tests        ~secs   npx vitest run <file>     │
├─────────────────────────────────────────────────────────────┤
│ 5. Visual Regression      ~mins   npm run test:visual:      │
│                                   headless                  │
└─────────────────────────────────────────────────────────────┘

Stop and fix at the first failure. Don't run expensive visual tests when data tests are failing.

Quick Reference

# Static analysis
npm run lint                              # ~1s

# Smoke test
npx playwright test tests/smoke.spec.js   # ~3s

# Data model tests (Vitest)
npx vitest run src/path/file.test.ts      # Specific file
npx vitest run src/render/*Progressions*  # All progression tests
npm test                                   # All Vitest tests

# Visual regression (Playwright)
npm run stories:build                      # Verify stories compile
npm run test:visual:headless               # Run visual regression
npm run test:visual:update:headless        # Update baselines
npm run reset:visual                       # Clear results
npm run reset:visual:all                   # Clear results + baselines

Debugging by Symptom

Skill Index

Critical Principles

1. Colocation

Tests live next to what they test. Don't hunt for tests in a separate tests/ tree.

2. Data Gates Visual

Never run visual tests when data tests fail. The matrix is the source of truth - if the numbers are wrong, the pixels will be wrong too.

3. Test Utilities Must Be Tested

src/test-utils/ is foundational. A bug there corrupts all tests:

npx vitest run src/test-utils/