ahtishamshahzad/agent_dev_flow/backend-unit-testing

Backend Unit Testing

Purpose

Test business logic in isolation: services, domain rules, mappers, policy functions — fast, deterministic, and independent of HTTP, databases, and providers. What crosses process boundaries is backend-integration-testing's job.

When to Use

• For logic-bearing units: services, calculators, policies (backend-authorization decisions as functions), validators' custom rules, error mapping.
• Not for route wiring, real queries, or provider calls — integration territory.

Inputs

• Testing strategy (../../testing-strategy) and the layer map (backend-api-architecture — services are the prime target).
• Framework/test-runner conventions already in the repo.

Discovery Questions

• Which modules hold real logic (vs pass-through plumbing not worth unit tests)?
• Are services injectable/constructible with test doubles (DI or explicit deps)?
• What time/randomness/ID generation needs controlling for determinism?

Responsibilities

• Target the service layer and pure logic; skip trivial pass-throughs — a unit test of a one-line delegation tests nothing.
• Isolate with focused doubles: stub the data-layer interface and provider interfaces (third-party-integrations isolation pays off here); don't mock what you own trivially — refactor for constructibility instead.
• Cover the paths that matter: happy path, edge cases (bounds, empty, duplicates), and failure paths (dependency throws, policy denies) — error behavior is logic.
• Keep tests deterministic: fake clock, seeded/injected IDs, no real network/filesystem/DB, no order dependence.
• Make tests document behavior: names state the rule ("expired token is rejected"), assertions check outcomes, not implementation internals.
• Wire into CI as the fast tier — the suite runs in seconds and gates every change (../../git-workflow hooks).

Required Workflow

1. Identify logic-bearing units from the layer map.
2. Ensure constructibility with test doubles (flag DI problems to the foundation skill).
3. Write tests per unit: happy, edge, failure — regression test for every bug fixed (../../bug-investigation).
4. Verify determinism (repeat runs, no shared state).
5. Keep the suite in the fast CI tier.

Decision Rules

• Mock at boundaries you own as interfaces (repo, provider client), not deep internals — over-mocked tests pin implementation and rot on refactor.
• A test that duplicates the implementation's arithmetic proves nothing; assert known input→output pairs.
• Coverage % is a smell detector, not a target — uncovered logic matters, uncovered plumbing doesn't.
• Authorization policies get unit tests per rule here and endpoint-level negative tests in integration — both, not either.

Rules

• No network, no real DB, no real clock in unit tests.
• One behavior per test; failures must point at the rule that broke.
• Bug fixes land with the failing-then-passing test.

Anti-Patterns

• Unit-testing controllers by mocking the entire framework.
• Mock setups longer than the logic under test.
• Asserting internal call sequences instead of outcomes.
• Snapshot tests as a substitute for behavioral assertions.
• Skipping failure-path tests ("it usually works").

Validation Checklist

• [ ] Logic-bearing units identified; plumbing consciously skipped.
• [ ] Doubles at owned boundaries only.
• [ ] Happy + edge + failure paths covered.
• [ ] Deterministic (clock/ID/network controlled).
• [ ] Suite fast, in CI, gating changes.

Definition of Done

A fast, deterministic unit suite covering the service layer's real logic — edges and failures included — isolated at owned boundaries, gating changes in CI.

Related Skills

../../testing-strategy, backend-integration-testing, backend-api-architecture, backend-authorization (policy rules), ../../bug-investigation, ../../code-review.

Related Knowledge

../../../knowledge/ (domain rules worth encoding as tests).

Related References

../../../references/backend/testing/ (conventions, when populated).

Context Loading Guidance

• Requires: layer map, the unit under test + its interface deps.
• Does not require: route definitions, migrations, provider docs.
• May load: backend-integration-testing (boundary split), ../../testing-strategy.
• Stop when: the unit-test plan (or the tests) for the target module is done.

Token Efficiency Guidance

Read the unit and its interfaces, not the whole app. Table of case → expected outcome per unit beats prose test plans.