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 />)
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:
- Analyze & Plan: List all files, order by complexity (simple → complex)
- Process ONE at a time: Write test → Run test → Fix if needed → Next
- 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:
- 🟢 Utility functions (simplest)
- 🟢 Custom hooks
- 🟡 Simple components (presentational)
- 🟡 Medium components (state, effects)
- 🔴 Complex components (API, routing)
- 🔴 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)
- Rendering: Component renders without crashing
- Props: Required props, optional props, default values
- Edge Cases: null, undefined, empty values, boundary conditions
Conditional (When Present)
| Feature |
Test Focus |
useState |
Initial state, transitions, cleanup |
useEffect |
Execution, dependencies, cleanup |
| Event handlers |
All onClick, onChange, onSubmit, keyboard |
| API calls |
Loading, success, error states |
| Routing |
Navigation, params, query strings |
useCallback/useMemo |
Referential equality |
| Context |
Provider values, consumer behavior |
| Forms |
Validation, submission, error display |
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.
1---2name: frontend-testing3description: Generate Vitest + React Testing Library tests for Dify frontend components, hooks, and utilities. Triggers on testing, spec files, coverage, Vitest, RTL, unit tests, integration tests, or write/review test requests.4metadata:5 source: https://skillmd.com/skills/zuoguyoupan2023/frontend-testing6---78# Dify Frontend Testing Skill910This skill enables Codex to generate high-quality, comprehensive frontend tests for the Dify project following established conventions and best practices.1112> **⚠️ Authoritative Source**: This skill is derived from `web/docs/test.md`. Use Vitest mock/timer APIs (`vi.*`).1314## When to Apply This Skill1516Apply this skill when the user:1718- Asks to **write tests** for a component, hook, or utility19- Asks to **review existing tests** for completeness20- Mentions **Vitest**, **React Testing Library**, **RTL**, or **spec files**21- Requests **test coverage** improvement22- Uses `pnpm analyze-component` output as context23- Mentions **testing**, **unit tests**, or **integration tests** for frontend code24- Wants to understand **testing patterns** in the Dify codebase2526**Do NOT apply** when:2728- User is asking about backend/API tests (Python/pytest)29- User is asking about E2E tests (Cucumber + Playwright under `e2e/`)30- User is only asking conceptual questions without code context3132## Quick Reference3334### Key Commands3536Run these commands from `web/`. From the repository root, prefix them with `pnpm -C web`.3738```bash39# Run all tests40pnpm test4142# Watch mode43pnpm test --watch4445# Run specific file46pnpm test path/to/file.spec.tsx4748# Generate coverage report49pnpm test --coverage5051# Analyze component complexity52pnpm analyze-component <path>5354# Review existing test55pnpm analyze-component <path> --review56```5758### File Naming5960- Test files: `ComponentName.spec.tsx` inside a same-level `__tests__/` directory61- 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`.62- Integration tests: `web/__tests__/` directory6364## Test Structure Template6566```typescript67import { render, screen, fireEvent, waitFor } from '@testing-library/react'68import Component from './index'6970// ✅ Import real project components (DO NOT mock these)71// import Loading from '@/app/components/base/loading'72// import { ChildComponent } from './child-component'7374// ✅ Mock external dependencies only75vi.mock('@/service/api')76vi.mock('next/navigation', () => ({77 useRouter: () => ({ push: vi.fn() }),78 usePathname: () => '/test',79}))8081// ✅ Zustand stores: Use real stores (auto-mocked globally)82// Set test state with: useAppStore.setState({ ... })8384// Shared state for mocks (if needed)85let mockSharedState = false8687describe('ComponentName', () => {88 beforeEach(() => {89 vi.clearAllMocks() // ✅ Reset mocks BEFORE each test90 mockSharedState = false // ✅ Reset shared state91 })9293 // Rendering tests (REQUIRED)94 describe('Rendering', () => {95 it('should render without crashing', () => {96 // Arrange97 const props = { title: 'Test' }98 99 // Act100 render(<Component {...props} />)101 102 // Assert103 expect(screen.getByText('Test')).toBeInTheDocument()104 })105 })106107 // Props tests (REQUIRED)108 describe('Props', () => {109 it('should apply custom className', () => {110 render(<Component className="custom" />)111 expect(screen.getByRole('button')).toHaveClass('custom')112 })113 })114115 // User Interactions116 describe('User Interactions', () => {117 it('should handle click events', () => {118 const handleClick = vi.fn()119 render(<Component onClick={handleClick} />)120 121 fireEvent.click(screen.getByRole('button'))122 123 expect(handleClick).toHaveBeenCalledTimes(1)124 })125 })126127 // Edge Cases (REQUIRED)128 describe('Edge Cases', () => {129 it('should handle null data', () => {130 render(<Component data={null} />)131 expect(screen.getByText(/no data/i)).toBeInTheDocument()132 })133134 it('should handle empty array', () => {135 render(<Component items={[]} />)136 expect(screen.getByText(/empty/i)).toBeInTheDocument()137 })138 })139})140```141142## Testing Workflow (CRITICAL)143144### ⚠️ Incremental Approach Required145146**NEVER generate all test files at once.** For complex components or multi-file directories:1471481. **Analyze & Plan**: List all files, order by complexity (simple → complex)1491. **Process ONE at a time**: Write test → Run test → Fix if needed → Next1501. **Verify before proceeding**: Do NOT continue to next file until current passes151152```153For each file:154 ┌────────────────────────────────────────┐155 │ 1. Write test │156 │ 2. Run: pnpm test <file>.spec.tsx │157 │ 3. PASS? → Mark complete, next file │158 │ FAIL? → Fix first, then continue │159 └────────────────────────────────────────┘160```161162### Complexity-Based Order163164Process in this order for multi-file testing:1651661. 🟢 Utility functions (simplest)1671. 🟢 Custom hooks1681. 🟡 Simple components (presentational)1691. 🟡 Medium components (state, effects)1701. 🔴 Complex components (API, routing)1711. 🔴 Integration tests (index files - last)172173### When to Refactor First174175- **Complexity > 50**: Break into smaller pieces before testing176- **500+ lines**: Consider splitting before testing177- **Many dependencies**: Extract logic into hooks first178179> 📖 See `references/workflow.md` for complete workflow details and todo list format.180181## Testing Strategy182183### Path-Level Testing (Directory Testing)184185When assigned to test a directory/path, test **ALL content** within that path:186187- Test all components, hooks, utilities in the directory (not just `index` file)188- Use incremental approach: one file at a time, verify each before proceeding189- Goal: 100% coverage of ALL files in the directory190191### Integration Testing First192193**Prefer integration testing** when writing tests for a directory:194195- ✅ **Import real project components** directly (including base components and siblings)196- ✅ **Only mock**: API services (`@/service/*`), `next/navigation`, complex context providers197- ❌ **DO NOT mock** base components (`@/app/components/base/*`) or dify-ui primitives (`@langgenius/dify-ui/*`)198- ❌ **DO NOT mock** sibling/child components in the same directory199200> See [Test Structure Template](#test-structure-template) for correct import/mock patterns.201202### `nuqs` Query State Testing (Required for URL State Hooks)203204When a component or hook uses `useQueryState` / `useQueryStates`:205206- ✅ Use `NuqsTestingAdapter` (prefer shared helpers in `web/test/nuqs-testing.tsx`)207- ✅ Assert URL synchronization via `onUrlUpdate` (`searchParams`, `options.history`)208- ✅ For custom parsers (`createParser`), keep `parse` and `serialize` bijective and add round-trip edge cases (`%2F`, `%25`, spaces, legacy encoded values)209- ✅ Verify default-clearing behavior (default values should be removed from URL when applicable)210- ⚠️ Only mock `nuqs` directly when URL behavior is explicitly out of scope for the test211212## Core Principles213214### 1. AAA Pattern (Arrange-Act-Assert)215216Every test should clearly separate:217218- **Arrange**: Setup test data and render component219- **Act**: Perform user actions220- **Assert**: Verify expected outcomes221222### 2. Black-Box Testing223224- Test observable behavior, not implementation details225- Use semantic queries (`getByRole` with accessible `name`, `getByLabelText`, `getByPlaceholderText`, `getByText`, and scoped `within(...)`)226- 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`.227- 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.228- Do not assert decorative icons by test id. Assert the named control that contains them, or mark decorative icons `aria-hidden`.229- Avoid testing internal state directly230- **Prefer pattern matching over hardcoded strings** in assertions:231232```typescript233// ❌ Avoid: hardcoded text assertions234expect(screen.getByText('Loading...')).toBeInTheDocument()235236// ✅ Better: role-based queries237expect(screen.getByRole('status')).toBeInTheDocument()238239// ✅ Better: pattern matching240expect(screen.getByText(/loading/i)).toBeInTheDocument()241```242243### 3. Single Behavior Per Test244245Each test verifies ONE user-observable behavior:246247```typescript248// ✅ Good: One behavior249it('should disable button when loading', () => {250 render(<Button loading />)251 expect(screen.getByRole('button')).toBeDisabled()252})253254// ❌ Bad: Multiple behaviors255it('should handle loading state', () => {256 render(<Button loading />)257 expect(screen.getByRole('button')).toBeDisabled()258 expect(screen.getByText('Loading...')).toBeInTheDocument()259 expect(screen.getByRole('button')).toHaveClass('loading')260})261```262263### 4. Semantic Naming264265Use `should <behavior> when <condition>`:266267```typescript268it('should show error message when validation fails')269it('should call onSubmit when form is valid')270it('should disable input when isReadOnly is true')271```272273## Required Test Scenarios274275### Always Required (All Components)2762771. **Rendering**: Component renders without crashing2781. **Props**: Required props, optional props, default values2791. **Edge Cases**: null, undefined, empty values, boundary conditions280281### Conditional (When Present)282283| Feature | Test Focus |284|---------|-----------|285| `useState` | Initial state, transitions, cleanup |286| `useEffect` | Execution, dependencies, cleanup |287| Event handlers | All onClick, onChange, onSubmit, keyboard |288| API calls | Loading, success, error states |289| Routing | Navigation, params, query strings |290| `useCallback`/`useMemo` | Referential equality |291| Context | Provider values, consumer behavior |292| Forms | Validation, submission, error display |293294## Coverage Goals (Per File)295296For each test file generated, aim for:297298- ✅ **100%** function coverage299- ✅ **100%** statement coverage300- ✅ **>95%** branch coverage301- ✅ **>95%** line coverage302303> **Note**: For multi-file directories, process one file at a time with full coverage each. See `references/workflow.md`.304305## Detailed Guides306307For more detailed information, refer to:308309- `references/workflow.md` - **Incremental testing workflow** (MUST READ for multi-file testing)310- `references/mocking.md` - Mock patterns, Zustand store testing, and best practices311- `references/async-testing.md` - Async operations and API calls312- `references/domain-components.md` - Workflow, Dataset, Configuration testing313- `references/common-patterns.md` - Frequently used testing patterns314- `references/checklist.md` - Test generation checklist and validation steps315316## Authoritative References317318### Primary Specification (MUST follow)319320- **`web/docs/test.md`** - The canonical testing specification. This skill is derived from this document.321322### Reference Examples in Codebase323324- `web/utils/classnames.spec.ts` - Utility function tests325- `web/app/components/base/radio/__tests__/index.spec.tsx` - Component tests326- `web/__mocks__/provider-context.ts` - Mock factory example327328### Project Configuration329330- `web/vite.config.ts` - Vite/Vitest configuration331- `web/vitest.setup.ts` - Test environment setup332- `web/scripts/analyze-component.js` - Component analysis tool333- 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.