apitest

README

This library is on Version 0 and we won't guarantee backwards compatible API changes until we go to version 1

api-test

Simple behavioural (black box) api testing library.

In black box tests the internal structure of the app is not know by the tests. Data is input to the system and the outputs are expected to meet certain conditions.

Check the godoc here.

This library is dependency free and we intend to keep it that way

Installation

go get -u github.com/steinfletcher/api-test

Examples

Framework and library integration examples

Example	Comment
gin	popular martini-like web framework
gorilla	the gorilla web toolkit

Companion libraries

Library	Comment
JSONPath	JSONPath assertion addons

Code snippets

JSON body matcher

func TestApi(t *testing.T) {
	apitest.New().
		Handler(handler).
		Get("/user/1234").
		Expect(t).
		Body(`{"id": "1234", "name": "Tate"}`).
		Status(http.StatusCreated).
		End()
}

JSONPath

For asserting on parts of the response body JSONPath may be used. A separate module must be installed which provides these assertions - go get -u github.com/steinfletcher/api-test-jsonpath. This is packaged separately to keep this library dependency free.

Given the response is {"a": 12345, "b": [{"key": "c", "value": "result"}]}

func TestApi(t *testing.T) {
	apitest.New().
		Handler(handler).
		Get("/hello").
		Expect(t).
		Assert(jsonpath.Contains(`$.b[? @.key=="c"].value`, "result")).
		End()
}

and jsonpath.Equals checks for value equality

func TestApi(t *testing.T) {
	apitest.New(handler).
		Get("/hello").
		Expect(t).
		Assert(jsonpath.Equal(`$.a`, float64(12345))).
		End()
}

Custom assert functions

func TestApi(t *testing.T) {
	apitest.New().
		Handler(handler).
		Get("/hello").
		Expect(t).
		Assert(func(res *http.Response, req *http.Request) {
			assert.Equal(t, http.StatusOK, res.StatusCode)
		}).
		End()
}

Assert cookies

func TestApi(t *testing.T) {
	apitest.New().
		Handler(handler).
		Patch("/hello").
		Expect(t).
		Status(http.StatusOK).
		Cookies(ExpectedCookie"ABC").Value("12345")).
		CookiePresent("Session-Token").
		CookieNotPresent("XXX").
        Cookies(
			ExpectedCookie"ABC").Value("12345"),
			ExpectedCookie"DEF").Value("67890")).
		End()
}

Assert headers

func TestApi(t *testing.T) {
	apitest.New().
		Handler(handler).
		Get("/hello").
		Expect(t).
		Status(http.StatusOK).
		Headers(map[string]string{"ABC": "12345"}).
		End()
}

Provide basic auth in the request

func TestApi(t *testing.T) {
	apitest.New().
		Handler(handler).
		Get("/hello").
		BasicAuth("username:password").
		Expect(t).
		Status(http.StatusOK).
		End()
}

Provide cookies in the request

func TestApi(t *testing.T) {
	apitest.New().
		Handler(handler).
		Get("/hello").
		Cookies(ExpectedCookie"ABC").Value("12345")).
		Expect(t).
		Status(http.StatusOK).
		End()
}

Provide headers in the request

func TestApi(t *testing.T) {
	apitest.New().
		Handler(handler).
		Delete("/hello").
		Headers(map[string]string{"My-Header": "12345"}).
		Expect(t).
		Status(http.StatusOK).
		End()
}

Provide query parameters in the request

Query can be used in combination with QueryCollection

func TestApi(t *testing.T) {
	apitest.New().
		Handler(handler).
		Get("/hello").
		Query(map[string]string{"a": "b"}).
		Expect(t).
		Status(http.StatusOK).
		End()
}

Provide query parameters in collection format in the request

Providing {"a": {"b", "c", "d"} results in parameters encoded as a=b&a=c&a=d. QueryCollection can be used in combination with Query

func TestApi(t *testing.T) {
	apitest.New().
		Handler(handler).
		Get("/hello").
		QueryCollection(map[string][]string{"a": {"b", "c", "d"}}).
		Expect(t).
		Status(http.StatusOK).
		End()
}

Capture the request and response data

func TestApi(t *testing.T) {
	apitest.New().
		Observe(func(res *http.Response, req *http.Request) {
    	    		// do something with res and req
    		}).
		Handler(handler).
		Get("/hello").
		Expect(t).
		Status(http.StatusOK).
		End()
}

one usage for this might be debug logging to the console. The provided DumpHttp function does this automatically

func TestApi(t *testing.T) {
	apitest.New().
		Observe(apitest.DumpHttp).
		Handler(handler).
		Post("/hello").
		Body(`{"a": 12345}`).
		Headers(map[string]string{"Content-Type": "application/json"}).
		Expect(t).
		Status(http.StatusCreated).
		End()
}

Intercept the request

This is useful for mutating the request before it is sent to the system under test.

func TestApi(t *testing.T) {
	apitest.New().
		Handler(handler).
		Intercept(func(req *http.Request) {
			req.URL.RawQuery = "a[]=xxx&a[]=yyy"
		}).
		Get("/hello").
		Expect(t).
		Status(http.StatusOK).
		End()
}

Documentation

Index

• func ExpectedCookie(name string) *expectedCookie
• type APITest
  • func New(name ...string) *APITest
  • func (a *APITest) BuildRequest() *http.Request
  • func (a *APITest) Handler(handler http.Handler) *Request
  • func (a *APITest) Observe(observer Observe) *APITest
  • func (a *APITest) Request() *Request
  • func (a *APITest) Response() *Response
• type Assert
• type Intercept
• type Observe
• type Request
  • func (r *Request) BasicAuth(auth string) *Request
  • func (r *Request) Body(b string) *Request
  • func (r *Request) Cookies(c ...*expectedCookie) *Request
  • func (r *Request) Delete(url string) *Request
  • func (r *Request) Expect(t *testing.T) *Response
  • func (r *Request) Get(url string) *Request
  • func (r *Request) Headers(h map[string]string) *Request
  • func (r *Request) Intercept(interceptor Intercept) *Request
  • func (r *Request) Method(method string) *Request
  • func (r *Request) Patch(url string) *Request
  • func (r *Request) Post(url string) *Request
  • func (r *Request) Put(url string) *Request
  • func (r *Request) Query(q map[string]string) *Request
  • func (r *Request) QueryCollection(q map[string][]string) *Request
  • func (r *Request) URL(url string) *Request
• type Response
  • func (r *Response) Assert(fn func(*http.Response, *http.Request) error) *Response
  • func (r *Response) Body(b string) *Response
  • func (r *Response) CookieNotPresent(cookieName string) *Response
  • func (r *Response) CookiePresent(cookieName string) *Response
  • func (r *Response) Cookies(cookies ...*expectedCookie) *Response
  • func (r *Response) End()
  • func (r *Response) Headers(headers map[string]string) *Response
  • func (r *Response) JSONPath(expression string, assert func(interface{})) *Response
  • func (r *Response) Status(s int) *Response

Functions

func ExpectedCookie

func ExpectedCookie(name string) *expectedCookie

Types

type APITest

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

APITest is the top level struct holding the test spec

func New

func New(name ...string) *APITest

func (*APITest) BuildRequest

func (a *APITest) BuildRequest() *http.Request

func (*APITest) Handler

func (a *APITest) Handler(handler http.Handler) *Request

Handler defines the http handler that is invoked when the test is run

func (*APITest) Observe

func (a *APITest) Observe(observer Observe) *APITest

Observe is a builder method for setting the observer

func (*APITest) Request

func (a *APITest) Request() *Request

Request returns the request spec

func (*APITest) Response

func (a *APITest) Response() *Response

Response returns the expected response

type Assert

type Assert func(*http.Response, *http.Request) error

Assert is a user defined custom assertion function

var IsClientError Assert = func(response *http.Response, request *http.Request) error {
	if response.StatusCode >= 400 && response.StatusCode < 500 {
		return nil
	}
	return errors.New("not a client error. Status code=" + strconv.Itoa(response.StatusCode))
}

IsClientError is a convenience function to assert on a range of client error status codes

var IsServerError Assert = func(response *http.Response, request *http.Request) error {
	if response.StatusCode >= 500 {
		return nil
	}
	return errors.New("not a server error. Status code=" + strconv.Itoa(response.StatusCode))
}

IsServerError is a convenience function to assert on a range of server error status codes

var IsSuccess Assert = func(response *http.Response, request *http.Request) error {
	if response.StatusCode >= 200 && response.StatusCode < 400 {
		return nil
	}
	return errors.New("not a client error. Status code=" + strconv.Itoa(response.StatusCode))
}

IsSuccess is a convenience function to assert on a range of happy path status codes

type Intercept

type Intercept func(*http.Request)

Intercept will be called before the request is made. Updates to the request will be reflected in the test

type Observe

type Observe func(*http.Response, *http.Request)

Observe will be called by with the request and response on completion

var DumpHttp Observe = func(res *http.Response, req *http.Request) {
	requestDump, err := httputil.DumpRequest(req, true)
	if err == nil {
		fmt.Println("--> http request dump\n\n" + string(requestDump))
	}

	responseDump, err := httputil.DumpResponse(res, true)
	if err == nil {
		fmt.Println("<-- http response dump:\n\n" + string(responseDump))
	}
}

DumpHttp logs the http wire representation of the request and response

type Request

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

Request is the user defined request that will be invoked on the handler under test

func (*Request) BasicAuth

func (r *Request) BasicAuth(auth string) *Request

BasicAuth is a builder method to sets basic auth on the request. The credentials should be provided delimited by a colon, e.g. "username:password"

func (*Request) Body

func (r *Request) Body(b string) *Request

Body is a builder method to set the request body

func (*Request) Cookies

func (r *Request) Cookies(c ...*expectedCookie) *Request

Cookies is a builder method to set the request cookies

func (*Request) Delete

func (r *Request) Delete(url string) *Request

Delete is a convenience method for setting the request as http.MethodDelete

func (*Request) Expect

func (r *Request) Expect(t *testing.T) *Response

Expect marks the request spec as complete and following code will define the expected response

func (*Request) Get

func (r *Request) Get(url string) *Request

Get is a convenience method for setting the request as http.MethodGet

func (*Request) Headers

func (r *Request) Headers(h map[string]string) *Request

Headers is a builder method to set the request headers

func (*Request) Intercept

func (r *Request) Intercept(interceptor Intercept) *Request

Intercept is a builder method for setting the request interceptor

func (*Request) Method

func (r *Request) Method(method string) *Request

Method is a builder method for setting the http method of the request

func (*Request) Patch

func (r *Request) Patch(url string) *Request

Patch is a convenience method for setting the request as http.MethodPatch

func (*Request) Post

func (r *Request) Post(url string) *Request

Post is a convenience method for setting the request as http.MethodPost

func (*Request) Put

func (r *Request) Put(url string) *Request

Put is a convenience method for setting the request as http.MethodPut

func (*Request) Query

func (r *Request) Query(q map[string]string) *Request

Query is a builder method to set the request query parameters. This can be used in combination with request.QueryCollection

func (*Request) QueryCollection

func (r *Request) QueryCollection(q map[string][]string) *Request

QueryCollection is a builder method to set the request query parameters This can be used in combination with request.Query

func (*Request) URL

func (r *Request) URL(url string) *Request

URL is a builder method for setting the url of the request

type Response

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

Response is the user defined expected response from the application under test

func (*Response) Assert

func (r *Response) Assert(fn func(*http.Response, *http.Request) error) *Response

Assert allows the consumer to provide a user defined function containing their own custom assertions

func (*Response) Body

func (r *Response) Body(b string) *Response

Body is the expected response body

func (*Response) CookieNotPresent

func (r *Response) CookieNotPresent(cookieName string) *Response

CookieNotPresent is used to assert that a cookie is not present in the response

func (*Response) CookiePresent

func (r *Response) CookiePresent(cookieName string) *Response

CookiePresent is used to assert that a cookie is present in the response, regardless of its value

func (*Response) Cookies

func (r *Response) Cookies(cookies ...*expectedCookie) *Response

Cookies is the expected response cookies

func (*Response) End

func (r *Response) End()

End runs the test and all defined assertions

func (*Response) Headers

func (r *Response) Headers(headers map[string]string) *Response

Headers is the expected response headers

func (*Response) JSONPath

func (r *Response) JSONPath(expression string, assert func(interface{})) *Response

JSONPath provides support for jsonpath expectations as defined by https://goessner.net/articles/JsonPath/

func (*Response) Status

func (r *Response) Status(s int) *Response

Status is the expected response http status code