tdd-workflow

TDD Workflow (TypeScript/JavaScript)

The RED-GREEN-REFACTOR loop tells you how to write one test. This skill is one level up: how a whole feature's test surface is planned across the test pyramid, wired into CI, and gated on coverage, in a Jest/Vitest + Playwright stack. For the loop itself and the Prove-It bug-fix pattern, see skills/test-driven-development/ — that skill applies inside every step below.

Use skills/laravel-tdd/ instead for PHP/Laravel; use this skill for Next.js/React/Node projects with Jest, Vitest, Testing Library, or Playwright.

From user journey to test cases

Start from the observable behavior, not the implementation:

As a user, I want to search for markets semantically,
so that I can find relevant markets even without exact keywords.

describe('Semantic Search', () => {
  it('returns relevant markets for query', async () => {})
  it('handles empty query gracefully', async () => {})
  it('falls back to substring search when Redis unavailable', async () => {})
  it('sorts results by similarity score', async () => {})
})

Write the cases before any implementation exists; the shape of the describe block is the spec for what "search" means here — including the fallback and the empty-input path, not just the primary path.

Test pyramid for this stack

• Unit (Jest/Vitest + Testing Library) — components and pure functions in isolation. Test user-visible behavior (screen.getByText), not internal state (component.state.count) — internal state can be correct while the rendered output is wrong, and refactors that preserve behavior will still break a state-shape assertion.
• Integration — API route handlers against a real or in-memory database boundary, external services mocked.
• E2E (Playwright) — a small number of critical user flows through a real browser. Prefer semantic selectors (button:has-text("Submit"), [data-testid=...]) over CSS class selectors, which break on any style refactor unrelated to the behavior under test.