hex-test-restapi-endpoint
Use when testing one REST endpoint through the real ASGI app — one file per endpoint under `tests/integration/api/<resource>/`, asserting the success body and each advertised error code, with per-reso
SKILL.mdplugins/pyhouse-hex/skills/hex-test-restapi-endpoint/SKILL.md
GitHubHex Test — REST API Endpoint
Consult test-principles for the testing constitution. Where this skill contradicts test-principles, the constitution wins.
Produces one integration-test file per endpoint. Self-contained: every test in the file constructs its own state by calling factory fixtures or POSTing through the API; no cross-test state, no shared registries, no cross-file edits when a new endpoint is added.
When to use vs. neighbours
- A new or modified endpoint added by
hex-restapi-endpoint→ this skill. - A new resource introduces several endpoints (create + list + get + update + delete) → invoke this skill once per endpoint file; sibling files share a per-resource
conftest.py. - The
tests/integration/conftest.pyitself (rollback, container fixtures,container,real_app) →hex-test-integration-setup(one-shot). - The auth half — the
authenticated_clientfactory and its signing-key fixtures, a route driven as an authenticated caller, a role rejection or a cross-tenant 404, the token verifier's own unit test →hex-test-restapi-auth(auth apps only; this skill is complete without it). - The route-side auth dependency, the role gate and the 401/403 codes a route advertises because of them →
hex-restapi-auth. - Cross-cutting "every advertised error code carries the catalogue's shape" / CORS / request-size →
hex-test-app-invariants(one-shot; discovers by walking the app's published document). - Repository contract (real DB, no HTTP) →
hex-test-repository-contract. - Pure domain unit test →
hex-test-domain. - The testing constitution these rules defer to — speed targets, fixture placement, the mocking prohibition →
test-principles. - A structural invariant enforced by a grep firewall at compile time rather than over HTTP →
test-architecture-rule.
Template(s) — pytest, httpx2 over an in-process ASGI transport, FastAPI
tests/integration/api/<resource>/
├── conftest.py # per-resource fixtures (sibling-shared)
└── test_<verb>_<noun>.py # one file per endpoint
The templates below are the primary, auth-free form — a public route, or any route in an app that
declares no auth. An authenticated route is the same file driven through an authenticated client
instead of the plain one, and hex-test-restapi-auth carries those variants along with the role and
tenancy assertions that only exist when there is a caller to have a role.
test_<verb>_<noun>.py — the endpoint test
from fastapi import FastAPI
from httpx2 import ASGITransport, AsyncClient
from myapp.domain.exceptions import ValidationError
async def test_create_foo_returns_the_created_foo(real_app: FastAPI) -> None:
transport = ASGITransport(app=real_app)
async with AsyncClient(transport=transport, base_url="http://testserver") as client:
response = await client.post("/foos", json={"name": "alpha"})
assert response.status_code == 201
assert response.json()["name"] == "alpha"
async def test_create_foo_empty_body_returns_422(real_app: FastAPI) -> None:
transport = ASGITransport(app=real_app)
async with AsyncClient(transport=transport, base_url="http://testserver") as client:
response = await client.post("/foos", json={})
assert response.status_code == 422
assert response.json()["code"] == ValidationError.code
The plain AsyncClient over real_app is the sanctioned client for a route with no auth dependency
(hex-test-restapi-auth rule 4). Every error path for the same endpoint lives in this file too, each
asserted by code (Rule 8) — here the 422 an empty create body produces. A 404 on an {id} route,
and a 409 where the aggregate carries a uniqueness constraint, are further tests of the same shape.
Where the route transfers a file, the test also asserts the media type and disposition the route sets,
never a fixed download shape.
Per-resource conftest.py — relational seed factory, SQLAlchemy
A raw INSERT is legitimate setup here: hex-test-repository-contract rule 9 bans it only in a test of the repository under test, where seeding behind the subject would prove nothing. An endpoint test's subject is the route, so the fastest honest way to put a row in front of it is to write one. The make_foo factory below seeds via a raw SQL INSERT through session_factory — that is the relational-store variant, valid when the resource is backed by a relational store. A resource backed by a client-style store (redis / a document store / …) has no session_factory and no SQL table: seed it either by POSTing through the API (drive the create endpoint, then test against the result) or via the store's own client in the fixture. Pick the path from the resource's datastore kind; don't reach for INSERT INTO when there is no SQL table.
import uuid
from collections.abc import Awaitable, Callable
import pytest
from sqlalchemy import text
from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
@pytest.fixture
def make_foo(session_factory: async_sessionmaker[AsyncSession]) -> Callable[..., Awaitable[uuid.UUID]]:
async def _make(*, name: str | None = None) -> uuid.UUID:
foo_id = uuid.uuid4()
async with session_factory() as session:
await session.execute(
text("INSERT INTO foos(id, name) VALUES(:id, :name)"),
{"id": str(foo_id), "name": name or f"foo-{foo_id}"},
)
await session.commit()
return foo_id
return _make
Other bindings
- Another way to drive the app. An in-process ASGI transport is one; a framework's own test client, or a live server on a loopback port, are the others. What changes is how the client is constructed and whether the app's start-up events run — an out-of-process server runs them, an in-process transport may not, so a test that depends on start-up wiring has to arrange it. One file per endpoint, the by-value body assertion, the error-code assertion and per-test factory fixtures are unchanged.
Rules
- One file per endpoint, named for its operation (
test_create_foo.py) — the subject is one route, not the router module. It holds the happy path and one test for each error code the route advertises (hex-restapi-endpoint); in an auth app the401and403arehex-test-restapi-auth's. No mega-files spanning a whole resource. - Assert the success body by value — the fields the request set and those the operation promises to derive or leave alone. A framework that enforces the declared response model on the way out already turns a drifted body into a
500; validate the whole body only where a route bypasses that model (a raw response). - No cross-cutting registries but one. Adding a new endpoint touches exactly one new test file. The one sanctioned table is the auth probe's public set: in an auth app, a route meant to be public is also named there (
hex-test-restapi-auth). The discovered global checks — "every advertised error code carries the catalogue's shape", and in an auth app "every operation not declared public refuses an anonymous or untrusted caller" — are owned byhex-test-app-invariantsandhex-test-restapi-auth, and derive their inputs from the app's published document and its resolved routes; there is no hand-maintained endpoint table to extend. - Each test builds its own state —
make_foo, or a POST through the API; fixed natural keys and exact counts followtest-principles, Assert strength. - An order assertion is reliable only where the seeded rows differ in the sort key: a store that stamps rows inside one transaction can give them all one instant (
test-principles, reliability 4), so sort by a key the test sets, or assert the set of ids. A mutation whose response carries no state (a204delete) is followed by a read through the API that proves the effect — the row's404, and a second row still served. - The client is entered as a context manager, never assigned. Bare-assigning it leaks the transport, and the leak surfaces as an unrelated test failing later in the session.
- Per-resource fixtures live in the sibling
conftest.py. Factory fixtures (make_foo) return one fresh row per call — a default for a unique column differs per call. - Error responses are asserted by
code, not by message.assert response.json()["code"] == ValidationError.code— message text drifts, thecodeconstant is the contract. The actual HTTP status is asserted separately. - Mocking. Follow
test-principlesfor the mocking prohibition. If a test needs to mock, it isn't an integration test; move it to a domain unit test (hex-test-domain) or to a handler test over fakes (hex-test-application-handler), which is also where a compensating handler's undo is pinned.
Inlined typing / import rules
pytest,httpx2,fastapi,myapp.domain.exceptions. Nomyapp.application.*ormyapp.infrastructure.*imports — the test drives over HTTP, not by reaching in.- Full annotations on every signature, tests included —
-> Noneon every test, every fixture parameter typed.python-styleowns annotation policy and admits no test carve-out. - No
from __future__ import annotations.
Hard stops
- Nothing up-tree builds the app on the test's own infrastructure bindings (
real_appunder this catalogue's binding) → stop, usehex-test-integration-setup; the missing thing is the guarantee, not the fixture name. - Asked to register the new endpoint in a hand-maintained route or expectation table so a global check sees it → stop, use
hex-test-app-invariants; the global checks derive their inputs from the running app, so a new route joins them with nothing to update. The auth probe's public set is the one exception (rule 3). - A test asserts a role rejection or a cross-tenant 404 here → stop, use
hex-test-restapi-auth; those assertions need a caller identity this skill does not mint. - A test asserts on a response field that is not in the Pydantic response schema → stop, use
hex-restapi-schemato extend the schema first. - A test uses a plain
AsyncClientfor a request to a route that attaches an auth dependency → stop, usehex-test-restapi-auth's authenticated client; a plain client on a gated route tests the rejection, not the endpoint.