httpmock

README

httpmock

This library builds on Go's built-in httptest library, adding a more mockable interface that can be used easily with other mocking tools like testify/mock. It does this by providing a Handler that receives HTTP components separately rather than an *http.Request object.

Where the typical http.Handler interface is:

type Handler interface {
	ServeHTTP(ResponseWriter, *Request)
}

This library provides a server with the following interface, which works naturally with mocking libraries:

// Handler is the interface used by httpmock instead of http.Handler so that it can be mocked very easily.
type Handler interface {
	Handle(method, path string, body []byte) Response
}

Examples

The most primitive example, the OKHandler, just returns 200 OK to everything.

s := httpmock.NewServer(&httpmock.OKHandler{})
defer s.Close()

// Make any requests you want to s.URL(), using it as the mock downstream server

This example uses MockHandler, a Handler that is a testify/mock object.

downstream := &httpmock.MockHandler{}

// A simple GET that returns some pre-canned content
downstream.On("Handle", "GET", "/object/12345", mock.Anything).Return(httpmock.Response{
    Body: []byte(`{"status": "ok"}`),
})

s := httpmock.NewServer(downstream)
defer s.Close()

//
// Make any requests you want to s.URL(), using it as the mock downstream server
//

downstream.AssertExpectations(t)

The httpmock package also provides helpers for checking calls using json objects, like so:

// This tests a hypothetical "echo" endpoint, which returns the body we pass to it.
type Obj struct {
    A string `json:"a"`
}

o := &Obj{A: "aye"}

// JSONMatcher ensures that this mock is triggered only when the HTTP body, when deserialized, matches the given
// object. Here, this mock response will get triggered only if `{"a":"aye"}` is sent.
downstream.On("Handle", "POST", "/echo", httpmock.JSONMatcher(o)).Return(httpmock.Response{
    Body: httpmock.ToJSON(o),
})

Documentation

Overview

Package httpmock builds on httptest, providing easier API mocking.

Essentially all httpmock does is implement a similar interface to httptest, but using a Handler that receives the HTTP method, path, and body rather than a request object. This makes it very easy to use a featureful mock as the handler, e.g. github.com/stretchr/testify/mock

Examples

s := httpmock.NewServer(&httpmock.OKHandler{})
defer s.Close()

// Make any requests you want to s.URL(), using it as the mock downstream server

This example uses MockHandler, a Handler that is a github.com/stretchr/testify/mock object.

downstream := &httpmock.MockHandler{}

// A simple GET that returns some pre-canned content
downstream.On("Handle", "GET", "/object/12345", mock.Anything).Return(httpmock.Response{
	Body: []byte(`{"status": "ok"}`),
})

s := httpmock.NewServer(downstream)
defer s.Close()

//
// Make any requests you want to s.URL(), using it as the mock downstream server
//

downstream.AssertExpectations(t)

Httpmock also provides helpers for checking calls using json objects, like so:

// This tests a hypothetical "echo" endpoint, which returns the body we pass to it.
type Obj struct {
	A string `json:"a"`
	B string `json:"b"`
}

o := &Obj{A: "ay", B: "bee"}

// JSONMatcher ensures that this mock is triggered only when the HTTP body, when deserialized, matches the given
// object.
downstream.On("Handle", "POST", "/echo", httpmock.JSONMatcher(o)).Return(httpmock.Response{
	Body: httpmock.ToJSON(o),
})

Index

• func JSONMatcher(o1 interface{}) interface{}
• func ToJSON(obj interface{}) []byte
• type Handler
• type MockHandler
  • func (m *MockHandler) Handle(method, path string, body []byte) Response
• type OKHandler
  • func (r *OKHandler) Handle(method, path string, body []byte) Response
• type Response
• type Server
  • func NewServer(handler Handler) *Server
  • func NewUnstartedServer(handler Handler) *Server
  • func (s *Server) Close()
  • func (s *Server) Start()
  • func (s *Server) URL() string

Functions

func JSONMatcher

func JSONMatcher(o1 interface{}) interface{}

JSONMatcher returns a mock.MatchedBy func to check if the argument is the json form of the provided object. See the github.com/stretchr/testify/mock documentation and example in httpmock.go.

func ToJSON

func ToJSON(obj interface{}) []byte

ToJSON is a convenience function for converting an object to JSON inline. It panics on failure, so should be used only in test code.

Types

type Handler

type Handler interface {
	Handle(method, path string, body []byte) Response
}

Handler is the interface used by httpmock instead of http.Handler so that it can be mocked very easily.

type MockHandler

type MockHandler struct {
	mock.Mock
}

MockHandler is a httpmock.Handler that uses github.com/stretchr/testify/mock.

func (*MockHandler) Handle

func (m *MockHandler) Handle(method, path string, body []byte) Response

Handle makes this implement the Handler interface.

type OKHandler

type OKHandler struct {
}

OKHandler is a simple Handler that returns 200 OK responses for any request.

func (*OKHandler) Handle

func (r *OKHandler) Handle(method, path string, body []byte) Response

Handle makes this implement the Handler interface.

type Response

type Response struct {
	// The HTTP status code to write (default: 200)
	Status int
	// Headers to add to the response
	Header http.Header
	// The response body to write (default: no body)
	Body []byte
}

Response holds the response a handler wants to return to the client.

type Server

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

Server listens for requests and interprets them into calls to your Handler.

func NewServer

func NewServer(handler Handler) *Server

NewServer constructs a new server and starts it (compare to httptest.NewServer). It needs to be Closed()ed.

func NewUnstartedServer

func NewUnstartedServer(handler Handler) *Server

NewServer constructs a new server but doesn't start it (compare to httptest.NewUnstartedServer).

func (*Server) Close

func (s *Server) Close()

Close shuts down a started server.

func (*Server) Start

func (s *Server) Start()

Start starts an unstarted server.

func (*Server) URL

func (s *Server) URL() string

URL is the URL for the local test server, i.e. the value of httptest.Server.URL