ahtishamshahzad/agent_dev_flow/backend-integration-testing

Backend Integration Testing

Purpose

Prove the assembled backend works: routes through middleware, validation, authorization, services, and a real database — exercised over HTTP the way clients will call it. This is where authorization and validation guarantees get verified, not just designed.

When to Use

• For endpoint behavior, auth/authz enforcement, DB-touching flows, webhook intake, job execution.
• Not for pure logic (backend-unit-testing) or full multi-app E2E (client packs / ../../testing-strategy).

Inputs

• Endpoint design + auth matrix (rest-api-design, backend-authorization).
• Schema/migrations (../../database/database-migrations), seed strategy (../../database/seed-data).

Discovery Questions

• How does a test get a real database — containerized per suite (testcontainers-style), shared with per-test isolation, or transaction-rollback per test?
• How do tests authenticate (helper that mints sessions/tokens per persona: anonymous, user A, user B, admin, other-tenant)?
• Which flows are release-critical and must be covered first?

Responsibilities

• Stand up the app + real database in tests: migrations applied, known seed state, isolation between tests (truncate/transaction/unique-tenant per test) — SQLite-in-place-of-Postgres “convenience” swaps test a different database; don't.
• Fake only true externals: provider clients stubbed at your interface (third-party-integrations); queues either run inline/test-mode or assert enqueue + test workers directly (background-jobs).
• Cover per endpoint: success shape (contract match — api-contracts), validation rejection (malformed/unknown-field/oversize), and the authorization negative suite:
• anonymous → 401 on protected routes;
• User A cannot read/update/delete User B's resource;
• non-admin → admin action rejected;
• client-supplied ownership/tenant IDs ignored (scope stays the session's);
• cross-tenant access rejected with a valid guessed ID.
• Cover auth flows end-to-end: signup/login/refresh/logout, expired/tampered tokens, reset-token single-use (backend-authentication).
• Cover non-HTTP entries: inbound webhooks (bad signature rejected, duplicate deduped — webhooks), job handlers (idempotent re-run — background-jobs).
• Keep the suite honest in CI: hermetic (no shared external state), parallelizable, failures reproducible locally.

Required Workflow

1. Choose the DB provisioning + isolation strategy.
2. Build test helpers: app bootstrap, persona auth, seed factories.
3. Cover release-critical flows first; per endpoint add success + validation + authz-negative cases.
4. Add webhook/job-path tests.
5. Wire into CI as the merge gate; keep runtime bounded (parallel, scoped seeds).

Decision Rules

• Same database engine as production, always.
• The authorization negative suite is mandatory per scoped resource — a missing cross-user test is a missing control.
• Assert response contracts (status + shape), not implementation artifacts.
• Flaky integration tests get fixed or quarantined same-day; a red-noise suite gates nothing.

Rules

• No test hits real third-party services or sends real email (third-party-integrations sinks).
• Tests own their data; no dependence on execution order or leftover state.
• Every bug fix at this layer lands with its regression test.

Anti-Patterns

• Mocking the data layer in an "integration" test — that's a slow unit test.
• Testing only happy paths; skipping the negative authz suite.
• One shared mutable seed database for the whole suite.
• Asserting exact error strings instead of codes/shapes.
• A 40-minute suite nobody runs locally.

Validation Checklist

• [ ] Real same-engine DB, migrations + isolation strategy.
• [ ] Persona auth helpers (anonymous, A, B, admin, other-tenant).
• [ ] Per endpoint: success, validation rejection, authz negatives.
• [ ] Cross-user / non-admin / untrusted-ID / cross-tenant tests present.
• [ ] Webhook + job paths covered; externals faked.
• [ ] Suite hermetic, parallel, gating merges.

Definition of Done

An integration suite running real HTTP against the app with a production-engine database — covering critical flows, validation rejection, and the full authorization negative suite — hermetic, CI-gating, and reproducible locally.

Related Skills

backend-unit-testing, ../../testing-strategy, backend-authorization, ownership-authorization, backend-authentication, backend-validation, webhooks, background-jobs, ../../database/database-migrations, ../../database/seed-data.

Related Knowledge

../../../knowledge/ (critical flows, personas/tenancy model).

Related References

../../../references/backend/testing/ (helper patterns, when populated).

Context Loading Guidance

• Requires: endpoint + authz matrix, schema/seed strategy, CI constraints.
• Does not require: service internals (tests go over HTTP), provider docs.
• May load: backend-authorization (negative matrix), ../../database/seed-data.
• Stop when: the suite plan (or tests) covering the matrix is done and CI-wired.

Token Efficiency Guidance

Drive coverage from the endpoint × authz matrix — each cell is a test case; don't re-derive cases per endpoint in prose.