Documentation ¶
Overview ¶
Package httpmock provides tools for mocking HTTP responses.
Simple Example:
func TestFetchArticles(t *testing.T) { httpmock.Activate() defer httpmock.DeactivateAndReset() httpmock.RegisterStubRequest( httpmock.NewStubRequest( "GET", "https://api.mybiz.com/articles.json", httpmock.NewStringResponder(200, `[{"id": 1, "name": "My Great Article"}]`), ), ) // do stuff that makes a request to articles.json // verify that all stubs were called if err := httpmock.AllStubsCalled(); err != nil { t.Errorf("Not all stubs were called: %s", err) } }
Advanced Example:
func TestFetchArticles(t *testing.T) { httpmock.Activate( WithAllowedHosts("localhost"), ) defer httpmock.DeactivateAndReset() // our database of articles articles := make([]map[string]interface{}, 0) // mock to list out the articles httpmock.RegisterStubRequest( httpmock.NewStubRequest( "GET", "https://api.mybiz.com/articles.json", func(req *http.Request) (*http.Response, error) { resp, err := httpmock.NewJsonResponse(200, articles) if err != nil { return httpmock.NewStringResponse(500, ""), nil } return resp }, ).WithHeader( &http.Header{ "Api-Key": []string{"1234abcd"}, }, ), ) // mock to add a new article httpmock.RegisterStubRequest( httpmock.NewStubRequest( "POST", "https://api.mybiz.com/articles.json", func(req *http.Request) (*http.Response, error) { article := make(map[string]interface{}) if err := json.NewDecoder(req.Body).Decode(&article); err != nil { return httpmock.NewStringResponse(400, ""), nil } articles = append(articles, article) resp, err := httpmock.NewJsonResponse(200, article) if err != nil { return httpmock.NewStringResponse(500, ""), nil } return resp, nil }, ).WithHeader( &http.Header{ "Api-Key": []string{"1234abcd"}, }, ).WithBody( bytes.NewBufferString(`{"title":"article"}`), ), ) // do stuff that adds and checks articles // verify that all stubs were called if err := httpmock.AllStubsCalled(); err != nil { t.Errorf("Not all stubs were called: %s", err) } }
Index ¶
- Variables
- func Activate(opts ...func())
- func ActivateNonDefault(client *http.Client, opts ...func())
- func AllStubsCalled() error
- func ConnectionFailure(req *http.Request, err error) (*http.Response, error)
- func Deactivate()
- func DeactivateAndReset()
- func Disabled() bool
- func NewBytesResponse(status int, body []byte) *http.Response
- func NewJSONResponse(status int, body interface{}) (*http.Response, error)
- func NewRespBodyFromBytes(body []byte) io.ReadCloser
- func NewRespBodyFromString(body string) io.ReadCloser
- func NewStringResponse(status int, body string) *http.Response
- func NewXMLResponse(status int, body interface{}) (*http.Response, error)
- func RegisterNoResponder(responder Responder)
- func RegisterStubRequest(request *StubRequest)
- func Reset()
- func WithAllowedHosts(hosts ...string) func()
- type ErrNoResponderFound
- type ErrStubsNotCalled
- type MockTransport
- func (m *MockTransport) AllStubsCalled() error
- func (m *MockTransport) CancelRequest(req *http.Request)
- func (m *MockTransport) RegisterNoResponder(responder Responder)
- func (m *MockTransport) RegisterStubRequest(stub *StubRequest)
- func (m *MockTransport) Reset()
- func (m *MockTransport) RoundTrip(req *http.Request) (*http.Response, error)
- type Responder
- func NewBytesResponder(status int, body []byte) Responder
- func NewJSONResponder(status int, body interface{}) (Responder, error)
- func NewStringResponder(status int, body string) Responder
- func NewXMLResponder(status int, body interface{}) (Responder, error)
- func ResponderFromResponse(resp *http.Response) Responder
- type StubRequest
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var ( // ErrIncorrectMethod is the error returned when Matches detects an incorrect // HTTP method ErrIncorrectMethod = errors.New("Incorrect request method attempted") // ErrIncorrectURL is the error returned when Matches detects an incorrect // normalized URL ErrIncorrectURL = errors.New("Incorrect URL used") // ErrIncorrectHeaders is the error returned when Matches detects incorrect // headers sent ErrIncorrectHeaders = errors.New("Incorrect HTTP headers sent") // ErrIncorrectRequestBody = is the error returned when Matches detects an // incorrect request body was sent ErrIncorrectRequestBody = errors.New("Incorrect request body sent") )
var ErrNoResponders = NewErrNoResponderFound(nil)
ErrNoResponders is an instance of ErrNoResponderFound created when no errors returned, i.e. no registered responders
Functions ¶
func Activate ¶
func Activate(opts ...func())
Activate starts the mock environment. This should be called before your tests run. Under the hood this replaces the Transport on the http.DefaultClient with mockTransport.
To enable mocks for a test, simply activate at the beginning of a test:
func TestFetchArticles(t *testing.T) { httpmock.Activate() // all http requests will now be intercepted }
If you want all of your tests in a package to be mocked, just call Activate from init():
func init() { httpmock.Activate() }
Activate takes a variadic list of functions to configure the behaviour of httpmock.
func ActivateNonDefault ¶
ActivateNonDefault starts the mock environment with a non-default http.Client. This emulates the Activate function, but allows for custom clients that do not use http.DefaultTransport
To enable mocks for a test using a custom client, activate at the beginning of a test:
client := &http.Client{Transport: &http.Transport{TLSHandshakeTimeout: 60 * time.Second}} httpmock.ActivateNonDefault(client)
func AllStubsCalled ¶
func AllStubsCalled() error
AllStubsCalled is a function intended to be used within your tests to verify that all registered stubs were actually invoked during the course of the test. Registering stubs but then not calling them is either a sign that something is wrong in your test, or a waste of time. This function retuns an error unless all currently registered stubs were called.
func ConnectionFailure ¶
ConnectionFailure is a responder that returns a connection failure. This is the default responder, and is called when no other matching responder is found.
func Deactivate ¶
func Deactivate()
Deactivate shuts down the mock environment. Any HTTP calls made after this will use a live transport.
Usually you'll call it in a defer right after activating the mock environment:
func TestFetchArticles(t *testing.T) { httpmock.Activate() defer httpmock.Deactivate() // when this test ends, the mock environment will close }
func DeactivateAndReset ¶
func DeactivateAndReset()
DeactivateAndReset is just a convenience method for calling Deactivate() and then Reset() Happy deferring!
func Disabled ¶
func Disabled() bool
Disabled returns true if the GONOMOCKS environment variable is not empty
func NewBytesResponse ¶
NewBytesResponse creates an *http.Response with a body based on the given bytes. Also accepts an http status code.
func NewJSONResponse ¶
NewJSONResponse creates an *http.Response with a body that is a json encoded representation of the given interface{}. Also accepts an http status code.
func NewRespBodyFromBytes ¶
func NewRespBodyFromBytes(body []byte) io.ReadCloser
NewRespBodyFromBytes creates an io.ReadCloser from a byte slice that is suitable for use as an http response body.
func NewRespBodyFromString ¶
func NewRespBodyFromString(body string) io.ReadCloser
NewRespBodyFromString creates an io.ReadCloser from a string that is suitable for use as an http response body.
func NewStringResponse ¶
NewStringResponse creates an *http.Response with a body based on the given string. Also accepts an http status code.
func NewXMLResponse ¶
NewXMLResponse creates an *http.Response with a body that is an xml encoded representation of the given interface{}. Also accepts an http status code.
func RegisterNoResponder ¶
func RegisterNoResponder(responder Responder)
RegisterNoResponder adds a mock that will be called whenever a request for an unregistered URL is received. The default behavior is to return a connection error.
In some cases you may not want all URLs to be mocked, in which case you can do this:
func TestFetchArticles(t *testing.T) { httpmock.Activate() defer httpmock.DeactivateAndReset() httpmock.RegisterNoResponder(httpmock.InitialTransport.RoundTrip) // any requests that don't have a registered URL will be fetched normally }
func RegisterStubRequest ¶
func RegisterStubRequest(request *StubRequest)
RegisterStubRequest adds a mock that will catch requests to the given HTTP method and URL, then route them to the Responder which will generate a response to be returned to the client.
Example ¶
package main import ( "fmt" "io/ioutil" "net/http" "github.com/thingful/httpmock" ) func main() { httpmock.Activate() defer httpmock.DeactivateAndReset() httpmock.RegisterStubRequest( httpmock.NewStubRequest( "GET", "http://example.com/", httpmock.NewStringResponder(200, "ok"), ), ) resp, err := http.Get("http://example.com/") if err != nil { // handle error properly in real code panic(err) } defer resp.Body.Close() body, err := ioutil.ReadAll(resp.Body) if err != nil { // handle error properly in real code panic(err) } fmt.Println(string(body)) if err = httpmock.AllStubsCalled(); err != nil { // handle error properly in real code panic(err) } }
Output: ok
func Reset ¶
func Reset()
Reset will remove any registered mocks and return the mock environment to it's initial state.
func WithAllowedHosts ¶ added in v0.0.2
func WithAllowedHosts(hosts ...string) func()
WithAllowedHosts is used to configure the behaviour of httpmock, by allowing clients to specify a list of allowed hosts when calling Activate. A list of hostnames excluding any scheme or port parts can be passed here, and any requests matching that hostname will be allowed to proceed as normal.
Types ¶
type ErrNoResponderFound ¶
type ErrNoResponderFound struct {
// contains filtered or unexported fields
}
ErrNoResponderFound is a custom error type used when no responders were found.
func NewErrNoResponderFound ¶
func NewErrNoResponderFound(errs []error) *ErrNoResponderFound
NewErrNoResponderFound returns a new ErrNoResponderFound error
func (*ErrNoResponderFound) Error ¶
func (e *ErrNoResponderFound) Error() string
Error ensures our ErrNoResponderFound type implements the error interface
type ErrStubsNotCalled ¶
type ErrStubsNotCalled struct {
// contains filtered or unexported fields
}
ErrStubsNotCalled is a type implementing the error interface we return when not all registered stubs were called
func NewErrStubsNotCalled ¶
func NewErrStubsNotCalled(uncalledStubs []*StubRequest) *ErrStubsNotCalled
NewErrStubsNotCalled returns a new StubsNotCalled error
func (*ErrStubsNotCalled) Error ¶
func (e *ErrStubsNotCalled) Error() string
Error ensures our ErrStubsNotCalled type implements the error interface
type MockTransport ¶
type MockTransport struct {
// contains filtered or unexported fields
}
MockTransport implements http.RoundTripper, which fulfills single http requests issued by an http.Client. This implementation doesn't actually make the call, instead deferring to the registered list of stubbed requests.
func NewMockTransport ¶
func NewMockTransport() *MockTransport
NewMockTransport creates a new *MockTransport with no stubbed requests.
func (*MockTransport) AllStubsCalled ¶
func (m *MockTransport) AllStubsCalled() error
AllStubsCalled returns nil if all of the currently registered stubs have been called; if some haven't been called, then it returns an error.
func (*MockTransport) CancelRequest ¶
func (m *MockTransport) CancelRequest(req *http.Request)
CancelRequest does nothing with timeout
func (*MockTransport) RegisterNoResponder ¶
func (m *MockTransport) RegisterNoResponder(responder Responder)
RegisterNoResponder is used to register a responder that will be called if no other responder is found. The default is ConnectionFailure.
func (*MockTransport) RegisterStubRequest ¶
func (m *MockTransport) RegisterStubRequest(stub *StubRequest)
RegisterStubRequest adds a new responder, associated with a given stubbed request. When a request comes in that matches, the responder will be called and the response returned to the client.
func (*MockTransport) Reset ¶
func (m *MockTransport) Reset()
Reset removes all registered responders (including the no responder) from the MockTransport
type Responder ¶
Responder types are callbacks that receive and http request and return a mocked response.
func NewBytesResponder ¶
NewBytesResponder creates a Responder from a given body (as a byte slice) and status code.
func NewJSONResponder ¶
NewJSONResponder creates a Responder from a given body (as an interface{} that is encoded to json) and status code.
func NewStringResponder ¶
NewStringResponder creates a Responder from a given body (as a string) and status code.
func NewXMLResponder ¶
NewXMLResponder creates a Responder from a given body (as an interface{} that is encoded to xml) and status code.
func ResponderFromResponse ¶
ResponderFromResponse wraps an *http.Response in a Responder
type StubRequest ¶
type StubRequest struct { Method string URL string Header *http.Header Body io.Reader Responder Responder Called bool }
StubRequest is used to capture data about a new stubbed request. It wraps up the Method and URL along with optional http.Header struct, holds the Responder used to generate a response, and also has a flag indicating whether or not this stubbed request has actually been called.
func NewStubRequest ¶
func NewStubRequest(method, url string, responder Responder) *StubRequest
NewStubRequest is a constructor function that returns a StubRequest for the given method and url. We also supply a responder which actually generates the response should the stubbed request match the request.
func (*StubRequest) Matches ¶
func (r *StubRequest) Matches(req *http.Request) error
Matches is a test function that returns true if an incoming request is matched by this fetcher. Should an incoming request URL cause an error when normalized, we return false.
func (*StubRequest) String ¶
func (r *StubRequest) String() string
func (*StubRequest) WithBody ¶
func (r *StubRequest) WithBody(body io.Reader) *StubRequest
WithBody is a function used to add a body to a stubbed request
func (*StubRequest) WithHeader ¶
func (r *StubRequest) WithHeader(header *http.Header) *StubRequest
WithHeader is a function used to add http headers onto a stubbed request.