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(title string)
  • func (c *Config) Run(t *testing.T, tgs []*TestGroup)
• 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 T
• type Test
  • func (t *Test) Error(err error)
  • func (t Test) GetName() string
  • func (t Test) GetT() T
• type TestGroup
  • func (tg TestGroup) GetName() string

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 host URL from which the target API is being served.
	HostURL 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
	// SetupAndTeardown is a two-func chain that can be used to setup and
	// teardown the API's internal state needed for an endpoint's test.
	//
	// The setup function is the first one in the chain and it is invoked
	// before a test is executed, the teardown, returned by the setup, is
	// the second one in the chain and it is invoked after the test is executed.
	//
	// If a Test instance has its own SetupAndTeardown, then that will be
	// used instead of this one.
	SetupAndTeardown func(e E, t *Test) (teardown func() error, err error)
	// contains filtered or unexported fields
}

func (*Config) LogReport

func (c *Config) LogReport(title string)

LogReport logs a summary of the test to stderr. It is intended to be called at "teardown".

func (*Config) Run

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

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
}

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
}

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

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
	// SetupAndTeardown is a two-func chain that can be used to setup and
	// teardown the API's internal state needed for an endpoint's test.
	//
	// The setup function is the first one in the chain and it is invoked
	// before a test is executed. The teardown, returned by the setup, is
	// the second one in the chain and it is invoked after the test is executed.
	SetupAndTeardown func(e E, t *Test) (teardown func() error, err error)
	// 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{}
	// contains filtered or unexported fields
}

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.

func (*Test) Error

func (t *Test) Error(err error)

func (Test) GetName

func (t Test) GetName() string

func (Test) GetT

func (t Test) GetT() T

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.

func (TestGroup) GetName

func (tg TestGroup) GetName() string