----|----------------------|-----------| | Test Runner | Vitest or Jest + Testing Library | Native ESM, fast HMR, query-based assertions | | DOM Environment | jsdom or happy-dom | Lightweight, spec-compliant, sufficient for 95% of components | | Mocking Strategy | Module-level mocks + service workers | Isolates network without coupling to HTTP clients | | Snapshot Usage | Minimal, structural only | Prevents false confidence; use for serialization, not UI | | Coverage Target | 75–85% for component files | Focus on branches, not lines; ignore trivial renders |

Code Example: Behavioral Component Test (React + Vitest + Testing Library)

// components/DataTable.tsx
import { useState } from 'react';

type Row = { id: number; name: string; status: 'active' | 'inactive' };

export function DataTable({ rows, onRowSelect }: { rows: Row[]; onRowSelect: (id: number) => void }) {
  const [filter, setFilter] = useState<'all' | 'active' | 'inactive'>('all');
  
  const visibleRows = rows.filter(r => 
    filter === 'all' || r.status === filter
  );

  return (
    <div>
      <select data-testid="filter" value={filter} onChange={e => setFilter(e.target.value as typeof filter)}>
        <option value="all">All</option>
        <option value="active">Active</option>
        <option value="inactive">Inactive</option>
      </select>
      <ul>
        {visibleRows.map(row => (
          <li key={row.id} onClick={() => onRowSelect(row.id)} role="button" tabIndex={0}>
            {row.name}
          </li>
        ))}
      </ul>
    </div>
  );
}

// __tests__/DataTable.test.tsx
import { render, screen, fireEvent, waitFor } from '@testing-library/react';
import { vi } from 'vitest';
import { DataTable } from '../components/DataTable';

const mockRows = [
  { id: 1, name: 'Alpha', status: 'active' },
  { id: 2, name: 'Beta', status: 'inactive' },
  { id: 3, name: 'Gamma', status: 'active' }
];

describe('DataTable', () => {
  it('filters rows based on selection and triggers callback', async () => {
    const onSelect = vi.fn();
    render(<DataTable rows={mockRows} onRowSelect={onSelect} />);

    // Initial render shows all rows
    expect(screen.getByRole('list').children).toHaveLength(3);

    // Filter to active
    fireEvent.change(screen.getByTestId('filter'), { target: { value: 'active' } });
    
    await waitFor(() => {
      expect(screen.getByRole('list').children).toHaveLength(2);
    });

    // Click row triggers callback
    fireEvent.click(screen.getByRole('button', { name: 'Alpha' }));
    expect(onSelect).toHaveBeenCalledWith(1);
  });
});

Key patterns applied:

• Queries by role/text, not DOM structure
• waitFor handles React state batching
• Callback verified via spy, not internal state
• No snapshot assertions; behavior-driven validation

Pitfall Guide

1. Testing Implementation Details Asserting state, refs, useEffect calls, or internal methods ties tests to architecture. Refactors break tests without changing behavior. Solution: Query rendered output and verify callbacks/events.

2. Snapshot Abuse Snapshots capture DOM structure, not behavior. They pass even when accessibility or interaction breaks. Solution: Use snapshots only for serialization, config objects, or stable contracts. Never for UI.

3. Ignoring Async State Transitions React/Vue batch updates. Tests that assert immediately after state changes fail intermittently. Solution: Use waitFor, findBy*, or explicit await on async utilities. Fake timers for scheduled callbacks.

4. Coupling to CSS/Styling Frameworks Tests that query by class names or inline styles break on theme updates or CSS-in-JS changes. Solution: Query by role, label, test ID, or text content. Style should never drive test assertions.

5. Inconsistent Mocking Boundaries Mocking too deeply hides integration bugs; mocking too shallowly introduces network flake. Solution: Mock at service/API boundaries. Keep child components and context providers real unless explicitly testing isolation.

6. Skipping Accessibility & Keyboard Navigation Components that work with mouse input often fail screen readers or keyboard users. Solution: Assert aria-* attributes, tabindex, focus management, and keyboard event handlers. Use axe-core or built-in a11y queries.

7. Running Tests in Non-Production Environments Testing with dev-only polyfills, mock data shapes, or disabled error boundaries creates false confidence. Solution: Align test environment with production builds. Use same bundler config, same strict mode, same error handling.

Production Bundle

Action Checklist

• Map component public contracts (inputs, outputs, boundaries)
• Select behavioral query strategy (role, label, text, test ID)
• Configure deterministic async handling (waitFor, fake timers)
• Establish mocking boundaries (network vs. composition)
• Set coverage thresholds per component directory
• Integrate component tests into CI pipeline with parallel execution
• Audit existing tests for implementation detail coupling and refactor
• Enable accessibility assertions in test runner

Decision Matrix

Configuration Template

vitest.config.ts

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

export default defineConfig({
  plugins: [react()],
  test: {
    environment: 'jsdom',
    globals: true,
    setupFiles: ['./test/setup.ts'],
    include: ['src/**/__tests__/**/*.test.{ts,tsx}'],
    coverage: {
      provider: 'v8',
      include: ['src/components/**/*.{ts,tsx}'],
      thresholds: {
        branches: 80,
        functions: 85,
        lines: 80,
        statements: 80
      }
    },
    alias: {
      '@/': new URL('./src/', import.meta.url).pathname
    }
  }
});

test/setup.ts

import '@testing-library/jest-dom/vitest';
import { cleanup } from '@testing-library/react';
import { afterEach } from 'vitest';

// Auto-cleanup after each test
afterEach(() => {
  cleanup();
});

// Polyfill ResizeObserver if needed
global.ResizeObserver = class ResizeObserver {
  observe() {}
  unobserve() {}
  disconnect() {}
};

// Silence console errors/warnings during tests unless explicitly testing them
const originalError = console.error;
console.error = (...args) => {
  if (typeof args[0] === 'string' && args[0].includes('act(')) return;
  originalError(...args);
};

Quick Start Guide

1. Initialize Runner & Library Install vitest, @testing-library/react (or Vue/Testing Library equivalent), and @testing-library/jest-dom. Configure vitest.config.ts with jsdom environment and setup file.

2. Create First Behavioral Test Pick a presentational or controlled component. Write a test that renders the component, interacts with a queryable element, and asserts an output (DOM change, callback, or state reflection). Use role/text queries. Avoid implementation details.

3. Enforce Async Determinism Replace immediate assertions after state changes with waitFor or findBy*. Add fake timers for scheduled callbacks. Ensure tests await microtask resolution before verifying outcomes.

4. Integrate & Gate CI Add component test script to package.json. Configure CI to run tests in parallel. Set coverage thresholds. Block merges on regression. Schedule periodic flakiness audits and refactor coupling patterns.

Component testing is not optional infrastructure. It is the structural load-bearing layer that keeps UI validation fast, stable, and production-aligned. Implement it deliberately, enforce behavioral contracts, and eliminate implementation coupling. The ROI compounds across CI velocity, defect escape reduction, and engineering sanity.