Frontend Testing

This skill enables Claude to generate high-quality, comprehensive frontend tests following established conventions and best practices.

When to Apply This Skill

Apply this skill when the user:

• Asks to write tests for a component, hook, or utility
• Asks to review existing tests for completeness
• Mentions Vitest, React Testing Library, RTL, or spec files
• Requests test coverage improvement
• Mentions testing, unit tests, or integration tests for frontend code
• Wants to understand testing patterns in the frontend codebase

Do NOT apply when:

• User is asking about E2E tests (Playwright)
• User is only asking conceptual questions without code context

Quick Reference

Tech Stack

Note: keep this list up to date with the project's dependencies.

Key Commands

Always prefer running specific tests over the entire suite for faster feedback:

# Run ALL tests (avoid during development)
npx vitest run

# ✅ PREFERRED: Run specific file
npx vitest run src/components/Button.spec.tsx

# ✅ PREFERRED: Run tests matching a pattern
npx vitest run --grep "Button"
npx vitest run -t "should render"

# ✅ PREFERRED: Run specific describe block
npx vitest run --grep "Button > Rendering"

# ✅ Run tests in a directory
npx vitest run src/components/

# ✅ Run single test by name
npx vitest run -t "should disable button when loading"

Watch Mode (Background Testing)

Use watch mode for efficient iterative development:

# ✅ Watch mode - reruns on file changes
npx vitest

# ✅ Watch specific file
npx vitest src/components/Button.spec.tsx

# ✅ Watch tests matching pattern
npx vitest --grep "Button"

File Naming

• Test files: ComponentName.spec.tsx (same directory as component)

Test Structure Template

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

// ✅ Import real project components (DO NOT mock these)
// import Loading from '@/app/components/base/loading'
// import { ChildComponent } from './child-component'

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

// Shared state for mocks (if needed)
let mockSharedState = false

describe('ComponentName', () => {
  beforeEach(() => {
    vi.clearAllMocks()  // ✅ Reset mocks BEFORE each test
    mockSharedState = false  // ✅ Reset shared state
  })

  // Rendering tests (REQUIRED)
  describe('Rendering', () => {
    it('should render without crashing', () => {
      // Arrange
      const props = { title: 'Test' }

      // Act
      render(<Component {...props} />)

      // Assert
      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 (CRITICAL)

⚠️ Incremental Approach Required

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

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

For each file:
  ┌────────────────────────────────────────────────┐
  │ 1. Write test                                  │
  │ 2. Run: npm run test-unit <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

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

Testing Strategy

Path-Level Testing (Directory Testing)

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

• Test all components, hooks, utilities in the directory (not just index file)
• Use incremental approach: one file at a time, verify each before proceeding
• Goal: 100% coverage of ALL files in the directory

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 (@/service/*), next/navigation, complex context providers
• ❌ DO NOT mock base components (@/app/components/base/*)
• ❌ DO NOT mock sibling/child components in the same 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 in assertions:

// ❌ Avoid: hardcoded text assertions
expect(screen.getByText('Loading...')).toBeInTheDocument()

// ✅ Better: role-based queries
expect(screen.getByRole('status')).toBeInTheDocument()

// ✅ Better: 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 1. Props: Required props, optional props, default values 1. Edge Cases: null, undefined, empty values, boundary conditions

Conditional (When Present)

Coverage Goals (Per File)

For each test file generated, aim for:

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

Note: For multi-file directories, process one file at a time with full coverage each. See references/workflow.md.

Detailed Guides

For more detailed information, refer to:

• references/workflow.md - Incremental testing workflow (MUST READ for multi-file testing)
• references/mocking.md - Mock patterns and best practices
• references/async-testing.md - Async operations and API calls
• references/common-patterns.md - Frequently used testing patterns
• references/checklist.md - Test generation checklist and validation steps

Project Configuration

• vitest.config.ts - Vitest configuration
• vitest.setup.ts - Test environment setup
• Modules are not mocked automatically. Global mocks live in vitest.setup.ts (for example react-i18next, next/image); mock other modules like ky or mime locally in test files.

Async Testing Guide

Core Async Patterns

1. waitFor - Wait for Condition

import { render, screen, waitFor } from '@testing-library/react'

it('should load and display data', async () => {
  render(<DataComponent />)
  
  // Wait for element to appear
  await waitFor(() => {
    expect(screen.getByText('Loaded Data')).toBeInTheDocument()
  })
})

it('should hide loading spinner after load', async () => {
  render(<DataComponent />)
  
  // Wait for element to disappear
  await waitFor(() => {
    expect(screen.queryByText('Loading...')).not.toBeInTheDocument()
  })
})

2. findBy\* - Async Queries

it('should show user name after fetch', async () => {
  render(<UserProfile />)
  
  // findBy returns a promise, auto-waits up to 1000ms
  const userName = await screen.findByText('John Doe')
  expect(userName).toBeInTheDocument()
  
  // findByRole with options
  const button = await screen.findByRole('button', { name: /submit/i })
  expect(button).toBeEnabled()
})

3. userEvent for Async Interactions

import userEvent from '@testing-library/user-event'

it('should submit form', async () => {
  const user = userEvent.setup()
  const onSubmit = vi.fn()
  
  render(<Form onSubmit={onSubmit} />)
  
  // userEvent methods are async
  await user.type(screen.getByLabelText('Email'), 'test@example.com')
  await user.click(screen.getByRole('button', { name: /submit/i }))
  
  await waitFor(() => {
    expect(onSubmit).toHaveBeenCalledWith({ email: 'test@example.com' })
  })
})

Fake Timers

When to Use Fake Timers

• Testing components with setTimeout/setInterval
• Testing debounce/throttle behavior
• Testing animations or delayed transitions
• Testing polling or retry logic

Basic Fake Timer Setup

describe('Debounced Search', () => {
  beforeEach(() => {
    vi.useFakeTimers()
  })

  afterEach(() => {
    vi.useRealTimers()
  })

  it('should debounce search input', async () => {
    const onSearch = vi.fn()
    render(<SearchInput onSearch={onSearch} debounceMs={300} />)
    
    // Type in the input
    fireEvent.change(screen.getByRole('textbox'), { target: { value: 'query' } })
    
    // Search not called immediately
    expect(onSearch).not.toHaveBeenCalled()
    
    // Advance timers
    vi.advanceTimersByTime(300)
    
    // Now search is called
    expect(onSearch).toHaveBeenCalledWith('query')
  })
})

Fake Timers with Async Code

it('should retry on failure', async () => {
  vi.useFakeTimers()
  const fetchData = vi.fn()
    .mockRejectedValueOnce(new Error('Network error'))
    .mockResolvedValueOnce({ data: 'success' })
  
  render(<RetryComponent fetchData={fetchData} retryDelayMs={1000} />)
  
  // First call fails
  await waitFor(() => {
    expect(fetchData).toHaveBeenCalledTimes(1)
  })
  
  // Advance timer for retry
  vi.advanceTimersByTime(1000)
  
  // Second call succeeds
  await waitFor(() => {
    expect(fetchData).toHaveBeenCalledTimes(2)
    expect(screen.getByText('success')).toBeInTheDocument()
  })
  
  vi.useRealTimers()
})

Common Fake Timer Utilities

// Run all pending timers
vi.runAllTimers()

// Run only pending timers (not new ones created during execution)
vi.runOnlyPendingTimers()

// Advance by specific time
vi.advanceTimersByTime(1000)

// Get current fake time
Date.now()

// Clear all timers
vi.clearAllTimers()

API Testing Patterns

Loading → Success → Error States

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

  it('should show loading state', () => {
    mockedApi.fetchData.mockImplementation(() => new Promise(() => {})) // Never resolves
    
    render(<DataFetcher />)
    
    expect(screen.getByTestId('loading-spinner')).toBeInTheDocument()
  })

  it('should show data on success', async () => {
    mockedApi.fetchData.mockResolvedValue({ items: ['Item 1', 'Item 2'] })
    
    render(<DataFetcher />)
    
    // Use findBy* for multiple async elements (better error messages than waitFor with multiple assertions)
    const item1 = await screen.findByText('Item 1')
    const item2 = await screen.findByText('Item 2')
    expect(item1).toBeInTheDocument()
    expect(item2).toBeInTheDocument()
    
    expect(screen.queryByTestId('loading-spinner')).not.toBeInTheDocument()
  })

  it('should show error on failure', async () => {
    mockedApi.fetchData.mockRejectedValue(new Error('Failed to fetch'))
    
    render(<DataFetcher />)
    
    await waitFor(() => {
      expect(screen.getByText(/failed to fetch/i)).toBeInTheDocument()
    })
  })

  it('should retry on error', async () => {
    mockedApi.fetchData.mockRejectedValue(new Error('Network error'))
    
    render(<DataFetcher />)
    
    await waitFor(() => {
      expect(screen.getByRole('button', { name: /retry/i })).toBeInTheDocument()
    })
    
    mockedApi.fetchData.mockResolvedValue({ items: ['Item 1'] })
    fireEvent.click(screen.getByRole('button', { name: /retry/i }))
    
    await waitFor(() => {
      expect(screen.getByText('Item 1')).toBeInTheDocument()
    })
  })
})

Testing Mutations

it('should submit form and show success', async () => {
  const user = userEvent.setup()
  mockedApi.createItem.mockResolvedValue({ id: '1', name: 'New Item' })
  
  render(<CreateItemForm />)
  
  await user.type(screen.getByLabelText('Name'), 'New Item')
  await user.click(screen.getByRole('button', { name: /create/i }))
  
  // Button should be disabled during submission
  expect(screen.getByRole('button', { name: /creating/i })).toBeDisabled()
  
  await waitFor(() => {
    expect(screen.getByText(/created successfully/i)).toBeInTheDocument()
  })
  
  expect(mockedApi.createItem).toHaveBeenCalledWith({ name: 'New Item' })
})

useEffect Testing

Testing Effect Execution

it('should fetch data on mount', async () => {
  const fetchData = vi.fn().mockResolvedValue({ data: 'test' })
  
  render(<ComponentWithEffect fetchData={fetchData} />)
  
  await waitFor(() => {
    expect(fetchData).toHaveBeenCalledTimes(1)
  })
})

Testing Effect Dependencies

it('should refetch when id changes', async () => {
  const fetchData = vi.fn().mockResolvedValue({ data: 'test' })
  
  const { rerender } = render(<ComponentWithEffect id="1" fetchData={fetchData} />)
  
  await waitFor(() => {
    expect(fetchData).toHaveBeenCalledWith('1')
  })
  
  rerender(<ComponentWithEffect id="2" fetchData={fetchData} />)
  
  await waitFor(() => {
    expect(fetchData).toHaveBeenCalledWith('2')
    expect(fetchData).toHaveBeenCalledTimes(2)
  })
})

Testing Effect Cleanup

it('should cleanup subscription on unmount', () => {
  const subscribe = vi.fn()
  const unsubscribe = vi.fn()
  subscribe.mockReturnValue(unsubscribe)
  
  const { unmount } = render(<SubscriptionComponent subscribe={subscribe} />)
  
  expect(subscribe).toHaveBeenCalledTimes(1)
  
  unmount()
  
  expect(unsubscribe).toHaveBeenCalledTimes(1)
})

Common Async Pitfalls

❌ Don't: Forget to await

// Bad - test may pass even if assertion fails
it('should load data', () => {
  render(<Component />)
  waitFor(() => {
    expect(screen.getByText('Data')).toBeInTheDocument()
  })
})

// Good - properly awaited
it('should load data', async () => {
  render(<Component />)
  await waitFor(() => {
    expect(screen.getByText('Data')).toBeInTheDocument()
  })
})

❌ Don't: Use multiple assertions in single waitFor

// Bad - if first assertion fails, won't know about second
await waitFor(() => {
  expect(screen.getByText('Title')).toBeInTheDocument()
  expect(screen.getByText('Description')).toBeInTheDocument()
})

// Good - separate waitFor or use findBy
const title = await screen.findByText('Title')
const description = await screen.findByText('Description')
expect(title).toBeInTheDocument()
expect(description).toBeInTheDocument()

❌ Don't: Mix fake timers with real async

// Bad - fake timers don't work well with real Promises
vi.useFakeTimers()
await waitFor(() => {
  expect(screen.getByText('Data')).toBeInTheDocument()
}) // May timeout!

// Good - use runAllTimers or advanceTimersByTime
vi.useFakeTimers()
render(<Component />)
vi.runAllTimers()
expect(screen.getByText('Data')).toBeInTheDocument()

Test Generation Checklist

Use this checklist when generating or reviewing tests for frontend components.

Pre-Generation

• [ ] Read the component source code completely
• [ ] Identify component type (component, hook, utility, page)
• [ ] Analyze component complexity and features
• [ ] Note complexity score and features detected
• [ ] Check for existing tests in the same directory
• [ ] Identify ALL files in the directory that need testing (not just index)

Testing Strategy

⚠️ Incremental Workflow (CRITICAL for Multi-File)

• [ ] NEVER generate all tests at once - process one file at a time
• [ ] Order files by complexity: utilities → hooks → simple → complex → integration
• [ ] Create a todo list to track progress before starting
• [ ] For EACH file: write → run test → verify pass → then next
• [ ] DO NOT proceed to next file until current one passes

Path-Level Coverage

• [ ] Test ALL files in the assigned directory/path
• [ ] List all components, hooks, utilities that need coverage
• [ ] Decide: single spec file (integration) or multiple spec files (unit)

Complexity Assessment

• [ ] Medium Complexity and higher: Consider refactoring before testing
• [ ] 500+ lines: Consider splitting before testing
• [ ] Low complexity: Use multiple describe blocks, organized structure

Integration vs Mocking

• [ ] Only mock: API calls, complex context providers, third-party libs with side effects
• [ ] Prefer integration testing when using single spec file

Required Test Sections

All Components MUST Have

• [ ] Rendering tests - Component renders without crashing
• [ ] Props tests - Required props, optional props, default values
• [ ] Edge cases - null, undefined, empty values, boundaries

Conditional Sections (Add When Feature Present)

Code Quality Checklist

Structure

• [ ] Uses describe blocks to group related tests
• [ ] Test names follow should <behavior> when <condition> pattern
• [ ] AAA pattern (Arrange-Act-Assert) is clear
• [ ] Comments explain complex test scenarios

Mocks

• [ ] vi.clearAllMocks() in beforeEach (not afterEach)
• [ ] Shared mock state reset in beforeEach
• [ ] Router mocks match actual Next.js API
• [ ] Mocks reflect actual component conditional behavior
• [ ] Only mock: API services, complex context providers, third-party libs

Queries

• [ ] Prefer semantic queries (getByRole, getByLabelText)
• [ ] Use queryBy* for absence assertions
• [ ] Use findBy* for async elements
• [ ] getByTestId only as last resort

Async

• [ ] All async tests use async/await
• [ ] waitFor wraps async assertions
• [ ] Fake timers properly setup/teardown
• [ ] No floating promises

TypeScript

• [ ] No any types without justification
• [ ] Mock data uses actual types from source
• [ ] Factory functions have proper return types

Coverage Goals (Per File)

For the current file being tested:

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

Post-Generation (Per File)

Run these checks after EACH test file, not just at the end:

• [ ] Run npm run test-unit path/to/file.spec.tsx - MUST PASS before next file
• [ ] Fix any failures immediately
• [ ] Mark file as complete in todo list
• [ ] Only then proceed to next file

After All Files Complete

• [ ] Run full directory test: npm run test-unit path/to/directory/
• [ ] Check coverage report: npm run test-unit:coverage path/to/directory/
• [ ] Run npm run lint --fix on all test files
• [ ] Run npm run typecheck

Common Issues to Watch

False Positives

// ❌ Mock doesn't match actual behavior
vi.mock('./Component', () => () => <div>Mocked</div>)

// ✅ Mock matches actual conditional logic
vi.mock('./Component', () => ({ isOpen }: any) =>
  isOpen ? <div>Content</div> : null
)

State Leakage

// ❌ Shared state not reset
let mockState = false
vi.mock('./useHook', () => () => mockState)

// ✅ Reset in beforeEach
beforeEach(() => {
  mockState = false
})

Async Race Conditions

// ❌ Not awaited
it('loads data', () => {
  render(<Component />)
  expect(screen.getByText('Data')).toBeInTheDocument()
})

// ✅ Properly awaited
it('loads data', async () => {
  render(<Component />)
  await waitFor(() => {
    expect(screen.getByText('Data')).toBeInTheDocument()
  })
})

Missing Edge Cases

Always test these scenarios:

• null / undefined inputs
• Empty strings / arrays / objects
• Boundary values (0, -1, MAX_INT)
• Error states
• Loading states
• Disabled states

Quick Commands

# Run specific test
npm run test-unit path/to/file.spec.tsx

# Run with coverage
npm run test-unit:coverage path/to/file.spec.tsx

Common Testing Patterns

Query Priority

Use queries in this order (most to least preferred):

// 1. getByRole - Most recommended (accessibility)
screen.getByRole('button', { name: /submit/i })
screen.getByRole('textbox', { name: /email/i })
screen.getByRole('heading', { level: 1 })

// 2. getByLabelText - Form fields
screen.getByLabelText('Email address')
screen.getByLabelText(/password/i)

// 3. getByPlaceholderText - When no label
screen.getByPlaceholderText('Search...')

// 4. getByText - Non-interactive elements
screen.getByText('Welcome')
screen.getByText(/loading/i)

// 5. getByDisplayValue - Current input value
screen.getByDisplayValue('current value')

// 6. getByAltText - Images
screen.getByAltText('Company logo')

// 7. getByTitle - Tooltip elements
screen.getByTitle('Close')

// 8. getByTestId - Last resort only!
screen.getByTestId('custom-element')

Event Handling Patterns

Click Events

// Basic click
fireEvent.click(screen.getByRole('button'))

// With userEvent (preferred for realistic interaction)
const user = userEvent.setup()
await user.click(screen.getByRole('button'))

// Double click
await user.dblClick(screen.getByRole('button'))

// Right click
await user.pointer({ keys: '[MouseRight]', target: screen.getByRole('button') })

Form Input

const user = userEvent.setup()

// Type in input
await user.type(screen.getByRole('textbox'), 'Hello World')

// Clear and type
await user.clear(screen.getByRole('textbox'))
await user.type(screen.getByRole('textbox'), 'New value')

// Select option
await user.selectOptions(screen.getByRole('combobox'), 'option-value')

// Check checkbox
await user.click(screen.getByRole('checkbox'))

// Upload file
const file = new File(['content'], 'test.pdf', { type: 'application/pdf' })
await user.upload(screen.getByLabelText(/upload/i), file)

Keyboard Events

const user = userEvent.setup()

// Press Enter
await user.keyboard('{Enter}')

// Press Escape
await user.keyboard('{Escape}')

// Keyboard shortcut
await user.keyboard('{Control>}a{/Control}') // Ctrl+A

// Tab navigation
await user.tab()

// Arrow keys
await user.keyboard('{ArrowDown}')
await user.keyboard('{ArrowUp}')

Component State Testing

Testing State Transitions

describe('Counter', () => {
  it('should increment count', async () => {
    const user = userEvent.setup()
    render(<Counter initialCount={0} />)

    // Initial state
    expect(screen.getByText('Count: 0')).toBeInTheDocument()

    // Trigger transition
    await user.click(screen.getByRole('button', { name: /increment/i }))

    // New state
    expect(screen.getByText('Count: 1')).toBeInTheDocument()
  })
})

Testing Controlled Components

describe('ControlledInput', () => {
  it('should call onChange with new value', async () => {
    const user = userEvent.setup()
    const handleChange = vi.fn()

    render(<ControlledInput value="" onChange={handleChange} />)

    await user.type(screen.getByRole('textbox'), 'a')

    expect(handleChange).toHaveBeenCalledWith('a')
  })

  it('should display controlled value', () => {
    render(<ControlledInput value="controlled" onChange={vi.fn()} />)

    expect(screen.getByRole('textbox')).toHaveValue('controlled')
  })
})

Conditional Rendering Testing

describe('ConditionalComponent', () => {
  it('should show loading state', () => {
    render(<DataDisplay isLoading={true} data={null} />)

    expect(screen.getByText(/loading/i)).toBeInTheDocument()
    expect(screen.queryByTestId('data-content')).not.toBeInTheDocument()
  })

  it('should show error state', () => {
    render(<DataDisplay isLoading={false} data={null} error="Failed to load" />)

    expect(screen.getByText(/failed to load/i)).toBeInTheDocument()
  })

  it('should show data when loaded', () => {
    render(<DataDisplay isLoading={false} data={{ name: 'Test' }} />)

    expect(screen.getByText('Test')).toBeInTheDocument()
  })

  it('should show empty state when no data', () => {
    render(<DataDisplay isLoading={false} data={[]} />)

    expect(screen.getByText(/no data/i)).toBeInTheDocument()
  })
})

List Rendering Testing

describe('ItemList', () => {
  const items = [
    { id: '1', name: 'Item 1' },
    { id: '2', name: 'Item 2' },
    { id: '3', name: 'Item 3' },
  ]

  it('should render all items', () => {
    render(<ItemList items={items} />)

    expect(screen.getAllByRole('listitem')).toHaveLength(3)
    items.forEach(item => {
      expect(screen.getByText(item.name)).toBeInTheDocument()
    })
  })

  it('should handle item selection', async () => {
    const user = userEvent.setup()
    const onSelect = vi.fn()

    render(<ItemList items={items} onSelect={onSelect} />)

    await user.click(screen.getByText('Item 2'))

    expect(onSelect).toHaveBeenCalledWith(items[1])
  })

  it('should handle empty list', () => {
    render(<ItemList items={[]} />)

    expect(screen.getByText(/no items/i)).toBeInTheDocument()
  })
})

Modal/Dialog Testing

describe('Modal', () => {
  it('should not render when closed', () => {
    render(<Modal isOpen={false} onClose={vi.fn()} />)

    expect(screen.queryByRole('dialog')).not.toBeInTheDocument()
  })

  it('should render when open', () => {
    render(<Modal isOpen={true} onClose={vi.fn()} />)

    expect(screen.getByRole('dialog')).toBeInTheDocument()
  })

  it('should call onClose when clicking overlay', async () => {
    const user = userEvent.setup()
    const handleClose = vi.fn()

    render(<Modal isOpen={true} onClose={handleClose} />)

    await user.click(screen.getByTestId('modal-overlay'))

    expect(handleClose).toHaveBeenCalled()
  })

  it('should call onClose when pressing Escape', async () => {
    const user = userEvent.setup()
    const handleClose = vi.fn()

    render(<Modal isOpen={true} onClose={handleClose} />)

    await user.keyboard('{Escape}')

    expect(handleClose).toHaveBeenCalled()
  })

  it('should trap focus inside modal', async () => {
    const user = userEvent.setup()

    render(
      <Modal isOpen={true} onClose={vi.fn()}>
        <button>First</button>
        <button>Second</button>
      </Modal>
    )

    // Focus should cycle within modal
    await user.tab()
    expect(screen.getByText('First')).toHaveFocus()

    await user.tab()
    expect(screen.getByText('Second')).toHaveFocus()

    await user.tab()
    expect(screen.getByText('First')).toHaveFocus() // Cycles back
  })
})

Form Testing

describe('LoginForm', () => {
  it('should submit valid form', async () => {
    const user = userEvent.setup()
    const onSubmit = vi.fn()

    render(<LoginForm onSubmit={onSubmit} />)

    await user.type(screen.getByLabelText(/email/i), 'test@example.com')
    await user.type(screen.getByLabelText(/password/i), 'password123')
    await user.click(screen.getByRole('button', { name: /sign in/i }))

    expect(onSubmit).toHaveBeenCalledWith({
      email: 'test@example.com',
      password: 'password123',
    })
  })

  it('should show validation errors', async () => {
    const user = userEvent.setup()

    render(<LoginForm onSubmit={vi.fn()} />)

    // Submit empty form
    await user.click(screen.getByRole('button', { name: /sign in/i }))

    expect(screen.getByText(/email is required/i)).toBeInTheDocument()
    expect(screen.getByText(/password is required/i)).toBeInTheDocument()
  })

  it('should validate email format', async () => {
    const user = userEvent.setup()

    render(<LoginForm onSubmit={vi.fn()} />)

    await user.type(screen.getByLabelText(/email/i), 'invalid-email')
    await user.click(screen.getByRole('button', { name: /sign in/i }))

    expect(screen.getByText(/invalid email/i)).toBeInTheDocument()
  })

  it('should disable submit button while submitting', async () => {
    const user = userEvent.setup()
    const onSubmit = vi.fn(() => new Promise(resolve => setTimeout(resolve, 100)))

    render(<LoginForm onSubmit={onSubmit} />)

    await user.type(screen.getByLabelText(/email/i), 'test@example.com')
    await user.type(screen.getByLabelText(/password/i), 'password123')
    await user.click(screen.getByRole('button', { name: /sign in/i }))

    expect(screen.getByRole('button', { name: /signing in/i })).toBeDisabled()

    await waitFor(() => {
      expect(screen.getByRole('button', { name: /sign in/i })).toBeEnabled()
    })
  })
})

Data-Driven Tests with test.each

describe('StatusBadge', () => {
  test.each([
    ['success', 'bg-green-500'],
    ['warning', 'bg-yellow-500'],
    ['error', 'bg-red-500'],
    ['info', 'bg-blue-500'],
  ])('should apply correct class for %s status', (status, expectedClass) => {
    render(<StatusBadge status={status} />)

    expect(screen.getByTestId('status-badge')).toHaveClass(expectedClass)
  })

  test.each([
    { input: null, expected: 'Unknown' },
    { input: undefined, expected: 'Unknown' },
    { input: '', expected: 'Unknown' },
    { input: 'invalid', expected: 'Unknown' },
  ])('should show "Unknown" for invalid input: $input', ({ input, expected }) => {
    render(<StatusBadge status={input} />)

    expect(screen.getByText(expected)).toBeInTheDocument()
  })
})

Debugging Tips

// Print entire DOM
screen.debug()

// Print specific element
screen.debug(screen.getByRole('button'))

// Log testing playground URL
screen.logTestingPlaygroundURL()

// Pretty print DOM
import { prettyDOM } from '@testing-library/react'
console.log(prettyDOM(screen.getByRole('dialog')))

// Check available roles
import { getRoles } from '@testing-library/react'
console.log(getRoles(container))

Common Mistakes to Avoid

❌ Don't Use Implementation Details

// Bad - testing implementation
expect(component.state.isOpen).toBe(true)
expect(wrapper.find('.internal-class').length).toBe(1)

// Good - testing behavior
expect(screen.getByRole('dialog')).toBeInTheDocument()

❌ Don't Forget Cleanup

// Bad - may leak state between tests
it('test 1', () => {
  render(<Component />)
})

// Good - cleanup is automatic with RTL, but reset mocks
beforeEach(() => {
  vi.clearAllMocks()
})

❌ Don't Use Exact String Matching (Prefer Black-Box Assertions)

// ❌ Bad - hardcoded strings are brittle
expect(screen.getByText('Submit Form')).toBeInTheDocument()
expect(screen.getByText('Loading...')).toBeInTheDocument()

// ✅ Good - role-based queries (most semantic)
expect(screen.getByRole('button', { name: /submit/i })).toBeInTheDocument()
expect(screen.getByRole('status')).toBeInTheDocument()

// ✅ Good - pattern matching (flexible)
expect(screen.getByText(/submit/i)).toBeInTheDocument()
expect(screen.getByText(/loading/i)).toBeInTheDocument()

// ✅ Good - test behavior, not exact UI text
expect(screen.getByRole('button')).toBeDisabled()
expect(screen.getByRole('alert')).toBeInTheDocument()

Why prefer black-box assertions?

• Text content may change (i18n, copy updates)
• Role-based queries test accessibility
• Pattern matching is resilient to minor changes
• Tests focus on behavior, not implementation details

❌ Don't Assert on Absence Without Query

// Bad - throws if not found
expect(screen.getByText('Error')).not.toBeInTheDocument() // Error!

// Good - use queryBy for absence assertions
expect(screen.queryByText('Error')).not.toBeInTheDocument()

Mocking Guide for Frontend Tests

⚠️ Important: What NOT to Mock

What TO Mock

Only mock these categories:

1. API services - Network calls 2. Complex context providers - When setup is too difficult 3. Third-party libraries with side effects - next/navigation, external SDKs 4. i18n - Always mock to return keys

Modules are not mocked automatically. Use vi.mock in test files, or add global mocks in web/vitest.setup.ts.

Essential Mocks

1. Next.js Router

const mockPush = vi.fn()
const mockReplace = vi.fn()

vi.mock('next/navigation', () => ({
  useRouter: () => ({
    push: mockPush,
    replace: mockReplace,
    back: vi.fn(),
    prefetch: vi.fn(),
  }),
  usePathname: () => '/current-path',
  useSearchParams: () => new URLSearchParams('?key=value'),
}))

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

  it('should navigate on click', () => {
    render(<Component />)
    fireEvent.click(screen.getByRole('button'))
    expect(mockPush).toHaveBeenCalledWith('/expected-path')
  })
})

2. Portal Components (with Shared State)

// ⚠️ Important: Use shared state for components that depend on each other
let mockPortalOpenState = false

vi.mock('@/app/components/base/portal-to-follow-elem', () => ({
  PortalToFollowElem: ({ children, open, ...props }: any) => {
    mockPortalOpenState = open || false  // Update shared state
    return <div data-testid="portal" data-open={open}>{children}</div>
  },
  PortalToFollowElemContent: ({ children }: any) => {
    // ✅ Matches actual: returns null when portal is closed
    if (!mockPortalOpenState) return null
    return <div data-testid="portal-content">{children}</div>
  },
  PortalToFollowElemTrigger: ({ children }: any) => (
    <div data-testid="portal-trigger">{children}</div>
  ),
}))

describe('Component', () => {
  beforeEach(() => {
    vi.clearAllMocks()
    mockPortalOpenState = false  // ✅ Reset shared state
  })
})

3. API Service Mocks

import * as api from '@/service/api'

vi.mock('@/service/api')

const mockedApi = vi.mocked(api)

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

    // Setup default mock implementation
    mockedApi.fetchData.mockResolvedValue({ data: [] })
  })

  it('should show data on success', async () => {
    mockedApi.fetchData.mockResolvedValue({ data: [{ id: 1 }] })

    render(<Component />)

    await waitFor(() => {
      expect(screen.getByText('1')).toBeInTheDocument()
    })
  })

  it('should show error on failure', async () => {
    mockedApi.fetchData.mockRejectedValue(new Error('Network error'))

    render(<Component />)

    await waitFor(() => {
      expect(screen.getByText(/error/i)).toBeInTheDocument()
    })
  })
})

4. HTTP Mocking with Nock

import nock from 'nock'

const GITHUB_HOST = 'https://api.github.com'
const GITHUB_PATH = '/repos/owner/repo'

const mockGithubApi = (status: number, body: Record<string, unknown>, delayMs = 0) => {
  return nock(GITHUB_HOST)
    .get(GITHUB_PATH)
    .delay(delayMs)
    .reply(status, body)
}

describe('GithubComponent', () => {
  afterEach(() => {
    nock.cleanAll()
  })

  it('should display repo info', async () => {
    mockGithubApi(200, { name: 'repo', stars: 1000 })

    render(<GithubComponent />)

    await waitFor(() => {
      expect(screen.getByText('repo')).toBeInTheDocument()
    })
  })

  it('should handle API error', async () => {
    mockGithubApi(500, { message: 'Server error' })

    render(<GithubComponent />)

    await waitFor(() => {
      expect(screen.getByText(/error/i)).toBeInTheDocument()
    })
  })
})

5. Context Providers

import { ProviderContext } from '@/context/provider-context'
import { createMockProviderContextValue, createMockPlan } from '@/__mocks__/provider-context'

describe('Component with Context', () => {
  it('should render for free plan', () => {
    const mockContext = createMockPlan('sandbox')

    render(
      <ProviderContext.Provider value={mockContext}>
        <Component />
      </ProviderContext.Provider>
    )

    expect(screen.getByText('Upgrade')).toBeInTheDocument()
  })

  it('should render for pro plan', () => {
    const mockContext = createMockPlan('professional')

    render(
      <ProviderContext.Provider value={mockContext}>
        <Component />
      </ProviderContext.Provider>
    )

    expect(screen.queryByText('Upgrade')).not.toBeInTheDocument()
  })
})

6. React Query

import { QueryClient, QueryClientProvider } from '@tanstack/react-query'

const createTestQueryClient = () => new QueryClient({
  defaultOptions: {
    queries: { retry: false },
    mutations: { retry: false },
  },
})

const renderWithQueryClient = (ui: React.ReactElement) => {
  const queryClient = createTestQueryClient()
  return render(
    <QueryClientProvider client={queryClient}>
      {ui}
    </QueryClientProvider>
  )
}

Mock Best Practices

✅ DO

1. Use real base components - Import from @/app/components/base/ directly 1. Use real project components - Prefer importing over mocking 1. Reset mocks in `beforeEach`, not afterEach 1. Match actual component behavior in mocks (when mocking is necessary) 1. Use factory functions for complex mock data 1. Import actual types for type safety 1. Reset shared mock state in beforeEach

❌ DON'T

1. Don't mock base components (Loading, Button, Tooltip, etc.) 1. Don't mock components you can import directly 1. Don't create overly simplified mocks that miss conditional logic 1. Don't forget to clean up nock after each test 1. Don't use any types in mocks without necessity

Mock Decision Tree

Need to use a component in test?
│
├─ Is it from @/app/components/base/*?
│  └─ YES → Import real component, DO NOT mock
│
├─ Is it a project component?
│  └─ YES → Prefer importing real component
│           Only mock if setup is extremely complex
│
├─ Is it an API service (@/service/*)?
│  └─ YES → Mock it
│
├─ Is it a third-party lib with side effects?
│  └─ YES → Mock it (next/navigation, external SDKs)
│
└─ Is it i18n?
   └─ YES → Uses shared mock (auto-loaded). Override only for custom translations

Factory Function Pattern

// __mocks__/data-factories.ts
import type { User, Project } from '@/types'

export const createMockUser = (overrides: Partial<User> = {}): User => ({
  id: 'user-1',
  name: 'Test User',
  email: 'test@example.com',
  role: 'member',
  createdAt: new Date().toISOString(),
  ...overrides,
})

export const createMockProject = (overrides: Partial<Project> = {}): Project => ({
  id: 'project-1',
  name: 'Test Project',
  description: 'A test project',
  owner: createMockUser(),
  members: [],
  createdAt: new Date().toISOString(),
  ...overrides,
})

// Usage in tests
it('should display project owner', () => {
  const project = createMockProject({
    owner: createMockUser({ name: 'John Doe' }),
  })

  render(<ProjectCard project={project} />)
  expect(screen.getByText('John Doe')).toBeInTheDocument()
})

Testing Workflow Guide

This guide defines the workflow for generating tests, especially for complex components or directories with multiple files.

Scope Clarification

This guide addresses multi-file workflow (how to process multiple test files).

⚠️ Critical Rule: Incremental Approach for Multi-File Testing

When testing a directory with multiple files, NEVER generate all test files at once. Use an incremental, verify-as-you-go approach.

Why Incremental?

Single File Workflow

When testing a single component, hook, or utility:

1. Read source code completely
2. Analyze complexity first to identify required test scenarios
3. Check complexity score and features detected
4. Write the test file
5. Run test: `pnpm test <file>.spec.tsx`
6. Fix any failures
7. Verify coverage meets goals (100% function, >95% branch)

Directory/Multi-File Workflow (MUST FOLLOW)

When testing a directory or multiple files, follow this strict workflow:

Step 1: Analyze and Plan

1. List all files that need tests in the directory 1. Categorize by complexity:

• 🟢 Simple: Utility functions, simple hooks, presentational components
• 🟡 Medium: Components with state, effects, or event handlers
• 🔴 Complex: Components with API calls, routing, or many dependencies

1. Order by dependency: Test dependencies before dependents 1. Create a todo list to track progress

Step 2: Determine Processing Order

Process files in this recommended order:

1. Utility functions (simplest, no React)
2. Custom hooks (isolated logic)
3. Simple presentational components (few/no props)
4. Medium complexity components (state, effects)
5. Complex components (API, routing, many deps)
6. Container/index components (integration tests - last)

Rationale:

• Simpler files help establish mock patterns
• Hooks used by components should be tested first
• Integration tests (index files) depend on child components working

Step 3: Process Each File Incrementally

For EACH file in the ordered list:

┌─────────────────────────────────────────────┐
│  1. Write test file                         │
│  2. Run: npm run test-unit <file>.spec.tsx          │
│  3. If FAIL → Fix immediately, re-run       │
│  4. If PASS → Mark complete in todo list    │
│  5. ONLY THEN proceed to next file          │
└─────────────────────────────────────────────┘

DO NOT proceed to the next file until the current one passes.

Step 4: Final Verification

After all individual tests pass:

# Run all tests in the directory together
npm run test-unit path/to/directory/

# Check coverage
npm run test-unit:coverage path/to/directory/

🔴 Very Complex Components

Consider refactoring BEFORE testing:

• Break component into smaller, testable pieces
• Extract complex logic into custom hooks
• Separate container and presentational layers

If testing as-is:

• Use integration tests for complex workflows
• Use test.each() for data-driven testing
• Multiple describe blocks for organization
• Consider testing major sections separately

🟡 Medium Complexity

• Group related tests in describe blocks
• Test integration scenarios between internal parts
• Focus on state transitions and side effects
• Use helper functions to reduce test complexity

🟢 Simple Components

• Standard test structure
• Focus on props, rendering, and edge cases
• Usually straightforward to test

📏 Large Files (500+ lines)

Regardless of complexity score:

• Strongly consider refactoring before testing
• If testing as-is, test major sections separately
• Create helper functions for test setup
• May need multiple test files

Todo List Format

When testing multiple files, use a todo list like this:

Testing: path/to/directory/

Ordered by complexity (simple → complex):

☐ utils/helper.ts           [utility, simple]
☐ hooks/use-custom-hook.ts  [hook, simple]
☐ empty-state.tsx           [component, simple]
☐ item-card.tsx             [component, medium]
☐ list.tsx                  [component, complex]
☐ index.tsx                 [integration]

Progress: 0/6 complete

Update status as you complete each:

• ☐ → ⏳ (in progress)
• ⏳ → ✅ (complete and verified)
• ⏳ → ❌ (blocked, needs attention)

When to Stop and Verify

Always run tests after:

• Completing a test file
• Making changes to fix a failure
• Modifying shared mocks
• Updating test utilities or helpers

Signs you should pause:

• More than 2 consecutive test failures
• Mock-related errors appearing
• Unclear why a test is failing
• Test passing but coverage unexpectedly low

Common Pitfalls to Avoid

❌ Don't: Generate Everything First

# BAD: Writing all files then testing
Write component-a.spec.tsx
Write component-b.spec.tsx
Write component-c.spec.tsx
Write component-d.spec.tsx
Run pnpm test  ← Multiple failures, hard to debug

✅ Do: Verify Each Step

# GOOD: Incremental with verification
Write component-a.spec.tsx
Run pnpm test component-a.spec.tsx ✅
Write component-b.spec.tsx
Run pnpm test component-b.spec.tsx ✅
...continue...

❌ Don't: Skip Verification for "Simple" Components

Even simple components can have:

• Import errors
• Missing mock setup
• Incorrect assumptions about props

Always verify, regardless of perceived simplicity.

❌ Don't: Continue When Tests Fail

Failing tests compound:

• A mock issue in file A affects files B, C, D
• Fixing A later requires revisiting all dependent tests
• Time wasted on debugging cascading failures

Fix failures immediately before proceeding.

Integration with Claude's Todo Feature

When using Claude for multi-file testing:

1. Ask Claude to create a todo list before starting 1. Request one file at a time or ensure Claude processes incrementally 1. Verify each test passes before asking for the next 1. Mark todos complete as you progress

Example prompt:

Test all components in `path/to/directory/`.
First, analyze the directory and create a todo list ordered by complexity.
Then, process ONE file at a time, waiting for my confirmation that tests pass
before proceeding to the next.

Summary Checklist

Before starting multi-file testing:

• [ ] Listed all files needing tests
• [ ] Ordered by complexity (simple → complex)
• [ ] Created todo list for tracking
• [ ] Understand dependencies between files

During testing:

• [ ] Processing ONE file at a time
• [ ] Running tests after EACH file
• [ ] Fixing failures BEFORE proceeding
• [ ] Updating todo list progress

After completion:

• [ ] All individual tests pass
• [ ] Full directory test run passes
• [ ] Coverage goals met
• [ ] Todo list shows all complete