Documentation ¶
Overview ¶
Package h provides matchers used by assert and expect packages. See the documentations in assert and expect for more details.
Index ¶
- Variables
- func RegisterComparator(callback interface{})
- func UnregisterComparator(callback interface{})
- type Matcher
- func AllOf(values ...interface{}) *Matcher
- func Any() *Matcher
- func AnyOf(values ...interface{}) *Matcher
- func Contains(w interface{}) *Matcher
- func EQ(want interface{}) *Matcher
- func Each(w interface{}) *Matcher
- func ElementsAre(w ...interface{}) *Matcher
- func ElementsAreArray(w interface{}) *Matcher
- func GE(want interface{}) *Matcher
- func GT(want interface{}) *Matcher
- func HasPrefix(want string) *Matcher
- func HasSubstr(want string) *Matcher
- func LE(want interface{}) *Matcher
- func LT(want interface{}) *Matcher
- func MapContains(key, val interface{}) *Matcher
- func NEQ(want interface{}) *Matcher
- func Nil() *Matcher
- func None() *Matcher
- func Not(val interface{}) *Matcher
- func NotNil() *Matcher
- func Panics(want interface{}) *Matcher
- func Regexp(want interface{}) *Matcher
- func UnorderedElementsAre(w ...interface{}) *Matcher
- func UnorderedElementsAreArray(w interface{}) *Matcher
- func WhenSorted(m *Matcher) *Matcher
- func Zero() *Matcher
- type Result
- type Status
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var NoError = Nil
NoError is an alias of Nil. It should be checked when the value is of type error.
assert.That(t, os.Close(fd), h.NoError())
Functions ¶
func RegisterComparator ¶
func RegisterComparator(callback interface{})
RegisterComparator registers a comparator function for a user-defined type. The callback should have signature
func(a, b T) (int, error)
where T is an arbitrary type. The callback will be invoked by h.EQ, h.GT and similar matchers. It is also invoked if type T appears inside a struct, pointer, or an interface.
The callback should return a negative value if a<b, zero if a==b, a positive value if a>b. It should return a non-nil error if a and b are not comparable, or on any other error. The callback may define its own meanings of ">", "==", and "<", but they must define a total ordering over T.
Example ¶
package main import ( "fmt" "github.com/grailbio/testutil/expect" "github.com/grailbio/testutil/h" ) type T struct{} func (t *T) Error(args ...interface{}) { fmt.Println(args...) } func (t *T) Fatal(args ...interface{}) { fmt.Println(args...) panic("fatal") } func main() { t := &T{} type tt struct{ val int } h.RegisterComparator(func(x, y tt) (int, error) { if x.val > 1000 { return 0, fmt.Errorf("test failure") } return x.val - y.val, nil }) expect.LT(t, tt{val: 10}, tt{val: 11}) expect.EQ(t, tt{val: 10}, tt{val: 10}) expect.GT(t, tt{val: 11}, tt{val: 10}) expect.Regexp(t, h.EQ(tt{1001}).Match(tt{1001}), "test failure") }
Output:
func UnregisterComparator ¶
func UnregisterComparator(callback interface{})
UnregisterComparator unregisters the callback registered in RegisteredComparator. It panics if the callback was not registered.
Types ¶
type Matcher ¶
type Matcher struct { // Desc describes this matcher. Msg string // NotDesc describes the negation of this matcher. It's shown when this // matcher is wrapped around Not(). NotMsg string // Match is invoked to check if the given value satisfies the matcher // condition. Match func(val interface{}) Result // contains filtered or unexported fields }
Matcher represents a node of a matcher expression tree.
func AllOf ¶
func AllOf(values ...interface{}) *Matcher
AllOf checks if the target value matches all the submatchers.
Example ¶
package main import ( "fmt" "github.com/grailbio/testutil/expect" "github.com/grailbio/testutil/h" ) type T struct{} func (t *T) Error(args ...interface{}) { fmt.Println(args...) } func (t *T) Fatal(args ...interface{}) { fmt.Println(args...) panic("fatal") } func main() { t := &T{} expect.That(t, 10, h.AllOf()) expect.That(t, 10, h.AllOf(h.LT(11), h.GT(9))) expect.That(t, 10, h.Not(h.AllOf(h.LT(11), h.GT(10)))) }
Output:
func Any ¶
func Any() *Matcher
Any matches anything.
Example ¶
package main import ( "fmt" "github.com/grailbio/testutil/expect" "github.com/grailbio/testutil/h" ) type T struct{} func (t *T) Error(args ...interface{}) { fmt.Println(args...) } func (t *T) Fatal(args ...interface{}) { fmt.Println(args...) panic("fatal") } func main() { t := &T{} expect.That(t, nil, h.Any()) }
Output:
func AnyOf ¶
func AnyOf(values ...interface{}) *Matcher
AnyOf checks if the target value matches at least one of the submatchers.
Example ¶
package main import ( "fmt" "github.com/grailbio/testutil/expect" "github.com/grailbio/testutil/h" ) type T struct{} func (t *T) Error(args ...interface{}) { fmt.Println(args...) } func (t *T) Fatal(args ...interface{}) { fmt.Println(args...) panic("fatal") } func main() { t := &T{} expect.That(t, 10, h.AnyOf(9, 10, 11)) expect.That(t, 10, h.Not(h.AnyOf(h.GE(11), h.LE(9)))) expect.That(t, 10, h.AnyOf(h.LT(11), h.GT(10))) expect.That(t, 10, h.Not(h.AnyOf())) }
Output:
func Contains ¶
func Contains(w interface{}) *Matcher
Contains checks if an array, slice, or string contains the given element. The element can be an immediate value or a Matcher.
Example:
assert.That(t, []int{10, 12}, h.Contains(10)) assert.That(t, []int{10, 12}, h.Contains(h.LT(11)))
Example ¶
package main import ( "fmt" "github.com/grailbio/testutil/expect" "github.com/grailbio/testutil/h" ) type T struct{} func (t *T) Error(args ...interface{}) { fmt.Println(args...) } func (t *T) Fatal(args ...interface{}) { fmt.Println(args...) panic("fatal") } func main() { t := &T{} expect.That(t, []int{42, 43}, h.Contains(43)) expect.That(t, []int{42, 43}, h.Contains(h.LE(42))) expect.That(t, []int{42, 43}, h.Not(h.Contains(h.LT(42)))) }
Output:
func EQ ¶
func EQ(want interface{}) *Matcher
EQ checks if the two values are equal. Equality is defined as follows.
EQ returns true only if the two values are of the same type. In addition:
- Two slices/arrays are equal if they are of the same length and the element at every position are equal.
- For other data types, the two values x and y are equal if reflect.DeepEqual(x, y)
Example ¶
package main import ( "fmt" "github.com/grailbio/testutil/expect" ) type T struct{} func (t *T) Error(args ...interface{}) { fmt.Println(args...) } func (t *T) Fatal(args ...interface{}) { fmt.Println(args...) panic("fatal") } func main() { t := &T{} expect.EQ(t, 42, 42) expect.EQ(t, uint(42), uint(42)) expect.EQ(t, uint8(42), uint8(42)) expect.EQ(t, uint16(42), uint16(42)) expect.EQ(t, uint32(42), uint32(42)) expect.EQ(t, uint64(42), uint64(42)) expect.EQ(t, int8(42), int8(42)) expect.EQ(t, int16(42), int16(42)) expect.EQ(t, int32(42), int32(42)) expect.EQ(t, int64(42), int64(42)) expect.EQ(t, "42", "42") expect.EQ(t, 42.0, 42.0) expect.EQ(t, true, true) expect.EQ(t, false, false) expect.NEQ(t, false, true) expect.EQ(t, nil, nil) expect.EQ(t, uintptr(1234), uintptr(1234)) expect.NEQ(t, uintptr(1234), uintptr(1235)) expect.EQ(t, complex(1.0, 3.0), complex(1.0, 3.0)) expect.EQ(t, complex(float64(2.0), float64(3.0)), complex(float64(2.0), float64(3.0))) expect.EQ(t, complex(float32(2.0), float32(3.0)), complex(float32(2.0), float32(3.0))) expect.NEQ(t, complex(2.0, 3.0), complex(1.0, 3.0)) expect.EQ(t, []int{42, 43}, []int{42, 43}) expect.EQ(t, [...]int{42, 43}, [...]int{42, 43}) expect.EQ(t, map[int]int{1: 2, 3: 4}, map[int]int{3: 4, 1: 2}) type tt struct { x int y *tt } expect.EQ(t, tt{10, nil}, tt{10, nil}) expect.EQ(t, &tt{10, nil}, &tt{10, nil}) expect.EQ(t, []tt{{10, nil}, {11, nil}}, []tt{{10, nil}, {11, nil}}) expect.EQ(t, tt{10, &tt{11, nil}}, tt{10, &tt{11, nil}}) xt0 := &tt{10, nil} xt0.y = xt0 xt1 := &tt{10, nil} xt1.y = xt1 expect.EQ(t, xt0, xt1) var it0 interface{} = tt{10, nil} var it1 interface{} = tt{10, nil} expect.EQ(t, it0, it1) ch0 := make(chan uint8) ch1 := make(chan uint8) expect.EQ(t, ch0, ch0) expect.NEQ(t, ch0, ch1) }
Output:
func Each ¶
func Each(w interface{}) *Matcher
Each checks if the every element in the target value has the given property. The target must be a slice, array, or a string.
Example:
assert.That(t, []string{"abc", "abd"}, h.Each(h.HasPrefix("ab"))) assert.That(t, []int{10, 10}, h.Each(10))
func ElementsAre ¶
func ElementsAre(w ...interface{}) *Matcher
ElementsAre checks if a sequence matches the given conditions, in order.
Example:
// Note: the below is the same as assert.EQ(t, []int{12, 10}, []int{12, 10}) assert.That(t, []int{12, 10}, h.ElementsAre(12, 10)) assert.That(t, []int{12, 10}, h.ElementsAre(h.LT(20), 10))
Example ¶
package main import ( "fmt" "github.com/grailbio/testutil/expect" "github.com/grailbio/testutil/h" ) type T struct{} func (t *T) Error(args ...interface{}) { fmt.Println(args...) } func (t *T) Fatal(args ...interface{}) { fmt.Println(args...) panic("fatal") } func main() { t := &T{} expect.That(t, []int{10, 11}, h.ElementsAre([]interface{}{10, 11}...)) expect.That(t, []int{10, 16}, h.ElementsAre(10, h.GT(15))) expect.That(t, []int{}, h.ElementsAre()) }
Output:
func ElementsAreArray ¶
func ElementsAreArray(w interface{}) *Matcher
ElementsAreArray checks if a sequence matches the given array of values, in order. The argument must be array-like (slice, array, string, ...).
Example:
// Note: the below is the same as assert.EQ(t, []int{12, 10}, []int{12, 10}) assert.That(t, []int{12, 10}, h.ElementsAreArray([]int{12, 10})) assert.That(t, []int{12, 10}, h.ElementsAreArray([]interface{}{h.LT(20), 10)))
Example ¶
package main import ( "fmt" "github.com/grailbio/testutil/expect" "github.com/grailbio/testutil/h" ) type T struct{} func (t *T) Error(args ...interface{}) { fmt.Println(args...) } func (t *T) Fatal(args ...interface{}) { fmt.Println(args...) panic("fatal") } func main() { t := &T{} expect.That(t, []int{10, 16}, h.ElementsAreArray([]int{10, 16})) expect.That(t, []int{10, 16}, h.ElementsAreArray([]interface{}{10, h.GT(15)})) }
Output:
func GE ¶
func GE(want interface{}) *Matcher
GE checks if got >= want. Got and want must be a numeric (int*, uint*, float*) or a string type.
func GT ¶
func GT(want interface{}) *Matcher
GT checks if got > want. Got and want must be a numeric (int*, uint*, float*) or a string type.
func HasPrefix ¶
HasPrefix checks if the value starts with the given substring. If the target value is not a string, it is converted to a string with fmt.Sprintf("%v").
func HasSubstr ¶
HasSubstr checks if the value contains the given substring. If the target value is not a string, it is converted to a string with fmt.Sprintf("%v").
Example ¶
package main import ( "fmt" "github.com/grailbio/testutil/expect" "github.com/grailbio/testutil/h" ) type T struct{} func (t *T) Error(args ...interface{}) { fmt.Println(args...) } func (t *T) Fatal(args ...interface{}) { fmt.Println(args...) panic("fatal") } func main() { t := &T{} expect.That(t, "abc def", h.HasSubstr("c d")) expect.That(t, 12345, h.HasSubstr("234")) }
Output:
func LE ¶
func LE(want interface{}) *Matcher
LE checks if got <= want. Got and want must be a numeric (int*, uint*, float*) or a string type.
Example ¶
package main import ( "fmt" "github.com/grailbio/testutil/expect" "github.com/grailbio/testutil/h" ) type T struct{} func (t *T) Error(args ...interface{}) { fmt.Println(args...) } func (t *T) Fatal(args ...interface{}) { fmt.Println(args...) panic("fatal") } func main() { t := &T{} expect.That(t, 10, h.LE(11)) expect.That(t, 10, h.LE(10)) expect.That(t, 10, h.Not(h.LE(9))) var z0 [2]int x := &z0[0] y := &z0[1] expect.That(t, x, h.LE(y)) expect.That(t, x, h.LE(x)) }
Output:
func LT ¶
func LT(want interface{}) *Matcher
LT checks if got < want. Got and want must be a numeric (int*, uint*, float*) or a string type.
Example ¶
package main import ( "fmt" "github.com/grailbio/testutil/expect" "github.com/grailbio/testutil/h" ) type T struct{} func (t *T) Error(args ...interface{}) { fmt.Println(args...) } func (t *T) Fatal(args ...interface{}) { fmt.Println(args...) panic("fatal") } func main() { t := &T{} expect.That(t, 10, h.LT(11)) expect.That(t, 10, h.Not(h.LT(10))) expect.That(t, 10, h.Not(h.LT(9))) var z0 [2]int x := &z0[0] y := &z0[1] expect.That(t, x, h.LT(y)) }
Output:
func MapContains ¶
func MapContains(key, val interface{}) *Matcher
MapContains checks if a map contains an entry with the given key and value. Key and value can be immediate values, or Matchers. The target value must be a map.
Example:
assert.That(t, map[int]int{10:15, 11:20}, h.MapContains(10, 15)) assert.That(t, map[int]int{10:15, 11:20}, h.MapContains(h.Any, 15)) assert.That(t, map[int]int{10:15, 11:20}, h.MapContains(h.LT(11), h.GT(12)))
func Nil ¶
func Nil() *Matcher
Nil checks that the value is nil.
Example ¶
package main import ( "fmt" "unsafe" "github.com/grailbio/testutil/expect" "github.com/grailbio/testutil/h" ) type T struct{} func (t *T) Error(args ...interface{}) { fmt.Println(args...) } func (t *T) Fatal(args ...interface{}) { fmt.Println(args...) panic("fatal") } func main() { t := &T{} expect.That(t, nil, h.Nil()) var m map[int]int expect.That(t, m, h.Nil()) expect.That(t, map[int]int{}, h.Not(h.Nil())) var c chan int expect.That(t, c, h.Nil()) expect.That(t, make(chan int), h.Not(h.Nil())) var i interface{} expect.That(t, i, h.Nil()) var p *int expect.That(t, p, h.Nil()) expect.That(t, unsafe.Pointer(p), h.Nil()) var q int p = &q expect.That(t, p, h.Not(h.Nil())) expect.That(t, unsafe.Pointer(p), h.Not(h.Nil())) }
Output:
func None ¶
func None() *Matcher
None matches nothing.
Example ¶
package main import ( "fmt" "github.com/grailbio/testutil/expect" "github.com/grailbio/testutil/h" ) type T struct{} func (t *T) Error(args ...interface{}) { fmt.Println(args...) } func (t *T) Fatal(args ...interface{}) { fmt.Println(args...) panic("fatal") } func main() { t := &T{} expect.That(t, nil, h.Not(h.None())) }
Output:
func Not ¶
func Not(val interface{}) *Matcher
Not negates the result of the child matcher. The argument can be a *Matcher, or any value.
Example:
assert.That(t, "abc", h.Not(h.Regexp("e+"))) assert.That(t, 10, h.Not(11))
Example ¶
package main import ( "fmt" "github.com/grailbio/testutil/expect" "github.com/grailbio/testutil/h" ) type T struct{} func (t *T) Error(args ...interface{}) { fmt.Println(args...) } func (t *T) Fatal(args ...interface{}) { fmt.Println(args...) panic("fatal") } func main() { t := &T{} expect.That(t, 10, h.Not(11)) expect.That(t, "abc", h.Not(h.HasPrefix("b"))) }
Output:
func Panics ¶
func Panics(want interface{}) *Matcher
Panics checks that the a function invocation panics with the given value. If you just want to test that the code panics, pass NotNil() as the matcher.
Example:
assert.That(t, func() { panic("fox jumped over a dog") }, h.Panics(h.Regexp("j.*d")) assert.That(t, func() { panic("fox jumped over a dog") }, h.Panics(h.NotNil()))
Example ¶
package main import ( "fmt" "github.com/grailbio/testutil/expect" "github.com/grailbio/testutil/h" ) type T struct{} func (t *T) Error(args ...interface{}) { fmt.Println(args...) } func (t *T) Fatal(args ...interface{}) { fmt.Println(args...) panic("fatal") } func main() { t := &T{} expect.That(t, func() { fmt.Println("hello") }, h.Panics(h.Nil())) expect.That(t, func() { panic("blue fox jumped over a red hen") }, h.Panics(h.HasSubstr("fox jumped"))) }
Output: hello
func Regexp ¶
func Regexp(want interface{}) *Matcher
Regexp checks that the value matches the given regex. The regex can be given as a string, or *regexp.Regexp. The regexp is matched using regexp.Regexp.Find. If the target value is not a string, it is converted to a string with fmt.Sprintf("%v").
Example:
assert.That(t, "fox jumped over a dog", h.Regexp("j.*d"))
Example ¶
package main import ( "fmt" "github.com/grailbio/testutil/expect" ) type T struct{} func (t *T) Error(args ...interface{}) { fmt.Println(args...) } func (t *T) Fatal(args ...interface{}) { fmt.Println(args...) panic("fatal") } func main() { t := &T{} expect.Regexp(t, 12345, "2.*4") expect.Regexp(t, "12345", "2.*4") }
Output:
func UnorderedElementsAre ¶
func UnorderedElementsAre(w ...interface{}) *Matcher
UnorderedElementsAre checks if the target sequence matches some permutation of the given values.
Example ¶
package main import ( "fmt" "github.com/grailbio/testutil/expect" "github.com/grailbio/testutil/h" ) type T struct{} func (t *T) Error(args ...interface{}) { fmt.Println(args...) } func (t *T) Fatal(args ...interface{}) { fmt.Println(args...) panic("fatal") } func main() { t := &T{} expect.That(t, []int{12, 10, 11}, h.UnorderedElementsAre(10, 11, 12)) expect.That(t, []int{12, 11, 10}, h.UnorderedElementsAre(10, 11, 12)) expect.That(t, []int{11, 10, 12}, h.UnorderedElementsAre(10, 11, 12)) expect.That(t, []int{10}, h.UnorderedElementsAre(10)) expect.That(t, []int{}, h.UnorderedElementsAre()) }
Output:
Example (Struct) ¶
package main import ( "fmt" "github.com/grailbio/testutil/expect" "github.com/grailbio/testutil/h" ) type T struct{} func (t *T) Error(args ...interface{}) { fmt.Println(args...) } func (t *T) Fatal(args ...interface{}) { fmt.Println(args...) panic("fatal") } func main() { t := &T{} type T struct { Name string Type string } val := []T{ T{Name: "n0", Type: "t0"}, T{Name: "n1", Type: "t1"}, } expect.That(t, val, h.UnorderedElementsAre( T{Name: "n1", Type: "t1"}, T{Name: "n0", Type: "t0"})) }
Output:
func UnorderedElementsAreArray ¶
func UnorderedElementsAreArray(w interface{}) *Matcher
UnorderedElementsAreArray checks if the target sequence matches some permutation of the given list of values. The argument must be array-like (slice, array, string, ...).
Example ¶
package main import ( "fmt" "github.com/grailbio/testutil/expect" "github.com/grailbio/testutil/h" ) type T struct{} func (t *T) Error(args ...interface{}) { fmt.Println(args...) } func (t *T) Fatal(args ...interface{}) { fmt.Println(args...) panic("fatal") } func main() { t := &T{} expect.That(t, []int{12, 10, 11}, h.UnorderedElementsAreArray([]int{10, 11, 12})) expect.That(t, []int{12, 11, 10}, h.UnorderedElementsAreArray([]int{10, 11, 12})) expect.That(t, []int{11, 10, 12}, h.UnorderedElementsAreArray([]int{10, 11, 12})) expect.That(t, []int{10}, h.UnorderedElementsAreArray([]int{10})) expect.That(t, []int{}, h.UnorderedElementsAreArray([]int{})) }
Output:
Example (Struct) ¶
package main import ( "fmt" "github.com/grailbio/testutil/expect" "github.com/grailbio/testutil/h" ) type T struct{} func (t *T) Error(args ...interface{}) { fmt.Println(args...) } func (t *T) Fatal(args ...interface{}) { fmt.Println(args...) panic("fatal") } func main() { t := &T{} type T struct { Name string Type string } val := []T{ T{Name: "n0", Type: "t0"}, T{Name: "n1", Type: "t1"}, } expect.That(t, val, h.UnorderedElementsAreArray([]T{ {Name: "n1", Type: "t1"}, {Name: "n0", Type: "t0"}})) }
Output:
func WhenSorted ¶
WhenSorted wraps another matcher that matches against a sequence, most often ElementsAre. It sorts the target value using go's "<" operator, then passes the resulting sequence to the underlying matcher. The target value must be an array, slice, or string.
Example:
assert.That(t, []int{12, 10}, h.WhenSorted(h.ElementsAre(10, 12)))
Example ¶
package main import ( "fmt" "github.com/grailbio/testutil/expect" "github.com/grailbio/testutil/h" ) type T struct{} func (t *T) Error(args ...interface{}) { fmt.Println(args...) } func (t *T) Fatal(args ...interface{}) { fmt.Println(args...) panic("fatal") } func main() { t := &T{} expect.That(t, []int{11, 10, 12}, h.WhenSorted(h.ElementsAre(10, 11, 12))) }
Output:
func Zero ¶
func Zero() *Matcher
Zero checks if the value is the zero value of its type.
Example ¶
package main import ( "fmt" "github.com/grailbio/testutil/expect" "github.com/grailbio/testutil/h" ) type T struct{} func (t *T) Error(args ...interface{}) { fmt.Println(args...) } func (t *T) Fatal(args ...interface{}) { fmt.Println(args...) panic("fatal") } func main() { t := &T{} expect.That(t, 0, h.Zero()) expect.That(t, 0.0, h.Zero()) expect.That(t, "", h.Zero()) expect.That(t, 1, h.Not(h.Zero())) expect.That(t, 0.1, h.Not(h.Zero())) expect.That(t, "x", h.Not(h.Zero())) type tt struct{ x int } expect.That(t, tt{x: 0}, h.Zero()) expect.That(t, tt{x: 1}, h.Not(h.Zero())) expect.That(t, nil, h.Zero()) expect.That(t, []int{}, h.Not(h.Zero())) expect.That(t, []int{0}, h.Not(h.Zero())) }
Output:
type Result ¶
type Result struct {
// contains filtered or unexported fields
}
Result is the result of a matcher.
func NewResult ¶
NewResult creates a new Result object. If matched (or !matched), the status will be Match (Mismatch), respectively. got is the value under test.
type Status ¶
type Status int
Status represents the match result.
const ( // DomainError is reported when the value has a wrong type or cardinality. // For example, assert.That(t, 10, h.LT("foo")) raises this error. // // DomainError is different from Mismatch in that Not() of Mismatch becomes a // Match, but Not() of DomainError remains a DomainError. DomainError Status = iota // Match is reported on a successful match. Match // Mismatch is reported when the matcher fails. Mismatch )