Behavioral testing

Purpose

Protect the changed contract with tests that would catch an incorrect implementation, not tests that merely mirror it.

When to use

Behavior changes, regression fixes, and unit/integration/API test authoring. Project test conventions override these defaults.

Preconditions

Read project instructions, package scripts, CI configuration, nearby tests and the implementation's callers. Identify the runner and target environment; do not install a second framework by default.

Workflow

1. Write a small case list: trigger, expected observable result, relevant failure/boundary, and suitable layer.
2. Unit: isolate business decisions and transformations. Integration: prove component/persistence boundaries. API: exercise the actual HTTP route, validation, authentication, authorization and response contract. E2E: reserve for essential user journeys; use the E2E skill.
3. For a bug, write a regression that fails on the original behavior for the expected reason. For new behavior, make a focused failing test when the existing harness supports it. Implement the smallest change and observe the test pass; do not report red/green evidence you did not run.
4. Use explicit arrange/act/assert, independent cases and deterministic clocks/randomness where relevant. Mock external boundaries, not the decision under test. Assert outcomes rather than private call order.
5. API case selection: valid request; invalid body/query/params; unauthenticated and forbidden role/ownership; not found; conflict; pagination limits; relevant side effects and rollback. Select cases affected by the endpoint, not an exhaustive template for every change.
6. Use isolated local/test storage and disposable fixtures. Verify persistence through an independent read when that is the contract. Clean up only owned data, including after failure.
7. Run the changed cases and applicable existing quality checks, then affected callers if a shared contract changed. If no harness exists, choose a compatible minimal setup within scope or document the blocker and concrete cases left unverified.

Rules

• One case proves one outcome; several assertions may establish that outcome.
• A route unit test with mocked guards is not evidence that HTTP authentication works.
• Do not add trivial implementation-mirroring tests or demand 100% coverage. Prioritize business risk and regressions.
• Snapshot updates require inspected, intentional changes. Test failures use test-failure-triage.

Common mistakes

Mocking everything; testing only the happy path; shared mutable fixtures; asserting a status without payload/side effects; treating skipped tests as passed.

Validation

Record the command and actual result. Confirm the regression detects the original defect when feasible, tests are independent, and no test touched shared or production data. State missing coverage explicitly.