esplotter/tests-e2e

<!-- AUTO-GENERATED FILE. DO NOT EDIT DIRECTLY. Edit files under IA/ and run `bash IA/sync-ai-files.sh` to regenerate. -->

Skill: E2E Tests

Run with: npm run test:e2e

Use packaged parity mode with: npm run test:e2e:compiled

This skill defines how to validate full Electron user flows across renderer, preload, and main integration boundaries. It standardizes where E2E specs and Test Objects live, what flow coverage is required, how to keep scenarios deterministic, and how to report outcomes so E2E reviews stay fast and objective.

Canonical policy source: docs/testing/tests.md. Local layout/context source: docs/testing/tests.md.

Scope

Use when

• Validating user flows that cross process/runtime boundaries (UI + preload + IPC + main side effects).
• Validating behavior involving menus, dialogs, shortcuts, persistence, clipboard, and asynchronous event chains.
• Verifying regressions that only reproduce in running-app conditions.
• Verifying packaging/runtime parity (dev vs packaged) for critical flows.

Do NOT use when

• Main use-case/domain logic can be validated without app runtime -> use tests-unit-main.
• Main infrastructure adapter behavior can be validated in isolation -> use tests-unit-main-infrastructure.
• Preload exposure/delegation contracts can be validated without app runtime -> use tests-unit-preload.
• Renderer pure logic can be validated without rendering -> use tests-unit-renderer.
• Renderer UI behavior can be validated without full Electron runtime -> use tests-components.

Mandatory rules (non-negotiable)

• Cover user-visible/public behavior only; do not assert private implementation details.
• Build scenarios with reusable Test Objects in e2e/support (Page Object pattern).
• Prefer interactions/selectors by role, label, and accessible names.
• Use data-testid only when no stable accessible selector exists.
• Keep tests deterministic:
  • isolated app state per test run
  • explicit setup/teardown
  • stable waits/assertions (expect.poll, event promises, explicit visibility checks)
• Do not use arbitrary sleeps as primary synchronization strategy.
• Do not modify production code only to make tests pass.
• Minimum coverage for each affected E2E flow:
  1. happy path
  2. failure or blocked-path behavior (when applicable)
• Bug fixes must add a failing-first regression E2E scenario.
• Test naming should follow behavior wording (should ...) whenever possible and remain user-intent focused.

File layout (must follow)

• E2E specs:
  • e2e/<feature-flow>.spec.ts
• Reusable Test Objects/helpers:
  • e2e/support/<Subject>TestObject.ts
  • Keep each file focused on one subject boundary (for example MainPage, Menu, Sidebar, Chart, Preferences, Clipboard, ElectronApp).
• Environment/bootstrap helpers:
  • e2e/support/setupE2eTestEnvironment.ts

Test Object conventions

• Keep E2E specs intent-driven; move mechanics into Test Objects.
• Expose high-level methods that represent user actions and user-observable assertions.
• Reuse existing support objects before creating new ones.
• Add new support objects only when multiple specs share the same behavior boundary.
• Avoid duplicating selector logic across specs.

Execution modes

• Development runtime mode:
  • command: npm run test:e2e
  • uses Playwright config with renderer dev server
• Packaged runtime parity mode:
  • command: npm run test:e2e:compiled
  • uses packaged app flow for release-like validation
• Prefer running both modes when a change affects menus, preload/IPC wiring, startup/packaging, or OS integrations.

Anti-patterns (blocker)

• Asserting private/internal implementation details.
• Packing complex selector logic directly into specs instead of support Test Objects.
• Using fixed sleeps as the main synchronization mechanism.
• Reusing mutable app state across tests without isolation.
• Over-scoping one spec to validate many unrelated flows.
• E2E-only coverage for behavior already sufficiently covered in lower suites.

Definition of done

• Affected user flows have E2E coverage through public behavior assertions.
• Happy path and relevant failure/regression paths are covered.
• Specs use reusable Test Objects under e2e/support.
• Required E2E command(s) pass (test:e2e, and test:e2e:compiled when applicable).

Execution protocol (follow in order)

1. Identify impacted flow boundary:
   • Which user flow crosses renderer/preload/main and needs runtime validation?
2. Decide test action:
   • New flow -> add new spec/cases
   • Changed flow -> update existing spec/cases
   • Bug fix -> write failing regression case first
3. Implement with Test Objects:
   • Add/extend methods in e2e/support first when behavior is reused
   • Keep spec steps concise and intent-focused
4. Run tests:
   • npm run test:e2e
   • npm run test:e2e:compiled when parity is required
5. Report:
   • files changed
   • command(s) executed
   • pass/fail + concise error summary
   • next actions if failing

Output contract

Return a structured YAML report including:

• status: ok | needs_clarification | error
• summary: what was tested/changed in one paragraph
• files_changed: list of changed paths
• tests_added_or_updated: list of e2e spec files added/updated
• support_added_or_updated: list of e2e/support files added/updated
• commands_run: commands executed (test:e2e and test:e2e:compiled when applicable)
• result:
  • passed: boolean
  • failed_tests: list
  • error_excerpt: short excerpt when failing
• questions: open questions with reason when clarification is needed
• next_actions: recommended follow-up actions
• warnings: risks, assumptions, or deviations