Test-Driven Development Workflow
This skill ensures all code development follows TDD principles with comprehensive test coverage.
When to Activate
- Writing new features or functionality
- Fixing bugs or issues
- Refactoring existing code
- Adding API endpoints
- Creating new components
Core Principles
1. Tests BEFORE Code
ALWAYS write tests first, then implement code to make tests pass.
2. Coverage Requirements
- Minimum 80% coverage (unit + integration + E2E)
- All edge cases covered
- Error scenarios tested
- Boundary conditions verified
3. Test Types
Unit Tests
- Individual functions and utilities
- Component logic
- Pure functions
- Helpers and utilities
Integration Tests
- API endpoints
- Database operations
- Service interactions
- External API calls
E2E Tests (Playwright)
- Critical user flows
- Complete workflows
- Browser automation
- UI interactions
TDD Workflow Steps
Step 0: Detect the Test Runner
Do not assume npm test. The commands in the steps and examples below use <test>, <test-watch>, and <coverage> as placeholders for the project's actual runner. Resolve them once before starting:
-
Run the package-manager detector (ships with ECC):
It resolves the package manager (npm / pnpm / yarn / bun) from, in order:
CLAUDE_PACKAGE_MANAGER,.claude/package-manager.json, thepackage.jsonpackageManagerfield, the lockfile, then global config. -
Distinguish the package manager from the test runner — they are not the same. A project can use Bun to install dependencies yet still run Jest or Vitest. Inspect
package.jsonscripts.testand the test files:scripts.testinvokesjest/vitest-> run through the detected PM (npm test,pnpm test,yarn test, orbun run test).scripts.testisbun test, or test filesimport { test, expect } from "bun:test", or there is no jest/vitest config but Bun is present -> use Bun's native runner (bun test). See Bun Native Test Pattern below.
Runner command matrix:
bun test(Bun's built-in runner) is not the same asbun run test(which runs thepackage.jsontestscript). Picking the wrong one is a common failure — e.g. invoking Jest throughnpx/bun runin an ESM-only project breaks, whilebun testruns the suite natively. Confirm which the project expects before the RED gate, then substitute<test>/<coverage>everywherenpm testappears below.
Step 1: Write User Journeys
Step 2: Generate Test Cases
For each user journey, create comprehensive test cases:
Step 3: Run Tests (They Should Fail)
Step 4: Implement Code
Write minimal code to make tests pass:
Step 5: Run Tests Again
Step 6: Refactor
Improve code quality while keeping tests green:
- Remove duplication
- Improve naming
- Optimize performance
- Enhance readability
Step 7: Verify Coverage
Testing Patterns
Unit Test Pattern (Jest/Vitest)
Bun Native Test Pattern (bun:test)
When the project uses Bun's built-in runner (see Step 0), import from bun:test and run with bun test — not bun run test. The API is Jest-like, so describe / it / expect and most matchers carry over. See the bun-runtime skill for runtime, install, and bundler details.
- Mock modules with
mock.module(...)/mock(...)frombun:testinstead ofjest.mock(...). - Configure coverage thresholds in
bunfig.tomlunder[test](e.g.coverageThreshold) rather than the JestcoverageThresholdsconfig block.
API Integration Test Pattern
E2E Test Pattern (Playwright)
Test File Organization
Mocking External Services
Supabase Mock
Redis Mock
OpenAI Mock
Test Coverage Verification
Run Coverage Report
Coverage Thresholds
Common Testing Mistakes to Avoid
FAIL: WRONG: Testing Implementation Details
PASS: CORRECT: Test User-Visible Behavior
FAIL: WRONG: Brittle Selectors
PASS: CORRECT: Semantic Selectors
FAIL: WRONG: No Test Isolation
PASS: CORRECT: Independent Tests
Continuous Testing
Watch Mode During Development
Pre-Commit Hook
CI/CD Integration
Best Practices
- Write Tests First - Always TDD
- One Assert Per Test - Focus on single behavior
- Descriptive Test Names - Explain what's tested
- Arrange-Act-Assert - Clear test structure
- Mock External Dependencies - Isolate unit tests
- Test Edge Cases - Null, undefined, empty, large
- Test Error Paths - Not just happy paths
- Keep Tests Fast - Unit tests < 50ms each
- Clean Up After Tests - No side effects
- Review Coverage Reports - Identify gaps
Success Metrics
- 80%+ code coverage achieved
- All tests passing (green)
- No skipped or disabled tests
- Fast test execution (< 30s for unit tests)
- E2E tests cover critical user flows
- Tests catch bugs before production
Remember: Tests are not optional. They are the safety net that enables confident refactoring, rapid development, and production reliability.

