1# Testing Review Rules
2 
3Use these rules when reviewing test files, testability of changed code, or risky frontend changes that should have tests.
4 
5## Missing Coverage
6 
7Flag missing tests when the change affects:
8 
9- User-visible behavior, navigation, form submission, validation, permissions, or loading/error/empty states.
10- Query/mutation cache behavior.
11- Accessibility-critical behavior such as labels, keyboard flow, focus, disabled state, or popup reachability.
12- URL state parsing/serialization.
13- Storage persistence or one-shot signals.
14- Regression-prone workflow or generated contract migration paths.
15 
16Do not request tests for purely mechanical renames or styling-only changes unless the styling affects layout, focus, or interaction.
17 
18## Selectors
19 
20Flag:
21 
22- `getByTestId` used where role, label, text, placeholder, landmark, or scoped dialog/menu queries are available.
23- Production `data-testid` added only to satisfy tests.
24- Assertions against decorative icons rather than the named control.
25- Tests that cannot find controls semantically but leave broken markup unchanged.
26 
27Prefer `getByRole` with accessible name, then `getByLabelText`, `getByPlaceholderText`, `getByText`, and `within(...)`.
28 
29## Mocking
30 
31Flag:
32 
33- Mocking `@langgenius/dify-ui/*` primitives.
34- Mocking `@/app/components/base/*` components when the real component is practical.
35- Mocking sibling or child components in the same directory for integration behavior.
36- Mocks that do not match the real component's conditional rendering.
37- Module-level mock state not reset in `beforeEach`.
38- `vi.clearAllMocks()` in `afterEach` instead of `beforeEach`.
39 
40Use real project components for integration behavior. Mock APIs, `next/navigation`, browser shims, or complex providers only when setup would dominate the test.
41 
42## Behavior
43 
44Flag:
45 
46- Tests inspecting implementation details instead of user-observable behavior.
47- Assertions that hardcode brittle copy when pattern matching or semantic roles would express behavior better.
48- Fake timers used without real timing behavior.
49- Async assertions missing `await`, `findBy*`, or `waitFor`.
50- Test data missing required fields because inline partial objects bypass real types.
51 
52Use typed factory functions with complete defaults and partial overrides.
53 
54## URL State
55 
56For `nuqs` or query-state hooks, flag tests that:
57 
58- Mock URL state when URL synchronization is the behavior under review.
59- Do not test parser serialize/parse round trips for custom parsers.
60- Do not assert default-clearing behavior when defaults should be removed from the URL.
61 
62Prefer shared `NuqsTestingAdapter` helpers when available.
63 
64## Organization
65 
66Flag:
67 
68- Component/hook/util tests outside sibling `__tests__/` directories.
69- Directory-level reviews that test only `index.tsx` while other files in scope contain behavior.
70- Large test files with repeated setup that should use local builders.
71 
72When a component is very complex, prefer a refactor finding before asking for exhaustive tests.
73