esplotter/tests-unit-main-infrastructure

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

Skill: Unit Main Infrastructure Tests

Run with: npm run test:unit:main-infrastructure

This skill defines how to test infrastructure implementations in the main process through their public contracts. It standardizes where tests and doubles live, what persistence/migration/notification behavior must be covered, and how to report outcomes so infrastructure reviews stay fast and objective.

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

Scope

Use when

• Updating repository implementations, storage adapters, or infrastructure services under src/app/main/**/infrastructure/**.
• Updating persistence mapping, serialization/deserialization, defaults, and backward-compatibility rules.
• Updating migration behavior (schema/version evolution, fallback handling).
• Updating observer/event notification behavior emitted by infrastructure adapters.
• Fixing infrastructure bugs in persistence, migration, or adapter contracts (must add failing-first regression test).

Do NOT use when

• Use-case or domain-service orchestration changes -> use tests-unit-main.
• Preload bridge/API changes -> use tests-unit-preload.
• Renderer pure logic changes -> use tests-unit-renderer.
• Renderer UI/render-lifecycle behavior changes -> use tests-components.
• End-to-end flows across the running app are required -> use tests-e2e.

Mandatory rules (non-negotiable)

• Infrastructure specs must instantiate real adapter/repository/service implementations.
• Mock or isolate only external boundaries (filesystem location, env, process-level resources, platform APIs).
• Do not mock adapter internals.
• Assert only public contract behavior (read/write/query, migration effects, emitted notifications, error propagation).
• Do not modify production code only to make tests pass.
• Minimum coverage for each affected infrastructure implementation:
  1. happy path persistence/retrieval behavior
  2. failure propagation or fallback handling path
• If migrations/defaults/version branches exist, add at least one test per observable decision path.
• If adapter supports observers/events, assert:
  • callback registration through public API
  • callback payload contract
  • unsubscribe/cleanup behavior when supported
• Keep tests deterministic: isolated temp resources, explicit setup/teardown, no shared mutable cross-test state.
• Test naming must follow should ... format.

File layout (must follow)

• Base path:
  • src/test/main/<module>/infrastructure/
• Infrastructure implementation specs:
  • src/test/main/<module>/infrastructure/<type>/<AdapterOrRepository>.spec.ts
  • Typical <type> folders: repositories, services, adapters
• Reusable infra doubles for external boundaries (when needed):
  • src/test/main/<module>/infrastructure/<type>/<CollaboratorName>Mock.ts
• Domain-contract Object Mothers for infrastructure inputs/outputs:
  • Prefer existing Mothers under domain/shared test trees (for example src/test/main/<module>/domain/**/<Class>Mother.ts or src/test/shared/**/<Class>Mother.ts).
  • Create new Mothers only when the contract is not already represented.

Collaborator doubles: required conventions

• Use doubles only for external dependencies, not for the adapter under test.
• One reusable mock class/object per file.
• File name must follow <CollaboratorName>Mock.ts.
• Reuse existing mocks first; extend behavior instead of creating duplicates.
• Expose explicit controls:
  • setup: set* / given*
  • failure: fail* / willFailWith*
  • assertions: expect* with descriptive failures

Object Mother conventions for infrastructure tests

• Prefer Object Mothers that satisfy domain contracts used by the adapter/repository/service.
• Keep Mothers deterministic by default and override only the fields required by each scenario.
• Add explicit Mother helpers for migration boundaries (older schema, missing fields, incompatible values).
• Reuse existing shared/domain Mothers before creating infrastructure-specific data builders.
• Use random values only when those values are not asserted directly.

Anti-patterns (blocker)

• Replacing real adapter behavior with heavy internal mocks.
• Asserting private fields/methods instead of public adapter contract.
• Skipping migration/default/fallback paths when adapter supports them.
• Sharing mutable storage resources across tests without cleanup.
• Treating infrastructure tests as use-case orchestration tests.
• Test names that do not follow should ... convention.

Definition of done

• Tests are created or updated for every affected infrastructure implementation.
• Persistence happy path and relevant failure/fallback paths are covered.
• Migration/default/version behavior is covered when supported.
• Notification/observer contracts are covered when supported.
• npm run test:unit:main-infrastructure passes.

Execution protocol (follow in order)

1. Identify impacted infrastructure boundary:
   • Which <module> and which repository/service/adapter 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:
   • Validate public persistence/query contract first
   • Add migration/default/failure/notification cases as required
4. Add or extend external-boundary doubles only when needed:
   • keep adapter under test real
5. Run tests:
   • npm run test:unit:main-infrastructure
6. 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:main-infrastructure 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