Cursor rule

1---
2description: E2E testing with Cypress and Cucumber, feature files, step definitions, page objects, fluent interface, assertions, data-app-busy / waitUntilAppIsNotBusy pairing, test execution
3globs: e2e_test/**/*.{feature,ts}
4alwaysApply: false
5---
6# E2E Authoring Rules
7 
8Use this rule when writing or modifying E2E tests, Cypress/Cucumber feature files, step definitions, page objects, or E2E assertions. For OCR-specific canvas assertions, use `e2e-ocr.mdc`.
9 
10## Environment Assumption
11 
12Assume the developer has already started services with `pnpm sut`, including backend auto-reload, frontend HMR, and Mountebank. Services automatically restart when code changes are made.
13 
14If services are not running, suggest starting `pnpm sut` in a separate terminal.
15 
16## Cypress Origin
17 
18`http://localhost:5173` is always the Cypress app origin through the local load balancer. CI vs `pnpm sut`, `wait-on`, `NO_PROXY`, and env vars are documented in `docs/gcp/prod_env.md`, Local dev / Cypress under section 6.
19 
20## Run E2E Tests
21 
22Agents should default to `pnpm cypress run --spec` with one or more `.feature` paths tied to the changed capability. Add adjacent specs only when regression risk warrants it. Do not run bare `pnpm cypress run`, `pnpm verify`, or the whole suite unless the user explicitly asks for a full E2E run or the instructions require reproducing CI.
23 
24```bash
25CURSOR_DEV=true nix develop -c pnpm cypress run --spec e2e_test/features/ai_generated_recall_questions/question_contest.feature
26```
27 
28Important notes:
29 
30- Do not use `cypress run -- --spec`; the empty `--` causes the `--spec` parameter to be ignored.
31- The default tag filter is `tags` in `e2e_test/config/ci.ts`, for example `not @ignore`. Override per run with `--env tags='...'` when needed.
32- `@skipOptimizationDueToKnownNecessarySlowness` on a Scenario or Feature marks known-necessary slowness. Test-optimization profiles exclude it with `--env tags='not @ignore and not @skipOptimizationDueToKnownNecessarySlowness'`. Normal CI/dev runs still execute these scenarios. Do not add this tag without developer review.
33- `@focus` and `@only` are local debugging aids only. Do not commit them; CI runs `./scripts/check_focus_tags.sh` on `.feature` files to block `@focus`, and `@only` should be treated the same.
34- If any node in a feature file is tagged `@focus` or `@only`, `@badeball/cypress-cucumber-preprocessor` filters scenarios in that file to `@focus or @only` only.
35 
36## Debugging
37 
38Use the canonical log-tail command for backend E2E log inspection:
39 
40```bash
41CURSOR_DEV=true nix develop -c pnpm logs:tail backend-e2e
42```
43 
44Frontend Vite checker terminal errors still matter even though the browser overlay is disabled for E2E stability. For canonical lint and format commands, use `linting_formating.mdc`.
45 
46## Technology And Structure
47 
48- Cypress for E2E testing.
49- Cucumber plugin for BDD-style tests.
50- TypeScript for type safety.
51- Mountebank mocks external services.
52- `e2e_test/features` contains BDD-style tests.
53- `e2e_test/step_definitions` contains step definitions.
54- `e2e_test/start/` contains page objects.
55- `e2e_test/start/pageObjects/cli/` contains CLI page objects with the `cli.xxx` prefix.
56- `e2e_test/support/` contains support files.
57 
58## Gherkin
59 
60- Write features in Gherkin syntax focused on business value.
61- Group related features in domain-specific folders.
62- Name feature files and titles by domain/capability, such as `note_creation.feature` or `spaced_repetition.feature`. Never name them by phase or delivery order.
63- Use tags, such as `@usingMockedOpenAiService` or `@mockBrowserTime`, to control test execution.
64- Keep scenarios focused and concise.
65 
66## Step Definitions
67 
68- Keep step definitions lightweight.
69- Delegate implementation details to page objects, preferably as fluent chains.
70- When user-visible behavior differs, use different steps and thin implementations. Do not hide variants behind one parameterized step.
71- Use TypeScript and reuse steps where practical.
72- Use parameter types for complex objects.
73 
74```typescript
75When("I start a conversation about the note {string}", (noteTopology: string) => {
76  start.jumpToNotePage(noteTopology).startAConversationAboutNote()
77})
78```
79 
80## Page Objects
81 
82Use page objects with a fluent interface: methods perform an action and return the next page object, or `this` when staying on the same screen. This keeps step definitions short and navigation explicit in the types.
83 
84- Centralize UI interactions in page objects.
85- Prefer fluent chaining over one-off helpers that do not return a navigable object.
86- Keep page objects focused on a single responsibility.
87- Use meaningful method names that reflect user actions.
88 
89```typescript
90const notePage = {
91  startAConversationAboutNote() {
92    this.toolbarButton("Start a conversation").click()
93    return conversationPage()
94  },
95}
96```
97 
98CLI steps use `cli.xxx` page objects, not `start.xxx`. For the install feature, use `cli.backend()`, `cli.installation()`, and `cli.nonInteractiveOutput()` for spawned `version` / `update` stdout. Other `features/cli/*.feature` files are `@ignore` in CI; extend Vitest under `cli/tests/interactive/` for interactive TTY coverage instead of adding a second Cypress PTY harness.
99 
100```typescript
101Then("I should see {string} in the non-interactive output", (expected: string) => {
102  cli.nonInteractiveOutput().expectContains(expected)
103})
104```
105 
106## Waiting until the app is not busy
107 
108Product loading UI that means unfinished work marks itself with `data-app-busy` (`LoadingThinBar` from `apiCallWithLoading`, `ContentLoader` for pending page data, `LoadingModal` for `blockUi`). See `.cursor/rules/frontend-api.mdc`.
109 
110E2E waits with `waitUntilAppIsNotBusy()` from `e2e_test/start/pageBase.ts` (also `start.waitUntilAppIsNotBusy()`):
111 
112```typescript
113import { waitUntilAppIsNotBusy } from '../pageBase'
114 
115cy.findByRole('button', { name: 'Submit' }).click()
116waitUntilAppIsNotBusy()
117```
118 
119Rules of thumb:
120 
121- Call `waitUntilAppIsNotBusy()` in the page object **on the action that starts loading**, before the next step that needs that work’s result.
122- Prefer asserting a **user-visible** success outcome when the product provides one; use the waiter for “busy cleared,” not as a substitute for success.
123- Do not use hardcoded waits (`cy.wait(ms)`) for this.
124- Do not skip the wait and rely on a later navigation’s loading check alone — that races when the next step does not go through busy UI.
125- Network `cy.intercept` / `cy.wait('@…')` is optional; it is not the documented default stand-in for this product/E2E pair.
126 
127## Test Data And Service Mocking
128 
129- Use Given steps to set up test data.
130- Mock external services, such as OpenAI, for reliable tests.
131- Use tags to indicate when mocks are required.
132- Keep mock responses consistent with real service behavior.
133- Store mock data separately from test code.
134- Clean up test data after each test.
135- Use data tables for complex test data.
136 
137```gherkin
138Given I have a notebook "Geometry set" with notes:
139  | Title  |
140  | Shape  |
141  | Square |
142```
143 
144Square is placed under Shape when the notebook is created in one inject batch. Do not add a `Folder` column; see testability inject ordering.
145 
146```typescript
147Given("OpenAI assistant will reply below for user messages in a stream run:", (data: DataTable) => {
148  mock_services
149    .openAi()
150    .stubCreateThread("thread-123")
151    .createThreadAndStubMessages("thread-123", data.hashes())
152})
153```
154 
155## Assertions
156 
157Error messages must be immediately actionable:
158 
1591. Assert with clear domain meaning, not just technical selectors.
1602. Show expected and actual values when they differ.
1613. Include relevant context, such as page content or API response, when helpful.
1624. Given, When, and Then steps should be assertive and fail early.
1635. Put assertions inside page objects where that keeps step definitions simple.
164 
165```typescript
166expectQuizScore(expectedScore?: string) {
167  if (expectedScore) {
168    cy.get("[data-test='quiz-score']").should(($score) => {
169      const actualScore = $score.text().trim()
170      expect(
171        actualScore,
172        `Expected quiz score to be ${expectedScore}, but found ${actualScore}`
173      ).to.equal(expectedScore)
174    })
175  }
176  return this
177}
178```
179 
180## Explicit Conditions
181 
182A scenario describes one fixed path. Prefer dumb automation: the path is visible in Gherkin and in small, purpose-named page-object methods, not inferred at runtime from a string or flag.
183 
184- Avoid large `if` / `switch` trees, parameter sniffing, and mode flags in steps and page objects except when the branch exists only to assert or fail fast with a clear error.
185- Distinguish variants at the caller with different steps and/or page-object methods, not one smart API.
186- State the condition in step wording when behavior differs, for example slash command vs plain line vs Enter alone vs ESC.
187- For CLI TTY sequences, add or extend Vitest under `cli/tests/interactive/` instead of adding a second Cypress PTY stack.
188 
189## Before hook order
190 
191`@badeball/cypress-cucumber-preprocessor` defaults Before hooks to order `10000`. The shared DB reset Before uses **`order: 0`** so it runs before tagged setup. Hooks that start long-lived side effects (e.g. `@interactiveCLI` PTY at order `2`) must stay **after** that reset; otherwise truncate can block on MySQL locks held by the PTY’s HTTP traffic.
192 
193## Pitfalls
194 
195- Do not put complex logic in step definitions.
196- Do not create long scenarios with many steps.
197- Do not rely on test order.
198- Do not use hardcoded waits.
199- Do not fire a user action that starts app-busy loading and then assert domain state without `waitUntilAppIsNotBusy()` (or a clearer user-visible success signal) first.
200- Do not skip error handling.
201- Do not mix different levels of abstraction in scenarios.
202- Do not ignore linting errors that appear in the terminal.
203- Do not add OCR or DOM text layers to production just to satisfy E2E; run OCR in Cypress Node tasks instead.
204