gtest

README

Missing feature of the standard library: test assertions. Similar to the popular package .../testify, but better. Uses generics rather than any. Unobtrusively uses panic and recovery, allowing terse assertions without explicitly threading t through your function calls. Prints nice, readable stack traces.

API doc: https://pkg.go.dev/github.com/mitranim/gg/gtest

Documentation

Overview

Missing feature of the standard library: terse, expressive test assertions.

Index

• func Catch(t testing.TB)
• func Empty[A ~[]B, B any](src A, opt ...any)
• func Eq[A comparable](act, exp A, opt ...any)
• func EqAny[A any](act, exp A, opt ...any)
• func Equal[A any](act, exp A, opt ...any)
• func EqualSet[A ~[]B, B comparable](act, exp A, opt ...any)
• func Error(test func(error) bool, err error, opt ...any)
• func ErrorAny(err error, opt ...any)
• func ErrorIs(exp, err error, opt ...any)
• func ErrorStr(exp string, err error, opt ...any)
• func False(val bool, opt ...any)
• func Has[A ~[]B, B comparable](src A, val B, opt ...any)
• func HasEqual[A ~[]B, B any](src A, val B, opt ...any)
• func HasEvery[A ~[]B, B comparable](src, exp A, opt ...any)
• func HasNone[A ~[]B, B comparable](src, exp A, opt ...any)
• func HasSome[A ~[]B, B comparable](src, exp A, opt ...any)
• func Is[A any](act, exp A, opt ...any)
• func Len[A ~[]B, B any](src A, exp int, opt ...any)
• func Less[A gg.Lesser[A]](one, two A, opt ...any)
• func LessEq[A interface{ ... }](one, two A, opt ...any)
• func LessEqPrim[A gg.LesserPrim](one, two A, opt ...any)
• func LessPrim[A gg.LesserPrim](one, two A, opt ...any)
• func MapNotEmpty[Src ~map[Key]Val, Key comparable, Val any](src Src, opt ...any)
• func MsgEq(act, exp any) string
• func MsgEqDetailed(act, exp any) string
• func MsgEqInner(act, exp any) string
• func MsgEqSimple(act, exp any) string
• func MsgNotEq[A any](act A) string
• func Neg[A gg.Signed](src A, opt ...any)
• func NoError(err error, opt ...any)
• func NoPanic(fun func(), opt ...any)
• func NotEmpty[A ~[]B, B any](src A, opt ...any)
• func NotEq[A comparable](act, nom A, opt ...any)
• func NotEqual[A any](act, nom A, opt ...any)
• func NotHas[A ~[]B, B comparable](src A, val B, opt ...any)
• func NotHasEqual[A ~[]B, B any](src A, val B, opt ...any)
• func NotIs[A any](act, exp A, opt ...any)
• func NotSliceIs[A ~[]B, B any](act, nom A, opt ...any)
• func NotZero[A any](val A, opt ...any)
• func Panic(test func(error) bool, fun func(), opt ...any)
• func PanicAny(fun func(), opt ...any)
• func PanicErrIs(exp error, fun func(), opt ...any)
• func PanicStr(exp string, fun func(), opt ...any)
• func Pos[A gg.Signed](src A, opt ...any)
• func SliceIs[A ~[]B, B any](act, exp A, opt ...any)
• func Str[A fmt.Stringer](src A, exp string, opt ...any)
• func TextHas[A, B gg.Text](src A, exp B, opt ...any)
• func TextLen[A gg.Text](src A, exp int, opt ...any)
• func True(val bool, opt ...any)
• func Uniq[A ~[]B, B comparable](src A, opt ...any)
• func Zero[A any](val A, opt ...any)
• type Err
  • func ErrAt(skip int, msg ...any) Err
  • func ErrLines(msg ...any) Err
  • func (self Err) Error() string
  • func (self Err) String() string
• type ErrMsgTest
  • func (self ErrMsgTest) Is(err error) bool

Functions

func Catch

func Catch(t testing.TB)

Must be deferred. Usage:

func TestSomething(t *testing.T) {
	// Catches panics and uses `t.Fatalf`.
	defer gtest.Catch(t)

	// Test assertion. Panics and gets caught above.
	gtest.Eq(10, 20)
}

func Empty

func Empty[A ~[]B, B any](src A, opt ...any)

Asserts that the given slice is empty, or fails the test, printing the optional additional messages and the stack trace.

func Eq

func Eq[A comparable](act, exp A, opt ...any)

Asserts that the inputs are equal via `==`, or fails the test, printing the optional additional messages and the stack trace.

func EqAny

func EqAny[A any](act, exp A, opt ...any)

Asserts that the inputs are equal via `==`, or fails the test, printing the optional additional messages and the stack trace. Doesn't statically require the inputs to be comparable, but may panic if they aren't.

func Equal

func Equal[A any](act, exp A, opt ...any)

Asserts that the inputs are deeply equal, or fails the test, printing the optional additional messages and the stack trace.

func EqualSet

func EqualSet[A ~[]B, B comparable](act, exp A, opt ...any)

Asserts that the input slices have the same set of elements, or fails the test, printing the optional additional messages and the stack trace.

func Error

func Error(test func(error) bool, err error, opt ...any)

Asserts that the given error is non-nil AND satisfies the given error-testing function. Otherwise fails the test, printing the optional additional messages and the stack trace.

func ErrorAny

func ErrorAny(err error, opt ...any)

Asserts that the given error is non-nil, or fails the test, printing the optional additional messages and the stack trace.

func ErrorIs

func ErrorIs(exp, err error, opt ...any)

Asserts that the given error is non-nil and matches the expected error via `errors.Is`, or fails the test, printing the optional additional messages and the stack trace.

func ErrorStr

func ErrorStr(exp string, err error, opt ...any)

Asserts that the given error is non-nil and its message contains the given substring, or fails the test, printing the optional additional messages and the stack trace.

func False

func False(val bool, opt ...any)

Asserts that the input is `false`, or fails the test, printing the optional additional messages and the stack trace.

func Has

func Has[A ~[]B, B comparable](src A, val B, opt ...any)

Asserts that the given slice contains the given value, or fails the test, printing the optional additional messages and the stack trace.

func HasEqual

func HasEqual[A ~[]B, B any](src A, val B, opt ...any)

Asserts that the given slice contains the given value, or fails the test, printing the optional additional messages and the stack trace. Uses `gg.Equal` to compare values. For values that implement `comparable`, use `Has` which is simpler and faster.

func HasEvery

func HasEvery[A ~[]B, B comparable](src, exp A, opt ...any)

Asserts that the first slice contains all elements from the second slice. In other words, asserts that the first slice is a strict superset of the second. Otherwise fails the test, printing the optional additional messages and the stack trace.

func HasNone

func HasNone[A ~[]B, B comparable](src, exp A, opt ...any)

Asserts that the first slice does not contain any from the second slice. In other words, asserts that the element sets are disjoint. Otherwise fails the test, printing the optional additional messages and the stack trace.

func HasSome

func HasSome[A ~[]B, B comparable](src, exp A, opt ...any)

Asserts that the first slice contains some elements from the second slice. In other words, asserts that the element sets have an intersection. Otherwise fails the test, printing the optional additional messages and the stack trace.

func Is

func Is[A any](act, exp A, opt ...any)

Asserts that the inputs are byte-for-byte identical, via `gg.Is`. Otherwise fails the test, printing the optional additional messages and the stack trace.

func Len

func Len[A ~[]B, B any](src A, exp int, opt ...any)

Asserts that the given slice has exactly the given length, or fails the test, printing the optional additional messages and the stack trace.

func Less

func Less[A gg.Lesser[A]](one, two A, opt ...any)

Asserts `one < two`, or fails the test, printing the optional additional messages and the stack trace. For primitives, see `LessPrim`.

func LessEq

func LessEq[A interface {
	gg.Lesser[A]
	comparable
}](one, two A, opt ...any)

Asserts `one <= two`, or fails the test, printing the optional additional messages and the stack trace. For primitives, see `LessEqPrim`. Also see `Less`.

func LessEqPrim

func LessEqPrim[A gg.LesserPrim](one, two A, opt ...any)

Asserts `one <= two`, or fails the test, printing the optional additional messages and the stack trace. For non-primitives that implement `gg.Lesser`, see `LessEq`. Also see `LessPrim`.

func LessPrim

func LessPrim[A gg.LesserPrim](one, two A, opt ...any)

Asserts `one < two`, or fails the test, printing the optional additional messages and the stack trace. For non-primitives that implement `gg.Lesser`, see `Less`. Also see `LessEqPrim`.

func MapNotEmpty

func MapNotEmpty[Src ~map[Key]Val, Key comparable, Val any](src Src, opt ...any)

Asserts that the given slice is not empty, or fails the test, printing the optional additional messages and the stack trace.

func MsgEq

func MsgEq(act, exp any) string

func MsgEqDetailed

func MsgEqDetailed(act, exp any) string

func MsgEqInner

func MsgEqInner(act, exp any) string

Used internally when generating error messages about failed equality.

func MsgEqSimple

func MsgEqSimple(act, exp any) string

func MsgNotEq

func MsgNotEq[A any](act A) string

func Neg

func Neg[A gg.Signed](src A, opt ...any)

Asserts that the given number is < 0, or fails the test, printing the optional additional messages and the stack trace.

func NoError

func NoError(err error, opt ...any)

Asserts that the given error is nil, or fails the test, printing the error's trace if possible, the optional additional messages, and the stack trace.

func NoPanic

func NoPanic(fun func(), opt ...any)

Asserts that the given function doesn't panic, or fails the test, printing the error's trace if possible, the optional additional messages, and the stack trace.

func NotEmpty

func NotEmpty[A ~[]B, B any](src A, opt ...any)

Asserts that the given slice is not empty, or fails the test, printing the optional additional messages and the stack trace.

func NotEq

func NotEq[A comparable](act, nom A, opt ...any)

Asserts that the inputs are not equal via `!=`, or fails the test, printing the optional additional messages and the stack trace.

func NotEqual

func NotEqual[A any](act, nom A, opt ...any)

Asserts that the inputs are not deeply equal, or fails the test, printing the optional additional messages and the stack trace.

func NotHas

func NotHas[A ~[]B, B comparable](src A, val B, opt ...any)

Asserts that the given slice does not contain the given value, or fails the test, printing the optional additional messages and the stack trace.

func NotHasEqual

func NotHasEqual[A ~[]B, B any](src A, val B, opt ...any)

Asserts that the given slice does not contain the given value, or fails the test, printing the optional additional messages and the stack trace. Uses `gg.Equal` to compare values. For values that implement `comparable`, use `HasNot` which is simpler and faster.

func NotIs

func NotIs[A any](act, exp A, opt ...any)

Asserts that the inputs are NOT byte-for-byte identical, via `gg.Is`. Otherwise fails the test, printing the optional additional messages and the stack trace.

func NotSliceIs

func NotSliceIs[A ~[]B, B any](act, nom A, opt ...any)

Asserts that the given slice headers (not their elements) are distinct. This means at least one of the following fields is different: data pointer, length, capacity. Does NOT compare individual elements, unlike `NotEqual`. Otherwise fails the test, printing the optional additional messages and the stack trace.

func NotZero

func NotZero[A any](val A, opt ...any)

Asserts that the input is zero via `gg.IsZero`, or fails the test, printing the optional additional messages and the stack trace.

func Panic

func Panic(test func(error) bool, fun func(), opt ...any)

Asserts that the given function panics AND that the resulting error satisfies the given error-testing function. Otherwise fails the test, printing the optional additional messages and the stack trace.

func PanicAny

func PanicAny(fun func(), opt ...any)

Asserts that the given function panics, or fails the test, printing the optional additional messages and the stack trace.

func PanicErrIs

func PanicErrIs(exp error, fun func(), opt ...any)

Asserts that the given function panics and the panic result matches the given error via `errors.Is`, or fails the test, printing the optional additional messages and the stack trace.

func PanicStr

func PanicStr(exp string, fun func(), opt ...any)

Asserts that the given function panics with an error whose message contains the given substring, or fails the test, printing the optional additional messages and the stack trace.

func Pos

func Pos[A gg.Signed](src A, opt ...any)

Asserts that the given number is > 0, or fails the test, printing the optional additional messages and the stack trace.

func SliceIs

func SliceIs[A ~[]B, B any](act, exp A, opt ...any)

Asserts that the given slice headers (not their elements) are equal via `gg.SliceIs`. This means they have the same data pointer, length, capacity. Does NOT compare individual elements, unlike `Equal`. Otherwise fails the test, printing the optional additional messages and the stack trace.

func Str

func Str[A fmt.Stringer](src A, exp string, opt ...any)

Asserts that `.String` of the input matches the expected string, or fails the test, printing the optional additional messages and the stack trace.

func TextHas

func TextHas[A, B gg.Text](src A, exp B, opt ...any)

Asserts that the given chunk of text contains the given substring, or fails the test, printing the optional additional messages and the stack trace.

func TextLen

func TextLen[A gg.Text](src A, exp int, opt ...any)

Asserts that the given text has exactly the given length, or fails the test, printing the optional additional messages and the stack trace.

func True

func True(val bool, opt ...any)

Asserts that the input is `true`, or fails the test, printing the optional additional messages and the stack trace.

func Uniq

func Uniq[A ~[]B, B comparable](src A, opt ...any)

Asserts that the given slice contains no duplicates, or fails the test, printing the optional additional messages and the stack trace.

func Zero

func Zero[A any](val A, opt ...any)

Asserts that the input is zero via `gg.IsZero`, or fails the test, printing the optional additional messages and the stack trace.

Types

type Err

type Err struct{ gg.Err }

Used internally by assertion utils. Error wrapper whose default stringing uses "%+v" formatting on the inner error, causing it to be ALWAYS formatted with a stack trace, which is useful when panics are not caught.

func ErrAt

func ErrAt(skip int, msg ...any) Err

Shortcut for generating a test error (of type `Err` provided by this package) with the given message, skipping the given amount of stack frames.

func ErrLines

func ErrLines(msg ...any) Err

Shortcut for generating an error where the given messages are combined as lines.

func (Err) Error

func (self Err) Error() string

Implement `error` by using full formatting on the inner error: multiline with a stack trace.

func (Err) String

func (self Err) String() string

Implement `fmt.Stringer` by using full formatting on the inner error: multiline with a stack trace.

type ErrMsgTest

type ErrMsgTest string

Shortcut for error testing.

func (ErrMsgTest) Is

func (self ErrMsgTest) Is(err error) bool

Tests that the given error has the given message.