Stage 9 · L44

Own fixtures and choose meaningful test boundaries

Core · original Session 9

Choose a test boundary that matches the claim. Pure validation tests establish conversion/constraints. ASGI/TestClient tests establish the app contract. A real Uvicorn connection establishes TCP serving. A PostgreSQL fixture establishes stored constraints, isolation and committed effects. A deterministic HTTP transport establishes classified provider failures; one real local provider establishes an actual outbound HTTP boundary.

Fixtures own their resource lifetimes. The runner creates a unique internal network, a tmpfs PostgreSQL instance and a random synthetic credential, then removes exactly its owned containers/network in finally. Test URLs are guarded by the fixture database/host prefix. No .env or existing service connection is loaded; SQLite is not substituted for PostgreSQL behavior.

An app transport does not automatically run lifespan. Use TestClient as a context manager or explicitly enter app.router.lifespan_context for ASGITransport. Shared clients and engine cleanup must be established, not assumed. The observation test demonstrates the explicit async lifespan boundary.

Patch or override where the collaborator is used, and restore it in finally. The provider fixture patches equipment.api.SessionLocal, the actual import boundary used by current identity/preparation. The query-count fixture observes the same engine selected by its dependency override. Mocking a different module or counting another engine can make a test pass while bypassing the intended evidence.

Baseline checks exercise completed guided behavior. Transfer checks specify the still-unfinished independent task. A starter's expected transfer failure is not an application regression; a solution must pass both. Passing a toy dictionary would not establish an API/database lab, so these snapshot tests actually issue HTTP and inspect independent PostgreSQL sessions.

Arrange–Act–Assert gives a test a readable causal order. Arrange supplies the owned database/app/client and chosen input; Act makes the request or calls the operation; Assert compares its public outcome and protected effects with the contract. Avoid assertions that merely repeat implementation labels. A missing/forbidden response should be accompanied by a stored or outbound no-effect observation when that is the claim.

A stub supplies a chosen response, a spy records how a collaborator was called, and a mock combines substitution with configured expectations checked by the test. The local HTTP MockTransport may act as a stub while a calls list acts as a spy; asserting the expected path/count makes that collaborator expectation explicit. The terms describe roles in the test, not whether the object happens to have Mock in its library name.

Arrange: owned app/fixture and expected provider response
Act: issue one HTTP request
Assert: status/public output plus protected effects

Stub: supplies a chosen result
Spy: records calls/arguments
Mock: configured collaborator checked against expectations

The response supplier is a stub; the call list is a spy; using configured expectations/assertions makes the substituted collaborator a mock in that test. Arrange establishes owned resources, Act performs the behavior, Assert checks outcomes/effects. An identity/scope override proves wiring, not real JWT/authorization. Lifespan and patch-at-use must be explicit; savepoint isolation is taught next.