factory-testing

Factory testing

Each section leads with Principle (one sentence, stack-agnostic), then Why (constraint → option → tradeoff), then Recipe (the Vitest / Playwright / test-utils shape we use), and Failure mode when there's one to name.

The kit is opinionated on the recipe layer (Vitest + Playwright + __tests__ co-location + shared test-utils). A reader on a different stack can read the principle and skip the recipe.

Tests-before-merge — coverage gates, not test-first dogma

Principle. Every PR ships with tests that cover the new behavior; CI enforces a coverage floor; the kit does not mandate red-green-refactor authoring.

Why. Strict TDD is unenforceable mechanically — a commit hook can't see whether the test was written before or after the code. A coverage floor is enforceable: CI either passes or fails. The trade-off accepted: we lose the design-pressure of test-first authoring; we keep a gate that catches the actual failure mode (un-tested code merging). Strict test-first also contradicts how most of the factory's existing code was written, which would make the rule aspirational from day one — and aspirational rules erode all the others.

Recipe. Coverage thresholds live in vitest.config.ts and are enforced by vitest --coverage:

// vitest.config.ts
import { defineConfig } from 'vitest/config';
import react from '@vitejs/plugin-react';
import path from 'path';

export default defineConfig({
  plugins: [react()],
  test: {
    environment: 'happy-dom',
    globals: true,
    setupFiles: ['./src/lib/test-utils.tsx'],
    exclude: ['node_modules', 'e2e/**'],
    coverage: {
      provider: 'v8',
      reporter: ['text', 'json', 'html', 'lcov'],
      exclude: [
        'node_modules/',
        'src/lib/test-utils.tsx',
        '**/*.test.{ts,tsx}',
        '**/*.spec.{ts,tsx}',
        '**/types.ts',
        '**/*.d.ts',
      ],
      thresholds: {
        lines: 70,
        functions: 70,
        branches: 60,
        statements: 70,
      },
    },
  },
  resolve: { alias: { '@': path.resolve(__dirname, './src') } },
});