You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
awaitpage.keyboard.press(`${modKey}+Comma`) // Open settings
168
170
```
169
171
172
+
### Terminal Tests
173
+
174
+
- In terminal tests, type through the browser. Do not write to the PTY through the SDK.
175
+
- Use `waitTerminalReady(page, { term? })` and `runTerminal(page, { cmd, token, term?, timeout? })` from `actions.ts`.
176
+
- These helpers use the fixture-enabled test-only terminal driver and wait for output after the terminal writer settles.
177
+
- After opening the terminal, use `waitTerminalFocusIdle(...)` before the next keyboard action when prompt focus or keyboard routing matters.
178
+
- This avoids racing terminal mount, focus handoff, and prompt readiness when the next step types or sends shortcuts.
179
+
- Avoid `waitForTimeout` and custom DOM or `data-*` readiness checks.
180
+
181
+
### Wait on state
182
+
183
+
- Never use wall-clock waits like `page.waitForTimeout(...)` to make a test pass
184
+
- Avoid race-prone flows that assume work is finished after an action
185
+
- Wait or poll on observable state with `expect(...)`, `expect.poll(...)`, or existing helpers
186
+
- Prefer locator assertions like `toBeVisible()`, `toHaveCount(0)`, and `toHaveAttribute(...)` for normal UI state, and reserve `expect.poll(...)` for probe, mock, or backend state
187
+
- Prefer semantic app state over transient DOM visibility when behavior depends on active selection, focus ownership, or async retry loops
188
+
- Do not treat a visible element as proof that the app will route the next action to it
189
+
- When fixing a flake, validate with `--repeat-each` and multiple workers when practical
190
+
191
+
### Add hooks
192
+
193
+
- If required state is not observable from the UI, add a small test-only driver or probe in app code instead of sleeps or fragile DOM checks
194
+
- Keep these hooks minimal and purpose-built, following the style of `packages/app/src/testing/terminal.ts`
195
+
- Test-only hooks must be inert unless explicitly enabled; do not add normal-runtime listeners, reactive subscriptions, or per-update allocations for e2e ceremony
196
+
- When mocking routes or APIs, expose explicit mock state and wait on that before asserting post-action UI
197
+
- Add minimal test-only probes for semantic state like the active list item or selected command when DOM intermediates are unstable
198
+
- Prefer probing committed app state over asserting on transient highlight, visibility, or animation states
199
+
200
+
### Prefer helpers
201
+
202
+
- Prefer fluent helpers and drivers when they make intent obvious and reduce locator-heavy noise
203
+
- Use direct locators when the interaction is simple and a helper would not add clarity
204
+
- Prefer helpers that both perform an action and verify the app consumed it
205
+
- Avoid composing helpers redundantly when one already includes the other or already waits for the resulting state
206
+
- If a helper already covers the required wait or verification, use it directly instead of layering extra clicks, keypresses, or assertions
0 commit comments