README
¶
assert 
assert is a Go library that helps you make assertions in tests, printing a human-readable report of the differences between two values in assertions that fail.
Installation
$ go get github.com/kkyr/assert@latest
Usage
package person_test
import (
"testing"
"github.com/kkyr/assert"
)
func TestPerson(t *testing.T) {
assert := assert.New(t)
want := []string{"John", "Jim"}
got := []string{"John", "Joe"}
assert.Field("Names").Equal(want, got)
// Output:
// --- FAIL: TestPerson (0.00s)
// person_test.go:15: Names: (-want, +got):
// []string{
// "John",
// - "Jim",
// + "Joe",
// }
}
Documentation
Documentation
¶
Overview ¶
Package assert provides an assertion library for use within Go tests.
Example Usage ¶
import (
"testing"
"github.com/kkyr/assert"
)
func TestPeople(t *testing.T) {
assert := assert.New(t)
want, got := "John", "Jane"
assert.Equal(want, got) // calls t.Error
}
If you'd like for assert to call t.Fatal instead of t.Error on failures, use Assert.Require:
func TestPeople(t *testing.T) {
require := assert.New(t).Require()
want, got := "John", "Jane"
require.Equal(want, got) // calls t.Fatal
}
Alternatively, you can have a mixed approach by calling Assert.Require only on certain tests using a fluent syntax:
func TestPeople(t *testing.T) {
assert := assert.New(t)
want, got := "John", "Jane"
assert.Equal(want, got) // calls t.Error
assert.Require().Equal(want, got) // calls t.Fatal
}
You can use Assert.Field to add additional context to failure messages:
func TestPeople(t *testing.T) {
assert := assert.New(t)
want, got := "John", "Jane"
assert.Field("Person").Equal(want, got) // prefixes failure message with "Person: "
}
Successive calls to Assert.Field will overwrite previous values and only the last field will be used.
You can chain fluent syntax methods together:
func TestPeople(t *testing.T) {
assert := assert.New(t)
want, got := "John", "Jane"
assert.Require().Field("Person").Equal(want, got)
}
Equality ¶
Equality of two values is determined using the Equal func in the go-cmp package.
Index ¶
- type Assert
- func (a *Assert) Equal(want, got any) bool
- func (a *Assert) ErrorIs(err, target error) bool
- func (a *Assert) Field(s string) *Assert
- func (a *Assert) Len(value any, n int) bool
- func (a *Assert) Nil(value any) bool
- func (a *Assert) NotEqual(want, got any) bool
- func (a *Assert) NotNil(value any) bool
- func (a *Assert) NotZero(value any) bool
- func (a *Assert) Require() *Assert
- func (a *Assert) Zero(value any) bool
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Assert ¶
type Assert struct {
// contains filtered or unexported fields
}
Assert is a type that can make assertions.
By default, assertion failures are reported using t.Error.
func (*Assert) Equal ¶
Equal asserts that want and got are equal. See cmp.Equal for details on how equality is determined.
Example ¶
package main
import (
"fmt"
"strings"
"testing"
"github.com/kkyr/assert"
)
type mockT struct {
*testing.T
print bool
}
func (t mockT) Error(args ...any) {
if t.print {
str := args[0].(string)
str = strings.Join(strings.Fields(str), " ")
fmt.Println(str)
}
}
func (t mockT) Fatal(args ...any) {
t.Error(args...)
}
func (_ mockT) Helper() {}
func main() {
t := mockT{print: true}
slice1, slice2 := []string{"go", "gopher"}, []string{"go", "slice"}
assert.New(t).Equal(slice1, slice2)
assert.New(t).Require().Field("terms").Equal(slice1, slice2)
}
Output: (-want, +got): []string{ "go", - "gopher", + "slice", } terms: (-want, +got): []string{ "go", - "gopher", + "slice", }
func (*Assert) ErrorIs ¶
ErrorIs asserts that at least one of the error in err's chain matches target. See errors.Is for details on how a matching error is found.
Example ¶
package main
import (
"fmt"
"strings"
"testing"
"github.com/kkyr/assert"
)
type mockT struct {
*testing.T
print bool
}
func (t mockT) Error(args ...any) {
if t.print {
str := args[0].(string)
str = strings.Join(strings.Fields(str), " ")
fmt.Println(str)
}
}
func (t mockT) Fatal(args ...any) {
t.Error(args...)
}
func (_ mockT) Helper() {}
func main() {
t := mockT{print: true}
err := fmt.Errorf("boom")
target := fmt.Errorf("wrapped %w", fmt.Errorf("failure"))
assert.New(t).ErrorIs(err, target)
assert.New(t).Field("err").ErrorIs(err, target)
}
Output: no error in err's chain matches target err: no error in err's chain matches target
func (*Assert) Field ¶
Field returns a copy of Assert that will prefix failure messages with s.
assert.Field("Age").Equal(18, 20)
This should be used to enrich failure messages with information about the field that is being asserted.
func (*Assert) Len ¶ added in v0.2.0
Len asserts that value has length n. If len() cannot be applied to value, the test fails.
Example ¶
package main
import (
"fmt"
"strings"
"testing"
"github.com/kkyr/assert"
)
type mockT struct {
*testing.T
print bool
}
func (t mockT) Error(args ...any) {
if t.print {
str := args[0].(string)
str = strings.Join(strings.Fields(str), " ")
fmt.Println(str)
}
}
func (t mockT) Fatal(args ...any) {
t.Error(args...)
}
func (_ mockT) Helper() {}
func main() {
t := mockT{print: true}
str := "hello world"
num := 2
assert.New(t).Len(str, 5)
assert.New(t).Len(num, 1)
}
Output: want len() = 5, got 11 could not apply len() to int
func (*Assert) Nil ¶
Nil asserts that value is nil.
Example ¶
package main
import (
"fmt"
"strings"
"testing"
"github.com/kkyr/assert"
)
type mockT struct {
*testing.T
print bool
}
func (t mockT) Error(args ...any) {
if t.print {
str := args[0].(string)
str = strings.Join(strings.Fields(str), " ")
fmt.Println(str)
}
}
func (t mockT) Fatal(args ...any) {
t.Error(args...)
}
func (_ mockT) Helper() {}
func main() {
t := mockT{print: true}
slice := make([]string, 0)
assert.New(t).Nil(slice)
assert.New(t).Field("users").Nil(slice)
}
Output: want <nil>, got [] users: want <nil>, got []
func (*Assert) NotEqual ¶
NotEqual asserts that want and got are not equal. See cmp.Equal for details on how equality is determined.
func (*Assert) NotNil ¶
NotNil asserts that value is not nil.
Example ¶
package main
import (
"fmt"
"strings"
"testing"
"github.com/kkyr/assert"
)
type mockT struct {
*testing.T
print bool
}
func (t mockT) Error(args ...any) {
if t.print {
str := args[0].(string)
str = strings.Join(strings.Fields(str), " ")
fmt.Println(str)
}
}
func (t mockT) Fatal(args ...any) {
t.Error(args...)
}
func (_ mockT) Helper() {}
func main() {
t := mockT{print: true}
var slice []string
assert.New(t).NotNil(slice)
assert.New(t).Field("users").NotNil(slice)
}
Output: want <non-nil>, got <nil> users: want <non-nil>, got <nil>
func (*Assert) NotZero ¶
NotZero asserts that value is not the zero value for its type. Pointer values are determined based on the zero value of the referenced values.
Example ¶
package main
import (
"fmt"
"strings"
"testing"
"time"
"github.com/kkyr/assert"
)
type mockT struct {
*testing.T
print bool
}
func (t mockT) Error(args ...any) {
if t.print {
str := args[0].(string)
str = strings.Join(strings.Fields(str), " ")
fmt.Println(str)
}
}
func (t mockT) Fatal(args ...any) {
t.Error(args...)
}
func (_ mockT) Helper() {}
func main() {
t := mockT{print: true}
duration := time.Duration(0)
assert.New(t).NotZero(duration)
assert.New(t).Field("timeout").NotZero(duration)
}
Output: want non-zero value, got 0s timeout: want non-zero value, got 0s
func (*Assert) Zero ¶
Zero asserts that value is the zero value for its type. Pointer values are determined based on the zero value of the referenced values.
Example ¶
package main
import (
"fmt"
"strings"
"testing"
"time"
"github.com/kkyr/assert"
)
type mockT struct {
*testing.T
print bool
}
func (t mockT) Error(args ...any) {
if t.print {
str := args[0].(string)
str = strings.Join(strings.Fields(str), " ")
fmt.Println(str)
}
}
func (t mockT) Fatal(args ...any) {
t.Error(args...)
}
func (_ mockT) Helper() {}
func main() {
t := mockT{print: true}
date, _ := time.Parse("2006-01-02", "2022-02-01")
assert.New(t).Zero(date)
assert.New(t).Field("updated_at").Zero(date)
}
Output: want zero value, got 2022-02-01 00:00:00 +0000 UTC updated_at: want zero value, got 2022-02-01 00:00:00 +0000 UTC
Source Files