httptest

README

godoc pkg.go.dev

WORK IN PROGRESS

httptest

The package httptest is intended to facilitate the testing of HTTP APIs.

Documentation

Index

• type AuthSetter
• type Body
• type Config
  • func (c *Config) LogReport()
  • func (c *Config) Run(t *testing.T, tgs []*TestGroup, mux http.Handler)
• type E
  • func (e E) Split() (method, pattern string)
  • func (e E) String() string
• type Header
  • func (h Header) GetHeader() http.Header
• type HeaderGetter
• type ParamSetter
• type Params
  • func (pp Params) SetParams(pattern string) (path string)
• type Query
  • func (q Query) GetQuery() string
• type QueryGetter
• type Request
• type Response
• type State
• type StateHandler
• type T
• type Test
• type TestGroup

Types

type AuthSetter

type AuthSetter interface {
	SetAuth(r *http.Request, t Request)
}

AuthSetter updates an HTTP request with auth information.

type Body

type Body interface {
	// Type returns the string used in an HTTP request's Content-Type header.
	Type() string
	// Reader returns an io.Reader that provides the content of an HTTP request's body.
	Reader() (body io.Reader, err error)
	// Compare returns the result of the comparison between the Body's contents
	// and the contents of the given io.Reader. The level of strictness of the
	// comparison depends on the implementation. If the contents are equivalent
	// the returned error will be nil, otherwise the error will describe the
	// negative result of the comparison.
	Compare(body io.Reader) error
}

The Body type represents the contents of an HTTP request or response body.

The httptype package contains a number of useful implementations.

type Config

type Config struct {
	// The URL of the host from which the target API is being served.
	//
	// If Host is left empty then Run will automatically start a test
	// server using its mux argument as the test server's handler.
	Host string
	// Label is the descriptive name of the set of tests ran by this config.
	// The label is primarily used in the logged report of the test results.
	Label string
	// The HTTP client to be used for sending test requests to the API.
	// If nil, a default client will be used.
	Client *http.Client
	// StateHandler, if set, will be used for managing the state of each test.
	StateHandler StateHandler
	// contains filtered or unexported fields
}

A Config specifies the configuration for test running. The zero value of Config is a ready-to-use default configuration.

func (*Config) LogReport

func (c *Config) LogReport()

LogReport logs a summary of the test results to stderr.

func (*Config) Run

func (c *Config) Run(t *testing.T, tgs []*TestGroup, mux http.Handler)

Run executes the set of provided test groups. If the Config's Host is left empty then Run will automatically start a new test server using the mux argument as the test server's handler.

type E

type E string

The E string type represents the endpoint to be tested, it is expected to be of the format "METHOD PATTERN", i.e. the endpoint's HTTP method, followed by a single space which, in turn, is followed by the endpoint's URL path pattern. For example: "GET /foo/{id}/bar".

If the value provided by the user doesn't match the prescribed format the package will try to default to some sensible value however the result of that may not be what the user expects. It is therefore the user's responsibility to provide the value in the expected format.

func (E) Split

func (e E) Split() (method, pattern string)

Split splits the endpoint into two strings, the method and the pattern, and returns them.

func (E) String

func (e E) String() string

type Header

type Header map[string][]string

A Header represents the key-value pairs in an HTTP header.

func (Header) GetHeader

func (h Header) GetHeader() http.Header

GetHeader returns the receiver as http.Header.

type HeaderGetter

type HeaderGetter interface {
	GetHeader() http.Header
}

HeaderGetter returns an HTTP header.

type ParamSetter

type ParamSetter interface {
	SetParams(pattern string) string
}

The ParamSetter substitutes the placeholders of an endpoint pattern with actual parameter values.

SetParams should return a copy of the given pattern with all of its placeholders replaced with actual parameter values. How the placeholders should be demarcated in the pattern depends on the implementation of the interface.

type Params

type Params map[string]interface{}

Params is a ParamSetter that substitues an endpoint pattern's placeholders with its mapped values. The Params' keys represent the placeholders while the values are the actual parameters to be used to substitue those placeholders.

func (Params) SetParams

func (pp Params) SetParams(pattern string) (path string)

SetParams returns a copy of the given pattern replacing all of its placeholders with the actual parameter values contained in Params. The placeholders, used as keys to get the corresponding parameter values, are expected to be demarcated with curly braces; e.g.

pattern := "/users/{user_id}"
params := Params{"user_id": 123}
path := params.SetParams(pattern)
fmt.Println(path)
// outputs "/users/123"

type Query

type Query url.Values

Query is a QueryGetter that returns its' contents encoded into "URL encoded" form.

func (Query) GetQuery

func (q Query) GetQuery() string

GetQuery encodes the Query's underlying values into "URL encoded" form. GetQuery uses net/url's Values.Encode to encode the values, see the net/url documentation for more info.

type QueryGetter

type QueryGetter interface {
	GetQuery() string
}

The QueryGetter returns a string of query parameters in the "URL encoded" form.

type Request

type Request struct {
	// The auth information to be sent with the request.
	//
	// [httpdoc]: If the AuthSetter's type implements either the httpdoc.HTMLer
	// interface or the httpdoc.Valuer interface, then it will be used by httpdoc
	// to produce auth-specific documentation.
	Auth AuthSetter
	// The HTTP header to be sent with the request.
	//
	// [httpdoc]: If the HeaderGetter's type implements the httpdoc.Valuer interface,
	// then it will be used by httpdoc to produce input-specific documentation.
	Header HeaderGetter
	// The path parameters to be substituted in an endpoint pattern.
	//
	// [httpdoc]: If the ParamSetter's type implements the httpdoc.Valuer interface,
	// then it will be used by httpdoc to produce input-specific documentation.
	Params ParamSetter
	// The URL query parameters to be appended to an endpoint's path.
	//
	// [httpdoc]: If the QueryGetter's type implements the httpdoc.Valuer interface,
	// then it will be used by httpdoc to produce input-specific documentation.
	Query QueryGetter
	// The request body to be sent.
	//
	// [httpdoc]: If the Body's type implements the httpdoc.Valuer interface,
	// then it will be used by httpdoc to produce input-specific documentation.
	Body Body
	// If set to true and the test fails, a dump of the HTTP request
	// will be included in the test's output.
	DumpOnFail bool
	// If set to true, a dump of the HTTP request will be included in the test's output.
	Dump bool
}

The Request type describes the data to be sent in a single HTTP request.

type Response

type Response struct {
	// The expected HTTP status code.
	StatusCode int
	// The expected HTTP response headers.
	//
	// [httpdoc]: If the HeaderGetter's type implements the httpdoc.Valuer interface,
	// then it will be used by httpdoc to produce output-specific documentation.
	Header HeaderGetter
	// The expected response body.
	//
	// [httpdoc]: If the Body's type also implements the httpdoc.Valuer interface,
	// then it will be used by httpdoc to produce output-specific documentation.
	Body Body
	// If set to true and the test fails, a dump of the HTTP response
	// will be included in the test's output.
	DumpOnFail bool
	// If set to true, a dump of the HTTP response will be included in the test's output.
	Dump bool
}

Response is used to describe the expected HTTP response to a request.

type State

type State any

A State is a value of any type that the client code can use, together with an implementation of the StateHandler, to manage the state of individual tests.

type StateHandler

type StateHandler interface {
	// Init can be used to initialize (i.e., set up) a test's state.
	// Init will be invoked BEFORE the state's test is executed.
	Init(State) error
	// Check can be used to check whether a test's state is as expected.
	// Check will be invoked AFTER the state's test is executed.
	Check(State) error
	// Cleanup can be used to clean up (i.e., tear down) a test's state.
	// Cleanup will be invoked AFTER the state's test is executed.
	Cleanup(State) error
}

StateHandler can be implemented by the client code to provide a way to manage the application state of individual tests.

type T

type T interface {
	Error(args ...interface{})
	Run(name string, f func(T)) bool
}

The T interface represents a tiny portion of the *testing.T functionality which is being used by the Config.run method.

It's primary raison d'etre is to make Config.run testable.

type Test

type Test struct {
	// The request to be sent to the endpoint under test.
	Request Request
	// The expected response to the request.
	Response Response
	// N or Name hold the Test's name. Name takes precedence over N.
	//
	// The httptest package uses the name to identify the Test's subtest.
	N, Name string
	// State can optionally be set to a value that represents the test's state.
	// If set, it will be passed to the Config.StateHandler to manage the test's state.
	State State
	// Indicates that the Test should be skipped by the test runner.
	Skip bool
	// DocA and DocB are optional, they are ignored by the httptest package
	// and are used only by the httpdoc package. The httpdoc package uses the
	// Test's Request and Response to generate example docs for the resulting
	// article.
	//
	// DocA, if set, is used by httpdoc to generate documentation [A]bove the example docs.
	// DocB, if set, is used by httpdoc to generate documentation [B]elow the example docs.
	//
	// The following types are supported:
	//	- string
	//	- *os.File
	//	- httpdoc.HTMLer
	//	- httpdoc.Valuer
	//	- interface{} (named types only)
	// Anything else will result in an error.
	//
	// If the type is string, it is expected to contain raw HTML and it is
	// up to the user to ensure that that HTML is valid and safe.
	//
	// If the type is *os.File, it is expected to contain raw HTML and it is
	// up to the user to ensure that that HTML is valid and safe.
	//
	// If the type is httpdoc.HTMLer, then its HTML() method will be used
	// to retrieve the content and it is up to the user to ensure that that
	// content is valid and safe HTML.
	//
	// If the type is httpdoc.Valuer, then its Value() method will be used
	// to get the underlying Value, the source of that Value's dynamic type
	// is then analyzed and any relevant documentation that's found will be
	// used to generate the HTML text. If the dynamic type is unnamed an
	// error will be returned instead.
	//
	// If the type is none of the above, then the type's source is analyzed
	// and any relevant documentation that's found will be used to generate
	// the HTML text. If the type is unnamed an error will be returned.
	DocA, DocB interface{}
}

The Test type describes the HTTP request to be sent to an endpoint and the corresponding HTTP response that is expected to be received for that request.

type TestGroup

type TestGroup struct {
	// E, short for "endpoint, holds the endpoint to be tested.
	E E
	// N or Name hold the TestGroup's name. Name takes precedence over N.
	//
	// The httptest package uses the name to identify the TestGroup's subtests.
	// The httpdoc package uses the name to generate the link text of the corresponding
	// sidebar item and the heading text for the associated documentation.
	N, Name string
	// The list of tests that will be executed against the endpoint.
	Tests []*Test
	// Indicates that the TestGroup should be skipped by the test runner.
	Skip bool
	// DocA and DocB are optional, they are ignored by the httptest package
	// and are used only by the httpdoc package. The httpdoc package uses
	// the first Test's Request and Response to generate input/output docs
	// for the resulting article.
	//
	// DocA, if set, is used by httpdoc to generate documentation [A]bove the input/output docs.
	// DocB, if set, is used by httpdoc to generate documentation [B]elow the input/output docs.
	//
	// The following types are supported:
	//	- string
	//	- *os.File
	//	- httpdoc.HTMLer
	//	- httpdoc.Valuer
	//	- interface{} (where the dynamic type MUST be declared)
	// Anything else will result in an error.
	//
	// If the type is string, it is expected to contain raw HTML and it is
	// up to the user to ensure that that HTML is valid and safe.
	//
	// If the type is *os.File, it is expected to contain raw HTML and it is
	// up to the user to ensure that that HTML is valid and safe.
	//
	// If the type is httpdoc.HTMLer, then its HTML() method will be used
	// to retrieve the content and it is up to the user to ensure that that
	// content is valid and safe HTML.
	//
	// If the type is httpdoc.Valuer, then its Value() method will be used
	// to get the underlying Value, the source of that Value's dynamic type
	// is then analyzed and any relevant documentation that's found will be
	// used to generate the HTML text. If the dynamic type is unnamed an
	// error will be returned instead.
	//
	// If the type is none of the above, then the type's source is analyzed
	// and any relevant documentation that's found will be used to generate
	// the HTML text. If the type is unnamed an error will be returned.
	DocA, DocB interface{}
	// If set, httpdoc will not generate documentation from this TestGroup.
	SkipDoc bool
}

A TestGroup is a set of tests to be executed against a specific endpoint.