assert

README

Assert

Simple and lightweight testing assertion library for Go.

Installation

go get github.com/gravitton/assert

Usage

package main

import (
	"github.com/gravitton/assert"
	"testing"
)

func TestSomething(t *testing.T) {
	// assert equality
	assert.Equal(t, 123, 123)
	// assert inequality
	assert.NotEqual(t, 123, 456)
	// assert object contains element
	assert.Contains(t, []int{1, 2, 3}, 2)
}

Credits

• Tomáš Novotný
• All Contributors

License

The MIT License (MIT). Please see License File for more information.

Documentation

Overview

Package assert provides a simple and lightweight testing assertion library for Go.

This package offers a collection of assertion functions that can be used with any testing framework that implements the Testing interface (such as Go's standard testing.T). The assertions are designed to be intuitive and provide clear error messages when tests fail.

Basic Usage

The assert package works with any type that implements the Testing interface:

func TestExample(t *testing.T) {
	// Boolean assertions
	assert.True(t, condition)
	assert.False(t, !condition)

	// Equality assertions
	assert.Equal(t, actual, expected)
	assert.NotEqual(t, actual, unexpected)

	// Identity assertions (pointer comparison)
	assert.Same(t, &actual, &expected)
	assert.NotSame(t, &actual, &unexpected)
}

Assertion Functions

• True/False: Assert boolean values • Equal/NotEqual: Assert value equality using reflect.DeepEqual • Same/NotSame: Assert pointer identity (same memory address) • Fail/Failf: Manually fail tests with custom messages

Error Messages

All assertion functions provide detailed error messages when assertions fail, including actual and expected values formatted with Go's %#v verb for maximum clarity.

Helper Support

All assertion functions automatically call t.helper() if the testing type implements the helper interface, ensuring that test failures point to the correct line in your test code rather than inside the assertion library.

Return Values

All assertion functions return a boolean indicating success (true) or failure (false), allowing for conditional test logic if needed.

Index

• func Contains[S Iterable[E], E Comparable](t Testing, object S, element E) bool
• func Equal[T Comparable](t Testing, actual, expected T) bool
• func EqualDelta[T Numeric](t Testing, actual, expected, delta T) bool
• func EqualJSON(t Testing, actual, expected string) bool
• func Error(t Testing, err error) bool
• func ErrorIs(t Testing, err error, target error) bool
• func Fail(t Testing, message string) bool
• func Failf(t Testing, format string, args ...any) bool
• func False(t Testing, condition bool) bool
• func Length[S Iterable[any]](t Testing, object S, expected int) bool
• func NoError(t Testing, err error) bool
• func NotContains[S Iterable[E], E Comparable](t Testing, object S, element E) bool
• func NotEqual[T Comparable](t Testing, actual, expected T) bool
• func NotErrorIs(t Testing, err error, target error) bool
• func NotSame[T Reference](t Testing, actual, expected T) bool
• func Same[T Reference](t Testing, actual, expected T) bool
• func True(t Testing, condition bool) bool
• type Comparable
• type Iterable
• type Numeric
• type Reference
• type Testing

Functions

func Contains

func Contains[S Iterable[E], E Comparable](t Testing, object S, element E) bool

Contains asserts that object contains given element

assert.Contains(t, object, element)

Works with strings, arrays, slices, maps values and channels

func Equal

func Equal[T Comparable](t Testing, actual, expected T) bool

Equal asserts that two objects are equal.

assert.Equal(t, actual, expected)

Pointer variable equality is determined based on the equality of the referenced values (as opposed to the memory addresses).

func EqualDelta

func EqualDelta[T Numeric](t Testing, actual, expected, delta T) bool

EqualDelta asserts that two numeric values difference is less then delta.

assert.EqualDelta(t, actual, expected, delta)

Method panics if delta value is not positive.

func EqualJSON

func EqualJSON(t Testing, actual, expected string) bool

EqualJSON asserts that JSON strings are equal

assert.EqualJSON(t, actual, expected)

func Error

func Error(t Testing, err error) bool

Error asserts that error is NOT nil

assert.Error(t, err)

func ErrorIs

func ErrorIs(t Testing, err error, target error) bool

ErrorIs asserts that error is unwrappable to given target

assert.ErrorIs(t, err)

func Fail

func Fail(t Testing, message string) bool

Fail reports a failure message through

func Failf

func Failf(t Testing, format string, args ...any) bool

Failf reports a failure formatted message through

func False

func False(t Testing, condition bool) bool

False asserts that the specified value is false.

assert.False(t, condition)

func Length

func Length[S Iterable[any]](t Testing, object S, expected int) bool

Length asserts that object have given length.

assert.Length(t, object, expected)

func NoError

func NoError(t Testing, err error) bool

NoError asserts that error is nil

assert.NoError(t, err)

func NotContains

func NotContains[S Iterable[E], E Comparable](t Testing, object S, element E) bool

NotContains asserts that object do NOT contains given element

assert.NotContains(t, object, element)

Works with strings, arrays, slices, maps values and channels

func NotEqual

func NotEqual[T Comparable](t Testing, actual, expected T) bool

NotEqual asserts that the specified values are NOT equal.

assert.NotEqual(t, actual, expected)

Pointer variable equality is determined based on the equality of the referenced values (as opposed to the memory addresses).

func NotErrorIs

func NotErrorIs(t Testing, err error, target error) bool

NotErrorIs asserts that error is NOT unwrappable to given target

assert.NotErrorIs(t, err)

func NotSame

func NotSame[T Reference](t Testing, actual, expected T) bool

NotSame asserts that two pointers do NOT reference the same object.

assert.NotSame(t, actual, expected)

Both arguments must be pointer variables. Pointer variable equality is determined based on the equality of both type and value.

func Same

func Same[T Reference](t Testing, actual, expected T) bool

Same asserts that two pointers reference the same object.

assert.Same(t, actual, expected)

Both arguments must be pointer variables. Pointer variable equality is determined based on the equality of both type and value.

func True

func True(t Testing, condition bool) bool

True asserts that the specified value is true.

assert.True(t, condition)

Types

type Comparable

type Comparable interface {
	any
}

type Iterable

type Iterable[T Comparable] interface {
	any
}

type Numeric

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

type Reference

type Reference interface {
	any
}

type Testing

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

Testing is an interface wrapper around *testing.T