Backend Tests

Backend tests — four layers and a 100% gate

Read docs/testing.md and the ## Testing section of CLAUDE.md; both are current. .claude/rules/testing.md has the naming and fixture shapes. This file is where a test goes and what actually breaks.

make test-fast          # no coverage — the write-run-write loop
make test               # backend + the 100% gate on the platform layer
make test-integration   # only the tests that need a real database
make test-cov           # HTML at backend/htmlcov/index.html
make coverage-all        # includes template-inherited code (informational)
make test-migrations    # the whole chain forwards and back against Postgres
make check              # every CI job except e2e — before opening a PR

Which layer

A mock cannot tell you whether a constraint rejects a row. If the assertion is about the schema, it is an integration test or it is worthless.

anyio, not pytest-asyncio

import pytest

pytestmark = pytest.mark.anyio   # module top

There is no asyncio_mode and no @pytest.mark.asyncio. The anyio_backend fixture in tests/conftest.py pins asyncio because that is what uvicorn uses.

Fixtures worth knowing

tests/conftest.py:

• client — httpx.AsyncClient over ASGITransport(app=app). Use this, never Starlette's TestClient. It overrides get_db_session and get_redis, and clears app.dependency_overrides afterwards.
• mock_db_session — an AsyncMock. Mock repositories, never the service under test.
• mock_redis, api_key_headers.

The conftest also sets POSTGRES_DB to <base>_p<pid> before anything imports app.core.config. Do not move or weaken either half: running the unit suite against a checkout with a populated .env used to empty the development database, and a constant name meant two runs on one machine dropping each other's tables (#189).

The same block seeds Prefect, which reads backend/.env on its own account: PREFECT_API_URL empty so that calling a @flow starts a temporary server rather than reaching for the one make dev names (#536), and PREFECT_HOME at a directory belonging to the tests so that server's SQLite database is not a developer's ~/.prefect. tests/test_prefect_test_environment.py pins both, and docs/testing.md#prefect-and-why-no-test-reaches-a-server explains why an empty assignment is the shape that works.

tests/integration/conftest.py creates that database for the session and drops it afterwards, so two concurrent runs need nothing passed to them — make test and uv run pytest tests/integration are safe while another run is going. It skips the whole module when no database is reachable, and refuses any database whose name contains neither test nor ci, or that is not a plain identifier — it calls drop_all unconditionally and drops the database itself at the end.

A test earns its place by failing when the behaviour changes

• Name the behaviour, not the function. test_a_failed_run_still_records_its_cost, not test_finish.
• Assert the consequence. Not "the repository was called" but "the cost written was $2.00".
• The docstring says why it matters when the name cannot.
• Cover the refusal. Most of this platform's value is in what it refuses: a cross-tenant read, an ungranted scope, a second decision on a decided approval.
• No test for a mock. If removing the implementation still passes, delete it.

Invariants to test directly

Tenant isolation (including when the caller owns the row) · permission scopes and grants · budget checked before the model request and recorded even when the run fails · spec validation refused at publish, never at run time · no plaintext secret in any response, log or audit entry · channel mentions running as the sender · what a parser claims it reads vs what the pipeline routes · narrowing a rule on a field already stored as JSONB.

For parser/routing changes, read the rag-knowledge skill; for stored JSONB validation changes, read agent-spec and alembic-migration.

Depth

• references/coverage-gate.md — what is held to 100%, how the config selects it, and the two ways a module drops out silently.
• references/patterns.md — worked service, API and integration tests.