README
¶
shoulda
A Go testing library that shoulda be made as simple as possible, but not simpler.
You really shoulda not use it yet.
License
cmp/cmp.go and internal/diff/diff.go
are adapted from the Go source code and distributed under a similar license
(cmp/LICENSE, internal/diff/LICENSE).
Documentation
¶
Overview ¶
Package shoulda provides an assertion library that is as simple as possible, but not simpler.
Assertions ¶
The assertion functions return true if the assertion passes, return false and fail the test otherwise.
Comparison ¶
Helpers ending with `f` accept fmt.Printf-like format string and arguments for additional messages. The default messages are also included.
Index ¶
- Variables
- func BeDeepEqual(tb TB, actual, expected any) bool
- func BeEqual[T cmp.Ordered](tb TB, actual, expected T) bool
- func BeFalse(tb TB, actual bool) bool
- func BeGreater[T cmp.Ordered](tb TB, actual, expected T) bool
- func BeLess[T cmp.Ordered](tb TB, actual, expected T) bool
- func BeNil(tb TB, actual any) bool
- func BeNilf(tb TB, actual any, format string, args ...any) bool
- func BeTrue(tb TB, actual bool) bool
- func BeZero[T comparable](tb TB, actual T) bool
- func BeZerof[T comparable](tb TB, actual T, format string, args ...any) bool
- func CompareEqual[A, E any](tb TB, actual A, expected E, compare func(_ A, _ E) int) bool
- func CompareGreater[A, E any](tb TB, actual A, expected E, compare func(_ A, _ E) int) bool
- func CompareLess[A, E any](tb TB, actual A, expected E, compare func(_ A, _ E) int) bool
- func CompareWith[A, E any](tb TB, actual A, expected E, order cmp.Order, compare func(_ A, _ E) int) bool
- func Error(tb TB, actual error) bool
- func ErrorIs(tb TB, actual, expected error) bool
- func Errorf(tb TB, actual error, format string, args ...any) bool
- func NoError(tb TB, actual error) bool
- func NoErrorf(tb TB, actual error, format string, args ...any) bool
- func NotBeDeepEqual(tb TB, actual, expected any) bool
- func NotBeEqual[T cmp.Ordered](tb TB, actual, expected T) bool
- func NotBeNil(tb TB, actual any) bool
- func NotBeNilf(tb TB, actual any, format string, args ...any) bool
- func NotBeZero[T comparable](tb TB, actual T) bool
- func NotBeZerof[T comparable](tb TB, actual T, format string, args ...any) bool
- func NotPanic(tb TB, f func()) (ok bool)
- func PanicSatisfy[A any](tb TB, predicate func(_ A) bool, f func()) (ok bool)
- func Satisfy[A any](tb TB, actual A, predicate func(_ A) bool) bool
- func SatisfyWith[A, E any](tb TB, actual A, expected E, predicate func(_ A, _ E) bool) bool
- type TB
Examples ¶
- BeDeepEqual
- BeNil
- BeNil (TypedNil)
- BeNilf
- BeZero
- BeZerof
- CompareEqual (MethodExpression)
- Error
- ErrorIs
- Errorf
- NoError
- NoErrorf
- NotBeDeepEqual
- NotBeNil
- NotBeNilf
- NotBeZero
- NotBeZero (Pointer)
- NotBeZerof
- NotPanic
- PanicSatisfy (Assertion)
- PanicSatisfy (MethodExpression)
- Satisfy (Inline)
- Satisfy (MethodExpression)
- Satisfy (MethodValue)
- SatisfyWith (Function)
- SatisfyWith (Inline)
- SatisfyWith (MethodExpression)
Constants ¶
This section is empty.
Variables ¶
var Diff func(tb TB, actualName string, actual any, expectedName string, expected any) string = defaultDiff
Diff returns a diff between actual and expected.
var Dump func(tb TB, v any) string = defaultDump
Dump returns the textual representation of v.
Functions ¶
func BeDeepEqual ¶
BeDeepEqual checks that actual and expected are equal according to reflect.DeepEqual.
Example ¶
BeDeepEqual(t, []int{13}, []int64{13})
Output: actual is not deep equal to expected: actual: []int{ 13, } ([]int) expected: []int64{ 13, } ([]int64) diff expected actual --- expected +++ actual @@ -1,3 +1,3 @@ -[]int64{ +[]int{ 13, -} ([]int64) +} ([]int) FAIL
func BeGreater ¶
BeGreater checks that actual is greater than expected according to cmp.Greater.
func BeNil ¶
BeNil checks that actual is untyped nil.
It is recommended to use NoError for errors and BeZero where possible otherwise.
Example ¶
BeNil(t, new(uint32(13)))
Output: actual is not untyped nil, but: actual: &13 (*uint32) FAIL
Example (TypedNil) ¶
BeNil(t, (*uint32)(nil))
Output: actual is not untyped nil, but: actual: nil (*uint32) FAIL
func BeNilf ¶
BeNilf checks that actual is untyped nil.
It is recommended to use NoError for errors and BeZero where possible otherwise.
Example ¶
BeNilf(t, new(uint32(13)), "extra message: %s, %d", "foo", 42)
Output: actual is not untyped nil, but: actual: &13 (*uint32) extra message: foo, 42 FAIL
func BeZero ¶
func BeZero[T comparable](tb TB, actual T) bool
BeZero checks that actual is the zero value of its type.
Example ¶
BeZero(t, 13)
Output: actual is not zero, but: actual: 13 (int) FAIL
func BeZerof ¶
func BeZerof[T comparable](tb TB, actual T, format string, args ...any) bool
BeZerof checks that actual is the zero value of its type.
Example ¶
BeZerof(t, 13, "extra message: %s, %d", "foo", 42)
Output: actual is not zero, but: actual: 13 (int) extra message: foo, 42 FAIL
func CompareEqual ¶
CompareEqual checks that compare(actual, expected) returns 0 (cmp.OrderEqual).
Example (MethodExpression) ¶
actual := time.Date(2026, time.April, 9, 17, 32, 42, 123, time.UTC)
expected := time.Date(2026, time.April, 9, 17, 32, 42, 123, time.FixedZone("My", 4*int(time.Hour.Seconds())))
CompareEqual(t, actual, expected, time.Time.Compare)
Output: actual is not equal to expected, but greater: actual: time.Date(2026, 4, 9, 17, 32, 42, 123, time.UTC) (time.Time) expected: time.Date(2026, 4, 9, 13, 32, 42, 123, time.UTC) (time.Time) diff expected actual --- expected +++ actual @@ -1,1 +1,1 @@ -time.Date(2026, 4, 9, 13, 32, 42, 123, time.UTC) (time.Time) +time.Date(2026, 4, 9, 17, 32, 42, 123, time.UTC) (time.Time) FAIL
func CompareGreater ¶
CompareGreater checks that compare(actual, expected) returns 1 (cmp.OrderGreater).
func CompareLess ¶
CompareLess checks that compare(actual, expected) returns -1 (cmp.OrderLess).
func CompareWith ¶
func CompareWith[A, E any](tb TB, actual A, expected E, order cmp.Order, compare func(_ A, _ E) int) bool
CompareWith checks that compare(actual, expected) returns order.
func Error ¶
Error checks that actual is a non-nil error.
Example ¶
Error(t, nil)
Output: actual is nil error FAIL
func ErrorIs ¶
ErrorIs checks that actual matches expected using errors.Is.
Example ¶
ErrorIs(t, errors.New("actual"), errors.New("expected"))
Output: actual does not match expected: actual: &errors.errorString{ s: "actual", } (*errors.errorString) expected: &errors.errorString{ s: "expected", } (*errors.errorString) FAIL
func Errorf ¶
Errorf checks that actual is a non-nil error.
Example ¶
Errorf(t, nil, "extra message: %s, %d", "foo", 42)
Output: actual is nil error extra message: foo, 42 FAIL
func NoError ¶
NoError checks that actual is a nil error.
Example ¶
NoError(t, errors.New("boom"))
Output: actual is not nil error, but "boom": actual: &errors.errorString{ s: "boom", } (*errors.errorString) FAIL
func NoErrorf ¶
NoErrorf checks that actual is a nil error.
Example ¶
NoErrorf(t, errors.New("boom"), "extra message: %s, %d", "foo", 42)
Output: actual is not nil error, but "boom": actual: &errors.errorString{ s: "boom", } (*errors.errorString) extra message: foo, 42 FAIL
func NotBeDeepEqual ¶
NotBeDeepEqual checks that actual and expected are not equal according to reflect.DeepEqual.
Example ¶
ExampleNotBeDeepEqual demonstrates NotBeDeepEqual.
NotBeDeepEqual(t, []int{13}, []int{13})
Output: actual is deep equal to expected: actual: []int{ 13, } ([]int) expected: []int{ 13, } ([]int) FAIL
func NotBeEqual ¶
NotBeEqual checks that actual and expected are not equal according to cmp.Equal.
func NotBeNil ¶
NotBeNil checks that actual is not (untyped) nil.
It is recommended to use Error for errors and NotBeZero where possible otherwise.
Example ¶
NotBeNil(t, nil)
Output: actual is untyped nil FAIL
func NotBeNilf ¶
NotBeNilf checks that actual is not (untyped) nil.
It is recommended to use Error for errors and NotBeZero where possible otherwise.
Example ¶
NotBeNilf(t, nil, "extra message: %s, %d", "foo", 42)
Output: actual is untyped nil extra message: foo, 42 FAIL
func NotBeZero ¶
func NotBeZero[T comparable](tb TB, actual T) bool
NotBeZero checks that actual is not the zero value of its type.
Example ¶
NotBeZero(t, 0)
Output: actual is zero FAIL
Example (Pointer) ¶
NotBeZero(t, (*int)(nil))
Output: actual is zero FAIL
func NotBeZerof ¶
func NotBeZerof[T comparable](tb TB, actual T, format string, args ...any) bool
NotBeZerof checks that actual is not the zero value of its type.
Example ¶
NotBeZerof(t, 0, "extra message: %s, %d", "foo", 42)
Output: actual is zero extra message: foo, 42 FAIL
func NotPanic ¶
NotPanic checks that f does not panic.
Example ¶
NotPanic(t, func() { panic("boom") })
Output: function panicked: actual: "boom" (string) FAIL
func PanicSatisfy ¶
PanicSatisfy checks that f panics with the value of type A. If predicate is not nil, it also checks that the panic value satisfies it.
Example (Assertion) ¶
PanicSatisfy(t, func(actual time.Time) bool {
expected := time.Date(2026, time.April, 9, 17, 32, 42, 123, time.FixedZone("My", 4*int(time.Hour.Seconds())))
CompareEqual(t, actual, expected, time.Time.Compare)
return true
}, func() { panic(time.Date(2026, time.April, 9, 17, 32, 42, 123, time.UTC)) })
Output: actual is not equal to expected, but greater: actual: time.Date(2026, 4, 9, 17, 32, 42, 123, time.UTC) (time.Time) expected: time.Date(2026, 4, 9, 13, 32, 42, 123, time.UTC) (time.Time) diff expected actual --- expected +++ actual @@ -1,1 +1,1 @@ -time.Date(2026, 4, 9, 13, 32, 42, 123, time.UTC) (time.Time) +time.Date(2026, 4, 9, 17, 32, 42, 123, time.UTC) (time.Time) FAIL
Example (MethodExpression) ¶
PanicSatisfy(t, time.Time.IsZero, func() { panic(time.Date(2026, time.April, 9, 17, 32, 42, 123, time.UTC)) })
Output: actual is not satisfied by predicate: actual: time.Date(2026, 4, 9, 17, 32, 42, 123, time.UTC) (time.Time) FAIL
func Satisfy ¶
Satisfy checks that predicate returns true for actual.
Example (Inline) ¶
Satisfy(t, 13, func(v int) bool { return v > 42 })
Output: actual is not satisfied by predicate: actual: 13 (int) FAIL
Example (MethodExpression) ¶
actual := time.Date(2026, time.April, 9, 17, 32, 42, 123, time.UTC) Satisfy(t, actual, time.Time.IsZero)
Output: actual is not satisfied by predicate: actual: time.Date(2026, 4, 9, 17, 32, 42, 123, time.UTC) (time.Time) FAIL
Example (MethodValue) ¶
actual := time.Date(2026, time.April, 9, 17, 32, 42, 123, time.UTC) Satisfy(t, actual, time.Now().Before)
Output: actual is not satisfied by predicate: actual: time.Date(2026, 4, 9, 17, 32, 42, 123, time.UTC) (time.Time) FAIL
func SatisfyWith ¶
SatisfyWith checks that predicate returns true for actual and expected.
Example (Function) ¶
SatisfyWith(t, 13, 42, cmp.Greater)
Output: actual and expected are not satisfied by predicate: actual: 13 (int) expected: 42 (int) diff expected actual --- expected +++ actual @@ -1,1 +1,1 @@ -42 (int) +13 (int) FAIL
Example (Inline) ¶
SatisfyWith(t, 13, 42, func(x, y int) bool { return x > y })
Output: actual and expected are not satisfied by predicate: actual: 13 (int) expected: 42 (int) diff expected actual --- expected +++ actual @@ -1,1 +1,1 @@ -42 (int) +13 (int) FAIL
Example (MethodExpression) ¶
actual := time.Date(2026, time.April, 9, 17, 32, 42, 123, time.UTC)
expected := time.Date(2026, time.April, 9, 17, 32, 42, 123, time.FixedZone("My", 4*int(time.Hour.Seconds())))
SatisfyWith(t, actual, expected, time.Time.Before)
Output: actual and expected are not satisfied by predicate: actual: time.Date(2026, 4, 9, 17, 32, 42, 123, time.UTC) (time.Time) expected: time.Date(2026, 4, 9, 13, 32, 42, 123, time.UTC) (time.Time) diff expected actual --- expected +++ actual @@ -1,1 +1,1 @@ -time.Date(2026, 4, 9, 13, 32, 42, 123, time.UTC) (time.Time) +time.Date(2026, 4, 9, 17, 32, 42, 123, time.UTC) (time.Time) FAIL
Types ¶
type TB ¶
type TB interface {
Helper()
Log(args ...any)
Fail()
FailNow()
}
TB is a subset of testing.TB that is used by this package.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package cmp provides types and functions related to comparing ordered values.
|
Package cmp provides types and functions related to comparing ordered values. |
|
Package internal contains unstable code.
|
Package internal contains unstable code. |
|
diff
Package diff implements a diff algorithm.
|
Package diff implements a diff algorithm. |
|
mustagen
command
Package main generates the musta wrappers and mirrored tests.
|
Package main generates the musta wrappers and mirrored tests. |
|
Package musta provides assertions that fail the test immediately.
|
Package musta provides assertions that fail the test immediately. |