esplotter/tests-unit-main

Skill: Unit Main Tests

Run with: npm run test:unit:main

This skill defines how to test main-process business behavior with consistent structure and contracts. It standardizes where tests and mocks live, what minimum flows must be covered, how to model fixtures with Mothers, and how to report results so reviews stay fast and objective.

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

Scope

Use when

• Adding/modifying main-process business logic (use cases, domain services, validations).
• Fixing a bug in main-process logic (must add regression test first).
• Changing orchestration contracts affecting logic (IPC handler wiring to use cases, menu-triggered execution).

Do NOT use when

• Renderer DOM/UI behavior → use tests-components.
• Frontend utils logic -> use tests-unit-renderer.
• Preload changes -> use tests-unit-preload.
• Main infrastructure adapter behavior (persistence/migrations/notifications) -> use tests-unit-main-infrastructure.
• End-to-end flows across the running app → use tests-e2e.

Mandatory rules (non-negotiable)

• Primary unit-test entrypoint: use cases.
• Domain services are collaborators in use-case tests (mock them).
• Domain services have their own unit specs (mock their collaborators).
• Do not modify production code only to make tests easier.
• Minimum coverage for each tested unit:
  1. happy path
  2. collaborator error propagation
• If the unit has branching/validation/defaults/boundaries, add at least one extra test covering each decision path observable.
• For delegator use cases (thin orchestration), assert at minimum:
  • collaborator method called exactly once
  • collaborator called with expected args
• Use Object Mothers for relevant input data fixtures. If an input should be a Value Object, use a VO Mother.
• Prefer module-local Mothers; shared Mothers are allowed when the same fixture contract is reused across multiple modules.
• Use meaningful random data in Mothers (for example, faker names/emails/paths that match field semantics). Prefer deterministic pseudo-realistic values; random only when not asserted.
• Assertions focus on public contract: run() input/output + collaborator effects. No private internals.
• Test naming must follow should ... format.

File layout (must follow)

• Mirror src/app/main module structure under src/test/main.
• Organize by feature/module first (for example src/test/main/channel-file/...) as defined in docs/testing/tests.md.
• Use-case specs:
  • src/test/main/<module>/application/<UseCase>.spec.ts
• Domain-service specs:
  • src/test/main/<module>/domain/services/<Service>.spec.ts
• Domain-service collaborator mocks:
  • src/test/main/<module>/domain/services/<CollaboratorName>Mock.ts
• Use-case infrastructure collaborator mocks:
  • src/test/main/<module>/infrastructure/<type>/<CollaboratorName>Mock.ts
• Object Mothers:
  • src/test/main/<module>/domain/{primitives|entities|vos|aggregates|dtos}/<Class>Mother.ts
  • or shared when reused cross-module: src/test/shared/**/<Class>Mother.ts

Collaborator mocks: required conventions

• One mock class per file.
• File name must follow <CollaboratorName>Mock.ts.
• Use typed subfolders for infrastructure mocks (for example repositories, services) instead of flat folders.
• Keep use-case infrastructure mocks under src/test/main/<module>/infrastructure/<type>/.
• Use flat folders for domain-service collaborator mocks under src/test/main/<module>/domain/services/.
• Reuse existing module mocks by default. If a new test needs additional behavior/assertions, extend the existing mock instead of creating a parallel duplicate.
• Provide explicit controls:
  • setup: set* / given*
  • failure: fail* / willFailWith*
  • assertions: expect* (must throw with helpful message)
  • optional: capture args for expectCalledWith(...)

Object Mother conventions

• Keep one Mother per domain class/primitive intent.
• Provide with(overrides) as the primary entrypoint.
• Use random data only when it improves realism and still matches field semantics.
• Add explicit edge-case helpers for boundary scenarios (for example, invalid/unsupported variants).
• Use shared Mothers only for truly cross-module fixtures to avoid leaking module-specific semantics.

Anti-patterns (blocker)

• Inline reusable mock classes inside *.spec.ts.
• Direct unit tests for entities/value objects/aggregates in this suite.
• Asserting private/internal state or private methods.
• Skipping edge/boundary cases when behavior depends on inputs range, ordering, or branching.
• Using random fixture data that does not match the field semantics.
• Creating duplicate mocks for the same collaborator in the same module instead of extending the shared mock.
• Test names that do not follow should ... convention.

Definition of done

• Tests are created or updated for every affected use case and domain service.
• Happy path and collaborator error propagation are covered for each tested unit.
• For delegators, call-count and call-args assertions are present.
• Collaborator contracts are asserted through dedicated mocks.
• Required fixtures are created through Object Mothers (including VO Mothers for input value objects).
• npm run test:unit:main passes.

Execution protocol (follow in order)

1. Identify impacted unit(s):
   • Which <module>?
   • Which use case(s) and/or domain services changed?
2. Decide test action:
   • New behavior → create new specs or new tests cases
   • Changed behavior → update existing specs
   • Bug fix → write failing regression tests first
3. Create/Update tests:
   • Use-case spec first; mock collaborators as needed.
   • Add domain-service spec only if domain logic exists outside use-case orchestration.
4. Create/Update collaborator mocks:
   • Only if collaborator is reused or needs dedicated contract assertions.
5. Run tests:
   • npm run test:unit:main
6. Report:
   • What files changed
   • What command ran
   • Pass/fail + 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 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