DefaultTransport is the default mock transport used by Activate, Deactivate, Reset, DeactivateAndReset, RegisterResponder, and RegisterNoResponder.
var DefaultTransport = NewMockTransport()
ErrSubmatchNotFound is the error returned by GetSubmatch* functions when the given submatch index cannot be found.
var ErrSubmatchNotFound = errors.New("submatch not found")
InitialTransport is a cache of the original transport used so we can put it back when Deactivate is called.
var InitialTransport = http.DefaultTransport
NoResponderFound is returned when no responders are found for a given HTTP method and URL.
var NoResponderFound = internal.NoResponderFound
func Activate()
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 httpmock.DefaultTransport.
To enable mocks for a test, simply activate at the beginning of a test:
func TestFetchArticles(t *testing.T) {
httpmock.Activate()
// all http requests using http.DefaultTransport 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()
}
or using a TestMain function:
func TestMain(m *testing.M) {
httpmock.Activate()
os.Exit(m.Run())
}
func ActivateNonDefault(client *http.Client)
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 ConnectionFailure(*http.Request) (*http.Response, error)
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()
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
}
Since go 1.14 you can also use (*testing.T).Cleanup() method as in:
func TestFetchArticles(t *testing.T) {
httpmock.Activate()
t.Cleanup(httpmock.Deactivate)
// when this test ends, the mock environment will close
}
useful in test helpers to save your callers from calling defer themselves.
func DeactivateAndReset()
DeactivateAndReset is just a convenience method for calling Deactivate() and then Reset().
Happy deferring!
func Disabled() bool
Disabled allows to test whether httpmock is enabled or not. It depends on GONOMOCKS environment variable.
func GetCallCountInfo() map[string]int
GetCallCountInfo gets the info on all the calls httpmock has caught since it was activated or reset. The info is returned as a map of the calling keys with the number of calls made to them as their value. The key is the method, a space, and the url all concatenated together.
As a special case, regexp responders generate 2 entries for each call. One for the call caught and the other for the rule that matched. For example:
RegisterResponder("GET", `=~z\.com\z`, NewStringResponder(200, "body"))
http.Get("http://z.com")
will generate the following result:
map[string]int{
`GET http://z.com`: 1,
`GET =~z\.com\z`: 1,
}
func GetSubmatch(req *http.Request, n int) (string, error)
GetSubmatch has to be used in Responders installed by RegisterRegexpResponder or RegisterResponder + "=~" URL prefix. It allows to retrieve the n-th submatch of the matching regexp, as a string. Example:
RegisterResponder("GET", `=~^/item/name/([^/]+)\z`,
func(req *http.Request) (*http.Response, error) {
name, err := GetSubmatch(req, 1) // 1=first regexp submatch
if err != nil {
return nil, err
}
return NewJsonResponse(200, map[string]any{
"id": 123,
"name": name,
})
})
It panics if n < 1. See MustGetSubmatch to avoid testing the returned error.
func GetSubmatchAsFloat(req *http.Request, n int) (float64, error)
GetSubmatchAsFloat has to be used in Responders installed by RegisterRegexpResponder or RegisterResponder + "=~" URL prefix. It allows to retrieve the n-th submatch of the matching regexp, as a float64. Example:
RegisterResponder("PATCH", `=~^/item/id/\d+\?height=(\d+(?:\.\d*)?)\z`,
func(req *http.Request) (*http.Response, error) {
height, err := GetSubmatchAsFloat(req, 1) // 1=first regexp submatch
if err != nil {
return nil, err
}
return NewJsonResponse(200, map[string]any{
"id": id,
"name": "The beautiful name",
"height": height,
})
})
It panics if n < 1. See MustGetSubmatchAsFloat to avoid testing the returned error.
func GetSubmatchAsInt(req *http.Request, n int) (int64, error)
GetSubmatchAsInt has to be used in Responders installed by RegisterRegexpResponder or RegisterResponder + "=~" URL prefix. It allows to retrieve the n-th submatch of the matching regexp, as an int64. Example:
RegisterResponder("GET", `=~^/item/id/(\d+)\z`,
func(req *http.Request) (*http.Response, error) {
id, err := GetSubmatchAsInt(req, 1) // 1=first regexp submatch
if err != nil {
return nil, err
}
return NewJsonResponse(200, map[string]any{
"id": id,
"name": "The beautiful name",
})
})
It panics if n < 1. See MustGetSubmatchAsInt to avoid testing the returned error.
func GetSubmatchAsUint(req *http.Request, n int) (uint64, error)
GetSubmatchAsUint has to be used in Responders installed by RegisterRegexpResponder or RegisterResponder + "=~" URL prefix. It allows to retrieve the n-th submatch of the matching regexp, as a uint64. Example:
RegisterResponder("GET", `=~^/item/id/(\d+)\z`,
func(req *http.Request) (*http.Response, error) {
id, err := GetSubmatchAsUint(req, 1) // 1=first regexp submatch
if err != nil {
return nil, err
}
return NewJsonResponse(200, map[string]any{
"id": id,
"name": "The beautiful name",
})
})
It panics if n < 1. See MustGetSubmatchAsUint to avoid testing the returned error.
func GetTotalCallCount() int
GetTotalCallCount gets the total number of calls httpmock has taken since it was activated or reset.
func MustGetSubmatch(req *http.Request, n int) string
MustGetSubmatch works as GetSubmatch except that it panics in case of error (submatch not found). It has to be used in Responders installed by RegisterRegexpResponder or RegisterResponder + "=~" URL prefix. It allows to retrieve the n-th submatch of the matching regexp, as a string. Example:
RegisterResponder("GET", `=~^/item/name/([^/]+)\z`,
func(req *http.Request) (*http.Response, error) {
name := MustGetSubmatch(req, 1) // 1=first regexp submatch
return NewJsonResponse(200, map[string]any{
"id": 123,
"name": name,
})
})
It panics if n < 1.
func MustGetSubmatchAsFloat(req *http.Request, n int) float64
MustGetSubmatchAsFloat works as GetSubmatchAsFloat except that it panics in case of error (submatch not found or invalid float64 format). It has to be used in Responders installed by RegisterRegexpResponder or RegisterResponder + "=~" URL prefix. It allows to retrieve the n-th submatch of the matching regexp, as a float64. Example:
RegisterResponder("PATCH", `=~^/item/id/\d+\?height=(\d+(?:\.\d*)?)\z`,
func(req *http.Request) (*http.Response, error) {
height := MustGetSubmatchAsFloat(req, 1) // 1=first regexp submatch
return NewJsonResponse(200, map[string]any{
"id": id,
"name": "The beautiful name",
"height": height,
})
})
It panics if n < 1.
func MustGetSubmatchAsInt(req *http.Request, n int) int64
MustGetSubmatchAsInt works as GetSubmatchAsInt except that it panics in case of error (submatch not found or invalid int64 format). It has to be used in Responders installed by RegisterRegexpResponder or RegisterResponder + "=~" URL prefix. It allows to retrieve the n-th submatch of the matching regexp, as an int64. Example:
RegisterResponder("GET", `=~^/item/id/(\d+)\z`,
func(req *http.Request) (*http.Response, error) {
id := MustGetSubmatchAsInt(req, 1) // 1=first regexp submatch
return NewJsonResponse(200, map[string]any{
"id": id,
"name": "The beautiful name",
})
})
It panics if n < 1.
func MustGetSubmatchAsUint(req *http.Request, n int) uint64
MustGetSubmatchAsUint works as GetSubmatchAsUint except that it panics in case of error (submatch not found or invalid uint64 format). It has to be used in Responders installed by RegisterRegexpResponder or RegisterResponder + "=~" URL prefix. It allows to retrieve the n-th submatch of the matching regexp, as a uint64. Example:
RegisterResponder("GET", `=~^/item/id/(\d+)\z`,
func(req *http.Request) (*http.Response, error) {
id, err := MustGetSubmatchAsUint(req, 1) // 1=first regexp submatch
return NewJsonResponse(200, map[string]any{
"id": id,
"name": "The beautiful name",
})
})
It panics if n < 1.
func NewBytesResponse(status int, body []byte) *http.Response
NewBytesResponse creates an *http.Response with a body based on the given bytes. Also accepts an http status code.
To pass the content of an existing file as body use httpmock.File as in:
httpmock.NewBytesResponse(200, httpmock.File("body.raw").Bytes())
func NewJsonResponse(status int, body any) (*http.Response, error)
NewJsonResponse creates an *http.Response with a body that is a json encoded representation of the given any. Also accepts an http status code.
To pass the content of an existing file as body use httpmock.File as in:
httpmock.NewJsonResponse(200, httpmock.File("body.json"))
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.
To pass the content of an existing file as body use httpmock.File as in:
httpmock.NewRespBodyFromBytes(httpmock.File("body.txt").Bytes())
func NewRespBodyFromString(body string) io.ReadCloser
NewRespBodyFromString creates an io.ReadCloser from a string that is suitable for use as an http response body.
To pass the content of an existing file as body use httpmock.File as in:
httpmock.NewRespBodyFromString(httpmock.File("body.txt").String())
func NewStringResponse(status int, body string) *http.Response
NewStringResponse creates an *http.Response with a body based on the given string. Also accepts an http status code.
To pass the content of an existing file as body use httpmock.File as in:
httpmock.NewStringResponse(200, httpmock.File("body.txt").String())
func NewXmlResponse(status int, body any) (*http.Response, error)
NewXmlResponse creates an *http.Response with a body that is an xml encoded representation of the given any. Also accepts an http status code.
To pass the content of an existing file as body use httpmock.File as in:
httpmock.NewXmlResponse(200, httpmock.File("body.xml"))
func RegisterNoResponder(responder Responder)
RegisterNoResponder adds a mock that is 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 RegisterRegexpResponder(method string, urlRegexp *regexp.Regexp, responder Responder)
RegisterRegexpResponder adds a new responder, associated with a given HTTP method and URL (or path) regular expression.
When a request comes in that matches, the responder is called and the response returned to the client.
As 2 regexps can match the same URL, the regexp responders are tested in the order they are registered. Registering an already existing regexp responder (same method & same regexp string) replaces its responder, but does not change its position, and resets the corresponding statistics as returned by GetCallCountInfo().
Registering a nil Responder removes the existing one and the corresponding statistics as returned by GetCallCountInfo(). It does nothing if it does not already exist.
A "=~" prefix is added to the stringified regexp in the statistics returned by GetCallCountInfo().
See RegisterResponder function and the "=~" prefix in its url parameter to avoid compiling the regexp by yourself.
If method is a lower-cased version of CONNECT, DELETE, GET, HEAD, OPTIONS, POST, PUT or TRACE, a panics occurs to notice the possible mistake. This panic can be disabled by setting DefaultTransport.DontCheckMethod to true prior to this call.
func RegisterResponder(method, url string, responder Responder)
RegisterResponder adds a new responder, associated with a given HTTP method and URL (or path).
When a request comes in that matches, the responder is called and the response returned to the client.
If url contains query parameters, their order matters as well as their content. All following URLs are here considered as different:
http://z.tld?a=1&b=1 http://z.tld?b=1&a=1 http://z.tld?a&b http://z.tld?a=&b=
If url begins with "=~", the following chars are considered as a regular expression. If this regexp can not be compiled, it panics. Note that the "=~" prefix remains in statistics returned by GetCallCountInfo(). As 2 regexps can match the same URL, the regexp responders are tested in the order they are registered. Registering an already existing regexp responder (same method & same regexp string) replaces its responder, but does not change its position.
Registering an already existing responder resets the corresponding statistics as returned by GetCallCountInfo().
Registering a nil Responder removes the existing one and the corresponding statistics as returned by GetCallCountInfo(). It does nothing if it does not already exist.
See RegisterRegexpResponder() to directly pass a *regexp.Regexp.
Example:
func TestFetchArticles(t *testing.T) {
httpmock.Activate()
defer httpmock.DeactivateAndReset()
httpmock.RegisterResponder("GET", "http://example.com/",
httpmock.NewStringResponder(200, "hello world"))
httpmock.RegisterResponder("GET", "/path/only",
httpmock.NewStringResponder("any host hello world", 200))
httpmock.RegisterResponder("GET", `=~^/item/id/\d+\z`,
httpmock.NewStringResponder("any item get", 200))
// requests to http://example.com/ now return "hello world" and
// requests to any host with path /path/only return "any host hello world"
// requests to any host with path matching ^/item/id/\d+\z regular expression return "any item get"
}
If method is a lower-cased version of CONNECT, DELETE, GET, HEAD, OPTIONS, POST, PUT or TRACE, a panics occurs to notice the possible mistake. This panic can be disabled by setting DefaultTransport.DontCheckMethod to true prior to this call.
func RegisterResponderWithQuery(method, path string, query any, responder Responder)
RegisterResponderWithQuery it is same as RegisterResponder, but doesn't depends on query items order.
query type can be:
url.Values map[string]string string, a query string like "a=12&a=13&b=z&c" (see net/url.ParseQuery function)
If the query type is not recognized or the string cannot be parsed using net/url.ParseQuery, a panic() occurs.
Unlike RegisterResponder, path cannot be prefixed by "=~" to say it is a regexp. If it is, a panic occurs.
Registering an already existing responder resets the corresponding statistics as returned by GetCallCountInfo().
Registering a nil Responder removes the existing one and the corresponding statistics as returned by GetCallCountInfo(). It does nothing if it does not already exist.
Example using a net/url.Values:
func TestFetchArticles(t *testing.T) {
httpmock.Activate()
defer httpmock.DeactivateAndReset()
expectedQuery := net.Values{
"a": []string{"3", "1", "8"},
"b": []string{"4", "2"},
}
httpmock.RegisterResponderWithQueryValues(
"GET", "http://example.com/", expectedQuery,
httpmock.NewStringResponder("hello world", 200))
// requests to http://example.com?a=1&a=3&a=8&b=2&b=4
// and to http://example.com?b=4&a=2&b=2&a=8&a=1
// now return 'hello world'
}
or using a map[string]string:
func TestFetchArticles(t *testing.T) {
httpmock.Activate()
defer httpmock.DeactivateAndReset()
expectedQuery := map[string]string{
"a": "1",
"b": "2"
}
httpmock.RegisterResponderWithQuery(
"GET", "http://example.com/", expectedQuery,
httpmock.NewStringResponder("hello world", 200))
// requests to http://example.com?a=1&b=2 and http://example.com?b=2&a=1 now return 'hello world'
}
or using a query string:
func TestFetchArticles(t *testing.T) {
httpmock.Activate()
defer httpmock.DeactivateAndReset()
expectedQuery := "a=3&b=4&b=2&a=1&a=8"
httpmock.RegisterResponderWithQueryValues(
"GET", "http://example.com/", expectedQuery,
httpmock.NewStringResponder("hello world", 200))
// requests to http://example.com?a=1&a=3&a=8&b=2&b=4
// and to http://example.com?b=4&a=2&b=2&a=8&a=1
// now return 'hello world'
}
If method is a lower-cased version of CONNECT, DELETE, GET, HEAD, OPTIONS, POST, PUT or TRACE, a panics occurs to notice the possible mistake. This panic can be disabled by setting DefaultTransport.DontCheckMethod to true prior to this call.
func Reset()
Reset removes any registered mocks and returns the mock environment to its initial state. It zeroes call counters too.
func ZeroCallCounters()
ZeroCallCounters zeroes call counters without touching registered responders.
File is a file name. The contents of this file is loaded on demand by the following methods.
Note that:
file := httpmock.File("file.txt")
fmt.Printf("file: %s\n", file)
prints the content of file "file.txt" as String() method is used.
To print the file name, and not its content, simply do:
file := httpmock.File("file.txt")
fmt.Printf("file: %s\n", string(file))
type File string
func (f File) Bytes() []byte
Bytes returns the content of file as a []byte. If an error occurs during the opening or reading of the file, it panics.
Useful to be used in conjunction with NewBytesResponse() or NewBytesResponder() as in:
httpmock.NewBytesResponder(200, httpmock.File("body.raw").Bytes())
func (f File) MarshalJSON() ([]byte, error)
MarshalJSON implements json.Marshaler.
Useful to be used in conjunction with NewJsonResponse() or NewJsonResponder() as in:
httpmock.NewJsonResponder(200, httpmock.File("body.json"))
func (f File) String() string
String returns the content of file as a string. If an error occurs during the opening or reading of the file, it panics.
Useful to be used in conjunction with NewStringResponse() or NewStringResponder() as in:
httpmock.NewStringResponder(200, httpmock.File("body.txt").String())
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 responders.
type MockTransport struct {
// DontCheckMethod disables standard methods check. By default, if
// a responder is registered using a lower-cased method among CONNECT,
// DELETE, GET, HEAD, OPTIONS, POST, PUT and TRACE, a panic occurs
// as it is probably a mistake.
DontCheckMethod bool
// contains filtered or unexported fields
}
func NewMockTransport() *MockTransport
NewMockTransport creates a new *MockTransport with no responders.
func (m *MockTransport) GetCallCountInfo() map[string]int
GetCallCountInfo gets the info on all the calls httpmock has caught since it was activated or reset. The info is returned as a map of the calling keys with the number of calls made to them as their value. The key is the method, a space, and the url all concatenated together.
As a special case, regexp responders generate 2 entries for each call. One for the call caught and the other for the rule that matched. For example:
RegisterResponder("GET", `=~z\.com\z`, NewStringResponder(200, "body"))
http.Get("http://z.com")
will generate the following result:
map[string]int{
`GET http://z.com`: 1,
`GET =~z\.com\z`: 1,
}
func (m *MockTransport) GetTotalCallCount() int
GetTotalCallCount returns the totalCallCount.
func (m *MockTransport) NumResponders() int
NumResponders returns the number of responders currently in use. The responder registered with RegisterNoResponder() is not taken into account.
func (m *MockTransport) RegisterNoResponder(responder Responder)
RegisterNoResponder is used to register a responder that is called if no other responder is found. The default is httpmock.ConnectionFailure that returns an error able to indicate a possible method mismatch.
Use it in conjunction with NewNotFoundResponder to ensure that all routes have been mocked:
import (
"testing"
"github.com/jarcoal/httpmock"
)
...
func TestMyApp(t *testing.T) {
...
// Calls testing.Fatal with the name of Responder-less route and
// the stack trace of the call.
httpmock.RegisterNoResponder(httpmock.NewNotFoundResponder(t.Fatal))
Will abort the current test and print something like:
transport_test.go:735: Called from net/http.Get()
at /go/src/github.com/jarcoal/httpmock/transport_test.go:714
github.com/jarcoal/httpmock.TestCheckStackTracer()
at /go/src/testing/testing.go:865
testing.tRunner()
at /go/src/runtime/asm_amd64.s:1337
If responder is passed as nil, the default behavior (httpmock.ConnectionFailure) is re-enabled.
func (m *MockTransport) RegisterRegexpResponder(method string, urlRegexp *regexp.Regexp, responder Responder)
RegisterRegexpResponder adds a new responder, associated with a given HTTP method and URL (or path) regular expression.
When a request comes in that matches, the responder is called and the response returned to the client.
As 2 regexps can match the same URL, the regexp responders are tested in the order they are registered. Registering an already existing regexp responder (same method & same regexp string) replaces its responder, but does not change its position, and resets the corresponding statistics as returned by GetCallCountInfo().
Registering a nil Responder removes the existing one and the corresponding statistics as returned by GetCallCountInfo(). It does nothing if it does not already exist.
A "=~" prefix is added to the stringified regexp in the statistics returned by GetCallCountInfo().
See RegisterResponder function and the "=~" prefix in its url parameter to avoid compiling the regexp by yourself.
If method is a lower-cased version of CONNECT, DELETE, GET, HEAD, OPTIONS, POST, PUT or TRACE, a panics occurs to notice the possible mistake. This panic can be disabled by setting m.DontCheckMethod to true prior to this call.
func (m *MockTransport) RegisterResponder(method, url string, responder Responder)
RegisterResponder adds a new responder, associated with a given HTTP method and URL (or path).
When a request comes in that matches, the responder is called and the response returned to the client.
If url contains query parameters, their order matters as well as their content. All following URLs are here considered as different:
http://z.tld?a=1&b=1 http://z.tld?b=1&a=1 http://z.tld?a&b http://z.tld?a=&b=
If url begins with "=~", the following chars are considered as a regular expression. If this regexp can not be compiled, it panics. Note that the "=~" prefix remains in statistics returned by GetCallCountInfo(). As 2 regexps can match the same URL, the regexp responders are tested in the order they are registered. Registering an already existing regexp responder (same method & same regexp string) replaces its responder, but does not change its position.
Registering an already existing responder resets the corresponding statistics as returned by GetCallCountInfo().
Registering a nil Responder removes the existing one and the corresponding statistics as returned by GetCallCountInfo(). It does nothing if it does not already exist.
See RegisterRegexpResponder() to directly pass a *regexp.Regexp.
Example:
func TestFetchArticles(t *testing.T) {
httpmock.Activate()
defer httpmock.DeactivateAndReset()
httpmock.RegisterResponder("GET", "http://example.com/",
httpmock.NewStringResponder(200, "hello world"))
httpmock.RegisterResponder("GET", "/path/only",
httpmock.NewStringResponder("any host hello world", 200))
httpmock.RegisterResponder("GET", `=~^/item/id/\d+\z`,
httpmock.NewStringResponder("any item get", 200))
// requests to http://example.com/ now return "hello world" and
// requests to any host with path /path/only return "any host hello world"
// requests to any host with path matching ^/item/id/\d+\z regular expression return "any item get"
}
If method is a lower-cased version of CONNECT, DELETE, GET, HEAD, OPTIONS, POST, PUT or TRACE, a panics occurs to notice the possible mistake. This panic can be disabled by setting m.DontCheckMethod to true prior to this call.
func (m *MockTransport) RegisterResponderWithQuery(method, path string, query any, responder Responder)
RegisterResponderWithQuery is same as RegisterResponder, but it doesn't depend on query items order.
If query is non-nil, its type can be:
url.Values map[string]string string, a query string like "a=12&a=13&b=z&c" (see net/url.ParseQuery function)
If the query type is not recognized or the string cannot be parsed using net/url.ParseQuery, a panic() occurs.
Unlike RegisterResponder, path cannot be prefixed by "=~" to say it is a regexp. If it is, a panic occurs.
Registering an already existing responder resets the corresponding statistics as returned by GetCallCountInfo().
Registering a nil Responder removes the existing one and the corresponding statistics as returned by GetCallCountInfo(). It does nothing if it does not already exist.
If method is a lower-cased version of CONNECT, DELETE, GET, HEAD, OPTIONS, POST, PUT or TRACE, a panics occurs to notice the possible mistake. This panic can be disabled by setting m.DontCheckMethod to true prior to this call.
func (m *MockTransport) Reset()
Reset removes all registered responders (including the no responder) from the MockTransport. It zeroes call counters too.
func (m *MockTransport) Responders() []string
Responders returns the list of currently registered responders. Each responder is listed as a string containing "METHOD URL". Non-regexp responders are listed first in alphabetical order (sorted by URL then METHOD), then regexp responders in the order they have been registered. The responder registered with RegisterNoResponder() is not listed.
func (m *MockTransport) RoundTrip(req *http.Request) (*http.Response, error)
RoundTrip receives HTTP requests and routes them to the appropriate responder. It is required to implement the http.RoundTripper interface. You will not interact with this directly, instead the *http.Client you are using will call it for you.
func (m *MockTransport) ZeroCallCounters()
ZeroCallCounters zeroes call counters without touching registered responders.
Responder is a callback that receives an http request and returns a mocked response.
type Responder func(*http.Request) (*http.Response, error)
func NewBytesResponder(status int, body []byte) Responder
NewBytesResponder creates a Responder from a given body (as a byte slice) and status code.
To pass the content of an existing file as body use httpmock.File as in:
httpmock.NewBytesResponder(200, httpmock.File("body.raw").Bytes())
func NewErrorResponder(err error) Responder
NewErrorResponder creates a Responder that returns an empty request and the given error. This can be used to e.g. imitate more deep http errors for the client.
func NewJsonResponder(status int, body any) (Responder, error)
NewJsonResponder creates a Responder from a given body (as an any that is encoded to json) and status code.
To pass the content of an existing file as body use httpmock.File as in:
httpmock.NewJsonResponder(200, httpmock.File("body.json"))
func NewJsonResponderOrPanic(status int, body any) Responder
NewJsonResponderOrPanic is like NewJsonResponder but panics in case of error.
It simplifies the call of RegisterResponder, avoiding the use of a temporary variable and an error check, and so can be used as NewStringResponder or NewBytesResponder in such context:
httpmock.RegisterResponder( "GET", "/test/path", httpmock.NewJSONResponderOrPanic(200, &MyBody), )
To pass the content of an existing file as body use httpmock.File as in:
httpmock.NewJsonResponderOrPanic(200, httpmock.File("body.json"))
func NewNotFoundResponder(fn func(...any)) Responder
NewNotFoundResponder creates a Responder typically used in conjunction with RegisterNoResponder() function and testing package, to be proactive when a Responder is not found. fn is called with a unique string parameter containing the name of the missing route and the stack trace to localize the origin of the call. If fn returns (= if it does not panic), the responder returns an error of the form: "Responder not found for GET http://foo.bar/path". Note that fn can be nil.
It is useful when writing tests to ensure that all routes have been mocked.
Example of use:
import (
"testing"
"github.com/jarcoal/httpmock"
)
...
func TestMyApp(t *testing.T) {
...
// Calls testing.Fatal with the name of Responder-less route and
// the stack trace of the call.
httpmock.RegisterNoResponder(httpmock.NewNotFoundResponder(t.Fatal))
Will abort the current test and print something like:
transport_test.go:735: Called from net/http.Get()
at /go/src/github.com/jarcoal/httpmock/transport_test.go:714
github.com/jarcoal/httpmock.TestCheckStackTracer()
at /go/src/testing/testing.go:865
testing.tRunner()
at /go/src/runtime/asm_amd64.s:1337
func NewStringResponder(status int, body string) Responder
NewStringResponder creates a Responder from a given body (as a string) and status code.
To pass the content of an existing file as body use httpmock.File as in:
httpmock.NewStringResponder(200, httpmock.File("body.txt").String())
func NewXmlResponder(status int, body any) (Responder, error)
NewXmlResponder creates a Responder from a given body (as an any that is encoded to xml) and status code.
To pass the content of an existing file as body use httpmock.File as in:
httpmock.NewXmlResponder(200, httpmock.File("body.xml"))
func NewXmlResponderOrPanic(status int, body any) Responder
NewXmlResponderOrPanic is like NewXmlResponder but panics in case of error.
It simplifies the call of RegisterResponder, avoiding the use of a temporary variable and an error check, and so can be used as NewStringResponder or NewBytesResponder in such context:
httpmock.RegisterResponder( "GET", "/test/path", httpmock.NewXmlResponderOrPanic(200, &MyBody), )
To pass the content of an existing file as body use httpmock.File as in:
httpmock.NewXmlResponderOrPanic(200, httpmock.File("body.xml"))
func ResponderFromMultipleResponses(responses []*http.Response, fn ...func(...any)) Responder
ResponderFromMultipleResponses wraps an *http.Response list in a Responder.
Each response will be returned in the order of the provided list. If the responder is called more than the size of the provided list, an error will be thrown.
Be careful, except for responses generated by httpmock (NewStringResponse and NewBytesResponse functions) for which there is no problems, it is the caller responsibility to ensure the response body can be read several times and concurrently if needed, as it is shared among all Responder returned responses.
For home-made responses, NewRespBodyFromString and NewRespBodyFromBytes functions can be used to produce response bodies that can be read several times and concurrently.
If all responses have been returned and fn is passed and non-nil, it acts as the fn parameter of NewNotFoundResponder, allowing to dump the stack trace to localize the origin of the call.
import (
"github.com/jarcoal/httpmock"
"testing"
)
...
func TestMyApp(t *testing.T) {
...
// This responder is callable only once, then an error is returned and
// the stacktrace of the call logged using t.Log()
httpmock.RegisterResponder("GET", "/foo/bar",
httpmock.ResponderFromMultipleResponses(
[]*http.Response{
httpmock.NewStringResponse(200, `{"name":"bar"}`),
httpmock.NewStringResponse(404, `{"mesg":"Not found"}`),
},
t.Log),
)
}
func ResponderFromResponse(resp *http.Response) Responder
ResponderFromResponse wraps an *http.Response in a Responder.
Be careful, except for responses generated by httpmock (NewStringResponse and NewBytesResponse functions) for which there is no problems, it is the caller responsibility to ensure the response body can be read several times and concurrently if needed, as it is shared among all Responder returned responses.
For home-made responses, NewRespBodyFromString and NewRespBodyFromBytes functions can be used to produce response bodies that can be read several times and concurrently.
func (r Responder) Delay(d time.Duration) Responder
Delay returns a new Responder that calls the original r Responder after a delay of d.
import (
"testing"
"time"
"github.com/jarcoal/httpmock"
)
...
func TestMyApp(t *testing.T) {
...
httpmock.RegisterResponder("GET", "/foo/bar",
httpmock.NewStringResponder(200, "{}").Delay(100*time.Millisecond),
)
func (r Responder) Once(fn ...func(...any)) Responder
Once returns a new Responder callable once before returning an error. If the Responder is called 2 or more times and fn is passed and non-nil, it acts as the fn parameter of NewNotFoundResponder, allowing to dump the stack trace to localize the origin of the call.
import (
"testing"
"github.com/jarcoal/httpmock"
)
...
func TestMyApp(t *testing.T) {
...
// This responder is callable only once, then an error is returned and
// the stacktrace of the call logged using t.Log()
httpmock.RegisterResponder("GET", "/foo/bar",
httpmock.NewStringResponder(200, "{}").Once(t.Log),
)
func (r Responder) Then(next Responder) (x Responder)
Then returns a new Responder that calls r on first invocation, then next on following ones, except when Then is chained, in this case next is called only once:
A := httpmock.NewStringResponder(200, "A")
B := httpmock.NewStringResponder(200, "B")
C := httpmock.NewStringResponder(200, "C")
httpmock.RegisterResponder("GET", "/pipo", A.Then(B).Then(C))
http.Get("http://foo.bar/pipo") // A is called
http.Get("http://foo.bar/pipo") // B is called
http.Get("http://foo.bar/pipo") // C is called
http.Get("http://foo.bar/pipo") // C is called, and so on
A panic occurs if next is the result of another Then call (because allowing it could cause inextricable problems at runtime). Then calls can be chained, but cannot call each other by parameter. Example:
A.Then(B).Then(C) // is OK A.Then(B.Then(C)) // panics as A.Then() parameter is another Then() call
func (r Responder) Times(n int, fn ...func(...any)) Responder
Times returns a Responder callable n times before returning an error. If the Responder is called more than n times and fn is passed and non-nil, it acts as the fn parameter of NewNotFoundResponder, allowing to dump the stack trace to localize the origin of the call.
import (
"testing"
"github.com/jarcoal/httpmock"
)
...
func TestMyApp(t *testing.T) {
...
// This responder is callable 3 times, then an error is returned and
// the stacktrace of the call logged using t.Log()
httpmock.RegisterResponder("GET", "/foo/bar",
httpmock.NewStringResponder(200, "{}").Times(3, t.Log),
)
func (r Responder) Trace(fn func(...any)) Responder
Trace returns a new Responder that allows to easily trace the calls of the original Responder using fn. It can be used in conjunction with the testing package as in the example below with the help of (*testing.T).Log method:
import (
"testing"
"github.com/jarcoal/httpmock"
)
...
func TestMyApp(t *testing.T) {
...
httpmock.RegisterResponder("GET", "/foo/bar",
httpmock.NewStringResponder(200, "{}").Trace(t.Log),
)
| Name | Synopsis |
|---|---|
| .. | |