Backend Testing Strategy

The future backend package system should be AI-generatable only when it is also AI-testable, human-reviewable, and safe to roll back.

Test Levels

Level	Purpose	Example packages
Unit tests	Pure helper and schema behavior.	api-contract, permissions, storage, observability
Contract tests	OpenAPI, response envelope, webhook event, job payload, and client compatibility.	api-contract, webhooks, jobs
Integration tests	Hono routes, middleware stack, DB access, storage mocks, queue mocks.	api-kit, auth, storage, media-service
Database migration tests	Apply/revert migrations, seed fixtures, relation checks, tenant isolation.	db
Permission policy tests	Deny-by-default, grants, revokes, app scopes, agent tool approval.	permissions, agents-runtime
Webhook signature tests	Valid/invalid signatures, replay fixtures, malformed payloads, idempotency.	webhooks, billing
Job retry/idempotency tests	Retry policy, dead letters, duplicate payloads, recovery behavior.	jobs
Agent tool permission tests	Tool call gating, approval workflows, audit emission, artifact creation.	agents-runtime
Billing event replay tests	Subscription lifecycle, tips, entitlements, usage limits, failure replay.	billing
Audit correlation tests	Request IDs, actor refs, resource refs, before/after summaries.	audit, api-kit, jobs

Local Testing Runtime

Future backend work may need:

Node test runtime for packages.
Hono local adapter.
Miniflare / Wrangler dev for Worker-specific integration.
Local Postgres or Neon branch database.
Test R2 mock.
Queue mock for Cloudflare Queues.
Webhook fixture replay.
Seed data and fixture factories.

The first backend packages should stay small enough to run tests locally without requiring real cloud credentials.

Contract-first Testing

Contract-first backend testing means:

API contract tests come from @prox-os/api-contract.
DB fixtures come from @prox-os/db.
Permission fixtures come from @prox-os/permissions.
Audit event snapshots come from @prox-os/audit.
Job payload schemas come from @prox-os/jobs.
Webhook fixtures come from @prox-os/webhooks.
Billing replay fixtures come from @prox-os/billing.
Agent tool fixtures come from @prox-os/agents-runtime.

AI Acceptance Checks

Every AI-generated backend PR should answer:

What contract did it implement?
What fixtures did it add?
What tests did it run?
What permission boundary did it respect?
What audit events does it emit?
What observability hooks exist?
What rollback path exists?

If those answers are missing, the PR should not be treated as backend-ready.

Minimum Package Test Harness

When any backend package becomes real, it should include:

package-level lint and typecheck;
unit tests or a documented reason tests are deferred;
fixture files for contracts and edge cases;
mock provider for external dependencies;
local test commands in package docs;
CI target in the repo task graph when appropriate.

Risk-based Expansion

Start with low-risk, deterministic tests:

pure type/schema tests;
response/error envelope tests;
mock middleware tests;
local DB migration tests;
webhook fixture replay;
permission policy matrix;
billing and agent runtime only after audit and permissions are stable.