package module
Version: v1.0.7 Latest Latest

This package is not in the latest version of its module.

Go to latest
Published: Mar 23, 2023 License: BSD-3-Clause Imports: 2 Imported by: 0



A hamcrest-like assertion library for Go. GoCrest matchers are composable, self-describing and can be strung together in a more readable form to create flexible assertions.

Inspired by Hamcrest.

Build Go Report Card GoDoc Coverage Status

Package import

import (


then.AssertThat(testing, "hi", is.EqualTo("bye").Reason("we are going"))


we are going
Expected: value equal to <bye>
     but: <hi>

Composed with AllOf:

then.AssertThat(t, "abcdef", is.AllOf(is.ValueContaining("abc"), is.LessThan("ghi")))

Asynchronous Matching (v1.0.7 onwards):

  then.WithinFiveSeconds(t, func(eventually gocrest.TestingT) {
		then.AssertThat(eventually, by.Reading(slowReader, 1024), is.EqualTo([]byte("abcdefghijklmnopqrstuv")))
	then.Eventually(t, time.Second*5, time.Second, func(eventually gocrest.TestingT) {
		then.AssertThat(eventually, by.Channelling(channel), is.EqualTo(3).Reason("should not fail"))

Matchers so far..

  • is.EqualTo(x)
  • is.EqualToIgnoringWhitespace(string) - compares two strings without comparing their whitespace characters.
  • is.Nil() - value must be nil
  • is.ValueContaining(expected) -- acts like containsAll
  • is.Not(m *Matcher) -- logical not of matcher's result
  • is.MatchForPattern(regex string) -- a string regex expression
  • has.FunctionNamed(string x) - checks if an interface has a function (method)
  • has.FieldNamed(string x) - checks if a struct has a field named x
  • is.AllOf(... *Matcher) - returns true if all matchers match
  • is.AnyOf(... *Matcher) - return true if any matcher matches
  • is.GreaterThan(expected) - checks if actual > expected
  • is.LessThan(expected)
  • is.Empty() - matches if the actual is "", nil or len(actual)==0
  • is.LessThan(x)
  • is.LessThanOrEqualTo(x)
  • is.GreaterThan(x)
  • is.GreaterThanOrEqualTo(x)
  • has.Length(x) - matcher if given value (int or matcher) matches the len of the given
  • has.Prefix(x) - string starts with x
  • has.Suffix(x) - string ends with x
  • has.Key(x) - map has key x
  • has.AllKeys(T x, T y) (or has.AllKeys([]T{x,y})) - finds key of type T in map
  • has.EveryElement(x1...xn) - checks if actual[i] matches corresponding expectation (x[i])
  • has.StructWithValues(map[string]*gocrest.Matcher) - checks if actual[key] matches corresponding expectation (x[key])

For more comprehensive documentation see godoc.




This section is empty.


This section is empty.


This section is empty.


type Matcher

type Matcher struct {
	// Matches returns true if the function matches.
	Matches func(actual interface{}) bool
	// Describe describes the matcher (e.g. "a value EqualTo(foo)" - foo being the expected value)
	Describe string
	// Actual is used by then.AssertThat if the matcher
	// needs to resolve the string description of the actual.
	// This is usually if the actual is a complex type.
	Actual string
	// ReasonString is a comment on why the matcher did not match, and set by the caller not the matcher.
	// Usually, this is set by the helper function, e.g. FooMatcher("foo").Reason("foo didn't foobar")
	ReasonString string

Matcher provides the structure for matcher operations.

func (*Matcher) AppendActual added in v1.0.1

func (matcher *Matcher) AppendActual(actualAsString string)

AppendActual appends an actual string to the matcher's actual description. This is useful if you want to preserve sub-matchers actual values. See is.AllOf() matcher for an example.

func (*Matcher) Reason

func (matcher *Matcher) Reason(r string) *Matcher

Reason for the mismatch.

func (*Matcher) Reasonf

func (matcher *Matcher) Reasonf(format string, args ...interface{}) *Matcher

Reasonf allows a formatted reason for the mismatch.

func (*Matcher) String added in v1.0.6

func (matcher *Matcher) String() string

Describes the Matcher to conform to the Stringer interface

type TestingT

type TestingT interface {
	Logf(format string, args ...interface{})
	Errorf(format string, args ...interface{})
	Failed() bool

TestingT supplies a convenience interface that matches the testing.T interface.


Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL