Documentation
¶
Overview ¶
Package testopenapi is a reusable helper: load a module's openapi.yaml fragment once, then validate RECORDED handler-test responses (status + body) against the operation the request actually matched, so the running service is proven to honor its contract at the HTTP boundary.
Library choice: github.com/getkin/kin-openapi (openapi3 + openapi3filter + routers/gorillamux). It is the most widely used, actively maintained pure-Go OpenAPI 3 implementation (used by Kubernetes-adjacent and many other production Go services), has no cgo/native dependency, and its openapi3filter sub-package already implements exactly the request/response validation needed here — no hand-rolled JSON Schema walker required. Footprint: one direct module (github.com/getkin/kin-openapi) plus its own small dependency tree (gorilla/mux for path routing, a YAML parser, a JSON Schema validator) — no other module in this repo touches any of them, so the added dependency surface is exactly one subtree, not a sprawl.
Usage: Load a module's fragment once per test file (typically in a package-level var or a t.Helper() wrapper), then call ValidateResponse with the *http.Request actually driven through the handler and the *httptest.ResponseRecorder it produced — same request/response pair every existing handler test already builds, no parallel fixture needed.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Spec ¶
type Spec struct {
// contains filtered or unexported fields
}
Spec is a loaded, validated openapi.yaml fragment plus its route matcher.
func Load ¶
Load reads and validates the OpenAPI document at path (a module's openapi.yaml), building the route matcher used by ValidateResponse. Fails fast (returns an error) on a malformed or internally-inconsistent fragment — the same class of error `make validate-modules` (cmd/modvalidate) already checks for its own OpenAPI rules, but this is kin-openapi's own OpenAPI 3 structural/schema validation, a different (complementary) check.
func LoadModule ¶
LoadModule is Load(modulePath(module)), memoized per module name for the life of the test binary — every _test.go in a module's package can call this cheaply (e.g. once per test) with no repeated disk/parse cost.
func (*Spec) ValidateResponse ¶
ValidateResponse validates rec (the recorder a handler test already produced) against the operation req matches in the loaded spec — status code AND body schema. req must be the SAME request object passed to the handler (method, URL path, and any headers/body the routing or request-side schema might consult); rec must be the SAME recorder the handler wrote to.
Fails the test (via tb.Fatalf) on: no matching operation for the request's method+path (the route itself is undocumented — a drift finding in its own right), an undeclared status code, or a response body that doesn't satisfy the declared schema (missing required field, wrong type, wrong nullability, etc. — exactly the drift class this helper exists to catch).