Pure Functions, Hooks, State) Focus on deterministic logic without DOM dependencies. Test custom hooks, state machines, and utility functions in complete isolation.

// useToggle.test.ts
import { renderHook, act } from '@testing-library/react';
import { useToggle } from './useToggle';

describe('useToggle', () => {
  it('should initialize with default state', () => {
    const { result } = renderHook(() => useToggle(false));
    expect(result.current[0]).toBe(false);
  });

  it('should toggle state on trigger', () => {
    const { result } = renderHook(() => useToggle(false));
    act(() => result.current[1]());
    expect(result.current[0]).toBe(true);
    act(() => result.current[1]());
    expect(result.current[0]).toBe(false);
  });

  it('should accept controlled state', () => {
    const { result } = renderHook(() => useToggle(true, true));
    expect(result.current[0]).toBe(true);
    act(() => result.current[1]());
    expect(result.current[0]).toBe(true); // controlled mode ignores toggle
  });
});

2. Integration & Behavior Testing (Interaction Contracts)

Validate how components respond to user actions, events, and prop changes. Use @testing-library/react to query by role, label, or accessible name. Avoid implementation-specific selectors.

// Button.test.tsx
import { render, screen, fireEvent } from '@testing-library/react';
import { Button } from './Button';

describe('Button', () => {
  it('should call onClick with correct payload', () => {
    const handleClick = vi.fn();
    render(<Button onClick={handleClick} variant="primary">Submit</Button>);
    
    fireEvent.click(screen.getByRole('button', { name: /submit/i }));
    expect(handleClick).toHaveBeenCalledTimes(1);
    expect(handleClick).toHaveBeenCalledWith(expect.any(Object));
  });

  it('should disable interaction when disabled prop is true', () => {
    render(<Button disabled>Submit</Button>);
    const btn = screen.getByRole('button', { name: /submit/i });
    expect(btn).toBeDisabled();
    expect(btn).toHaveAttribute('aria-disabled', 'true');
  });

  it('should render loading state with accessible indicator', () => {
    render(<Button loading>Loading</Button>);
    expect(screen.getByRole('status')).toBeInTheDocument();
    expect(screen.getByRole('button')).toHaveAttribute('aria-busy', 'true');
  });
});

3. Visual & Regression Testing (Deterministic Rendering)

Use Storybook for isolated component rendering and Playwright/Chromatic for visual diffing. Disable animations, enforce consistent fonts, and snapshot across theme variants.

// visual.spec.ts
import { test, expect } from '@playwright/experimental-ct-react';
import { Button } from './Button';

test.describe('Button Visual Regression', () => {
  test('should match baseline across themes', async ({ mount, page }) => {
    const themes = ['light', 'dark', 'high-contrast'];
    
    for (const theme of themes) {
      await page.addStyleTag({ content: `:root { --theme: ${theme}; }` });
      const component = await mount(<Button variant="primary">Submit</Button>);
      await expect(component).toHaveScreenshot(`button-${theme}.png`, {
        animations: 'disabled',
        maxDiffPixels: 10,
      });
    }
  });
});

4. Accessibility Testing (Automated Compliance)

Integrate axe-core into integration tests. Validate ARIA attributes, keyboard navigation, focus management, and color contrast.

// a11y.spec.ts
import { test, expect } from '@playwright/experimental-ct-react';
import { axeCheck, injectAxe } from 'axe-playwright';
import { Modal } from './Modal';

test('Modal should pass a11y ruleset', async ({ mount, page }) => {
  await injectAxe(page);
  await mount(<Modal open onClose={() => {}}>
    <h2>Confirm Action</h2>
    <button>Cancel</button>
    <button>Confirm</button>
  </Modal>);

  const results = await axeCheck(page, {
    rules: {
      'color-contrast': { enabled: true },
      'focus-trap': { enabled: true },
      'aria-required-children': { enabled: true },
    }
  });
  
  expect(results.violations).toHaveLength(0);
});

5. Performance & Bundle Validation

Enforce size budgets and render-time thresholds. Use rollup-plugin-visualizer or size-limit to track component weight. Validate that tree-shaking eliminates unused code.

// package.json
{
  "scripts": {
    "test:size": "size-limit"
  },
  "size-limit": [
    {
      "path": "dist/button/index.js",
      "limit": "12 KB"
    },
    {
      "path": "dist/modal/index.js",
      "limit": "18 KB"
    }
  ]
}

Pitfall Guide

1. Over-Reliance on Snapshot Tests

   • Symptom: CI fails on every minor style change or dependency upgrade.
   • Root Cause: Snapshots capture implementation, not behavior. They drift with CSS, React internals, or environment differences.
   • Mitigation: Replace snapshots with behavior-driven assertions. Use visual regression only for theme/layout validation, not logic verification.

2. Testing Implementation Details

   • Symptom: Tests break when refactoring internal state management or component composition.
   • Root Cause: Queries target data-testid, class names, or DOM depth instead of accessible roles/labels.
   • Mitigation: Enforce @testing-library best practices. Query by role, name, placeholderText, or labelText. Reserve data-testid for non-accessible hooks only.

3. Ignoring Accessibility in Component Tests

   • Symptom: Components pass functional tests but fail screen reader navigation or keyboard traps.
   • Root Cause: a11y treated as a separate QA phase rather than a first-class test dimension.
   • Mitigation: Integrate axe-core into every integration test suite. Validate focus order, ARIA states, and contrast ratios during development, not after.

4. Flaky Visual Regression Due to Environment Drift

   • Symptom: Visual diffs show minor pixel shifts across CI runs or developer machines.
   • Root Cause: Font rendering, anti-aliasing, GPU acceleration, or headless browser inconsistencies.
   • Mitigation: Disable animations, lock system fonts via CSS, use deterministic rendering contexts, and set maxDiffPixels thresholds. Run visual tests in containerized CI with identical OS/font packages.

5. Testing in Isolation Without Real CSS Context

   • Symptom: Components render correctly in Storybook but break in consuming apps due to CSS resets, specificity wars, or theme overrides.
   • Root Cause: Tests run in unstyled or minimally styled environments.
   • Mitigation: Test components within a realistic theme provider. Include global CSS resets in test setups. Validate component behavior under multiple CSS scoping strategies (CSS Modules, Styled Components, Tailwind).

6. Neglecting Performance & Tree-Shaking Validation

   • Symptom: Library bundle size grows unexpectedly; consuming apps experience slower initial load.
   • Root Cause: No size budgets; dead code not eliminated; heavy dependencies bundled unconditionally.
   • Mitigation: Enforce per-component size limits. Use rollup or vite with preserveModules. Validate tree-shaking by importing individual paths and measuring output.

7. CI Environment Drift Causing False Positives/Negatives

   • Symptom: Tests pass locally but fail in CI, or vice versa.
   • Root Cause: Node version differences, OS-level font packages, missing environment variables, or non-deterministic test execution order.
   • Mitigation: Containerize test runners. Pin Node/npm versions. Use --runInBand for deterministic execution. Mock external APIs and time-based logic. Validate CI matrix across target environments.

Production Bundle

Checklist

• Unit tests cover all custom hooks, state logic, and utility functions
• Integration tests validate user interactions, event handlers, and prop contracts
• Visual regression suites run against light/dark/high-contrast themes
• Accessibility tests execute axe-core ruleset on every interactive component
• Performance budgets enforced per component family (<50KB gzipped target)
• Tree-shaking validated via individual path imports in test builds
• CI pipeline runs tests across Node 18, 20, and target bundlers (Vite, Webpack, Rollup)
• Test coverage thresholds set (min 85% statements, 80% branches)
• Flaky test quarantine enabled with automatic retry + reporting
• Release gate requires passing visual, a11y, and size checks before npm publish

Decision Matrix

Component Type	Primary Test Layer	Secondary Layer	When to Add Visual	When to Add E2E
Primitive (Button, Input, Checkbox)	Integration + a11y	Unit (hooks)	Always (theme variants)	Rarely
Composite (Card, FormField, Alert)	Integration + a11y	Visual (layout)	Always	If complex state flow
Layout/Container (Grid, Modal, Drawer)	Visual + a11y	Integration	Always	Always (focus trap, scroll)
Data-Driven (Table, Tree, Select)	Integration + Unit (data transforms)	Performance	Only for theming	If virtualization/pagination
Utility/Hook (useMediaQuery, useFocusTrap)	Unit	Integration (DOM side effects)	Never	Never

Config Template

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

export default defineConfig({
  plugins: [react()],
  test: {
    globals: true,
    environment: 'jsdom',
    setupFiles: ['./test/setup.ts'],
    coverage: {
      provider: 'v8',
      reporter: ['text', 'lcov'],
      thresholds: {
        statements: 85,
        branches: 80,
        functions: 90,
        lines: 85,
      },
    },
    include: ['src/**/*.test.{ts,tsx}'],
    sequence: {
      hooks: 'parallel',
    },
  },
});

// playwright-ct.config.ts
import { defineConfig, devices } from '@playwright/experimental-ct-react';

export default defineConfig({
  testDir: './tests/visual',
  forbidOnly: !!process.env.CI,
  retries: process.env.CI ? 2 : 0,
  workers: process.env.CI ? 1 : undefined,
  use: {
    trace: 'on-first-retry',
    ctViteConfig: {
      plugins: [require('@vitejs/plugin-react')()],
    },
  },
  projects: [
    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
    { name: 'firefox', use: { ...devices['Desktop Firefox'] } },
  ],
});

Quick Start

1. Initialize Tooling: Install vitest, @testing-library/react, @playwright/experimental-ct-react, axe-playwright, and size-limit. Configure vitest.config.ts and playwright-ct.config.ts using the templates above.
2. Create Test Setup: Add test/setup.ts to configure global mocks, resize observers, and theme providers. Ensure jsdom matches target browser behavior.
3. Write First Tests: Start with a primitive component. Add integration tests for interactions, a11y checks via axe-core, and visual snapshots across themes. Run locally with npx vitest and npx playwright test --ct.
4. Enforce Boundaries: Add size-limit config to package.json. Create a GitHub Actions workflow that runs unit/integration tests, visual regression, a11y checks, and size validation on every PR. Gate merges on passing pipelines.
5. Establish Baselines: Commit visual baselines, lock font/CSS rendering contexts, and document testing contracts in component READMEs. Schedule quarterly test audits to remove flaky tests, update thresholds, and validate tree-shaking efficiency.

By adopting this layered, deterministic approach, reusable UI libraries transition from fragile implementation artifacts to reliable, production-grade contracts. Components ship with verified behavior, guaranteed accessibility, predictable performance, and theme resilience—reducing maintenance overhead and accelerating cross-team development velocity.