gunit

README

gunit

gounit is test assertions library for Go. It was developed to address the shortcoming of many assertion frameworks that employ assertion of types at runtime rather than compile time.

Install

go get github.com/gogunit/gunit

Choosing An API

Use gunit when you want direct typed assertions on testing.T.

Use hammy when you want matcher-style assertions, especially when composing checks with AllOf, AnyOf, HavingField, ContainsInOrder, and related helpers.

Within hammy, prefer the typed wrappers for most assertions:

assert.Is(a.Number(actual).Matches(a.AllOf(
	a.GreaterThan(0),
	a.LessThan(10),
)))

Use a.Match(...) when no dedicated wrapper fits or when the value is intentionally held as any.

Examples

// direct assertion style
func Test_nine_plus_two_is_greater_than_ten(t *testing.T) {
	actual := 9 + 2
	expected := 10
	gunit.Number(t, actual).GreaterThan(expected)
}

// wrap testing.T struct
func Test_nine_plus_two_is_greater_than_ten(t *testing.T) {
	assert := gunit.New(t)
	actual := 9 + 2
	expected := 10
	assert.Int(actual).GreaterThan(expected)
}

Hammy Examples

package adder

import (
	"testing"

	a "github.com/gogunit/gunit/hammy"
)

func Test_add_returns_expected_sum(t *testing.T) {
	assert := a.New(t)
	actual := Add(2, 3)
	assert.Is(a.Number(actual).EqualTo(5))
}

func Test_add_returns_small_positive_sum(t *testing.T) {
	assert := a.New(t)
	actual := Add(2, 3)

	assert.Is(a.Number(actual).Matches(a.AllOf(
		a.GreaterThan(0),
		a.LessThan(10),
	)))
}

package service

import (
	"errors"
	"fmt"
	"testing"

	a "github.com/gogunit/gunit/hammy"
)

var errTimeout = errors.New("timeout")

func Test_run_wraps_timeout_error(t *testing.T) {
	assert := a.New(t)
	err := fmt.Errorf("request failed: %w", errTimeout)
	assert.Is(a.ErrorIs(err, errTimeout))
}

func Test_people_are_sorted_by_name(t *testing.T) {
	assert := a.New(t)
	people := []Person{{Name: "Ada"}, {Name: "Linus"}}

	assert.Is(a.Slice(people).ContainsInOrder(
		a.HavingField("Name", func(person Person) string { return person.Name }, a.EqualTo("Ada")),
		a.HavingField("Name", func(person Person) string { return person.Name }, a.EqualTo("Linus")),
	))
}

func Test_dynamic_payload_has_expected_type(t *testing.T) {
	assert := a.New(t)
	var payload any = Response{Status: "ok"}

	assert.Is(a.Match(payload, a.TypeOf[Response]()))
}

For more Hammy examples and the matcher reference, see hammy/README.md.

Documentation

Index

• func False(t T, actual bool)
• func True(t T, actual bool)
• type Mappy
  • func Map[K comparable, V any](t T, actual map[K]V) *Mappy[K, V]
  • func (m *Mappy[K, V]) EqualTo(expected map[K]V)
  • func (m *Mappy[K, V]) IsEmpty()
  • func (m *Mappy[K, V]) WithKeys(keys ...K)
  • func (m *Mappy[K, V]) WithValues(values ...V)
  • func (m *Mappy[K, V]) WithoutKeys(keys ...K)
• type Num
  • func Number[N Numeric](t T, actual N) *Num[N]
  • func (n *Num[N]) EqualTo(expected N)
  • func (n *Num[N]) GreaterOrEqual(expected N)
  • func (n *Num[N]) GreaterThan(expected N)
  • func (n *Num[N]) IsZero()
  • func (n *Num[N]) LessOrEqual(expected N)
  • func (n *Num[N]) LessThan(expected N)
  • func (n *Num[N]) NotEqualTo(expected N)
  • func (n *Num[N]) Within(expected N, error float64)
• type Numeric
• type St
  • func Struct[S any](t T, actual S) *St[S]
  • func (s St[S]) EqualTo(expected S)
• type Str
  • func String[S Stringy](t T, actual S) *Str[S]
  • func (s *Str[S]) Contains(needle S)
  • func (s *Str[S]) EqualTo(expected S)
  • func (s *Str[S]) HasPrefix(prefix S)
  • func (s *Str[S]) HasSuffix(suffix S)
  • func (s *Str[S]) IsEmpty()
  • func (s *Str[S]) IsNotEmpty()
• type Stringy
• type T

Functions

func False

func False(t T, actual bool)

func True

func True(t T, actual bool)

Types

type Mappy

type Mappy[K comparable, V any] struct {
	T
	// contains filtered or unexported fields
}

func Map

func Map[K comparable, V any](t T, actual map[K]V) *Mappy[K, V]

func (*Mappy[K, V]) EqualTo

func (m *Mappy[K, V]) EqualTo(expected map[K]V)

func (*Mappy[K, V]) IsEmpty

func (m *Mappy[K, V]) IsEmpty()

func (*Mappy[K, V]) WithKeys

func (m *Mappy[K, V]) WithKeys(keys ...K)

func (*Mappy[K, V]) WithValues

func (m *Mappy[K, V]) WithValues(values ...V)

func (*Mappy[K, V]) WithoutKeys

func (m *Mappy[K, V]) WithoutKeys(keys ...K)

type Num

type Num[N Numeric] struct {
	T
	// contains filtered or unexported fields
}

func Number

func Number[N Numeric](t T, actual N) *Num[N]

func (*Num[N]) EqualTo

func (n *Num[N]) EqualTo(expected N)

func (*Num[N]) GreaterOrEqual

func (n *Num[N]) GreaterOrEqual(expected N)

func (*Num[N]) GreaterThan

func (n *Num[N]) GreaterThan(expected N)

func (*Num[N]) IsZero

func (n *Num[N]) IsZero()

func (*Num[N]) LessOrEqual

func (n *Num[N]) LessOrEqual(expected N)

func (*Num[N]) LessThan

func (n *Num[N]) LessThan(expected N)

func (*Num[N]) NotEqualTo

func (n *Num[N]) NotEqualTo(expected N)

func (*Num[N]) Within

func (n *Num[N]) Within(expected N, error float64)

type Numeric

type Numeric interface {
	~int | ~int8 | ~int16 | ~int32 | ~int64 |
		~uint | ~uint8 | ~uint16 | ~uint32 | ~uint64 |
		~float32 | ~float64
}

type St

type St[S any] struct {
	T
	// contains filtered or unexported fields
}

func Struct

func Struct[S any](t T, actual S) *St[S]

func (St[S]) EqualTo

func (s St[S]) EqualTo(expected S)

type Str

type Str[S Stringy] struct {
	T
	// contains filtered or unexported fields
}

func String

func String[S Stringy](t T, actual S) *Str[S]

func (*Str[S]) Contains

func (s *Str[S]) Contains(needle S)

func (*Str[S]) EqualTo

func (s *Str[S]) EqualTo(expected S)

func (*Str[S]) HasPrefix

func (s *Str[S]) HasPrefix(prefix S)

func (*Str[S]) HasSuffix

func (s *Str[S]) HasSuffix(suffix S)

func (*Str[S]) IsEmpty

func (s *Str[S]) IsEmpty()

func (*Str[S]) IsNotEmpty

func (s *Str[S]) IsNotEmpty()

type Stringy

type Stringy interface {
	~string
}

type T

type T interface {
	Helper()
	Errorf(format string, args ...any)
}