matchers

func For ¶

func For(t TestingT, name string) AssertionScope

For is the same as In, but adds a descriptive name in front of whatever assertions are done. In this example, a failure would be logged as "score: does not equal 2" rather than only "does not equal 2".

func TestSomething(t *testing.T) {
    matchers.For(t, "score").Assert(x, matchers.Equal(2))
}

func In ¶

func In(t TestingT) AssertionScope

In is for use with any test framework that has a test scope type with the same basic methods as Go's testing.T (as defined by the TestingT interface). Any calls to Assert or Require on the returned AssertionScope will update the state of t.

func TestSomething(t *testing.T) {
    matchers.In(t).Assert(x, matchers.Equal(2))
}

See also For.

func KV ¶

func KV(key interface{}, valueMatcher Matcher) KeyValueMatcher

KV is a shortcut for constructing a KeyValueMatcher for use with MapOf or MapIncluding.

func AllOf ¶

func AllOf(matchers ...Matcher) Matcher

AllOf requires that the input value passes all of the specified Matchers. If it fails, the failure message describes all of the Matchers that failed.

func AnyOf ¶

func AnyOf(matchers ...Matcher) Matcher

AnyOf requires that the input value passes at least one of the specified Matchers. It will not execute any further matches after the first pass. If it fails all of them, the failure message describes all of the failure conditions.

func BeNil ¶

func BeNil() Matcher

BeNil is a matcher that passes if the value is a nil interface value, a nil pointer, a nil slice, or a nil map.

func Equal ¶

func Equal(expectedValue interface{}) Matcher

Equal is a matcher that tests whether the input value matches the expected value according to reflect.DeepEqual, except in the case of numbers where an exact type match is not needed.

func Items ¶

func Items(matchers ...Matcher) Matcher

Items is a matcher for a slice or array value. It tests that the number of elements is equal to the number of matchers, and that each element matches the corresponding matcher in order.

s := []int{6,2}
matchers.Items(matchers.Equal(6), matchers.Equal(2)).Test(s) // pass
matchers.Items(matchers.Equal(2), matchers.Equal(6)).Test(s) // fail

func ItemsInAnyOrder ¶

func ItemsInAnyOrder(matchers ...Matcher) Matcher

ItemsInAnyOrder is a matcher for a slice or array value. It tests that the number of elements is equal to the number of matchers, and that each matcher matches an element.

s := []int{6,2}
matchers.ItemsInAnyOrder(matchers.Equal(2), matchers.Equal(6)).Test(s) // pass

func JSONEqual ¶

func JSONEqual(expectedValue interface{}) Matcher

JSONEqual is similar to Equal but with richer behavior for JSON values.

Both the expected value and the actual value can be of any type. If the type is either []byte or json.RawMessage, it will be interpreted as JSON which will be parsed; for all other types, it will be first serialized to JSON with json.Marshal and then parsed. Then the parsed values or data structures are tested for deep equality. For instance, this test passes:

matchers.In(t).Assert([]byte(`{"a": true, "b": false`),
    matchers.JSONEqual(map[string]bool{b: false, a: true}))

The shortcut JSONEqualStr can be used to avoid writing []byte() if the expected value is already a serialized JSON string.

func JSONStrEqual ¶

func JSONStrEqual(expectedValue string) Matcher

JSONStrEqual is equivalent to JSONEqual except that it converts expectedValue from string to []byte first, and if the input value is a string it does the same. This is convenient if you are matching against already-serialized JSON, because otherwise passing a string value to JSONEqual would cause that value to be serialized in the way JSON represents strings, that is, with quoting and escaping.

matchers.In(t).Assert(`{"a": true, "b": false`,
    matchers.JSONStrEqual(`{"b": false, "a": true}`)

func MapIncluding ¶

func MapIncluding(keyValueMatchers ...KeyValueMatcher) Matcher

MapIncluding is a matcher for a map value. It tests that the map contains all of the keys in the specified list, and that the matcher for each key is satisfied by the corresponding value. The map may also contain additional keys.

m := map[string]int{"a": 6, "b": 2}
matchers.MapOf(
    matchers.KV("a", matchers.Equal(2)),
    matchers.KV("b", matchers.Equal(6)),
}).Test(s) // pass

func MapOf ¶

func MapOf(keyValueMatchers ...KeyValueMatcher) Matcher

MapOf is a matcher for a map value. It tests that the map has exactly the same keys as the specified list, and that the matcher for each key is satisfied by the corresponding value.

m := map[string]int{"a": 6, "b": 2}
matchers.MapOf(
    matchers.KV("a", matchers.Equal(2)),
    matchers.KV("b", matchers.Equal(6)),
}).Test(s) // pass

func New ¶

func New(
	test TestFunc,
	describeTest DescribeTestFunc,
	describeFailure DescribeFailureFunc,
) Matcher

New creates a Matcher.

func Not ¶

func Not(matcher Matcher) Matcher

Not negates the result of another Matcher.

matchers.Not(Equal(3)).Assert(t, 4)
// failure message will describe expectation as "not (equal to 3)"

func StringContains ¶

func StringContains(substring string) Matcher

StringContains is a matcher for string values that tests for the presence of a substring, case-sensitively.

func StringHasPrefix ¶

func StringHasPrefix(prefix string) Matcher

StringHasPrefix is a matcher for string values that calls strings.HasPrefix.

func StringHasSuffix ¶

func StringHasSuffix(suffix string) Matcher

StringHasSuffix is a matcher for string values that calls strings.HasSuffix.

func JSONArray ¶

func JSONArray() MatcherTransform

JSONArray is a MatcherTransform that takes any value serializable as a JSON array, and converts it to []interface{} slice; then you can apply a matcher to that slice. It fails if the value is not serializable as a JSON array.

myArray := []byte(`["a", "b", "c"]`)
matchers.In(t).Assert(myArray,
    matchers.JSONArray().Should(matchers.Length().Should(matchers.Equal(3))))

func JSONMap ¶

func JSONMap() MatcherTransform

JSONMap is a MatcherTransform that takes any value serializable as a JSON object, and converts it to a map[interface{}]interface{}; then you can apply a matcher to that map. It fails if the value is not serializable as a JSON object.

myArray := []byte(`{"a": 1, "b": "xyz"}`)
matchers.In(t).Assert(myJSON,
    matchers.JSONMap().Should(
        matchers.MapOf(
            matchers.KV("a", matchers.Equal(1)),
            matchers.KV("b", matchers.StringHasPrefix("x")),
        )))

func JSONOptProperty ¶

func JSONOptProperty(name string) MatcherTransform

JSONOptProperty is the same as JSONProperty, but if the property does not exist, it treats it as a nil value rather than error.

func JSONProperty ¶

func JSONProperty(name string) MatcherTransform

JSONProperty is a MatcherTransform that takes any value serializable as a JSON object and gets a named property from it; then you can apply a matcher to the value of that property. It fails if no such property exists (see OptJSONProperty).

myObject := []byte(`{"a": {"b": 2}}`)
matchers.In(t).Assert(myObject,
    matchers.JSONProperty("a").Should(
        matchers.JSONProperty("b").Should(Equal(2))))

An alternative is to use JSONMap combined with MapOf or MapIncluding.

func Length ¶

func Length() MatcherTransform

Length is a MatcherTransform that takes any value len() can operate on, gets its length, and applies some matcher to the result.

func OptValueForKey ¶

func OptValueForKey(key interface{}) MatcherTransform

OptValueForKey is a MatcherTransform that takes a map, looks up a value in it by key, and applies a matcher to that value. If no such key exists, it returns the zero value for the type. If the map was nil, it returns nil.

myMap := map[string]map[string]int{"a": map[string]int{"b": 2}}
matchers.In(t).Assert(myMap,
    matchers.OptValueForKey("a").Should(
        matchers.OptValueForKey("c").Should(Equal(0))))

func Transform ¶

func Transform(
	name string,
	getValue func(interface{}) (interface{}, error),
) MatcherTransform

Transform creates a MatcherTransform. The name parameter is a brief description of what the output value is in relation to the input value (for instance, if you are getting a field called F from a struct, it could simply be "F"); it will be prefixed to the description of any Matcher that you use with Should(). The getValue parameter is a function that transforms the original value into the value you will be testing.

func ValueForKey ¶

func ValueForKey(key interface{}) MatcherTransform

ValueForKey is a MatcherTransform that takes a map, looks up a value in it by key, and applies a matcher to that value. It fails if no such key exists (see OptValueForKey).

myMap := map[string]map[string]int{"a": map[string]int{"b": 2}}
matchers.In(t).Assert(myObject,
    matchers.ValueForKey("a").Should(
        matchers.ValueForKey("b").Should(Equal(2))))