AGENTS.md

1# Frontend Testing Rules 🧪
2 
3## Testing Types Overview
4 
5| Type            | Tool                  | Speed           | Purpose                          |
6| --------------- | --------------------- | --------------- | -------------------------------- |
7| **E2E**         | Playwright            | Slow (~5s/test) | Real browser, full user journeys |
8| **Integration** | Vitest + RTL          | Fast (~100ms)   | Component + mocked API           |
9| **Unit**        | Vitest + RTL          | Fastest (~10ms) | Individual functions/components  |
10| **Visual**      | Storybook + Chromatic | N/A             | UI appearance, design system     |
11 
12---
13 
14## When to Use Each
15 
16### ✅ E2E Tests (Playwright)
17 
18**Use for:** Critical user journeys that MUST work in a real browser.
19 
20- Authentication flows (login, signup, logout)
21- Payment or sensitive transactions
22- Flows requiring real browser APIs (clipboard, downloads)
23- Cross-page navigation that must work end-to-end
24 
25**Location:** `src/playwright/*.spec.ts` (centralized, as there will be fewer of them)
26 
27**Import:** Always import `test` and `expect` from `./coverage-fixture` instead of `@playwright/test`. This auto-collects V8 coverage per test for Codecov reporting.
28 
29```ts
30// correct
31import { test, expect } from "./coverage-fixture";
32 
33// wrong - bypasses coverage collection
34import { test, expect } from "@playwright/test";
35```
36 
37### ✅ Integration Tests (Vitest + RTL)
38 
39**Use for:** Testing components with their dependencies (API calls, state).
40 
41- Page-level behavior with mocked API responses
42- Components that fetch data
43- User interactions that trigger API calls
44- Feature flows within a single page
45 
46**Location:** Place tests in a `__tests__` folder next to the component:
47 
48```
49ComponentName/
50  __tests__/
51    main.test.tsx
52    some-flow.test.tsx
53  ComponentName.tsx
54  useComponentName.ts
55```
56 
57**Start at page level:** Initially write integration tests at the "page" level. No need to write them for every small component.
58 
59```
60/library/
61  __tests__/
62    main.test.tsx
63    searching-agents.test.tsx
64    agents-pagination.test.tsx
65  page.tsx
66  useLibraryPage.ts
67```
68 
69Start with a `main.test.tsx` file and split into smaller files as it grows.
70 
71**What integration tests should do:**
72 
731. Render a page or complex modal (e.g., `AgentPublishModal`)
742. Mock API requests via MSW
753. Assert UI scenarios via Testing Library
76 
77**Prefer the UI surface over direct hook tests:** if a `use*.ts` hook only exists to support a page/component, test that page/component instead of adding a `renderHook()` test. Reserve direct hook tests for shared hooks with standalone business logic that cannot be exercised cleanly through the UI.
78 
79**Prefer Orval-generated mocks:** use the generated MSW handlers and response builders from `src/app/api/__generated__/endpoints/*/*.msw.ts` instead of hand-built API response objects or mocking a page/component hook.
80 
81```tsx
82// Example: Test page renders data from API
83import { server } from "@/mocks/mock-server";
84import { getDeleteV2DeleteStoreSubmissionMockHandler422 } from "@/app/api/__generated__/endpoints/store/store.msw";
85 
86test("shows error when submission fails", async () => {
87  // Override default handler to return error status
88  server.use(getDeleteV2DeleteStoreSubmissionMockHandler422());
89 
90  render(<MarketplacePage />);
91  await screen.findByText("Featured Agents");
92  // ... assert error UI
93});
94```
95 
96**Tip:** Use `findBy...` methods most of the time—they wait for elements to appear, so async code won't cause flaky tests. The regular `getBy...` methods don't wait and error immediately.
97 
98### ✅ Unit Tests (Vitest + RTL)
99 
100**Use for:** Testing isolated components and utility functions.
101 
102- Pure utility functions (`lib/utils.ts`)
103- Component rendering with various props
104- Component state changes
105- Shared hooks with standalone business logic
106 
107**Location:** Co-located with the file: `Component.test.tsx` next to `Component.tsx`
108 
109```tsx
110// Example: Test component renders correctly
111render(<AgentCard title="My Agent" />);
112expect(screen.getByText("My Agent")).toBeInTheDocument();
113```
114 
115### ✅ Storybook Tests (Visual)
116 
117**Use for:** Design system, visual appearance, component documentation.
118 
119- Atoms (Button, Input, Badge)
120- Molecules (Dialog, Card)
121- Visual states (hover, disabled, loading)
122- Responsive layouts
123 
124**Location:** Co-located: `Component.stories.tsx` next to `Component.tsx`
125 
126---
127 
128## Decision Flowchart
129 
130```
131Does it need a REAL browser/backend?
132├─ YES → E2E (Playwright)
133└─ NO
134   └─ Does it involve API calls or complex state?
135      ├─ YES → Integration (Vitest + RTL)
136      └─ NO
137         └─ Is it about visual appearance?
138            ├─ YES → Storybook
139            └─ NO → Unit (Vitest + RTL)
140```
141 
142---
143 
144## What NOT to Test
145 
146❌ Third-party library internals (Radix UI, React Query)  
147❌ CSS styling details (use Storybook)  
148❌ Simple prop-passing components with no logic  
149❌ TypeScript types
150 
151---
152 
153## File Organization
154 
155```
156src/
157├── components/
158│   └── atoms/
159│       └── Button/
160│           ├── Button.tsx
161│           ├── Button.test.tsx      # Unit test
162│           └── Button.stories.tsx   # Visual test
163├── app/
164│   └── (platform)/
165│       └── marketplace/
166│           └── components/
167│               └── MainMarketplacePage/
168│                   ├── __tests__/
169│                   │   ├── main.test.tsx           # Integration test
170│                   │   └── search-agents.test.tsx  # Integration test
171│                   ├── MainMarketplacePage.tsx
172│                   └── useMainMarketplacePage.ts
173├── lib/
174│   ├── utils.ts
175│   └── utils.test.ts                # Unit test
176├── mocks/
177│   ├── mock-handlers.ts             # MSW handlers (auto-generated via Orval)
178│   └── mock-server.ts               # MSW server setup
179├── playwright/
180│   ├── *.spec.ts                    # E2E tests (Playwright) - centralized
181│   ├── pages/                       # Playwright page objects
182│   └── utils/                       # Playwright helpers/fixtures
183└── tests/
184    ├── integrations/
185    │   ├── test-utils.tsx           # Testing utilities
186    │   └── vitest.setup.tsx         # Integration test setup
187    └── AGENTS.md                    # Testing guidance for agents
188```
189 
190---
191 
192## Priority Matrix
193 
194| Component Type      | Test Priority | Recommended Test                       |
195| ------------------- | ------------- | -------------------------------------- |
196| Pages/Features      | **Highest**   | Integration                            |
197| Custom Hooks        | Medium        | Parent integration or shared-hook unit |
198| Utility Functions   | High          | Unit                                   |
199| Organisms (complex) | High          | Integration                            |
200| Molecules           | Medium        | Unit + Storybook                       |
201| Atoms               | Medium        | Storybook only\*                       |
202 
203\*Atoms are typically simple enough that Storybook visual tests suffice.
204 
205---
206 
207## MSW Mocking
208 
209API mocking is handled via MSW (Mock Service Worker). Handlers are auto-generated by Orval from the OpenAPI schema.
210 
211**Default behavior:** All client-side requests are intercepted and return 200 status with faker-generated data.
212 
213**Override for specific tests:** Use generated error handlers to test non-OK status scenarios:
214 
215```tsx
216import { server } from "@/mocks/mock-server";
217import { getDeleteV2DeleteStoreSubmissionMockHandler422 } from "@/app/api/__generated__/endpoints/store/store.msw";
218 
219test("shows error when deletion fails", async () => {
220  server.use(getDeleteV2DeleteStoreSubmissionMockHandler422());
221 
222  render(<MyComponent />);
223  // ... assert error UI
224});
225```
226 
227**Generated handlers location:** `src/app/api/__generated__/endpoints/*/` - each endpoint has handlers for different status codes.
228 
229For Playwright support code, keep browser-only helpers in `src/playwright/` rather than `src/tests/`.
230 
231---
232 
233## Golden Rules
234 
2351. **Test behavior, not implementation** - Query by role/text, not class names
2362. **One assertion per concept** - Tests should be focused
2373. **Mock at boundaries** - Mock API calls, not internal functions
2384. **Co-locate integration tests** - Keep `__tests__/` folder next to the component
2395. **E2E is expensive** - Only for critical happy paths; prefer integration tests
2406. **AI agents are good at writing integration tests** - Start with these when adding test coverage
2417. **Prefer component/page tests over hook tests** - Don't add `renderHook()` coverage for component implementation details
2428. **Use generated API mocks** - Prefer Orval MSW helpers over manual API object stubs
243