backend-testing

name	backend-testing
description	Turn backend test ambiguity into one practical test packet — API/service/repo/auth coverage, fixture & seed/reset strategy, mock-vs-container choices, contract checks, and flaky-suite stabilization across local and CI.

Backend Testing

Instructions

Step 1: Classify the request into one packet

Choose the single best entry packet before giving advice.

Packets

• coverage-plan — which layers to add for a concrete backend change
• fixture-and-reset-plan — how to seed, isolate, reset, or bootstrap data/auth state
• contract-and-api-checks — how to protect response/event/schema compatibility once the interface already exists
• flake-stabilization — how to stabilize CI-only or intermittent backend failures
• execution-lane-split — how to divide local-fast, PR, nightly, and release-only backend checks

If the request mixes several concerns, name the primary packet and one secondary concern.

Step 2: Frame the backend surface and risk

Capture the smallest useful context:

• surface: endpoint, service, repository, worker, queue consumer, auth flow, integration, or migration
• highest-risk behaviors: validation, permissions, persistence, retries, idempotency, ordering, serialization, side effects, compatibility
• existing coverage already present
• external dependencies involved: DB, cache, queue, email, payment, third-party API, identity provider, filesystem
• runtime/language stack
• where the evidence must hold: local loop, PR CI, scheduled CI, release smoke

If the request is vague, choose the smallest regression slice worth protecting first.

Step 3: Choose the right test layers

Use the packet and risk to select the lightest credible layer mix.

Unit / service

Prefer when the main risk is branching logic, validation, orchestration, or pure-ish business rules.

Integration

Prefer when database behavior, framework wiring, middleware, transactions, queues, caches, or serialization matter.

Contract / API

Prefer when clients depend on response shapes, status codes, schemas, or events and the interface already exists.

Smoke / selective end-to-end

Prefer only when a narrow release-critical journey crosses several backend boundaries and lower layers would miss the core risk.

State what is in scope, what is out of scope, and why.

Step 4: Decide dependency realism on purpose

For each dependency, choose one of:

• mock / stub — expensive, unstable, or irrelevant to the behavior under test
• fake / simulator — behavior matters, but a lightweight substitute is enough
• containerized real dependency — queries, migrations, message semantics, or wire behavior matter enough that drift would hurt
• shared external environment — only when unavoidable; call out the fragility cost explicitly

Good defaults:

• prefer real DB behavior when repository, migration, transaction, or serialization behavior is central
• prefer mocks for outbound third-party APIs unless the integration contract itself is under test
• prefer a narrow containerized slice over a giant all-dependencies-in-PR setup
• do not claim fake and real dependencies are equivalent when production parity is the whole risk

Step 5: Define fixture, data, auth, and environment control

A backend suite becomes untrustworthy when state is vague.

Specify:

• fixture/factory strategy
• seed/reset/rollback plan
• auth/bootstrap helpers for users, roles, tenants, tokens, or sessions
• time/randomness/idempotency control where needed
• isolation rule: per test, per file, per suite, or per environment
• debugging signals to capture when failures happen

If the suite relies on ordering, leftovers, or sleeps, call that fragility out directly.

Step 6: Split the execution lanes

Treat local, PR, and slower lanes as different jobs.

Define:

• local-fast path — what developers should run repeatedly
• PR path — what must gate merges
• scheduled / nightly path — heavier breadth or expensive realism
• release / incident path — narrow confidence checks or regression ratchets when needed

If the suite is slow, split it. Do not pretend one giant authoritative path is practical everywhere.

Step 7: Produce one backend test packet

Return one concise packet, not a general essay.

Recommended packet shapes:

• coverage-plan → coverage table + dependency strategy + exclusions
• fixture-and-reset-plan → fixture/reset memo + auth/bootstrap notes
• contract-and-api-checks → compatibility packet + consumer/provider scope + route-outs
• flake-stabilization → flake memo with likely causes, isolation fixes, readiness checks, and debug signals
• execution-lane-split → lane matrix with local/PR/scheduled/release responsibilities

Minimum packet contents:

• change surface and primary risk
• chosen packet and any secondary concern
• selected layers and why
• dependency realism decisions
• fixture/data/auth/environment control
• execution-lane split
• explicit route-outs when the request is partly owned elsewhere

Step 8: Verify scope boundaries before finalizing

Check:

• does the packet protect the real backend regression risk rather than generic coverage vanity?
• did you keep org-wide validation policy in testing-strategies?
• did you route contract shape decisions to api-design while keeping contract protection here only when the interface already exists?
• did you route auth implementation work to authentication-setup?
• will a maintainer understand why a dependency is mocked, faked, containerized, or real?

Output format

## Backend Test Packet: [Surface or Change]

### Packet choice

- Primary packet: coverage-plan | fixture-and-reset-plan | contract-and-api-checks | flake-stabilization | execution-lane-split
- Secondary concern: optional
- Confidence: high | medium | low

### Change framing

- Surface: ...
- Main risks: ...
- Runtime: ...
- Existing coverage: ...

### Layer decisions

| Layer                 | In scope? | What it protects | Notes |
| --------------------- | --------- | ---------------- | ----- |
| Unit / service        | yes/no    | ...              | ...   |
| Integration           | yes/no    | ...              | ...   |
| Contract / API        | yes/no    | ...              | ...   |
| Smoke / selective E2E | yes/no    | ...              | ...   |

### Dependency realism

| Dependency               | Strategy | Why |
| ------------------------ | -------- | --- |
| Database / queue / cache | ...      | ... |
| External API             | ...      | ... |
| Auth provider            | ...      | ... |

### Data and environment control

- Fixtures / factories: ...
- Seed / reset: ...
- Auth bootstrap: ...
- Isolation rule: ...
- Debug signals: ...

### Execution lanes

- Local-fast: ...
- PR CI: ...
- Scheduled / nightly: ...
- Release / incident: ...

### Route-outs

- `testing-strategies`: ...
- `api-design`: ...
- `authentication-setup`: ...

Examples

Example 1: auth-heavy API change

Input: “We added refresh-token rotation and new admin-only endpoints to our Express API. I need backend tests that catch auth failures, token replay issues, and DB persistence bugs without turning CI into a giant end-to-end suite.”

Good response shape:

• chooses coverage-plan as the primary packet
• combines unit/service plus integration/API coverage instead of one giant E2E suite
• keeps real DB or containerized persistence where token/session behavior matters
• defines auth bootstrap helpers and reset strategy
• limits smoke coverage to a narrow release-critical path

Example 2: CI-only flake in a service suite

Input: “Our FastAPI tests pass locally but fail in CI around seeded Postgres state and background jobs. Give me a stabilization plan.”

Good response shape:

• chooses flake-stabilization as the primary packet
• identifies seed/reset drift, readiness, async timing, or leftover state as likely causes
• recommends stronger isolation, readiness checks, and debugging signals instead of just retries
• separates local-fast and CI-authoritative behavior clearly

Example 3: contract protection after an API already exists

Input: “Our payment service and webhook consumers keep drifting on response fields. I do not need API redesign, I need backend tests that catch compatibility regressions.”

Good response shape:

• chooses contract-and-api-checks as the primary packet
• keeps contract protection here because the interface already exists
• routes any schema redesign or versioning debate to api-design
• recommends consumer/provider or schema-compatibility coverage rather than broader smoke inflation

Example 4: too-broad policy request

Input: “Design our overall engineering org testing strategy for frontend, backend, mobile, and QA.”

Good response shape:

• recognizes that the primary task belongs to testing-strategies
• keeps any backend-specific advice scoped as a handoff only
• refuses to turn backend-testing into a universal QA-governance skill