testkit

Documentation

Overview

Package testkit provides small helpers for generated runtime integration tests.

Index

• func AssertEmitted[E any](t testing.TB, events []contracts.EventEnvelope, ...)
• func AssertHeader(t testing.TB, handler http.Handler, method, requestPath, name, want string)
• func AssertNoEvents(t testing.TB, events []contracts.EventEnvelope)
• func AssertStatus(t testing.TB, handler http.Handler, method, requestPath, body string, want int)
• func CaptureCommandEvents[C, R any](t testing.TB, registry *contracts.Registry, command C) (R, []contracts.EventEnvelope)
• func ContractRegistry(register ...func(*contracts.Registry)) *contracts.Registry
• func Response(handler http.Handler, scenario Scenario) *httptest.ResponseRecorder
• func Run(t testing.TB, handler http.Handler, scenarios []Scenario)
• type Client
  • func NewClient(t testing.TB, handler http.Handler) *Client
  • func NewServerClient(t testing.TB, handler http.Handler) *Client
  • func (client *Client) BaseURL() string
  • func (client *Client) Close()
  • func (client *Client) Do(t testing.TB, request Request) Result
  • func (client *Client) Get(t testing.TB, path string) Result
  • func (client *Client) PostForm(t testing.TB, path string, form url.Values) Result
  • func (client *Client) PostJSON(t testing.TB, path string, value any) Result
• type Request
  • func Get(path string) Request
  • func PostForm(path string, form url.Values) Request
  • func PostJSON(path string, value any) Request
  • func (request Request) WithCookie(cookie *http.Cookie) Request
  • func (request Request) WithHeader(name, value string) Request
  • func (request Request) WithQuery(name, value string) Request
• type Result
  • func (result Result) AssertBodyContains(t testing.TB, want string)
  • func (result Result) AssertBodyEquals(t testing.TB, want string)
  • func (result Result) AssertContentType(t testing.TB, want string)
  • func (result Result) AssertCookie(t testing.TB, name string) *http.Cookie
  • func (result Result) AssertHeader(t testing.TB, name, want string)
  • func (result Result) AssertHeaderContains(t testing.TB, name, want string)
  • func (result Result) AssertJSONEqual(t testing.TB, want any)
  • func (result Result) AssertStatus(t testing.TB, want int)
  • func (result Result) AssertStatusRange(t testing.TB, min, max int)
• type Scenario

Functions

func AssertEmitted

func AssertEmitted[E any](t testing.TB, events []contracts.EventEnvelope, category contracts.EventCategory, check func(E))

AssertEmitted finds one captured event with the requested category and type.

func AssertHeader

func AssertHeader(t testing.TB, handler http.Handler, method, requestPath, name, want string)

AssertHeader checks one response header value.

func AssertNoEvents

func AssertNoEvents(t testing.TB, events []contracts.EventEnvelope)

AssertNoEvents fails when a command unexpectedly emitted events.

func AssertStatus

func AssertStatus(t testing.TB, handler http.Handler, method, requestPath, body string, want int)

AssertStatus checks one request's response status.

func CaptureCommandEvents

func CaptureCommandEvents[C, R any](t testing.TB, registry *contracts.Registry, command C) (R, []contracts.EventEnvelope)

CaptureCommandEvents runs a command and fails the test on command errors.

func ContractRegistry

func ContractRegistry(register ...func(*contracts.Registry)) *contracts.Registry

ContractRegistry creates an in-memory registry for contract tests.

func Response

func Response(handler http.Handler, scenario Scenario) *httptest.ResponseRecorder

Response executes one scenario and returns the recorder for custom checks.

func Run

func Run(t testing.TB, handler http.Handler, scenarios []Scenario)

Run executes scenarios against handler.

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client drives generated app handlers with a cookie jar. It can execute requests directly against an http.Handler or through an httptest.Server.

func NewClient

func NewClient(t testing.TB, handler http.Handler) *Client

NewClient creates a cookie-preserving client that executes requests directly against handler without opening a listener.

func NewServerClient

func NewServerClient(t testing.TB, handler http.Handler) *Client

NewServerClient creates a cookie-preserving client backed by an httptest server. Use this when behavior depends on the HTTP transport.

func (*Client) BaseURL

func (client *Client) BaseURL() string

BaseURL returns the client's absolute base URL.

func (*Client) Close

func (client *Client) Close()

Close shuts down the backing test server, if one exists.

func (*Client) Do

func (client *Client) Do(t testing.TB, request Request) Result

Do executes one request and returns the captured result.

func (*Client) Get

func (client *Client) Get(t testing.TB, path string) Result

Get executes a GET request.

func (*Client) PostForm

func (client *Client) PostForm(t testing.TB, path string, form url.Values) Result

PostForm executes a form POST request.

func (*Client) PostJSON

func (client *Client) PostJSON(t testing.TB, path string, value any) Result

PostJSON executes a JSON POST request.

type Request

type Request struct {
	Method     string
	Path       string
	Body       string
	Headers    map[string]string
	Query      url.Values
	Form       url.Values
	JSON       any
	Cookies    []*http.Cookie
	Host       string
	RemoteAddr string
	Context    context.Context
}

Request describes one generated-handler test request.

func Get

func Get(path string) Request

Get builds a GET request.

func PostForm

func PostForm(path string, form url.Values) Request

PostForm builds an application/x-www-form-urlencoded POST request.

func PostJSON

func PostJSON(path string, value any) Request

PostJSON builds an application/json POST request.

func (Request) WithCookie

func (request Request) WithCookie(cookie *http.Cookie) Request

WithCookie returns a copy of request with a cookie attached.

func (Request) WithHeader

func (request Request) WithHeader(name, value string) Request

WithHeader returns a copy of request with a header set.

func (Request) WithQuery

func (request Request) WithQuery(name, value string) Request

WithQuery returns a copy of request with a query value appended.

type Result

type Result struct {
	StatusCode int
	Header     http.Header
	Body       string
	Cookies    []*http.Cookie
	Request    Request
}

Result captures one test response.

func (Result) AssertBodyContains

func (result Result) AssertBodyContains(t testing.TB, want string)

AssertBodyContains checks that the response body contains text.

func (Result) AssertBodyEquals

func (result Result) AssertBodyEquals(t testing.TB, want string)

AssertBodyEquals checks the complete response body.

func (Result) AssertContentType

func (result Result) AssertContentType(t testing.TB, want string)

AssertContentType checks the response Content-Type prefix.

func (Result) AssertCookie

func (result Result) AssertCookie(t testing.TB, name string) *http.Cookie

AssertCookie checks that a response Set-Cookie with name exists.

func (Result) AssertHeader

func (result Result) AssertHeader(t testing.TB, name, want string)

AssertHeader checks one exact response header value.

func (Result) AssertHeaderContains

func (result Result) AssertHeaderContains(t testing.TB, name, want string)

AssertHeaderContains checks that one response header contains text.

func (Result) AssertJSONEqual

func (result Result) AssertJSONEqual(t testing.TB, want any)

AssertJSONEqual compares the response body with want after JSON normalization.

func (Result) AssertStatus

func (result Result) AssertStatus(t testing.TB, want int)

AssertStatus checks the response status code.

func (Result) AssertStatusRange

func (result Result) AssertStatusRange(t testing.TB, min, max int)

AssertStatusRange checks that the response status code is within [min, max].

type Scenario

type Scenario struct {
	Name             string
	Method           string
	Path             string
	Body             string
	Headers          map[string]string
	WantStatus       int
	WantHeader       map[string]string
	WantBodyContains string
}

Scenario describes one HTTP expectation against a generated app handler.