Frontend Testing

Key Commands

# Run all tests
npm test            # or: pnpm test / yarn test

# Watch mode
npm run test:watch

# Run specific file
npx vitest path/to/file.spec.tsx

# Generate coverage report
npx vitest --coverage

File Naming

• Test files: ComponentName.spec.tsx (same directory as component)
• Integration tests: __tests__/ directory

Test Structure Template

import { render, screen, fireEvent, waitFor } from '@testing-library/react'
import Component from './index'

// Mock external dependencies only
vi.mock('@/service/api')
vi.mock('next/navigation', () => ({
  useRouter: () => ({ push: vi.fn() }),
  usePathname: () => '/test',
}))

describe('ComponentName', () => {
  beforeEach(() => {
    vi.clearAllMocks()
  })

  // Rendering tests (REQUIRED)
  describe('Rendering', () => {
    it('should render without crashing', () => {
      render(<Component title="Test" />)
      expect(screen.getByText('Test')).toBeInTheDocument()
    })
  })

  // Props tests (REQUIRED)
  describe('Props', () => {
    it('should apply custom className', () => {
      render(<Component className="custom" />)
      expect(screen.getByRole('button')).toHaveClass('custom')
    })
  })

  // User Interactions
  describe('User Interactions', () => {
    it('should handle click events', () => {
      const handleClick = vi.fn()
      render(<Component onClick={handleClick} />)
      fireEvent.click(screen.getByRole('button'))
      expect(handleClick).toHaveBeenCalledTimes(1)
    })
  })

  // Edge Cases (REQUIRED)
  describe('Edge Cases', () => {
    it('should handle null data', () => {
      render(<Component data={null} />)
      expect(screen.getByText(/no data/i)).toBeInTheDocument()
    })

    it('should handle empty array', () => {
      render(<Component items={[]} />)
      expect(screen.getByText(/empty/i)).toBeInTheDocument()
    })
  })
})

Testing Workflow

Incremental Approach (Required for Multi-File)

NEVER generate all test files at once. For complex components or multi-file directories:

1. Analyze & Plan: List all files, order by complexity (simple to complex)
2. Process ONE at a time: Write test, run test, fix if needed, then next
3. Verify before proceeding: Do NOT continue to next file until current passes

For each file:
  1. Write test
  2. Run: npx vitest <file>.spec.tsx
  3. PASS? -> Mark complete, next file
     FAIL? -> Fix first, then continue

Complexity-Based Order

Process in this order for multi-file testing:

1. Utility functions (simplest)
2. Custom hooks
3. Simple components (presentational)
4. Medium components (state, effects)
5. Complex components (API, routing)
6. Integration tests (index files -- last)

When to Refactor First

• Complexity > 50: Break into smaller pieces before testing
• 500+ lines: Consider splitting before testing
• Many dependencies: Extract logic into hooks first

Testing Strategy

Integration Testing First

Prefer integration testing when writing tests for a directory:

• Import real project components directly (including base components and siblings)
• Only mock: API services, next/navigation, complex context providers
• DO NOT mock base UI components (Button, Input, Loading, etc.)
• DO NOT mock sibling/child components in the same directory

Path-Level Testing

When assigned to test a directory/path, test ALL content within that path:

• Test all components, hooks, utilities in the directory
• Use incremental approach: one file at a time, verify each before proceeding
• Goal: full coverage of all files in the directory

Core Principles

1. AAA Pattern (Arrange-Act-Assert)

Every test should clearly separate:

• Arrange: Setup test data and render component
• Act: Perform user actions
• Assert: Verify expected outcomes

2. Black-Box Testing

• Test observable behavior, not implementation details
• Use semantic queries (getByRole, getByLabelText)
• Avoid testing internal state directly
• Prefer pattern matching over hardcoded strings:

// Prefer role-based queries
expect(screen.getByRole('status')).toBeInTheDocument()

// Prefer pattern matching
expect(screen.getByText(/loading/i)).toBeInTheDocument()

3. Single Behavior Per Test

Each test verifies ONE user-observable behavior:

// Good: One behavior
it('should disable button when loading', () => {
  render(<Button loading />)
  expect(screen.getByRole('button')).toBeDisabled()
})

// Bad: Multiple behaviors
it('should handle loading state', () => {
  render(<Button loading />)
  expect(screen.getByRole('button')).toBeDisabled()
  expect(screen.getByText('Loading...')).toBeInTheDocument()
  expect(screen.getByRole('button')).toHaveClass('loading')
})

4. Semantic Naming

Use should <behavior> when <condition>:

it('should show error message when validation fails')
it('should call onSubmit when form is valid')
it('should disable input when isReadOnly is true')

Required Test Scenarios

Always Required (All Components)

1. Rendering: Component renders without crashing
2. Props: Required props, optional props, default values
3. Edge Cases: null, undefined, empty values, boundary conditions

Conditional (When Present)

Coverage Goals (Per File)

• 100% function coverage
• 100% statement coverage
• >95% branch coverage
• >95% line coverage

References

• references/async-testing.md - Async operations, fake timers, and API testing patterns
• references/checklist.md - Test generation checklist and validation steps
• references/common-patterns.md - Query priority, event handling, forms, modals, lists
• references/mocking.md - Mock patterns, Zustand stores, factory functions
• references/workflow.md - Incremental testing workflow for multi-file directories
• assets/component-test.template.tsx - Component test template
• assets/hook-test.template.ts - Hook test template
• assets/utility-test.template.ts - Utility function test template