diff options
Diffstat (limited to 'packages/app/e2e/AGENTS.md')
| -rw-r--r-- | packages/app/e2e/AGENTS.md | 10 |
1 files changed, 10 insertions, 0 deletions
diff --git a/packages/app/e2e/AGENTS.md b/packages/app/e2e/AGENTS.md index 4b62634f0..f263e49a0 100644 --- a/packages/app/e2e/AGENTS.md +++ b/packages/app/e2e/AGENTS.md @@ -174,6 +174,8 @@ await page.keyboard.press(`${modKey}+Comma`) // Open settings - In terminal tests, type through the browser. Do not write to the PTY through the SDK. - Use `waitTerminalReady(page, { term? })` and `runTerminal(page, { cmd, token, term?, timeout? })` from `actions.ts`. - These helpers use the fixture-enabled test-only terminal driver and wait for output after the terminal writer settles. +- After opening the terminal, use `waitTerminalFocusIdle(...)` before the next keyboard action when prompt focus or keyboard routing matters. +- This avoids racing terminal mount, focus handoff, and prompt readiness when the next step types or sends shortcuts. - Avoid `waitForTimeout` and custom DOM or `data-*` readiness checks. ### Wait on state @@ -182,6 +184,9 @@ await page.keyboard.press(`${modKey}+Comma`) // Open settings - Avoid race-prone flows that assume work is finished after an action - Wait or poll on observable state with `expect(...)`, `expect.poll(...)`, or existing helpers - Prefer locator assertions like `toBeVisible()`, `toHaveCount(0)`, and `toHaveAttribute(...)` for normal UI state, and reserve `expect.poll(...)` for probe, mock, or backend state +- Prefer semantic app state over transient DOM visibility when behavior depends on active selection, focus ownership, or async retry loops +- Do not treat a visible element as proof that the app will route the next action to it +- When fixing a flake, validate with `--repeat-each` and multiple workers when practical ### Add hooks @@ -189,11 +194,16 @@ await page.keyboard.press(`${modKey}+Comma`) // Open settings - Keep these hooks minimal and purpose-built, following the style of `packages/app/src/testing/terminal.ts` - Test-only hooks must be inert unless explicitly enabled; do not add normal-runtime listeners, reactive subscriptions, or per-update allocations for e2e ceremony - When mocking routes or APIs, expose explicit mock state and wait on that before asserting post-action UI +- Add minimal test-only probes for semantic state like the active list item or selected command when DOM intermediates are unstable +- Prefer probing committed app state over asserting on transient highlight, visibility, or animation states ### Prefer helpers - Prefer fluent helpers and drivers when they make intent obvious and reduce locator-heavy noise - Use direct locators when the interaction is simple and a helper would not add clarity +- Prefer helpers that both perform an action and verify the app consumed it +- Avoid composing helpers redundantly when one already includes the other or already waits for the resulting state +- If a helper already covers the required wait or verification, use it directly instead of layering extra clicks, keypresses, or assertions ## Writing New Tests |