README
¶
expect
This package provides unit test helpers for checking values and errors, powered
by the cmp,
errors, and
reflect packages.
See godoc for usage and examples.
Installation
This package can be imported into a module-aware Go project as follows:
go get github.com/nicheinc/expect
Contributing
See CONTRIBUTING.md for details on contributing to the
expect package.
Documentation
¶
Index ¶
- Variables
- func DeepEqual[U any](t T, actual, expected U)
- func Equal[U any](t T, actual, expected U, opts ...cmp.Option)
- func EqualUnordered[Slice ~[]Elem, Elem constraints.Ordered](t T, actual, expected Slice, opts ...cmp.Option)
- func ErrorNil(t T, err error)
- func ErrorNonNil(t T, err error)
- type ErrorCheck
- type T
- type TMock
Constants ¶
This section is empty.
Variables ¶
var ErrTest = errors.New("test error")
ErrTest is an error for use in unit tests when the specific error type doesn't matter. It can be useful for testing handling of arbitrary errors from mocked dependencies.
The unit test in the following example fails because each errors.New call produces a new, independent error value. Changing errors.New("test error") to expect.ErrTest in both places allows it to pass.
func FunctionUnderTest(dependency func() error) error {
return dependency()
}
func TestFunctionUnderTest(t *testing.T) {
dependencyMock := func() error {
return errors.New("test error")
}
expectedErr := errors.New("test error")
actualErr := FunctionUnderTest(dependencyMock)
if !errors.Is(actualErr, expectedErr) {
t.Errorf("Unexpected error")
}
}
Functions ¶
func DeepEqual ¶
DeepEqual asserts that actual = expected according to the semantics of reflect.DeepEqual. This function should never be used to check error types since it's unaware of error wrapping. For non-errors, expect.Equal is almost always preferred since it has more legible output. This function exists for the rare circumstances where expect.Equal can't easily handle the given types.
func Equal ¶
Equal asserts that actual = expected according to the semantics of cmp.Equal/cmp.Diff. It forwards opts to the cmp library; see the cmp.Option documentation for details. For error-checking, an expect.ErrorCheck is usually preferred.
func EqualUnordered ¶
func EqualUnordered[Slice ~[]Elem, Elem constraints.Ordered](t T, actual, expected Slice, opts ...cmp.Option)
EqualUnordered asserts that the actual and expected slices have the same elements, irrespective of order. It's a convenience function for calling expect.Equal with cmpopts.SortSlices, using < in the lessFunc.
func ErrorNonNil ¶
ErrorNonNil is an ErrorCheck that an error is non-nil.
Types ¶
type ErrorCheck ¶
ErrorCheck is a type of test helper function for asserting that an error has an expected value. Different unit tests may call for different degrees of specificity when evaluating whether an error is expected, such as:
- Is the error nil or non-nil?
- Does the error contain another error?
- Does the error contain a list of errors?
- Is the error convertible to a certain type?
This function provides a uniform type over these checks so that they can be mixed within a single table-driven test function. The other functions in this file are or return a function conforming to the ErrorCheck signature.
testCases := []struct{
name string
// ...
errorCheck expect.ErrorCheck
}{
{
name: "CausesUnexpectedEOF",
// ...
errorCheck: expect.ErrorIs(io.ErrUnexpectedEOF ),
}
{
name: "CausesSyntaxError",
// ...
errorCheck: expect.ErrorAs[*json.SyntaxError](),
}
}
for _, testCase := range testCases {
t.Run(testCase.name, func(t *testing.T) {
err := FunctionUnderTest(/* ... */)
testCase.errorCheck(t, err)
})
}
func ErrorAs ¶
func ErrorAs[Target error]() ErrorCheck
ErrorAs returns an ErrorCheck that an error can be converted to the Target error type using errors.As.
func ErrorIs ¶
func ErrorIs(expected error) ErrorCheck
ErrorIs returns an ErrorCheck that an error is the given error, as defined by errors.Is.
func ErrorIsAll ¶
func ErrorIsAll(expected ...error) ErrorCheck
ErrorIsAll returns an ErrorCheck that an error (1) is all of the given expected errors as defined by errors.Is and (2) is nil only if expected is empty. It does not ensure that expected is exhaustive; i.e. there could be an error E for which errors.Is(err, E) returns true that is not included in expected, despite ErrorIsAll passing.
This check is useful for testing code that uses errors.Join to return multiple errors.
type T ¶
T exposes the testing.T methods that the expect package uses. Calls in unit tests to expect package functions should pass the test's *testing.T for parameters of this type.
type TMock ¶
type TMock struct {
HelperStub func()
HelperCalled int32
ErrorfStub func(format string, args ...any)
ErrorfCalled int32
}
TMock is a mock implementation of the T interface.
Source Files