test

README

4d63.com/test

Go test library that delivers simple test assertions with useful verbose output.

Features

• Lightweight
• Simplicity of testify
• Verbose logs based on successful assertions
• Concise git diff comparisons
• JSON comparisons (powered by pretty)

Todo

• Error is/as comparisons
• Slice contains
• Map contains
• Regex comparisons

Documentation

Overview

Package test is a package that provides equality functions for testing Go code. It is focused on making the most common action in test code simple, testing equality expectations.

Usage

A simple test function looks like this:

func TestAbs(t *testing.T) {
    tt := test.New(t)
    tt.Equal(Abs(-1), 1)
}

If the check passes, the verbose output looks like this:

--- PASS: TestAbs (0.00s)
    test.go:2: tt.Equal(Abs(-1), 1): got 1

If the check fails, and the type is a bool, int, or float, the output looks like this:

--- PASS: TestAbs (0.00s)
    test.go:2: tt.Equal(Abs(-1), 1): got 0, want 1

If the check fails, and the type is a string, the output looks like this:

--- FAIL: TestGoGophers (0.00s)
    test.go:2: tt.Equal("Golang\nGophers", "Go\nGophers"):
    --- got
    +++ want
    @@ -1,2 +1,2 @@
    -Golang
    +Go
     Gophers

If the check fails, and the type is an array or slice, the output looks like this:

--- FAIL: TestGoGophers (0.00s)
    test.go:2: tt.Equal([]string{"Golang", "Gophers"}, []string{"Go", "Gophers"}):
    --- got
    +++ want
    @@ -1,5 +1,5 @@
     ([]string) (len=2) {
    - (string) (len=6) "Golang",
    + (string) (len=2) "Go",
      (string) (len=7) "Gophers"
     }

If the check fails, and the type is a struct value, the output looks like this:

--- FAIL: TestGoGophers (0.00s)
    test.go:2: tt.Equal(struct{Name string; Age int}{"A", 44}, struct{Name string; Age int}{"a", 44}):
    --- got
    +++ want
    @@ -1,5 +1,5 @@
     (struct { Name string; Age int }) {
    - Name: (string) (len=1) "A",
    + Name: (string) (len=1) "a",
      Age: (int) 44
     }

Got and want

The terms got and want are used to describe what you got as a result of running the code, and what you want to have gotten. These terms are commonly found in the Go stdlib and it's own testing docs. In some other testing libraries they are sometimes referred to actual and expected.

Nesting

Checks can be nested using the bool return value of a prior check.

func TestAbs(t *testing.T) {
    tt := test.New(t)
    if tt.Equal(Abs(-1), 1) {
        ...
    }
}

Breaking early

Checks can cause a test to stop at a failure using the bool return value.

func TestAbs(t *testing.T) {
    tt := test.New(t)
    if !tt.Equal(Abs(-1), 1) {
        return
    }
    ...
}

Comparison

Comparison of values is performed using Google's cmp Go module: https://github.com/google/go-cmp/cmp

Index

• type T
  • func New(t testing.TB) *T
  • func (t *T) Equal(got, want interface{}) bool
  • func (t *T) EqualJSON(got, want []byte) bool
  • func (t *T) NotEqual(got, notWant interface{}) bool

Examples

• T.Equal (Fail)
• T.Equal (FailComparingDifferentTypes)
• T.Equal (FailDiff)
• T.Equal (Pass)
• T.EqualJSON (Fail)
• T.EqualJSON (Pass)
• T.NotEqual (Fail)
• T.NotEqual (Pass)

Types

type T

type T struct {
	testing.TB
}

func New

func New(t testing.TB) *T

New creates a new T.

func (*T) Equal

func (t *T) Equal(got, want interface{}) bool

Equal compares got to want and reports an error to tb if they are not equal. Returns true if equal.

Example (Fail)

tt := test.New(t)
tt.Equal(Abs(-1), 0)

Output:

tt.Equal(Abs(-1), 0): got 1, want 0

Example (FailComparingDifferentTypes)

tt := test.New(t)
tt.Equal(1, 1.0)

Output:

tt.Equal(1, 1.0):
--- got
+++ want
@@ -1,2 +1,2 @@
-(int) 1
+(float64) 1

Example (FailDiff)

tt := test.New(t)
tt.Equal("Hello World\nG'day World\n", "Hello World\nG'day Mate")

Output:

tt.Equal("Hello World\nG'day World\n", "Hello World\nG'day Mate"):
--- got
+++ want
@@ -1,3 +1,2 @@
 Hello World
-G'day World
-
+G'day Mate

Example (Pass)

t := test.T{t}
t.Equal(Abs(-1), 1)

Output:

t.Equal(Abs(-1), 1): got 1

func (*T) EqualJSON

func (t *T) EqualJSON(got, want []byte) bool

EqualJSON compares got to want and reports an error to tb if they are not equal. JSON is first formatted consistently and keys are sorted before comparing. Returns true if logically equal.

Example (Fail)

tt := test.New(t)
tt.EqualJSON(
	[]byte(`{"key":"value1","key3":3}`),
	[]byte(` {
				"key3": 3
				"key":"value2",
			}`),
)

Output:

tt.EqualJSON(:
--- got
+++ want
@@ -1,5 +1,5 @@
 {
-  "key": "value1",
+  "key": "value2",
   "key3": 3
 }

Example (Pass)

tt := test.New(t)
tt.EqualJSON(
	[]byte(`{"key":"value1","key":"value2","key3":3}`),
	[]byte(` {
				"key":"value2",
				"key":"value1",
				"key3": 3
			}`),
)

Output:

tt.EqualJSON(: got {
  "key": "value1",
  "key": "value2",
  "key3": 3
}

func (*T) NotEqual

func (t *T) NotEqual(got, notWant interface{}) bool

NotEqual compares got to want and reports an error to tb if they are equal. Returns true if not equal.

Example (Fail)

tt := test.New(t)
tt.NotEqual(Abs(-1), 1)

Output:

tt.NotEqual(Abs(-1), 1): got 1, want not 1

Example (Pass)

tt := test.New(t)
tt.NotEqual(Abs(-1), -1)

Output:

tt.NotEqual(Abs(-1), -1): got 1, not -1