testing

name

testing

description

Guides test writing for components, hooks, API integrations, and E2E flows. Activates when creating or editing test files, spec files, or when implementing features that need test coverage. Use when writing unit tests, integration tests, E2E tests, deciding what to test, choosing testing strategies, identifying edge cases, setting up mocks, or evaluating test quality. Triggers on questions like "how do I test this", "what tests do I need", "how do I mock this API", "what edge cases am I missing", "should this be a unit or integration test", "how do I write E2E tests for this flow".

Testing Skill

Ensure consistent, meaningful test coverage that catches real bugs without testing implementation details.

---

Core Principle

Test behavior, not implementation. Cover edge cases systematically. Never skip testing.

Tests exist to catch regressions and document expected behavior. If a test would break from a refactor that doesn't change behavior, it's testing the wrong thing.

---

Testing Pyramid

Layer	Coverage Target	Tests Per Feature	Purpose
Unit	60-70%	5-15 tests	Individual functions, hooks, components in isolation
Integration	15-25%	3-8 tests	Component interactions, form flows, API integration
E2E	5-15%	1-3 tests	Critical user journeys, happy paths

---

Decision Tree: What Type of Test?

What are you testing?
│
├─ Pure function (utility, transformer, validator)?
│  └─ UNIT TEST — test inputs → outputs, boundaries, errors
│
├─ Custom hook?
│  └─ UNIT TEST — use renderHook, test state transitions and effects
│
├─ Single component rendering?
│  └─ UNIT TEST — render with props, check output, simulate interactions
│
├─ Multiple components working together?
│  └─ INTEGRATION TEST — render parent, verify child behavior
│
├─ Form with validation and submission?
│  └─ INTEGRATION TEST — fill fields, trigger validation, mock API, verify states
│
├─ Component with API calls?
│  └─ INTEGRATION TEST — mock API, test loading/success/error states
│
├─ Critical user flow (login, checkout, CRUD)?
│  └─ E2E TEST — real browser, test the full journey
│
└─ Visual appearance / layout?
   └─ VISUAL TEST — screenshot comparison (if Playwright configured)

---

Edge Cases Checklist

For every component or feature, systematically check:

Data States

• Empty state — no items, null values, empty strings
• Single item — boundary between empty and populated
• Many items — performance, scrolling, pagination
• Invalid data — malformed responses, unexpected types
• Stale data — cached data that's outdated

User Interactions

• Double-click / rapid interactions — debounce, disable during loading
• Keyboard navigation — Tab, Enter, Escape, Arrow keys
• Form abandonment — unsaved changes warning
• Back button — state preservation or reset
• Offline / slow network — timeout handling, retry

Error States

• Network failure — API down, timeout, 5xx errors
• Validation errors — per-field and form-level
• Permission denied — 401, 403 responses
• Rate limiting — 429 responses
• Concurrent modifications — optimistic update conflicts

Boundary Values

• Zero, negative numbers, max integers
• Empty string, whitespace-only string, max-length string
• Unicode characters, RTL text, emoji
• Date boundaries — timezone, DST, leap year
• File size limits — empty file, max size, unsupported format

Accessibility

• Screen reader announcements — dynamic content changes
• Focus management — modal open/close, route changes
• Error announcement — validation errors reach assistive tech
• Loading state communication — aria-busy, live regions

---

Testing Patterns

Unit Testing (Vitest + Testing Library)

Hook testing:

// ✅ Good: Test behavior and state transitions
import { renderHook, act } from "@testing-library/react";
import { useCounter } from "./useCounter";

describe("useCounter", () => {
  it("increments count", () => {
    const { result } = renderHook(() => useCounter(0));
    act(() => result.current.increment());
    expect(result.current.count).toBe(1);
  });

  it("respects max limit", () => {
    const { result } = renderHook(() => useCounter(0, { max: 5 }));
    act(() => {
      for (let i = 0; i < 10; i++) result.current.increment();
    });
    expect(result.current.count).toBe(5);
  });
});

Component testing:

// ✅ Good: Test what users see and do
import { render, screen } from '@testing-library/react';
import userEvent from '@testing-library/user-event';

describe('SearchInput', () => {
  it('calls onSearch after debounce', async () => {
    const onSearch = vi.fn();
    render(<SearchInput onSearch={onSearch} debounceMs={100} />);

    await userEvent.type(screen.getByRole('searchbox'), 'query');
    await vi.advanceTimersByTimeAsync(100);

    expect(onSearch).toHaveBeenCalledWith('query');
  });

  it('shows clear button only when has value', async () => {
    render(<SearchInput onSearch={vi.fn()} />);
    expect(screen.queryByRole('button', { name: /clear/i })).not.toBeInTheDocument();

    await userEvent.type(screen.getByRole('searchbox'), 'x');
    expect(screen.getByRole('button', { name: /clear/i })).toBeInTheDocument();
  });
});

Integration Testing

API integration:

// ✅ Good: Test the full data flow with mocked API
import { render, screen, waitFor } from '@testing-library/react';
import { server } from '@/test/mocks/server';
import { http, HttpResponse } from 'msw';

describe('UserProfile', () => {
  it('shows loading then data', async () => {
    render(<UserProfile userId="123" />);
    expect(screen.getByRole('status')).toHaveTextContent(/loading/i);
    await waitFor(() => {
      expect(screen.getByText('John Doe')).toBeInTheDocument();
    });
  });

  it('shows error state on API failure', async () => {
    server.use(http.get('/api/users/:id', () => HttpResponse.error()));
    render(<UserProfile userId="123" />);
    await waitFor(() => {
      expect(screen.getByRole('alert')).toHaveTextContent(/failed/i);
    });
  });
});

E2E Testing (Playwright)

// ✅ Good: Test critical user journey
import { test, expect } from "@playwright/test";

test.describe("Checkout Flow", () => {
  test("completes purchase with valid card", async ({ page }) => {
    await page.goto("/products");
    await page.getByRole("button", { name: "Add to cart" }).first().click();
    await page.getByRole("link", { name: "Cart" }).click();
    await page.getByRole("button", { name: "Checkout" }).click();

    // Fill payment
    await page.getByLabel("Card number").fill("4242424242424242");
    await page.getByLabel("Expiry").fill("12/30");
    await page.getByLabel("CVC").fill("123");
    await page.getByRole("button", { name: "Pay" }).click();

    await expect(page.getByText("Order confirmed")).toBeVisible();
  });

  test("shows validation errors for invalid card", async ({ page }) => {
    // ... navigate to checkout
    await page.getByRole("button", { name: "Pay" }).click();
    await expect(page.getByText("Card number is required")).toBeVisible();
  });
});

---

What NOT to Test

• Implementation details (internal state shape, private methods)
• Third-party library internals (trust that React renders, trust that Zod validates)
• CSS styling (unless visual regression testing is configured)
• Exact error message wording (test for presence, not exact string — unless UX-critical)
• Console.log output
• TypeScript types at runtime (that's the compiler's job)

---

Mocking Boundaries

Mock at these boundaries:          Don't mock:
├─ Network (MSW for API calls)     ├─ Internal functions
├─ Browser APIs (localStorage)     ├─ Component children
├─ Time (vi.useFakeTimers)         ├─ Utility functions
├─ External services               ├─ State management
└─ File system                     └─ Your own hooks (test them directly)

Rule: Mock at the system boundary, test everything inside.

---

Test File Conventions

Source file	Test file
UserCard.tsx	UserCard.test.tsx
useAuth.ts	useAuth.test.ts
formatDate.ts	formatDate.test.ts
E2E flows	e2e/checkout.spec.ts

• Colocate unit tests with source files
• Place E2E tests in e2e/ or tests/e2e/ directory
• Use describe blocks matching the feature/component name
• Test names describe behavior: "shows error when API fails" not "test error"

---

Reference Files

File	Contents	Read when...
references/unit-testing.md	Vitest setup, hook testing patterns, component testing patterns	Writing unit tests for hooks or components
references/e2e-testing.md	Playwright setup, page objects, visual testing, CI integration	Writing E2E tests or setting up Playwright
references/edge-cases.md	Systematic edge case identification by domain (forms, lists, auth, payments)	Need comprehensive edge case coverage