abide: github.com/beme/abide Index | Examples | Files | Directories

package abide

import "github.com/beme/abide"

Package abide is a testing utility for http response snapshots inspired by Facebook's Jest.

It is designed to be used alongside Go's existing testing package and enable broader coverage of http APIs. When included in version control it can provide a historical log of API and application changes over time.

Snapshot

A snapshot is essentially a lockfile representing an http response.

/* snapshot: api endpoint */
HTTP/1.1 200 OK
Connection: close
Content-Type: application/json

{
  "foo": "bar"
}

In addition to testing `http.Response`, abide provides methods for testing `io.Reader` and any object that implements `Assertable`.

Snapshots are saved in a directory named __snapshots__ at the root of the package. These files are intended to be saved and included in version control.

Creating a Snapshot

Snapshots are automatically generated during the initial test run. For example this will create a snapshot identified by "example" for this http.Response.

func TestFunction(t *testing.T) {
   req := httptest.NewRequest(http.MethodGet, "http://example.com", nil)
   w := httptest.NewRecorder()
   handler(w, req)
   res := w.Result()
   abide.AssertHTTPResponse(t, "example", res)
}

Comparing and Updating

In subsequent test runs the existing snapshot is compared to the new results. In the event they do not match, the test will fail, and the diff will be printed. If the change was intentional, the snapshot can be updated.

$ go test -- -u

Index

Examples

Package Files

abide.go args.go assert.go assertables.go config.go doc.go error.go

Variables

var (
    // SnapshotsDir is the directory snapshots will be read to & written from
    // relative directories are resolved to present-working-directory of the executing process
    SnapshotsDir = "__snapshots__"
)

func Assert Uses

func Assert(t *testing.T, id string, a Assertable)

Assert asserts the value of an object with implements Assertable.

func AssertHTTPRequest Uses

func AssertHTTPRequest(t *testing.T, id string, r *http.Request)

AssertHTTPRequest asserts the value of an http.Request. Intended for use when testing incoming client requests See https://golang.org/pkg/net/http/httputil/#DumpRequest for more

func AssertHTTPRequestOut Uses

func AssertHTTPRequestOut(t *testing.T, id string, r *http.Request)

AssertHTTPRequestOut asserts the value of an http.Request. Intended for use when testing outgoing client requests See https://golang.org/pkg/net/http/httputil/#DumpRequestOut for more

func AssertHTTPResponse Uses

func AssertHTTPResponse(t *testing.T, id string, w *http.Response)

AssertHTTPResponse asserts the value of an http.Response.

Code:

req := httptest.NewRequest(http.MethodGet, "http://example.com", nil)
w := httptest.NewRecorder()
handler(w, req)
res := w.Result()
abide.AssertHTTPResponse(t, "http response", res)

func AssertReader Uses

func AssertReader(t *testing.T, id string, r io.Reader)

AssertReader asserts the value of an io.Reader.

Code:

file, _ := os.Open("/path/to/file")
abide.AssertReader(t, "io reader", file)

func Cleanup Uses

func Cleanup() error

Cleanup is an optional method which will execute cleanup operations affiliated with abide testing, such as pruning snapshots.

type Assertable Uses

type Assertable interface {
    String() string
}

Assertable represents an object that can be asserted.

func Interface Uses

func Interface(i interface{}) Assertable

Interface is syntactic sugar. It is a helper that converts any type to an Assertable.

Code:

type MyStruct struct {
    Field1 string
    Field2 int64
    Field3 bool
    field4 string
}
myStruct := MyStruct{
    "String1",
    1234567,
    true,
    "string4",
}
abide.Assert(t, "assertable struct", abide.Interface(myStruct))

func String Uses

func String(s string) Assertable

String is syntactic sugar. It is a helper that converts a string to an Assertable

Code:

myString := "this is a string I want to snapshot"
abide.Assert(t, "assertable string", abide.String(myString))

Directories

PathSynopsis
example
example/models
internal

Package abide imports 16 packages (graph). Updated 2019-07-24. Refresh now. Tools for package owners.