Backend Tests

Backend tests — four layers and a 100% gate

Read docs/testing.md and the ## Testing section of AGENTS.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.

bashCopy code
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

pythonCopy code
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 worker needs no server and no variable of its own. Its guarantees are tested against the real background_jobs table and real child processes, with the misbehaving kinds in tests/worker_handlers.py; a service that queues a job is unit-tested by patching enqueue where it is imported (the queued_fires fixture in tests/test_agent_triggers.py). docs/testing.md#the-workers-tests has which file covers what.

When listing files for one pytest run, keep the tests/integration/ files together: an integration file, then a plain tests/ file, then another integration file loses tests/integration/conftest.py for the last one and it errors with fixture 'db' not found. Whole directories, as CI runs them, are unaffected.

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.