testopenapi

package
v0.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 5, 2026 License: Apache-2.0 Imports: 11 Imported by: 0

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

func Load(path string) (*Spec, error)

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

func LoadModule(module string) (*Spec, error)

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

func (s *Spec) ValidateResponse(tb TB, req *http.Request, rec *httptest.ResponseRecorder)

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).

type TB

type TB interface {
	Helper()
	Fatalf(format string, args ...any)
}

TB is the subset of testing.TB this package needs — lets callers pass a *testing.T without this package importing "testing" itself being a hard requirement for Load's own callers that don't need it (Load has no TB parameter; only the *testing.T-facing validation calls do).

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL