esplotter/tests-components

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

Skill: Component Tests

Run with: npm run test:components

This skill defines how to validate renderer UI behavior from the user perspective using Testing Library. It standardizes where specs live, what behaviors must be covered, how to model interactions, and how to report outcomes so component reviews remain fast and objective.

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

Scope

Use when

• Updating renderer components with visible behavior (conditional rendering, validation feedback, disabled states, loading/error states).
• Updating interactions (click, keyboard, form input, selection, focus management, menu actions).
• Updating React hooks that require render lifecycle, context, effects, or provider wiring (renderHook(...)).
• Validating integration between nearby renderer pieces that still fits test runtime (component + store/hook wiring).

Do NOT use when

• Behavior is pure logic without rendering assertions -> use tests-unit-renderer.
• Preload bridge contracts or exposed preload APIs change -> use tests-unit-preload.
• Main-process application/domain/infrastructure behavior changes -> use tests-unit-main or tests-unit-main-infrastructure.
• End-to-end user flow across app windows/dialogs/persistence is required -> use tests-e2e.

Mandatory rules (non-negotiable)

• Assert public UI contract only: what a user can see, read, focus, or trigger.
• Prefer Testing Library queries in this order: getByRole/findByRole -> getByLabelText -> getByText.
• Avoid implementation-detail assertions (internal state vars, private functions, component instance details).
• Avoid brittle selectors; use data-testid only when no accessible selector is reliable.
• Use userEvent for meaningful interactions instead of directly calling handlers.
• For async UI behavior, use findBy*/waitFor and assert final user-visible state.
• Keep setup deterministic (fixtures, mocked timers/network, stable store initialization).
• Do not modify production code only to make tests pass.
• Bug fixes must add a failing-first regression test in the affected component/hook spec.
• Test naming must follow should ... format.
• Prefer suite-level Vitest environment configuration (environment: 'jsdom').

File layout (must follow)

• Add component tests under renderer test tree:
  • src/test/renderer/<feature>/components/<ComponentGroup>/<Component>.spec.tsx
• Hook specs that require React lifecycle:
  • src/test/renderer/<feature>/hooks/<Hook>.spec.ts

Test design conventions

• Cover at minimum for each affected component/hook:
  1. happy path render/interaction
  2. error/failure or blocked state path (when applicable)
• If behavior has branching/defaults/boundaries, add at least one test per observable decision path.
• For components using stores/providers, initialize test state explicitly and reset between tests.
• For events with side effects (callbacks, store actions, bridge calls), assert both:
  • user-visible outcome
  • collaborator contract (called count + expected args) when relevant

Anti-patterns (blocker)

• Asserting private/internal implementation details.
• Snapshot-only coverage without behavior assertions.
• Excessive mocking that removes real component behavior under test.
• Reusing mutable global state across tests without reset.
• Using component tests for logic that is fully pure and belongs to tests-unit-renderer.
• Test names that do not follow should ... convention.

Definition of done

• All affected component/hook behavior has user-visible coverage.
• Happy path and failure/edge behavior are covered where applicable.
• Regression test exists for bug fixes.
• Specs are located under src/test/renderer/.
• npm run test:components passes.

Execution protocol (follow in order)

1. Identify impacted UI units:
   • Which components/hooks and which user-visible contracts changed?
2. Decide test action:
   • New behavior -> add new specs/cases
   • Changed behavior -> update existing specs
   • Bug fix -> write failing regression test first
3. Implement tests:
   • Model user interactions and visible outcomes first
   • Add collaborator assertions only when behavior depends on them
4. Run tests:
   • npm run test:components
5. Report:
   • files changed
   • command 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 test files added/updated
• mocks_added_or_updated: list of mock files added/updated
• commands_run: commands executed (at minimum npm run test:components 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