httpfixture

README

orkes-io/go-httpfixture

Go helpers for unit testing using dead simple HTTP fixtures.

Usage

Installation via go get

go get github.com/orkes-io/go-httpfixture

This package provides logicless HTTP fixtures which provide a fixed response to requests, optionally asserting that the request matches an expected form.

Basic usage in a Go unit test:

package example

import (
	"testing"
	"net/http"
	"github.com/orkes-io/go-httpfixture"
)

func TestHTTP(t *testing.T) {
	s := httpfixture.NewServer(
		httpfixture.GetOK("/api/example", `{"response":"hello fixture"}`),
    )
	s.Start(t)
	defer s.Close()
	
	resp, err := http.Get(s.URL() + "/api/example")
	if err != nil {
		t.Fatalf("unexpected error: %v", err)
	}
	if resp.StatusCode != 200 {
	    t.Fatalf("expected 200 OK; got: %s", resp.StatusCode)	
    }
}

The above test starts a server which contains a single fixture, makes a GET request against the fixture, and asserts the success completed succesfully.

httpfixture serves as a terser alternative to net/http/httptest, which may be better suited to table-driven tests. All contributions are welcome! Please read the Contributor Covenant Code of Conduct prior to contributing.

Documentation

Overview

Package httpfixture provides HTTP fixtures for testing code that makes requests via HTTP servers. It aims to provide a more convenient abstraction than httptest, resulting in tests that use less code. All fixtures provided by this package are logicless: responses from the fixture are fixed and do not depend on the incoming request.

Index

• type F
  • func Bytes(route, method string, responseCode int, body []byte, opts ...FixtureOpt) F
  • func BytesOK(route string, method string, body []byte, opts ...FixtureOpt) F
  • func File(route, method string, responseCode int, path string, opts ...FixtureOpt) F
  • func FileOK(route, method string, path string, opts ...FixtureOpt) F
  • func GetBytesOK(route string, body []byte, opts ...FixtureOpt) F
  • func GetFileOK(route, path string, opts ...FixtureOpt) F
  • func GetOK(route string, body string, opts ...FixtureOpt) F
  • func NotFound(route, method string, opts ...FixtureOpt) F
  • func OK(route string, body string, opts ...FixtureOpt) F
  • func Reader(route, method string, responseCode int, reader io.Reader, opts ...FixtureOpt) F
  • func ResponseCode(route, method string, responseCode int, opts ...FixtureOpt) F
  • func Seq(route, method string, fixtures ...F) F
• type FixtureOpt
  • func AssertBodyContains(str string) FixtureOpt
  • func AssertBodyContainsBytes(b []byte) FixtureOpt
  • func AssertHeaderMatches(key, value string) FixtureOpt
  • func AssertURLContains(substr string) FixtureOpt
• type Server
  • func NewServer(fixtures ...F) *Server
  • func (s *Server) Close()
  • func (s *Server) ServeHTTP(rw http.ResponseWriter, req *http.Request)
  • func (s *Server) Start(t *testing.T)
  • func (s *Server) StartTLS(t *testing.T)
  • func (s *Server) URL() string

Types

type F

type F interface {
	// Run runs this fixture, exchanging the provided request for a response.
	Run(t *testing.T, req *http.Request) *http.Response
	// Route returns the route where this Fixture is hosted.
	Route() string
	// Method returns the method which this Fixture matches on.
	Method() string
}

F is an HTTP fixture.

func Bytes

func Bytes(route, method string, responseCode int, body []byte, opts ...FixtureOpt) F

Bytes returns a fixture which responds to requests with the provided route and HTTP method with the provided body and status code.

func BytesOK

func BytesOK(route string, method string, body []byte, opts ...FixtureOpt) F

BytesOK returns a fixture which responds to requests at the provided route and HTTP method with the provided body, and status 200 OK.

func File

func File(route, method string, responseCode int, path string, opts ...FixtureOpt) F

File returns a fixture which responds to matching requests with the contents of the provided file, which are read into memory by this func.

func FileOK

func FileOK(route, method string, path string, opts ...FixtureOpt) F

FileOK returns a fixture which responds to matching requests with the contents of the provided file and status 200 OK. The provided file is read into memory by this func.

func GetBytesOK

func GetBytesOK(route string, body []byte, opts ...FixtureOpt) F

GetBytesOK returns a fixture which responds to GET requests at the provided route with the provided body, and status 200 OK.

func GetFileOK

func GetFileOK(route, path string, opts ...FixtureOpt) F

GetFileOK returns a fixture which responds to GET requests at the provided route with the contents of the provided file and status 200 OK. The file at the provided path is read into memory by this func.

func GetOK

func GetOK(route string, body string, opts ...FixtureOpt) F

GetOK returns a fixture which responds to GET requests at the provided route with the provided response body, and status 200 OK.

func NotFound

func NotFound(route, method string, opts ...FixtureOpt) F

NotFound returns a fixture which returns 404 Not Found in response to any request, along with an empty body.

func OK

func OK(route string, body string, opts ...FixtureOpt) F

OK returns a fixture which responds to any request at the provided route with the provided body and status 200 OK.

func Reader

func Reader(route, method string, responseCode int, reader io.Reader, opts ...FixtureOpt) F

Reader returns a fixture which responds to matching requests with the contents of the provided reader, which are read into memory by this func.

func ResponseCode

func ResponseCode(route, method string, responseCode int, opts ...FixtureOpt) F

ResponseCode returns a fixture which returns the provided response code in response to any request, along with an empty body.

func Seq

func Seq(route, method string, fixtures ...F) F

Seq returns a fixture which responds with the provided list of fixtures, each of which is returned exactly once in the order they are provided, except for the last fixture, which is returned as often as this fixture is called.

All assertions on sub-fixtures of a Seq are run. However, the routes and methods of sub-fixtures are ignored when run as part of a Seq.

type FixtureOpt

type FixtureOpt func(f *baseFixture)

FixtureOpt represents an optional parameter added to a fixture, usually request assertions.

func AssertBodyContains

func AssertBodyContains(str string) FixtureOpt

AssertBodyContains asserts all requests passed to this fixture include a body containing the provided string.

func AssertBodyContainsBytes

func AssertBodyContainsBytes(b []byte) FixtureOpt

AssertBodyContainsBytes asserts all requests passed to this fixture contains the provided byte sequence in their body.

func AssertHeaderMatches

func AssertHeaderMatches(key, value string) FixtureOpt

AssertHeaderMatches asserts that the provided key, value pair is present in the headers of any incoming request.

func AssertURLContains

func AssertURLContains(substr string) FixtureOpt

AssertURLContains asserts that the URL passed contains the provided substring.

type Server

type Server struct {
	*httptest.Server
	// contains filtered or unexported fields
}

func NewServer

func NewServer(fixtures ...F) *Server

NewServer creates a new httpfixture.Server which responds to requests with the provided fixtures.

func (*Server) Close

func (s *Server) Close()

Close closes the underlying httptest.Server.

func (*Server) ServeHTTP

func (s *Server) ServeHTTP(rw http.ResponseWriter, req *http.Request)

ServeHTTP implements the http.Handler interface.

func (*Server) Start

func (s *Server) Start(t *testing.T)

Start starts the server, reporting assertions using the provided testing.T.

func (*Server) StartTLS

func (s *Server) StartTLS(t *testing.T)

StartTLS starts the server in TLS mode, reporting assertions using the provided testing.T.

func (*Server) URL

func (s *Server) URL() string

URL retrieves the URL of this server, once it's been started.