TDD Red / Green / Refactor

Use this skill whenever making code changes that should be covered by tests.

Non-negotiables

• Start with a failing test that expresses the behavior (red).
• Implement the smallest change to pass (green).
• Refactor for clarity/structure after green, keeping tests passing.
• If no tests exist, add a minimal test harness + a failing test first.

Workflow

1. Identify the smallest observable behavior.
2. Add or update a test to fail on current code.
3. Run the smallest relevant test command (targeted if possible).
4. Implement the minimal code to make it pass.
5. Refactor with tests still green.
6. Report: test command(s) run + results.

If tests cannot run

• State why (missing deps, env, credentials, etc.).
• Still write the failing test first and note the expected outcome.
• Provide a suggested test command for the user to run.

Test targeting

Prefer the narrowest scope:

• single file
• package-level
• repo-level only if needed

Typecheck policy

Types always pass. Do not blame pre-existing errors. Fix or revert.

WE USE VITEST - NOT BUN:TEST

This is non-negotiable. Never use bun:test imports or APIs.

typescript
1// ✅ CORRECT - Vitest
2import { describe, it, expect, vi, beforeEach } from 'vitest'
3
4// ❌ WRONG - bun:test (DO NOT USE)
5import { describe, it, expect, mock } from 'bun:test'

Test commands

bash
1# All tests via Turborepo
2bun run test
3
4# Filtered by package
5bun run test --filter=@skillrecordings/core
6bun run test --filter=web
7
8# Direct Vitest (when you need fine-grained control)
9bun run test:all
10bun run test:all -- -t "name of test"
11bun run test:all -- packages/core/src/tools/process-refund.test.ts

Common Vitest patterns

typescript
1// Mocking
2const mockFn = vi.fn()
3vi.mocked(someModule).someMethod.mockResolvedValue(result)
4
5// Hoisting mocks (required for factory functions)
6const mockClient = vi.hoisted(() => ({ method: vi.fn() }))
7vi.mock('./client', () => ({ client: mockClient }))
8
9// Spying
10vi.spyOn(object, 'method').mockImplementation(...)

Notes to include in the response

• Which test you wrote first.
• The command used to hit red and green.
• Any refactor that changed structure but not behavior.