Frontend Testing

Dify Frontend Testing Skill

This skill enables Codex to generate high-quality, comprehensive frontend tests for the Dify project following established conventions and best practices.

⚠️ Authoritative Source: This skill is derived from web/docs/test.md. Use Vitest mock/timer APIs (vi.*).

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
• Uses pnpm analyze-component output as context
• Mentions testing, unit tests, or integration tests for frontend code
• Wants to understand testing patterns in the Dify codebase

Do NOT apply when:

• User is asking about backend/API tests (Python/pytest)
• User is asking about E2E tests (Cucumber + Playwright under e2e/)
• User is only asking conceptual questions without code context

Quick Reference

Key Commands

Run these commands from web/. From the repository root, prefix them with pnpm -C web.

# Run all tests
pnpm test

# Watch mode
pnpm test --watch

# Run specific file
pnpm test path/to/file.spec.tsx

# Generate coverage report
pnpm test --coverage

# Analyze component complexity
pnpm analyze-component <path>

# Review existing test
pnpm analyze-component <path> --review

File Naming

• Test files: ComponentName.spec.tsx inside a same-level __tests__/ directory
• Placement rule: Component, hook, and utility tests must live in a sibling __tests__/ folder at the same level as the source under test. For example, foo/index.tsx maps to foo/__tests__/index.spec.tsx, and foo/bar.ts maps to foo/__tests__/bar.spec.ts.
• Integration tests: web/__tests__/ directory

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',
}))

// ✅ Zustand stores: Use real stores (auto-mocked globally)
// Set test state with: useAppStore.setState({ ... })

// 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: pnpm test <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) 1. 🟢 Custom hooks 1. 🟡 Simple components (presentational) 1. 🟡 Medium components (state, effects) 1. 🔴 Complex components (API, routing) 1. 🔴 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

📖 See references/workflow.md for complete workflow details and todo list format.

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/*) or dify-ui primitives (@langgenius/dify-ui/*)
• ❌ DO NOT mock sibling/child components in the same directory

See Test Structure Template for correct import/mock patterns.

nuqs Query State Testing (Required for URL State Hooks)

When a component or hook uses useQueryState / useQueryStates:

• ✅ Use NuqsTestingAdapter (prefer shared helpers in web/test/nuqs-testing.tsx)
• ✅ Assert URL synchronization via onUrlUpdate (searchParams, options.history)
• ✅ For custom parsers (createParser), keep parse and serialize bijective and add round-trip edge cases (%2F, %25, spaces, legacy encoded values)
• ✅ Verify default-clearing behavior (default values should be removed from URL when applicable)
• ⚠️ Only mock nuqs directly when URL behavior is explicitly out of scope for the test

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 with accessible name, getByLabelText, getByPlaceholderText, getByText, and scoped within(...))
• Treat getByTestId as a last resort. If a control cannot be found by role/name, label, landmark, or dialog scope, fix the component accessibility first instead of adding or relying on data-testid.
• Remove production data-testid attributes when semantic selectors can cover the behavior. Keep them only for non-visual mocked boundaries, editor/browser shims such as Monaco, canvas/chart output, or third-party widgets with no accessible DOM in the test environment.
• Do not assert decorative icons by test id. Assert the named control that contains them, or mark decorative icons aria-hidden.
• 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, Zustand store testing, and best practices
• references/async-testing.md - Async operations and API calls
• references/domain-components.md - Workflow, Dataset, Configuration testing
• references/common-patterns.md - Frequently used testing patterns
• references/checklist.md - Test generation checklist and validation steps

Authoritative References

Primary Specification (MUST follow)

• `web/docs/test.md` - The canonical testing specification. This skill is derived from this document.

Reference Examples in Codebase

• web/utils/classnames.spec.ts - Utility function tests
• web/app/components/base/radio/__tests__/index.spec.tsx - Component tests
• web/__mocks__/provider-context.ts - Mock factory example

Project Configuration

• web/vite.config.ts - Vite/Vitest configuration
• web/vitest.setup.ts - Test environment setup
• web/scripts/analyze-component.js - Component analysis tool
• Modules are not mocked automatically. Global mocks live in web/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 Dify frontend components.

Pre-Generation

• [ ] Read the component source code completely
• [ ] Identify component type (component, hook, utility, page)
• [ ] Run pnpm analyze-component <path> if available
• [ ] 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

• [ ] Run pnpm analyze-component <path> for complexity score
• [ ] Complexity > 50: Consider refactoring before testing
• [ ] 500+ lines: Consider splitting before testing
• [ ] 30-50 complexity: Use multiple describe blocks, organized structure

Integration vs Mocking

• [ ] DO NOT mock base components or dify-ui primitives (base Loading, Input, Badge; dify-ui Button, Tooltip, Dialog, etc.)
• [ ] Import real project components instead of 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

• [ ] DO NOT mock base components or dify-ui primitives (@/app/components/base/* or @langgenius/dify-ui/*)
• [ ] vi.clearAllMocks() in beforeEach (not afterEach)
• [ ] Shared mock state reset in beforeEach
• [ ] i18n uses global mock (auto-loaded in web/vitest.setup.ts); only override locally for custom translations
• [ ] Router mocks match actual Next.js API
• [ ] Mocks reflect actual component conditional behavior
• [ ] Only mock: API services, complex context providers, third-party libs
• [ ] For nuqs URL-state tests, wrap with NuqsTestingAdapter (prefer web/test/nuqs-testing.tsx)
• [ ] For nuqs URL-state tests, assert onUrlUpdate payload (searchParams, options.history)
• [ ] If custom nuqs parser exists, add round-trip tests for encoded edge cases (%2F, %25, spaces, legacy encoded values)

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 pnpm test 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: pnpm test path/to/directory/
• [ ] Check coverage report: pnpm test:coverage
• [ ] Run pnpm lint:fix on all test files
• [ ] Run pnpm type-check

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
pnpm test path/to/file.spec.tsx

# Run with coverage
pnpm test:coverage path/to/file.spec.tsx

# Watch mode
pnpm test:watch path/to/file.spec.tsx

# Update snapshots (use sparingly)
pnpm test -u path/to/file.spec.tsx

# Analyze component
pnpm analyze-component path/to/component.tsx

# Review existing test
pnpm analyze-component path/to/component.tsx --review

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 to Dify')
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()

Domain-Specific Component Testing

This guide covers testing patterns for Dify's domain-specific components.

Workflow Components (workflow/)

Workflow components handle node configuration, data flow, and graph operations.

Key Test Areas

1. Node Configuration 1. Data Validation 1. Variable Passing 1. Edge Connections 1. Error Handling

Example: Node Configuration Panel

import { render, screen, fireEvent, waitFor } from '@testing-library/react'
import userEvent from '@testing-library/user-event'
import NodeConfigPanel from './node-config-panel'
import { createMockNode, createMockWorkflowContext } from '@/__mocks__/workflow'

// Mock workflow context
vi.mock('@/app/components/workflow/hooks', () => ({
  useWorkflowStore: () => mockWorkflowStore,
  useNodesInteractions: () => mockNodesInteractions,
}))

let mockWorkflowStore = {
  nodes: [],
  edges: [],
  updateNode: vi.fn(),
}

let mockNodesInteractions = {
  handleNodeSelect: vi.fn(),
  handleNodeDelete: vi.fn(),
}

describe('NodeConfigPanel', () => {
  beforeEach(() => {
    vi.clearAllMocks()
    mockWorkflowStore = {
      nodes: [],
      edges: [],
      updateNode: vi.fn(),
    }
  })

  describe('Node Configuration', () => {
    it('should render node type selector', () => {
      const node = createMockNode({ type: 'llm' })
      render(<NodeConfigPanel node={node} />)
      
      expect(screen.getByLabelText(/model/i)).toBeInTheDocument()
    })

    it('should update node config on change', async () => {
      const user = userEvent.setup()
      const node = createMockNode({ type: 'llm' })
      
      render(<NodeConfigPanel node={node} />)
      
      await user.selectOptions(screen.getByLabelText(/model/i), 'gpt-4')
      
      expect(mockWorkflowStore.updateNode).toHaveBeenCalledWith(
        node.id,
        expect.objectContaining({ model: 'gpt-4' })
      )
    })
  })

  describe('Data Validation', () => {
    it('should show error for invalid input', async () => {
      const user = userEvent.setup()
      const node = createMockNode({ type: 'code' })
      
      render(<NodeConfigPanel node={node} />)
      
      // Enter invalid code
      const codeInput = screen.getByLabelText(/code/i)
      await user.clear(codeInput)
      await user.type(codeInput, 'invalid syntax {{{')
      
      await waitFor(() => {
        expect(screen.getByText(/syntax error/i)).toBeInTheDocument()
      })
    })

    it('should validate required fields', async () => {
      const node = createMockNode({ type: 'http', data: { url: '' } })
      
      render(<NodeConfigPanel node={node} />)
      
      fireEvent.click(screen.getByRole('button', { name: /save/i }))
      
      await waitFor(() => {
        expect(screen.getByText(/url is required/i)).toBeInTheDocument()
      })
    })
  })

  describe('Variable Passing', () => {
    it('should display available variables from upstream nodes', () => {
      const upstreamNode = createMockNode({
        id: 'node-1',
        type: 'start',
        data: { outputs: [{ name: 'user_input', type: 'string' }] },
      })
      const currentNode = createMockNode({
        id: 'node-2',
        type: 'llm',
      })
      
      mockWorkflowStore.nodes = [upstreamNode, currentNode]
      mockWorkflowStore.edges = [{ source: 'node-1', target: 'node-2' }]
      
      render(<NodeConfigPanel node={currentNode} />)
      
      // Variable selector should show upstream variables
      fireEvent.click(screen.getByRole('button', { name: /add variable/i }))
      
      expect(screen.getByText('user_input')).toBeInTheDocument()
    })

    it('should insert variable into prompt template', async () => {
      const user = userEvent.setup()
      const node = createMockNode({ type: 'llm' })
      
      render(<NodeConfigPanel node={node} />)
      
      // Click variable button
      await user.click(screen.getByRole('button', { name: /insert variable/i }))
      await user.click(screen.getByText('user_input'))
      
      const promptInput = screen.getByLabelText(/prompt/i)
      expect(promptInput).toHaveValue(expect.stringContaining('{{user_input}}'))
    })
  })
})

Dataset Components (dataset/)

Dataset components handle file uploads, data display, and search/filter operations.

Key Test Areas

1. File Upload 1. File Type Validation 1. Pagination 1. Search & Filtering 1. Data Format Handling

Example: Document Uploader

import { render, screen, fireEvent, waitFor } from '@testing-library/react'
import userEvent from '@testing-library/user-event'
import DocumentUploader from './document-uploader'

vi.mock('@/service/datasets', () => ({
  uploadDocument: vi.fn(),
  parseDocument: vi.fn(),
}))

import * as datasetService from '@/service/datasets'
const mockedService = vi.mocked(datasetService)

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

  describe('File Upload', () => {
    it('should accept valid file types', async () => {
      const user = userEvent.setup()
      const onUpload = vi.fn()
      mockedService.uploadDocument.mockResolvedValue({ id: 'doc-1' })
      
      render(<DocumentUploader onUpload={onUpload} />)
      
      const file = new File(['content'], 'test.pdf', { type: 'application/pdf' })
      const input = screen.getByLabelText(/upload/i)
      
      await user.upload(input, file)
      
      await waitFor(() => {
        expect(mockedService.uploadDocument).toHaveBeenCalledWith(
          expect.any(FormData)
        )
      })
    })

    it('should reject invalid file types', async () => {
      const user = userEvent.setup()
      
      render(<DocumentUploader />)
      
      const file = new File(['content'], 'test.exe', { type: 'application/x-msdownload' })
      const input = screen.getByLabelText(/upload/i)
      
      await user.upload(input, file)
      
      expect(screen.getByText(/unsupported file type/i)).toBeInTheDocument()
      expect(mockedService.uploadDocument).not.toHaveBeenCalled()
    })

    it('should show upload progress', async () => {
      const user = userEvent.setup()
      
      // Mock upload with progress
      mockedService.uploadDocument.mockImplementation(() => {
        return new Promise((resolve) => {
          setTimeout(() => resolve({ id: 'doc-1' }), 100)
        })
      })
      
      render(<DocumentUploader />)
      
      const file = new File(['content'], 'test.pdf', { type: 'application/pdf' })
      await user.upload(screen.getByLabelText(/upload/i), file)
      
      expect(screen.getByRole('progressbar')).toBeInTheDocument()
      
      await waitFor(() => {
        expect(screen.queryByRole('progressbar')).not.toBeInTheDocument()
      })
    })
  })

  describe('Error Handling', () => {
    it('should handle upload failure', async () => {
      const user = userEvent.setup()
      mockedService.uploadDocument.mockRejectedValue(new Error('Upload failed'))
      
      render(<DocumentUploader />)
      
      const file = new File(['content'], 'test.pdf', { type: 'application/pdf' })
      await user.upload(screen.getByLabelText(/upload/i), file)
      
      await waitFor(() => {
        expect(screen.getByText(/upload failed/i)).toBeInTheDocument()
      })
    })

    it('should allow retry after failure', async () => {
      const user = userEvent.setup()
      mockedService.uploadDocument
        .mockRejectedValueOnce(new Error('Network error'))
        .mockResolvedValueOnce({ id: 'doc-1' })
      
      render(<DocumentUploader />)
      
      const file = new File(['content'], 'test.pdf', { type: 'application/pdf' })
      await user.upload(screen.getByLabelText(/upload/i), file)
      
      await waitFor(() => {
        expect(screen.getByRole('button', { name: /retry/i })).toBeInTheDocument()
      })
      
      await user.click(screen.getByRole('button', { name: /retry/i }))
      
      await waitFor(() => {
        expect(screen.getByText(/uploaded successfully/i)).toBeInTheDocument()
      })
    })
  })
})

Example: Document List with Pagination

describe('DocumentList', () => {
  describe('Pagination', () => {
    it('should load first page on mount', async () => {
      mockedService.getDocuments.mockResolvedValue({
        data: [{ id: '1', name: 'Doc 1' }],
        total: 50,
        page: 1,
        pageSize: 10,
      })
      
      render(<DocumentList datasetId="ds-1" />)
      
      await waitFor(() => {
        expect(screen.getByText('Doc 1')).toBeInTheDocument()
      })
      
      expect(mockedService.getDocuments).toHaveBeenCalledWith('ds-1', { page: 1 })
    })

    it('should navigate to next page', async () => {
      const user = userEvent.setup()
      mockedService.getDocuments.mockResolvedValue({
        data: [{ id: '1', name: 'Doc 1' }],
        total: 50,
        page: 1,
        pageSize: 10,
      })
      
      render(<DocumentList datasetId="ds-1" />)
      
      await waitFor(() => {
        expect(screen.getByText('Doc 1')).toBeInTheDocument()
      })
      
      mockedService.getDocuments.mockResolvedValue({
        data: [{ id: '11', name: 'Doc 11' }],
        total: 50,
        page: 2,
        pageSize: 10,
      })
      
      await user.click(screen.getByRole('button', { name: /next/i }))
      
      await waitFor(() => {
        expect(screen.getByText('Doc 11')).toBeInTheDocument()
      })
    })
  })

  describe('Search & Filtering', () => {
    it('should filter by search query', async () => {
      const user = userEvent.setup()
      vi.useFakeTimers()
      
      render(<DocumentList datasetId="ds-1" />)
      
      await user.type(screen.getByPlaceholderText(/search/i), 'test query')
      
      // Debounce
      vi.advanceTimersByTime(300)
      
      await waitFor(() => {
        expect(mockedService.getDocuments).toHaveBeenCalledWith(
          'ds-1',
          expect.objectContaining({ search: 'test query' })
        )
      })
      
      vi.useRealTimers()
    })
  })
})

Configuration Components (app/configuration/, config/)

Configuration components handle forms, validation, and data persistence.

Key Test Areas

1. Form Validation 1. Save/Reset 1. Required vs Optional Fields 1. Configuration Persistence 1. Error Feedback

Example: App Configuration Form

import { render, screen, fireEvent, waitFor } from '@testing-library/react'
import userEvent from '@testing-library/user-event'
import AppConfigForm from './app-config-form'

vi.mock('@/service/apps', () => ({
  updateAppConfig: vi.fn(),
  getAppConfig: vi.fn(),
}))

import * as appService from '@/service/apps'
const mockedService = vi.mocked(appService)

describe('AppConfigForm', () => {
  const defaultConfig = {
    name: 'My App',
    description: '',
    icon: 'default',
    openingStatement: '',
  }

  beforeEach(() => {
    vi.clearAllMocks()
    mockedService.getAppConfig.mockResolvedValue(defaultConfig)
  })

  describe('Form Validation', () => {
    it('should require app name', async () => {
      const user = userEvent.setup()
      
      render(<AppConfigForm appId="app-1" />)
      
      await waitFor(() => {
        expect(screen.getByLabelText(/name/i)).toHaveValue('My App')
      })
      
      // Clear name field
      await user.clear(screen.getByLabelText(/name/i))
      await user.click(screen.getByRole('button', { name: /save/i }))
      
      expect(screen.getByText(/name is required/i)).toBeInTheDocument()
      expect(mockedService.updateAppConfig).not.toHaveBeenCalled()
    })

    it('should validate name length', async () => {
      const user = userEvent.setup()
      
      render(<AppConfigForm appId="app-1" />)
      
      await waitFor(() => {
        expect(screen.getByLabelText(/name/i)).toBeInTheDocument()
      })
      
      // Enter very long name
      await user.clear(screen.getByLabelText(/name/i))
      await user.type(screen.getByLabelText(/name/i), 'a'.repeat(101))
      
      expect(screen.getByText(/name must be less than 100 characters/i)).toBeInTheDocument()
    })

    it('should allow empty optional fields', async () => {
      const user = userEvent.setup()
      mockedService.updateAppConfig.mockResolvedValue({ success: true })
      
      render(<AppConfigForm appId="app-1" />)
      
      await waitFor(() => {
        expect(screen.getByLabelText(/name/i)).toHaveValue('My App')
      })
      
      // Leave description empty (optional)
      await user.click(screen.getByRole('button', { name: /save/i }))
      
      await waitFor(() => {
        expect(mockedService.updateAppConfig).toHaveBeenCalled()
      })
    })
  })

  describe('Save/Reset Functionality', () => {
    it('should save configuration', async () => {
      const user = userEvent.setup()
      mockedService.updateAppConfig.mockResolvedValue({ success: true })
      
      render(<AppConfigForm appId="app-1" />)
      
      await waitFor(() => {
        expect(screen.getByLabelText(/name/i)).toHaveValue('My App')
      })
      
      await user.clear(screen.getByLabelText(/name/i))
      await user.type(screen.getByLabelText(/name/i), 'Updated App')
      await user.click(screen.getByRole('button', { name: /save/i }))
      
      await waitFor(() => {
        expect(mockedService.updateAppConfig).toHaveBeenCalledWith(
          'app-1',
          expect.objectContaining({ name: 'Updated App' })
        )
      })
      
      expect(screen.getByText(/saved successfully/i)).toBeInTheDocument()
    })

    it('should reset to default values', async () => {
      const user = userEvent.setup()
      
      render(<AppConfigForm appId="app-1" />)
      
      await waitFor(() => {
        expect(screen.getByLabelText(/name/i)).toHaveValue('My App')
      })
      
      // Make changes
      await user.clear(screen.getByLabelText(/name/i))
      await user.type(screen.getByLabelText(/name/i), 'Changed Name')
      
      // Reset
      await user.click(screen.getByRole('button', { name: /reset/i }))
      
      expect(screen.getByLabelText(/name/i)).toHaveValue('My App')
    })

    it('should show unsaved changes warning', async () => {
      const user = userEvent.setup()
      
      render(<AppConfigForm appId="app-1" />)
      
      await waitFor(() => {
        expect(screen.getByLabelText(/name/i)).toHaveValue('My App')
      })
      
      // Make changes
      await user.type(screen.getByLabelText(/name/i), ' Updated')
      
      expect(screen.getByText(/unsaved changes/i)).toBeInTheDocument()
    })
  })

  describe('Error Handling', () => {
    it('should show error on save failure', async () => {
      const user = userEvent.setup()
      mockedService.updateAppConfig.mockRejectedValue(new Error('Server error'))
      
      render(<AppConfigForm appId="app-1" />)
      
      await waitFor(() => {
        expect(screen.getByLabelText(/name/i)).toHaveValue('My App')
      })
      
      await user.click(screen.getByRole('button', { name: /save/i }))
      
      await waitFor(() => {
        expect(screen.getByText(/failed to save/i)).toBeInTheDocument()
      })
    })
  })
})

Mocking Guide for Dify Frontend Tests

⚠️ Important: What NOT to Mock

DO NOT Mock Base Components or dify-ui Primitives

*Never mock components from `@/app/components/base/` or from `@langgenius/dify-ui/`** such as:

• Legacy base (@/app/components/base/*): Loading, Spinner, Input, Badge, Tag
• dify-ui primitives (@langgenius/dify-ui/*): Button, Tooltip, Dialog, Popover, DropdownMenu, ContextMenu, Select, AlertDialog, Toast

Why?

• These components have their own dedicated tests
• Mocking them creates false positives (tests pass but real integration fails)
• Using real components tests actual integration behavior

// ❌ WRONG: Don't mock base components or dify-ui primitives
vi.mock('@/app/components/base/loading', () => () => <div>Loading</div>)
vi.mock('@langgenius/dify-ui/button', () => ({ Button: ({ children }: any) => <button>{children}</button> }))

// ✅ CORRECT: Import and use the real components
import Loading from '@/app/components/base/loading'
import { Button } from '@langgenius/dify-ui/button'
// They will render normally in tests

What TO Mock

Only mock these categories:

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

Zustand Stores - DO NOT Mock Manually

Zustand is globally mocked in web/vitest.setup.ts. Use real stores with setState():

// ✅ CORRECT: Use real store, set test state
import { useAppStore } from '@/app/components/app/store'

useAppStore.setState({ appDetail: { id: 'test', name: 'Test' } })
render(<MyComponent />)

// ❌ WRONG: Don't mock the store module
vi.mock('@/app/components/app/store', () => ({ ... }))

See Zustand Store Testing section for full details.

Mock Placement

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

Note: Zustand is special - it's globally mocked but you should NOT mock store modules manually. See Zustand Store Testing.

Essential Mocks

1. i18n (Auto-loaded via Global Mock)

A global mock is defined in web/vitest.setup.ts and is auto-loaded by Vitest setup.

The global mock provides:

• useTranslation - returns translation keys with namespace prefix
• Trans component - renders i18nKey and components
• useMixedTranslation (from @/app/components/plugins/marketplace/hooks)
• useGetLanguage (from @/context/i18n) - returns 'en-US'

Default behavior: Most tests should use the global mock (no local override needed).

For custom translations: Use the helper function from @/test/i18n-mock:

import { createReactI18nextMock } from '@/test/i18n-mock'

vi.mock('react-i18next', () => createReactI18nextMock({
  'my.custom.key': 'Custom translation',
  'button.save': 'Save',
}))

Avoid: Manually defining useTranslation mocks that just return the key - the global mock already does this.

2. 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.1 nuqs Query State (Preferred: Testing Adapter)

For tests that validate URL query behavior, use NuqsTestingAdapter instead of mocking nuqs directly.

import { renderHookWithNuqs } from '@/test/nuqs-testing'

it('should sync query to URL with push history', async () => {
  const { result, onUrlUpdate } = renderHookWithNuqs(() => useMyQueryState(), {
    searchParams: '?page=1',
  })

  act(() => {
    result.current.setQuery({ page: 2 })
  })

  await waitFor(() => expect(onUrlUpdate).toHaveBeenCalled())
  const update = onUrlUpdate.mock.calls[onUrlUpdate.mock.calls.length - 1][0]
  expect(update.options.history).toBe('push')
  expect(update.searchParams.get('page')).toBe('2')
})

Use direct vi.mock('nuqs') only when URL synchronization is intentionally out of scope.

3. 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
  })
})

4. 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()
    })
  })
})

5. HTTP and fetch Mocking

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

  it('should display repo info', async () => {
    vi.mocked(globalThis.fetch).mockResolvedValueOnce(
      new Response(JSON.stringify({ name: 'dify', stars: 1000 }), {
        status: 200,
        headers: { 'Content-Type': 'application/json' },
      }),
    )
    
    render(<GithubComponent />)
    
    await waitFor(() => {
      expect(screen.getByText('dify')).toBeInTheDocument()
    })
  })

  it('should handle API error', async () => {
    vi.mocked(globalThis.fetch).mockResolvedValueOnce(
      new Response(JSON.stringify({ message: 'Server error' }), {
        status: 500,
        headers: { 'Content-Type': 'application/json' },
      }),
    )
    
    render(<GithubComponent />)
    
    await waitFor(() => {
      expect(screen.getByText(/error/i)).toBeInTheDocument()
    })
  })
})

Prefer mocking @/service/* modules or spying on global.fetch / ky clients with deterministic responses. Do not introduce an HTTP interception dependency such as nock or MSW unless it is already declared in the workspace or adding it is part of the task.

6. 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()
  })
})

7. 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 and dify-ui primitives - Import from @/app/components/base/ or @langgenius/dify-ui/* directly 1. Use real project components - Prefer importing over mocking 1. Use real Zustand stores - Set test state via store.setState() 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 or dify-ui primitives (Loading, Input, Button, Tooltip, Dialog, etc.) 1. Don't mock Zustand store modules - Use real stores with setState() 1. Don't mock components you can import directly 1. Don't create overly simplified mocks that miss conditional logic 1. Don't leave HTTP mocks or service mock state leaking between tests 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/* or @langgenius/dify-ui/*?
│  └─ 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 a Zustand store?
│  └─ YES → DO NOT mock the module!
│           Use real store + setState() to set test state
│           (Global mock handles auto-reset)
│
└─ Is it i18n?
   └─ YES → Uses shared mock (auto-loaded). Override only for custom translations

Zustand Store Testing

Global Zustand Mock (Auto-loaded)

Zustand is globally mocked in web/vitest.setup.ts following the official Zustand testing guide. The mock in web/__mocks__/zustand.ts provides:

• Real store behavior with getState(), setState(), subscribe() methods
• Automatic store reset after each test via afterEach
• Proper test isolation between tests

✅ Recommended: Use Real Stores (Official Best Practice)

DO NOT mock store modules manually. Import and use the real store, then use setState() to set test state:

// ✅ CORRECT: Use real store with setState
import { useAppStore } from '@/app/components/app/store'

describe('MyComponent', () => {
  it('should render app details', () => {
    // Arrange: Set test state via setState
    useAppStore.setState({
      appDetail: {
        id: 'test-app',
        name: 'Test App',
        mode: 'chat',
      },
    })

    // Act
    render(<MyComponent />)

    // Assert
    expect(screen.getByText('Test App')).toBeInTheDocument()
    // Can also verify store state directly
    expect(useAppStore.getState().appDetail?.name).toBe('Test App')
  })

  // No cleanup needed - global mock auto-resets after each test
})

❌ Avoid: Manual Store Module Mocking

Manual mocking conflicts with the global Zustand mock and loses store functionality:

// ❌ WRONG: Don't mock the store module
vi.mock('@/app/components/app/store', () => ({
  useStore: (selector) => mockSelector(selector),  // Missing getState, setState!
}))

// ❌ WRONG: This conflicts with global zustand mock
vi.mock('@/app/components/workflow/store', () => ({
  useWorkflowStore: vi.fn(() => mockState),
}))

Problems with manual mocking:

1. Loses getState(), setState(), subscribe() methods 1. Conflicts with global Zustand mock behavior 1. Requires manual maintenance of store API 1. Tests don't reflect actual store behavior

When Manual Store Mocking is Necessary

In rare cases where the store has complex initialization or side effects, you can mock it, but ensure you provide the full store API:

// If you MUST mock (rare), include full store API
const mockStore = {
  appDetail: { id: 'test', name: 'Test' },
  setAppDetail: vi.fn(),
}

vi.mock('@/app/components/app/store', () => ({
  useStore: Object.assign(
    (selector: (state: typeof mockStore) => unknown) => selector(mockStore),
    {
      getState: () => mockStore,
      setState: vi.fn(),
      subscribe: vi.fn(),
    },
  ),
}))

Store Testing Decision Tree

Need to test a component using Zustand store?
│
├─ Can you use the real store?
│  └─ YES → Use real store + setState (RECOMMENDED)
│           useAppStore.setState({ ... })
│
├─ Does the store have complex initialization/side effects?
│  └─ YES → Consider mocking, but include full API
│           (getState, setState, subscribe)
│
└─ Are you testing the store itself (not a component)?
   └─ YES → Test store directly with getState/setState
            const store = useMyStore
            store.setState({ count: 0 })
            store.getState().increment()
            expect(store.getState().count).toBe(1)

Example: Testing Store Actions

import { useCounterStore } from '@/stores/counter'

describe('Counter Store', () => {
  it('should increment count', () => {
    // Initial state (auto-reset by global mock)
    expect(useCounterStore.getState().count).toBe(0)

    // Call action
    useCounterStore.getState().increment()

    // Verify state change
    expect(useCounterStore.getState().count).toBe(1)
  })

  it('should reset to initial state', () => {
    // Set some state
    useCounterStore.setState({ count: 100 })
    expect(useCounterStore.getState().count).toBe(100)

    // After this test, global mock will reset to initial state
  })
})

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). For coverage requirements within a single test file, see web/docs/test.md § Coverage Goals.

⚠️ 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. Run `pnpm analyze-component <path>` (if available)
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: pnpm test <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
pnpm test path/to/directory/

# Check coverage
pnpm test:coverage path/to/directory/

Component Complexity Guidelines

Use pnpm analyze-component <path> to assess complexity before testing.

🔴 Very Complex Components (Complexity > 50)

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 (Complexity 30-50)

• 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 (Complexity < 30)

• 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 Codex's Todo Feature

When using Codex for multi-file testing:

1. Create a todo list before starting 1. Process one file at a time 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