README
¶
Package assert - Magic assert macros for Go
Package assert provides developer a way to assert expression and output useful contextual information automatically when a case fails.
With this package, we can focus on writing test code without worrying about how to print lots of verbose debug information for debug.
Here is a quick sample.
import "github.com/huandu/go-assert"
func TestSomething(t *testing.T) {
str := Foo(42)
assert.Assert(t, str == "expected")
// This case fails with following message.
//
// Assertion failed:
// str == "expected"
// Referenced variables are assigned in following statements:
// str := Foo(42)
}
Import
Use go get to install this package.
go get github.com/huandu/go-assert
Current stable version is v1.*. Old versions tagged by v0.* are obsoleted.
Usage
Assertion methods
If we just want to use functions like Assert, Equal or NotEqual, it's recommended to import this package as ..
import "github.com/huandu/go-assert"
func TestSomething(t *testing.T) {
a, b := 1, 2
assert.Assert(t, a > b)
// This case fails with message:
// Assertion failed:
// a > b
}
func TestAssertEquality(t *testing.T) {
assert.Equal(t, map[string]int{
"foo": 1,
"bar": -2,
}, map[string]int{
"bar": -2,
"foo": 10000,
})
// This case fails with message:
// Assertion failed:
// The value of following expression should equal.
// [1] map[string]int{
// "foo": 1,
// "bar": -2,
// }
// [2] map[string]int{
// "bar": -2,
// "foo": 10000,
// }
// Values:
// [1] -> (map[string]int)map[bar:-2 foo:1]
// [2] -> (map[string]int)map[bar:-2 foo:10000]
}
Advanced assertion wrapper: type A
If we want more controls on assertion, it's recommended to wrap t in an A.
There are lots of useful assert methods implemented in A.
Assert/Eqaul/NotEqual: Basic assertion methods.NilError/NonNilError: Test if a func/method returns expected error.Use: Track variables. If any assert method fails, all variables tracked byAand related in assert method will be printed out automatically in assertion message.
Here is a sample to demonstrate how to use A#Use to print related variables in assertion message.
import "github.com/huandu/go-assert"
func TestSomething(t *testing.T) {
a := assert.New(t)
v1 := 123
v2 := []string{"wrong", "right"}
v3 := v2[0]
v4 := "not related"
a.Use(&v1, &v2, &v3, &v4)
a.Assert(v1 == 123 && v3 == "right")
// This case fails with following message.
//
// Assertion failed:
// v1 == 123 && v3 == "right"
// Referenced variables are assigned in following statements:
// v1 := 123
// v3 := v2[0]
// Related variables:
// v1 -> (int)123
// v2 -> ([]string)[wrong right]
// v3 -> (string)wrong
}
Documentation
¶
Overview ¶
Package assert provides developer a way to assert expression and output useful contextual information automatically when a case fails. With this package, we can focus on writing test code without worrying about how to print lots of verbose debug information for debug.
See project page for more samples. https://github.com/huandu/go-assert
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Assert ¶
Assert tests expr and call `t.Fatalf` to terminate test case if expr is false-equivalent value. `false`, 0, nil and empty string are false-equivalent values.
Sample code.
import "github.com/huandu/go-assert"
func TestSomething(t *testing.T) {
a, b := 1, 2
assert.Assert(t, a > b)
}
Output:
Assertion failed:
a > b
Referenced variables are assigned in following statements:
a, b := 1, 2
func AssertEqual ¶
AssertEqual uses `reflect.DeepEqual` to test v1 and v2 equality.
Note: as golint dislike the name of this function, it will be removed in the future. Use Equal instead.
Sample code.
import "github.com/huandu/go-assert"
func TestSomething(t *testing.T) {
assert.AssertEqual(t, []int{1,2}, []int{1})
}
Output:
Assertion failed:
assert.AssertEqual(t, []int{1, 2}, []int{1})
The value of following expression should equal.
[1] []int{1, 2}
[2] []int{1}
Values:
[1] -> ([]int)[1 2]
[2] -> ([]int)[1]
func AssertNotEqual ¶
AssertNotEqual uses `reflect.DeepEqual` to test v1 and v2 equality.
Note: as golint dislike the name of this function, it will be removed in the future. Use NotEqual instead.
Sample code.
import "github.com/huandu/go-assert"
func TestSomething(t *testing.T) {
assert.AssertNotEqual(t, []int{1}, []int{1})
}
Output:
Assertion failed:
assert.AssertNotEqual(t, []int{1}, []int{1})
The value of following expression should not equal.
[1] []int{1}
[2] []int{1}
func Equal ¶ added in v1.1.5
Equal uses `reflect.DeepEqual` to test v1 and v2 equality.
Sample code.
import "github.com/huandu/go-assert"
func TestSomething(t *testing.T) {
assert.Equal(t, []int{1,2}, []int{1})
}
Output:
Assertion failed:
assert.Equal(t, []int{1, 2}, []int{1})
The value of following expression should equal.
[1] []int{1, 2}
[2] []int{1}
Values:
[1] -> ([]int)[1 2]
[2] -> ([]int)[1]
func NotEqual ¶ added in v1.1.5
NotEqual uses `reflect.DeepEqual` to test v1 and v2 equality.
Sample code.
import "github.com/huandu/go-assert"
func TestSomething(t *testing.T) {
assert.NotEqual(t, []int{1}, []int{1})
}
Output:
Assertion failed:
assert.NotEqual(t, []int{1}, []int{1})
The value of following expression should not equal.
[1] []int{1}
[2] []int{1}
Types ¶
type A ¶ added in v1.0.0
The A is a wrapper of testing.T with some extra help methods.
func (*A) Assert ¶ added in v1.0.0
func (a *A) Assert(expr interface{})
Assert tests expr and call `t.Fatalf` to terminate test case if expr is false-equivalent value. `false`, 0, nil and empty string are false-equivalent values.
Sample code.
func TestSomething(t *testing.T) {
a := assert.New(t)
x, y := 1, 2
a.Assert(x > y)
}
Output:
Assertion failed:
x > y
Referenced variables are assigned in following statements:
x, y := 1, 2
func (*A) Equal ¶ added in v1.0.0
func (a *A) Equal(v1, v2 interface{})
Equal uses `reflect.DeepEqual` to test v1 and v2 equality.
Sample code.
func TestSomething(t *testing.T) {
a := assert.New(t)
a.Equal([]int{1,2}, []int{1})
}
Output:
Assertion failed:
a.Equal([]int{1, 2}, []int{1})
The value of following expression should equal.
[1] []int{1, 2}
[2] []int{1}
Values:
[1] -> ([]int)[1 2]
[2] -> ([]int)[1]
func (*A) NilError ¶ added in v1.0.0
func (a *A) NilError(result ...interface{})
NilError expects a function return a nil error. Otherwise, it will terminate the test case using `t.Fatalf`.
Sample code.
func TestSomething(t *testing.T) {
a := assert.New(t)
a.NilError(os.Open("path/to/a/file"))
}
Output:
Assertion failed:
Following expression should return a nil error.
os.Open("path/to/a/file")
The error is:
open path/to/a/file: no such file or directory
func (*A) NonNilError ¶ added in v1.0.0
func (a *A) NonNilError(result ...interface{})
NonNilError expects a function return a non-nil error. Otherwise, it will terminate the test case using `t.Fatalf`.
Sample code.
func TestSomething(t *testing.T) {
a := assert.New(t)
f := func() (int, error) { return 0, errors.New("expected") }
a.NilError(f())
}
Output:
Assertion failed:
Following expression should return a nil error.
f()
f := func() (int, error) { return 0, errors.New("expected") }
The error is:
expected
func (*A) NotEqual ¶ added in v1.0.0
func (a *A) NotEqual(v1, v2 interface{})
NotEqual uses `reflect.DeepEqual` to test v1 and v2 equality.
Sample code.
func TestSomething(t *testing.T) {
a := assert.New(t)
a.NotEqual(t, []int{1}, []int{1})
}
Output:
Assertion failed:
a.NotEqual(t, []int{1}, []int{1})
The value of following expression should not equal.
[1] []int{1}
[2] []int{1}
func (*A) Use ¶ added in v1.1.0
func (a *A) Use(args ...interface{})
Use saves args in context and prints related args automatically in assertion method when referenced.
Sample code.
func TestSomething(t *testing.T) {
a := assert.New(t)
v1 := 123
v2 := []string{"wrong", "right"}
v3 := v2[0]
v4 := "not related"
a.Use(&v1, &v2, &v3, &v4)
}
Output:
Assertion failed:
v1 == 123 && v3 == "right"
Referenced variables are assigned in following statements:
v1 := 123
v3 := v2[0]
Related variables:
v1 = (int)123
v3 = (string)wrong
Source Files
Directories