Documentation
¶
Overview ¶
Package compatkit provides experimental downstream compatibility checks for services that adopt api-toolkit runtime contracts.
Use it from a consuming service's Go tests to run a named suite against an in-process http.Handler or an explicitly configured base URL. The package is designed for compatibility evidence: stable HTTP responses, Problem Details, OpenAPI compatibility, and other service-level checks that should keep passing across toolkit upgrades.
Purpose: Run downstream service compatibility checks without depending on generated scaffold internals. Import: `github.com/aatuh/api-toolkit/v4/compatkit`. Example: See compatkit/example_test.go and docs/downstream-compatibility.md. Errors: RunChecks returns structured findings; Run fails the supplied test when any finding is present. Concurrency: Suite values are read during a run and should be treated as immutable after construction. Each check gets a fresh request context. Stability: Experimental test-support package, not part of the v3 stable API gate unless promoted through the stable API review board process. When not to use: Prefer package-local tests or contracttest helpers directly when the service does not need reusable HTTP-level compatibility evidence.
Index ¶
- func Run(t testing.TB, suite Suite)
- type Check
- type Expectation
- func ExpectAll(expectations ...Expectation) Expectation
- func ExpectHeader(name, value string) Expectation
- func ExpectHeaderContains(name, value string) Expectation
- func ExpectOpenAPICompatible(base []byte) Expectation
- func ExpectOpenAPIDocument() Expectation
- func ExpectOpenAPIGolden(golden []byte) Expectation
- func ExpectProblemDetails(status int) Expectation
- func ExpectStatus(status int) Expectation
- type Finding
- type Request
- type Response
- type Result
- type StableHTTPConfig
- type Suite
- type Target
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Run ¶
Run executes a suite and fails t when any finding is reported.
Example ¶
package main
import (
"net/http"
"testing"
"github.com/aatuh/api-toolkit/v4/compatkit"
"github.com/aatuh/api-toolkit/v4/httpx"
)
func main() {
mux := http.NewServeMux()
mux.HandleFunc("/readyz", func(w http.ResponseWriter, r *http.Request) {
httpx.WriteJSON(w, http.StatusOK, map[string]string{"status": "ready"})
})
mux.HandleFunc("/problem", func(w http.ResponseWriter, r *http.Request) {
httpx.WriteProblem(w, http.StatusBadRequest, httpx.Problem{Title: "Bad Request"})
})
var t testing.T
compatkit.Run(&t, compatkit.Suite{
Target: compatkit.Target{Handler: mux},
Checks: compatkit.StableHTTPChecks(compatkit.StableHTTPConfig{
ReadinessPath: "/readyz",
ProblemRequest: compatkit.Request{
Method: http.MethodGet,
Path: "/problem",
},
ProblemStatus: http.StatusBadRequest,
}),
})
}
Output:
Types ¶
type Check ¶
type Check struct {
Name string
Request Request
Expect Expectation
}
Check is one named compatibility assertion.
func StableHTTPChecks ¶
func StableHTTPChecks(cfg StableHTTPConfig) []Check
StableHTTPChecks returns checks for common api-toolkit service contracts: readiness, version, OpenAPI drift, and Problem Details responses.
type Expectation ¶
Expectation validates one response.
func ExpectAll ¶
func ExpectAll(expectations ...Expectation) Expectation
ExpectAll combines response expectations and returns the first failure.
func ExpectHeader ¶
func ExpectHeader(name, value string) Expectation
ExpectHeader requires an exact response header value.
func ExpectHeaderContains ¶
func ExpectHeaderContains(name, value string) Expectation
ExpectHeaderContains requires a response header value to contain a substring.
func ExpectOpenAPICompatible ¶
func ExpectOpenAPICompatible(base []byte) Expectation
ExpectOpenAPICompatible requires the response body to be compatible with base according to contracttest.OpenAPICompatibilityFindings.
func ExpectOpenAPIDocument ¶
func ExpectOpenAPIDocument() Expectation
ExpectOpenAPIDocument requires a successful OpenAPI JSON document with an openapi version and paths object.
func ExpectOpenAPIGolden ¶
func ExpectOpenAPIGolden(golden []byte) Expectation
ExpectOpenAPIGolden requires the response body to match golden after deterministic OpenAPI JSON normalization.
func ExpectProblemDetails ¶
func ExpectProblemDetails(status int) Expectation
ExpectProblemDetails requires an RFC 9457-style Problem Details response. If status is zero, any 4xx or 5xx response is accepted.
func ExpectStatus ¶
func ExpectStatus(status int) Expectation
ExpectStatus requires the response status code to match status.
type Result ¶
type Result struct {
Findings []Finding
}
Result is the structured outcome from RunChecks.
func RunChecks ¶
RunChecks executes a suite and returns structured findings instead of failing a test. The caller-provided context bounds the whole run; Suite.Timeout bounds each individual request.
type StableHTTPConfig ¶
type StableHTTPConfig struct {
ReadinessPath string
VersionPath string
OpenAPIPath string
PreviousOpenAPI []byte
ProblemRequest Request
ProblemStatus int
}
StableHTTPConfig configures the built-in downstream HTTP compatibility profile. Empty paths are skipped so services can opt into only the contracts they expose.
Source Files