Documentation ¶
Overview ¶
Package oglematchers provides a set of matchers useful in a testing or mocking framework. These matchers are inspired by and mostly compatible with Google Test for C++ and Google JS Test.
This package is used by github.com/smartystreets/assertions/internal/ogletest and github.com/smartystreets/assertions/internal/oglemock, which may be more directly useful if you're not writing your own testing package or defining your own matchers.
Index ¶
- type FatalError
- type Matcher
- func AnyOf(vals ...interface{}) Matcher
- func Contains(x interface{}) Matcher
- func DeepEquals(x interface{}) Matcher
- func Equals(x interface{}) Matcher
- func GreaterOrEqual(x interface{}) Matcher
- func GreaterThan(x interface{}) Matcher
- func LessOrEqual(x interface{}) Matcher
- func LessThan(x interface{}) Matcher
- func Not(m Matcher) Matcher
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type FatalError ¶
type FatalError struct {
// contains filtered or unexported fields
}
FatalError is an implementation of the error interface that may be returned from matchers, indicating the error should be propagated. Returning a *FatalError indicates that the matcher doesn't process values of the supplied type, or otherwise doesn't know how to handle the value.
For example, if GreaterThan(17) returned false for the value "taco" without a fatal error, then Not(GreaterThan(17)) would return true. This is technically correct, but is surprising and may mask failures where the wrong sort of matcher is accidentally used. Instead, GreaterThan(17) can return a fatal error, which will be propagated by Not().
func NewFatalError ¶
func NewFatalError(s string) *FatalError
NewFatalError creates a FatalError struct with the supplied error text.
func (*FatalError) Error ¶
func (e *FatalError) Error() string
type Matcher ¶
type Matcher interface { // Check whether the supplied value belongs to the the set defined by the // matcher. Return a non-nil error if and only if it does not. // // The error describes why the value doesn't match. The error text is a // relative clause that is suitable for being placed after the value. For // example, a predicate that matches strings with a particular substring may, // when presented with a numerical value, return the following error text: // // "which is not a string" // // Then the failure message may look like: // // Expected: has substring "taco" // Actual: 17, which is not a string // // If the error is self-apparent based on the description of the matcher, the // error text may be empty (but the error still non-nil). For example: // // Expected: 17 // Actual: 19 // // If you are implementing a new matcher, see also the documentation on // FatalError. Matches(candidate interface{}) error // Description returns a string describing the property that values matching // this matcher have, as a verb phrase where the subject is the value. For // example, "is greather than 17" or "has substring "taco"". Description() string }
A Matcher is some predicate implicitly defining a set of values that it matches. For example, GreaterThan(17) matches all numeric values greater than 17, and HasSubstr("taco") matches all strings with the substring "taco".
Matchers are typically exposed to tests via constructor functions like HasSubstr. In order to implement such a function you can either define your own matcher type or use NewMatcher.
func AnyOf ¶
func AnyOf(vals ...interface{}) Matcher
AnyOf accepts a set of values S and returns a matcher that follows the algorithm below when considering a candidate c:
If there exists a value m in S such that m implements the Matcher interface and m matches c, return true.
Otherwise, if there exists a value v in S such that v does not implement the Matcher interface and the matcher Equals(v) matches c, return true.
Otherwise, if there is a value m in S such that m implements the Matcher interface and m returns a fatal error for c, return that fatal error.
Otherwise, return false.
This is akin to a logical OR operation for matchers, with non-matchers x being treated as Equals(x).
func Contains ¶
func Contains(x interface{}) Matcher
Return a matcher that matches arrays slices with at least one element that matches the supplied argument. If the argument x is not itself a Matcher, this is equivalent to Contains(Equals(x)).
func DeepEquals ¶
func DeepEquals(x interface{}) Matcher
DeepEquals returns a matcher that matches based on 'deep equality', as defined by the reflect package. This matcher requires that values have identical types to x.
func Equals ¶
func Equals(x interface{}) Matcher
Equals(x) returns a matcher that matches values v such that v and x are equivalent. This includes the case when the comparison v == x using Go's built-in comparison operator is legal (except for structs, which this matcher does not support), but for convenience the following rules also apply:
Type checking is done based on underlying types rather than actual types, so that e.g. two aliases for string can be compared:
type stringAlias1 string type stringAlias2 string
a := "taco" b := stringAlias1("taco") c := stringAlias2("taco")
ExpectTrue(a == b) // Legal, passes ExpectTrue(b == c) // Illegal, doesn't compile
ExpectThat(a, Equals(b)) // Passes ExpectThat(b, Equals(c)) // Passes
Values of numeric type are treated as if they were abstract numbers, and compared accordingly. Therefore Equals(17) will match int(17), int16(17), uint(17), float32(17), complex64(17), and so on.
If you want a stricter matcher that contains no such cleverness, see IdenticalTo instead.
Arrays are supported by this matcher, but do not participate in the exceptions above. Two arrays compared with this matcher must have identical types, and their element type must itself be comparable according to Go's == operator.
func GreaterOrEqual ¶
func GreaterOrEqual(x interface{}) Matcher
GreaterOrEqual returns a matcher that matches integer, floating point, or strings values v such that v >= x. Comparison is not defined between numeric and string types, but is defined between all integer and floating point types.
x must itself be an integer, floating point, or string type; otherwise, GreaterOrEqual will panic.
func GreaterThan ¶
func GreaterThan(x interface{}) Matcher
GreaterThan returns a matcher that matches integer, floating point, or strings values v such that v > x. Comparison is not defined between numeric and string types, but is defined between all integer and floating point types.
x must itself be an integer, floating point, or string type; otherwise, GreaterThan will panic.
func LessOrEqual ¶
func LessOrEqual(x interface{}) Matcher
LessOrEqual returns a matcher that matches integer, floating point, or strings values v such that v <= x. Comparison is not defined between numeric and string types, but is defined between all integer and floating point types.
x must itself be an integer, floating point, or string type; otherwise, LessOrEqual will panic.
func LessThan ¶
func LessThan(x interface{}) Matcher
LessThan returns a matcher that matches integer, floating point, or strings values v such that v < x. Comparison is not defined between numeric and string types, but is defined between all integer and floating point types.
x must itself be an integer, floating point, or string type; otherwise, LessThan will panic.