esplotter/tests-unit-preload

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

Skill: Unit Preload Tests

Run with: npm run test:unit:preload

This skill defines how to test preload bridge contracts that connect renderer and IPC. It standardizes where tests live, what contract behavior must be covered, how to isolate Electron runtime dependencies, and how to report outcomes so reviews stay fast and objective.

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

Scope

Use when

• Updating preload exposures registered through contextBridgeExposeInMainWorld(...).
• Updating preload wrappers around ipcRendererInvoke(...) and ipcRendererOn(...).
• Updating IPC event/channel mapping used by renderer-facing preload API.
• Fixing preload bridge bugs (must add failing-first regression test).

Do NOT use when

• Main-process application/domain logic changes -> use tests-unit-main.
• Main infrastructure adapter behavior changes -> use tests-unit-main-infrastructure.
• Renderer pure logic changes without preload boundary concerns -> use tests-unit-renderer.
• Renderer UI/render lifecycle behavior changes -> use tests-components.
• Full user flows across app runtime are required -> use tests-e2e.

Mandatory rules (non-negotiable)

• Assert preload public contract from renderer perspective (exposed namespace, method names, call signature effects).
• Keep tests runtime-isolated: mock preload IPC wrappers and context-bridge adapter dependencies.
• Do not use DOM rendering assertions (render(...), renderHook(...), DOM queries, interaction events) in this suite.
• Do not assert private/internal implementation details.
• Do not modify production code only to make tests pass.
• Specs must be named *.preload.spec.ts.
• Minimum coverage for each affected preload surface:
  1. happy path contract (exposed API + delegated call)
  2. failure propagation path (reject/throw passthrough when applicable)
• For delegator methods (most preload wrappers), assert at minimum:
  • collaborator called exactly once
  • collaborator called with expected channel and args
  • return value or promise behavior is passed through unchanged
• For event subscriptions, assert at minimum:
  • expected IPC event name is used
  • listener identity is forwarded
  • unsubscribe function contract is preserved
• Test naming must follow should ... format.

File layout (must follow)

• Base path: src/test/preload/
• Contract specs (split by namespace):
  • src/test/preload/preload.<namespace>.preload.spec.ts
  • Use exactly one spec file per exposed preload namespace (versions, files, userPreferences, clipboard).
  • Keep namespace-specific assertions in its corresponding file; avoid monolithic preload.preload.spec.ts files.
• Reusable preload collaborator mocks (when needed in more than one spec):
  • src/test/preload/mocks/<CollaboratorName>Mock.ts
• Shared deterministic preload fixtures/builders:
  • src/test/preload/shared/<FixtureName>Fixture.ts

Collaborator doubles: required conventions

• Prefer mocking preload adapters (contextBridgeExposeInMainWorld, ipcRendererInvoke, ipcRendererOn) over Electron internals directly.
• Reuse existing mocks first; extend behavior instead of duplicating.
• If reusable mock files are created, follow <CollaboratorName>Mock.ts naming.
• Expose explicit controls:
  • setup: set* / given*
  • failure: fail* / willFailWith*
  • assertions: expect* (throwing descriptive errors)

Fixture conventions

• Keep fixtures deterministic and semantically valid for IPC payloads.
• Prefer explicit fixture helpers over noisy inline objects when payload shape is non-trivial.
• Add edge-case fixtures for empty/invalid payloads and boundary arguments where applicable.

Anti-patterns (blocker)

• DOM/render assertions in preload suite.
• Asserting private module internals instead of contract behavior.
• Hard-coding brittle assertion order when API contract does not require it.
• Reusing mutable test state across specs without reset (vi.resetModules, mock resets, shared maps cleanup).
• Test names that do not follow should ... convention.

Definition of done

• All affected preload exposures/wrappers have updated contract coverage.
• Happy path and failure propagation are covered where applicable.
• Event subscription contracts include event key, listener forwarding, and unsubscribe behavior.
• Specs follow *.preload.spec.ts naming under src/test/preload/.
• npm run test:unit:preload passes.

Execution protocol (follow in order)

1. Identify impacted preload boundary:
   • Which exposed namespace/method/event mapping changed?
2. Decide test action:
   • New contract -> add new specs/cases
   • Changed contract -> update existing specs
   • Bug fix -> write failing regression test first
3. Implement tests:
   • Assert exposure shape and delegation contracts first
   • Add failure-propagation and unsubscribe assertions as needed
4. Run tests:
   • npm run test:unit:preload
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:preload 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