API testing

Discover the service's test runner and existing contract-test style. Use [[z-bdd]] for acceptance through the running service's public protocol. Exercise real application wiring and required dependencies. A health response alone does not prove a business journey. Add handler or dependency integration tests only for named residual risks per [[z-testing-strategy]]. Preserve existing tests.

Handler contracts

Use net/http/httptest with the repository's assertion library. Verify status, relevant headers, response shape, and caller-visible error behavior.

Cover authentication and resource authorization separately. A 200 response alone does not establish correct data or permissions.

Use httptest.NewServer when the network/client interaction is part of the contract. A recorder proves handler behavior without a network hop.

Integration setup

Inspect existing fixtures, build tags, and wrappers before adding testcontainers, compose, or another mechanism. Match the database version and migration path used by the project.

If the project uses short-mode guards, put one in each integration entry point before accessing its fixture: