esplotter/tests-unit-renderer

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

Skill: Unit Renderer Tests

Run with: npm run test:unit:renderer

This skill defines how to test renderer business/presentation logic that is pure from the UI rendering layer. It standardizes where tests live, what minimum behavior must be covered, how to isolate runtime collaborators, and how to report outcomes so 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 pure logic (mappers, formatters, parsers, guards, selectors, derived state helpers).
• Updating Zustand store behavior (actions, transitions, selectors, invariants, cross-store orchestration).
• Fixing a renderer logic bug that can be validated without DOM rendering assertions.

Do NOT use when

• UI rendering, user interaction, accessibility, or visible output assertions are required -> use tests-components.
• React hook lifecycle/context behavior requires renderHook(...) or component mounting -> use tests-components.
• Preload bridge contracts or exposed preload API behavior changes -> use tests-unit-preload.
• Main-process application/domain/infrastructure behavior changes -> use tests-unit-main or tests-unit-main-infrastructure.
• End-to-end flows across the running app are needed -> use tests-e2e.

Mandatory rules (non-negotiable)

• Assert only public contracts: function input/output, selector result, store state/effects via exposed APIs.
• Keep tests deterministic: fixed fixtures, controlled clocks/randomness, explicit setup for external collaborators.
• Do not use render(...), renderHook(...), DOM queries, or interaction events in this suite.
• Do not assert private/internal implementation details.
• Do not modify production code only to make tests pass.
• Minimum coverage for each tested unit:
  1. happy path
  2. error propagation or failure handling (when applicable)
• If branching/validation/defaults/boundaries exist, add at least one test per observable decision path.
• For store actions that delegate to collaborators (for example preload/window APIs), assert at minimum:
  • collaborator called exactly once
  • collaborator called with expected args
  • state remains consistent on collaborator failure
• Reset/rehydrate store state between tests to avoid leakage.
• Test naming must follow should ... format.

File layout (must follow)

• Base path: src/test/renderer/<feature>/
• Pure logic specs:
  • src/test/renderer/<feature>/<Unit>.spec.ts
• Store specs:
  • src/test/renderer/<feature>/store/<StoreName>.spec.ts
• Cross-store or renderer-logic flow specs (still no DOM/render assertions):
  • src/test/renderer/<feature>/<Flow>.spec.ts
  • Prefer assigning the flow to the owning feature instead of using a generic integration/ folder.
• Test doubles/mocks for renderer collaborators (when reused):
  • src/test/renderer/<feature>/mocks/<CollaboratorName>Mock.ts
• Shared deterministic fixtures/builders:
  • src/test/renderer/shared/<FixtureName>Fixture.ts

Collaborator doubles: required conventions

• One reusable mock class/object factory per file.
• File name must follow <CollaboratorName>Mock.ts.
• Reuse existing mocks first; extend behavior instead of duplicating mocks.
• Expose explicit controls:
  • setup: set* / given*
  • failure: fail* / willFailWith*
  • assertions: expect* (must throw with helpful messages)

Fixture conventions

• Keep fixtures semantic and deterministic by default.
• Prefer explicit builders/fixtures over ad-hoc inline object noise when shape is non-trivial.
• Provide edge-case helpers for boundary inputs (empty values, malformed ids, duplicates, ordering cases).
• Random values are allowed only when not asserted and when realism adds value.

Anti-patterns (blocker)

• Using render(...), renderHook(...), or DOM assertions in this suite.
• Testing hook lifecycle/context behavior in unit renderer specs.
• Asserting private functions/private state that are not part of public contract.
• Reusing mutable global/store state across tests without reset.
• Relying on implicit timer/random/Date behavior without control.
• Duplicate mock implementations for the same collaborator in the same boundary.
• Test names that do not follow should ... convention.

Definition of done

• All impacted renderer units/stores have updated coverage.
• Happy path and failure behavior are covered for each tested unit where applicable.
• Branching/default/boundary behavior has explicit tests.
• No DOM/render/hook-lifecycle assertions are present.
• npm run test:unit:renderer passes.

Execution protocol (follow in order)

1. Identify impacted unit(s):
   • Which renderer feature/store/selectors changed?
2. Decide test action:
   • New behavior -> add new specs or cases
   • Changed behavior -> update existing specs
   • Bug fix -> write failing regression test first
3. Implement tests:
   • Pure logic/store behavior first
   • Add collaborator doubles only when needed for clear contract assertions
4. Run tests:
   • npm run test:unit:renderer
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:unit:renderer 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