humatest

Documentation

Overview

Package humatest provides testing utilities for Huma services. It is based on the standard library `http.Request` & `http.ResponseWriter` types.

Index

• func DumpRequest(req *http.Request) ([]byte, error)
• func DumpResponse(resp *http.Response) ([]byte, error)
• func NewAdapter() huma.Adapter
• func NewContext(op *huma.Operation, r *http.Request, w http.ResponseWriter) huma.Context
• func PrintRequest(req *http.Request)
• func PrintResponse(resp *http.Response)
• type TB
• type TestAPI
  • func New(tb TB, configs ...huma.Config) (http.Handler, TestAPI)
  • func Wrap(tb TB, api huma.API) TestAPI

Examples

• PrintRequest
• PrintResponse

Functions

func DumpRequest

func DumpRequest(req *http.Request) ([]byte, error)

DumpRequest returns a string representation of an HTTP request, automatically pretty printing JSON bodies for readability.

func DumpResponse

func DumpResponse(resp *http.Response) ([]byte, error)

DumpResponse returns a string representation of an HTTP response, automatically pretty printing JSON bodies for readability.

func NewAdapter

func NewAdapter() huma.Adapter

NewAdapter creates a new test adapter from a router.

func NewContext

func NewContext(op *huma.Operation, r *http.Request, w http.ResponseWriter) huma.Context

NewContext creates a new test context from an HTTP request and response.

func PrintRequest

func PrintRequest(req *http.Request)

PrintRequest prints a string representation of an HTTP request to stdout, automatically pretty printing JSON bodies for readability.

Example

req, _ := http.NewRequest(http.MethodGet, "http://example.com/foo?bar=baz", nil)
req.Header.Set("Foo", "bar")
req.Host = "example.com"
PrintRequest(req)

Output:

GET /foo?bar=baz HTTP/1.1
Host: example.com
Foo: bar

func PrintResponse

func PrintResponse(resp *http.Response)

PrintResponse prints a string representation of an HTTP response to stdout, automatically pretty printing JSON bodies for readability.

Example

resp := &http.Response{
	StatusCode: http.StatusOK,
	ProtoMajor: 1,
	ProtoMinor: 1,
	Header: http.Header{
		"Content-Type": []string{"application/json"},
	},
	ContentLength: -1,
	Body:          io.NopCloser(strings.NewReader(`{"foo": "bar"}`)),
}
PrintResponse(resp)

Output:

HTTP/1.1 200 OK
Connection: close
Content-Type: application/json

{
  "foo": "bar"
}

Types

type TB

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

TB is a subset of the `testing.TB` interface used by the test API and implemented by the `*testing.T` and `*testing.B` structs.

type TestAPI

type TestAPI interface {
	huma.API

	// DoCtx a request against the API with a custom [context.Context] in the
	// [http.Request]. Args, if provided, should be string headers like
	// `Content-Type: application/json`, an `io.Reader` for the request body, or a
	// slice/map/struct which will be serialized to JSON and sent as the request
	// body. Anything else will panic.
	DoCtx(ctx context.Context, method, path string, args ...any) *httptest.ResponseRecorder

	// Do a request against the API using [context.Background] in the [http.Request].
	// Args, if provided, should be string headers like `Content-Type:
	// application/json`, an `io.Reader` for the request body, or a slice/map/struct
	// which will be serialized to JSON and sent as the request body. Anything else
	// will panic.
	Do(method, path string, args ...any) *httptest.ResponseRecorder

	// GetCtx performs a GET request against the API with a custom [context.Context]
	// in the [http.Request]. Args, if provided, should be string headers like
	// `Content-Type: application/json`, an `io.Reader` for the request body, or a
	// slice/map/struct which will be serialized to JSON and sent as the request
	// body. Anything else will panic.
	//
	// 	// Make a GET request
	//	api.GetCtx(ctx, "/foo")
	//
	// 	// Make a GET request with a custom header.
	// 	api.GetCtx(ctx, "/foo", "X-My-Header: my-value")
	GetCtx(ctx context.Context, path string, args ...any) *httptest.ResponseRecorder

	// Get performs a GET request against the API using [context.Background] in the
	// [http.Request]. Args, if provided, should be string headers like
	// `Content-Type: application/json`, an `io.Reader` for the request body, or a
	// slice/map/struct which will be serialized to JSON and sent as the request
	// body. Anything else will panic.
	//
	// 	// Make a GET request
	// 	api.Get("/foo")
	//
	// 	// Make a GET request with a custom header.
	// 	api.Get("/foo", "X-My-Header: my-value")
	Get(path string, args ...any) *httptest.ResponseRecorder

	// PostCtx performs a POST request against the API with a custom
	// [context.Context] in the [http.Request]. Args, if provided, should be string
	// headers like `Content-Type: application/json`, an `io.Reader` for the request
	// body, or a slice/map/struct which will be serialized to JSON and sent as the
	// request body. Anything else will panic.
	//
	// 	// Make a POST request
	// 	api.PostCtx(ctx, "/foo", strings.NewReader(`{"foo": "bar"}`))
	//
	// 	// Make a POST request with a custom header.
	// 	api.PostCtx(ctx, "/foo", "X-My-Header: my-value", MyBody{Foo: "bar"})
	PostCtx(ctx context.Context, path string, args ...any) *httptest.ResponseRecorder

	// Post performs a POST request against the API using [context.Background] in the
	// [http.Request]. Args, if provided, should be string headers like
	// `Content-Type: application/json`, an `io.Reader` for the request body, or a
	// slice/map/struct which will be serialized to JSON and sent as the request
	// body. Anything else will panic.
	//
	// 	// Make a POST request
	//	api.Post("/foo", strings.NewReader(`{"foo": "bar"}`))
	//
	// 	// Make a POST request with a custom header.
	// 	api.Post("/foo", "X-My-Header: my-value", MyBody{Foo: "bar"})
	Post(path string, args ...any) *httptest.ResponseRecorder

	// PutCtx performs a PUT request against the API with a custom [context.Context]
	// in the [http.Request]. Args, if provided, should be string headers like
	// `Content-Type: application/json`, an `io.Reader` for the request body, or a
	// slice/map/struct which will be serialized to JSON and sent as the request
	// body. Anything else will panic.
	//
	// 	// Make a PUT request
	// 	api.PutCtx(ctx, "/foo", strings.NewReader(`{"foo": "bar"}`))
	//
	// 	// Make a PUT request with a custom header.
	// 	api.PutCtx(ctx, "/foo", "X-My-Header: my-value", MyBody{Foo: "bar"})
	PutCtx(ctx context.Context, path string, args ...any) *httptest.ResponseRecorder

	// Put performs a PUT request against the API using [context.Background] in the
	// [http.Request]. Args, if provided, should be string headers like
	// `Content-Type: application/json`, an `io.Reader` for the request body, or a
	// slice/map/struct which will be serialized to JSON and sent as the request
	// body. Anything else will panic.
	//
	// 	// Make a PUT request
	// 	api.Put("/foo", strings.NewReader(`{"foo": "bar"}`))
	//
	// 	// Make a PUT request with a custom header.
	// 	api.Put("/foo", "X-My-Header: my-value", MyBody{Foo: "bar"})
	Put(path string, args ...any) *httptest.ResponseRecorder

	// PatchCtx performs a PATCH request against the API with a custom
	// [context.Context] in the [http.Request]. Args, if provided, should be string
	// headers like `Content-Type: application/json`, an `io.Reader` for the request
	// body, or a slice/map/struct which will be serialized to JSON and sent as the
	// request body. Anything else will panic.
	//
	// 	// Make a PATCH request
	// 	api.PatchCtx(ctx, "/foo", strings.NewReader(`{"foo": "bar"}`))
	//
	// 	// Make a PATCH request with a custom header.
	// 	api.PatchCtx(ctx, "/foo", "X-My-Header: my-value", MyBody{Foo: "bar"})
	PatchCtx(ctx context.Context, path string, args ...any) *httptest.ResponseRecorder

	// Patch performs a PATCH request against the API using [context.Background] in
	// the [http.Request]. Args, if provided, should be string headers like
	// `Content-Type: application/json`, an `io.Reader` for the request body, or a
	// slice/map/struct which will be serialized to JSON and sent as the request
	// body. Anything else will panic.
	//
	// 	// Make a PATCH request
	// 	api.Patch("/foo", strings.NewReader(`{"foo": "bar"}`))
	//
	// 	// Make a PATCH request with a custom header.
	// 	api.Patch("/foo", "X-My-Header: my-value", MyBody{Foo: "bar"})
	Patch(path string, args ...any) *httptest.ResponseRecorder

	// DeleteCtx performs a DELETE request against the API with a custom
	// [context.Context] in the [http.Request]. Args, if provided, should be string
	// headers like `Content-Type: application/json`, an `io.Reader` for the request
	// body, or a slice/map/struct which will be serialized to JSON and sent as the
	// request body. Anything else will panic.
	//
	// 	// Make a DELETE request
	// 	api.DeleteCtx(ctx, "/foo")
	//
	// 	// Make a DELETE request with a custom header.
	// 	api.DeleteCtx(ctx, "/foo", "X-My-Header: my-value")
	DeleteCtx(ctx context.Context, path string, args ...any) *httptest.ResponseRecorder

	// Delete performs a DELETE request against the API using [context.Background] in
	// the [http.Request]. Args, if provided, should be string headers like
	// `Content-Type: application/json`, an `io.Reader` for the request body, or a
	// slice/map/struct which will be serialized to JSON and sent as the request
	// body. Anything else will panic.
	//
	// 	// Make a DELETE request
	//	api.Delete("/foo")
	//
	// 	// Make a DELETE request with a custom header.
	// 	api.Delete("/foo", "X-My-Header: my-value")
	Delete(path string, args ...any) *httptest.ResponseRecorder
}

TestAPI is a `huma.API` with additional methods specifically for testing.

func New

func New(tb TB, configs ...huma.Config) (http.Handler, TestAPI)

New creates a new router and test API, making it easy to register operations and perform requests against them. Optionally takes a configuration object to customize how the API is created. If no configuration is provided then a simple default configuration supporting `application/json` is used.

func Wrap

func Wrap(tb TB, api huma.API) TestAPI

Wrap returns a `TestAPI` wrapping the given API.