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