Cursor rule

1---
2description: Frontend Vitest browser-mode tests, Testing Library queries, mockSdkService, makeMe builders, deterministic Vue component testing
3globs: frontend/tests/**/*.ts, frontend/src/**/*.spec.ts
4alwaysApply: false
5---
6# Frontend Testing Rules
7 
8Use this rule when creating or updating frontend Vitest tests. For canonical lint and format commands, use `linting_formating.mdc`.
9 
10## Test Commands
11 
12From the repo root:
13 
14```bash
15CURSOR_DEV=true nix develop -c pnpm frontend:test
16```
17 
18Run tests with browser rendering UI:
19 
20```bash
21CURSOR_DEV=true nix develop -c pnpm frontend:test:ui
22```
23 
24Run tests in browser-rendered watch mode:
25 
26```bash
27CURSOR_DEV=true nix develop -c pnpm frontend:test:watch
28```
29 
30Run a single test file from the repo root:
31 
32```bash
33CURSOR_DEV=true nix develop -c pnpm frontend:test tests/path/to/TestFile.spec.ts
34```
35 
36Or only the frontend package:
37 
38```bash
39CURSOR_DEV=true nix develop -c pnpm -C frontend test tests/path/to/TestFile.spec.ts
40```
41 
42Run a specific test case:
43 
44```bash
45CURSOR_DEV=true nix develop -c pnpm -C frontend test -t "test name pattern"
46```
47 
48The test file path is relative to `frontend/`. Do not use `pnpm ... test -- tests/...`; the `--` is forwarded to Vitest and file filtering is skipped.
49 
50In most situations, run all unit tests instead of a selected file only. Use a single test file when actively debugging or iterating on a specific component.
51 
52## Component Behavior
53 
54- Test through user interactions.
55- Avoid testing implementation details.
56- For cross-cutting guidance about observable outcomes, high-level entry points, and avoiding 1:1 test/file mapping, use the `phased-planning` skill's Observable behavior first section.
57- Use `data-testid` for test selectors.
58- Use Vitest browser mode and prefer real browser rendering over mocking; stop using jsdom.
59 
60## Avoid Role Queries
61 
62- Do not use `getByRole`, `findByRole`, `queryByRole`, `getAllByRole`, and similar queries; they are slow due to expensive visibility checks.
63- Testing Library recommends role queries for accessibility, but this project prioritizes test performance.
64- Use faster alternatives: `getByText`, `getByLabelText`, `getByTitle`, or `querySelector` / `querySelectorAll`.
65 
66## Mock SDK Services
67 
68- Use `mockSdkService` from `@tests/helpers` for type-safe mocking: pass the generated **controller class** and the **method name** (same static methods as `@generated/doughnut-backend-api/sdk.gen`).
69- It automatically wraps responses in the standard format `{ data, error, request, response }`.
70- It returns a spy that can be reconfigured in tests.
71- Use `wrapSdkResponse` when updating mock return values.
72- Use `mockSdkServiceWithImplementation` only for custom async logic based on options.
73 
74```typescript
75import { NoteController } from "@generated/doughnut-backend-api/sdk.gen"
76import { mockSdkService } from "@tests/helpers"
77 
78beforeEach(() => {
79  mockSdkService(NoteController, "getRecentNotes", [])
80  mockSdkService(NoteController, "showNote", makeMe.aNoteRealm.please())
81})
82```
83 
84```typescript
85import { NoteController } from "@generated/doughnut-backend-api/sdk.gen"
86import { mockSdkService, wrapSdkResponse } from "@tests/helpers"
87 
88const spy = mockSdkService(NoteController, "showNote", makeMe.aNoteRealm.please())
89spy.mockResolvedValue(wrapSdkResponse(differentNote))
90```
91 
92```typescript
93import { TextContentController } from "@generated/doughnut-backend-api/sdk.gen"
94import { mockSdkServiceWithImplementation } from "@tests/helpers"
95 
96mockSdkServiceWithImplementation(TextContentController, "updateNoteContent", async (options) => {
97  return await someAsyncOperation(options)
98})
99```
100 
101## Component Props
102 
103- Use `helper.component(ComponentName).withStorageProps` if the component requires a `storageAccessor` prop.
104- Use `withProps` instead of `withStorageProps` if the component does not require `storageAccessor`.
105- Test prop changes and their effects.
106 
107```typescript
108const wrapper = helper
109  .component(Component)
110  .withStorageProps({ value: initialValue })
111  .mount()
112 
113await wrapper.setProps({ value: newValue })
114```
115 
116## Data Builders
117 
118- Use `makeMe` for API-shaped test data; implementation lives in `packages/doughnut-test-fixtures`.
119- Import `doughnut-test-fixtures/makeMe` only. Do not import the bare package name or deep paths into `src/`.
120- Builders handle complex object creation.
121 
122```typescript
123const note = makeMe.aNoteRealm
124  .topicConstructor("Dummy Title")
125  .content("Description")
126  .please()
127```
128 
129## Browser Mode Mounting
130 
131- Use `render()` from `@testing-library/vue` for most tests.
132- `render()` encourages user-perspective tests and returns fast queries such as `getByText`, `getByLabelText`, and `data-testid`.
133- Use `mount()` from `@vue/test-utils` only when you need direct access to Vue internals, emitted events, slots, or provide/inject edge cases.
134- Query the DOM, not Vue components.
135 
136Prefer:
137 
138```typescript
139page.getByText(/submit/i)
140screen.getByText("Loading...")
141```
142 
143Avoid:
144 
145```typescript
146wrapper.findComponent(MyButton)
147wrapper.find("[data-testid='my-component']")
148```
149 
150## Deterministic Tests
151 
152- Tests must always execute the same way.
153- Use assertions instead of if-conditions so failures are clear.
154- Use sequential async operations instead of loops where possible.
155 
156Avoid:
157 
158```typescript
159if (vm.searchResults) {
160  const selected = vm.searchResults.find((result) => result.id === wikidataId)
161  if (selected) {
162    // do something
163  }
164}
165```
166 
167Prefer:
168 
169```typescript
170expect(vm.searchResults).toBeDefined()
171expect(vm.searchResults.length).toBeGreaterThan(0)
172const selected = vm.searchResults.find((result) => result.id === wikidataId)
173expect(selected).toBeDefined()
174```
175