testassert

package module
v0.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 23, 2026 License: MIT Imports: 6 Imported by: 0

README

go-testassert

CI Go Reference License

Fluent, type-safe test assertions for Go. Built with generics, zero dependencies

Installation

go get github.com/philiprehberger/go-testassert

Usage

import "github.com/philiprehberger/go-testassert"
Generic assertions
testassert.That(t, result).Equals(expected)
testassert.That(t, result).NotEquals(other)
testassert.That[*MyStruct](t, nil).IsNil()
testassert.That(t, ptr).IsNotNil()
Ordered comparisons
testassert.ThatOrdered(t, count).IsGreaterThan(0)
testassert.ThatOrdered(t, score).IsLessThan(100)
testassert.ThatOrdered(t, age).IsGreaterOrEqual(18)
testassert.ThatOrdered(t, temp).IsLessOrEqual(37.5)
Tolerance
testassert.ThatNumeric(t, 3.14).Within(3.0, 0.2)   // passes: 2.8 <= 3.14 <= 3.2
testassert.ThatNumeric(t, elapsed).Within(100, 10)  // passes if 90 <= elapsed <= 110
String assertions
testassert.ThatString(t, msg).Contains("hello")
testassert.ThatString(t, url).HasPrefix("https://")
testassert.ThatString(t, path).HasSuffix(".go")
testassert.ThatString(t, name).HasLen(5)
testassert.ThatString(t, "").IsEmpty()
testassert.ThatString(t, id).Matches(`^[a-f0-9]{8}$`)
Slice assertions
testassert.ThatSlice(t, items).HasLen(3)
testassert.ThatSlice(t, items).Contains("needle")
testassert.ThatSlice(t, items).IsNotEmpty()
testassert.ThatSlice(t, []int{}).IsEmpty()
Map assertions
testassert.ThatMap(t, m).HasKey("name")
testassert.ThatMap(t, m).HasLen(3)
testassert.ThatMap(t, m).IsNotEmpty()
testassert.ThatMap(t, map[string]int{}).IsEmpty()
Panic assertions
testassert.Panics(t, func() { panic("boom") })
testassert.NotPanics(t, func() { safeOperation() })
Error assertions
testassert.ThatError(t, err).IsNil()
testassert.ThatError(t, err).IsNotNil()
testassert.ThatError(t, err).Is(ErrNotFound)
testassert.ThatError(t, err).Contains("timeout")

var pathErr *PathError
testassert.ThatError(t, err).As(&pathErr)
JSON assertions
testassert.ThatJSON(t, body).Equals(`{"name":"alice","age":30}`)
testassert.ThatJSON(t, body).HasKey("name")
testassert.ThatJSON(t, body).Contains("age", 30)
Custom messages
testassert.That(t, result).WithMessage("user lookup").Equals(expected)
Chaining

All assertions return the receiver, so you can chain calls:

testassert.ThatString(t, msg).
    Contains("hello").
    HasPrefix("hello").
    HasLen(11)

testassert.ThatOrdered(t, n).
    IsGreaterThan(0).
    IsLessThan(100)

API

Constructors
Function Description
That[T](t, got) Generic assertion for any type
ThatOrdered[T](t, got) Assertion for ordered types (int, float, string)
ThatNumeric[T](t, got) Assertion for numeric types with arithmetic checks
ThatString(t, got) String-specific assertions
ThatSlice[T](t, got) Slice-specific assertions
ThatMap[K, V](t, got) Map-specific assertions
ThatError(t, got) Error-specific assertions
ThatJSON(t, got) JSON string assertions
Panics(t, fn) Assert function panics
NotPanics(t, fn) Assert function does not panic
Assertion Methods
Type Methods
Assertion[T] Equals, NotEquals, IsNil, IsNotNil, WithMessage
OrderedAssertion[T] Equals, NotEquals, IsGreaterThan, IsLessThan, IsGreaterOrEqual, IsLessOrEqual
NumericAssertion[T] Within
StringAssertion Equals, Contains, HasPrefix, HasSuffix, IsEmpty, HasLen, Matches
SliceAssertion[T] HasLen, IsEmpty, IsNotEmpty, Contains
MapAssertion[K, V] HasKey, HasLen, IsEmpty, IsNotEmpty
ErrorAssertion IsNil, IsNotNil, Is, Contains, As
JSONAssertion Equals, Contains, HasKey

Development

go test ./...
go vet ./...

License

MIT

Documentation

Overview

Package testassert provides fluent, type-safe test assertions for Go.

It offers a chainable API built with generics for asserting values in tests. Each assertion type is constructed with a That* function and exposes domain-specific methods that call t.Errorf on failure with readable messages.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func NotPanics added in v0.2.0 

func NotPanics(t testing.TB, fn func())

NotPanics asserts that fn does not panic when called.

func Panics added in v0.2.0 

func Panics(t testing.TB, fn func())

Panics asserts that fn panics when called.

Types

type Assertion 

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

Assertion provides fluent assertions for any type using reflect.DeepEqual.

func That 

func That[T any](t testing.TB, got T) *Assertion[T]

That creates a new Assertion for the given value.

func (*Assertion[T]) Equals 

func (a *Assertion[T]) Equals(want T) *Assertion[T]

Equals asserts that got is deeply equal to want.

func (*Assertion[T]) IsNil 

func (a *Assertion[T]) IsNil() *Assertion[T]

IsNil asserts that the value is nil. It handles both typed and untyped nils using reflection.

func (*Assertion[T]) IsNotNil 

func (a *Assertion[T]) IsNotNil() *Assertion[T]

IsNotNil asserts that the value is not nil.

func (*Assertion[T]) NotEquals 

func (a *Assertion[T]) NotEquals(want T) *Assertion[T]

NotEquals asserts that got is not deeply equal to want.

func (*Assertion[T]) WithMessage added in v0.2.0 

func (a *Assertion[T]) WithMessage(msg string) *Assertion[T]

WithMessage sets a custom failure message prefix for this assertion chain.

type ErrorAssertion 

type ErrorAssertion struct {
	// contains filtered or unexported fields
}

ErrorAssertion provides fluent assertions for error values.

func ThatError 

func ThatError(t testing.TB, got error) *ErrorAssertion

ThatError creates a new ErrorAssertion for an error value.

func (*ErrorAssertion) As 

func (a *ErrorAssertion) As(target any) *ErrorAssertion

As asserts that errors.As(got, target) returns true. The target must be a pointer to the desired error type.

func (*ErrorAssertion) Contains 

func (a *ErrorAssertion) Contains(msg string) *ErrorAssertion

Contains asserts that the error message contains msg.

func (*ErrorAssertion) Is 

func (a *ErrorAssertion) Is(target error) *ErrorAssertion

Is asserts that errors.Is(got, target) returns true.

func (*ErrorAssertion) IsNil 

func (a *ErrorAssertion) IsNil() *ErrorAssertion

IsNil asserts that the error is nil.

func (*ErrorAssertion) IsNotNil 

func (a *ErrorAssertion) IsNotNil() *ErrorAssertion

IsNotNil asserts that the error is not nil.

type JSONAssertion 

type JSONAssertion struct {
	// contains filtered or unexported fields
}

JSONAssertion provides fluent assertions for JSON strings.

func ThatJSON 

func ThatJSON(t testing.TB, got string) *JSONAssertion

ThatJSON creates a new JSONAssertion for a JSON string.

func (*JSONAssertion) Contains 

func (a *JSONAssertion) Contains(key string, value any) *JSONAssertion

Contains asserts that the top-level JSON object contains the given key with the given value. The value is compared after JSON unmarshalling for type consistency.

func (*JSONAssertion) Equals 

func (a *JSONAssertion) Equals(want string) *JSONAssertion

Equals asserts that the JSON is semantically equal to want, ignoring formatting. Both strings are unmarshalled and compared with reflect.DeepEqual.

func (*JSONAssertion) HasKey 

func (a *JSONAssertion) HasKey(key string) *JSONAssertion

HasKey asserts that the top-level JSON object contains the given key.

type MapAssertion added in v0.2.0 

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

MapAssertion provides fluent assertions for map values.

func ThatMap added in v0.2.0 

func ThatMap[K comparable, V any](t testing.TB, got map[K]V) *MapAssertion[K, V]

ThatMap creates a new MapAssertion for a map value.

func (*MapAssertion[K, V]) HasKey added in v0.2.0 

func (a *MapAssertion[K, V]) HasKey(key K) *MapAssertion[K, V]

HasKey asserts that the map contains the given key.

func (*MapAssertion[K, V]) HasLen added in v0.2.0 

func (a *MapAssertion[K, V]) HasLen(n int) *MapAssertion[K, V]

HasLen asserts that the map has length n.

func (*MapAssertion[K, V]) IsEmpty added in v0.2.0 

func (a *MapAssertion[K, V]) IsEmpty() *MapAssertion[K, V]

IsEmpty asserts that the map is empty.

func (*MapAssertion[K, V]) IsNotEmpty added in v0.2.0 

func (a *MapAssertion[K, V]) IsNotEmpty() *MapAssertion[K, V]

IsNotEmpty asserts that the map is not empty.

type Numeric added in v0.2.0 

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

Numeric is a constraint for numeric types that support arithmetic operations.

type NumericAssertion added in v0.2.0 

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

NumericAssertion provides fluent assertions for numeric types that support arithmetic operations like tolerance checks.

func ThatNumeric added in v0.2.0 

func ThatNumeric[T Numeric](t testing.TB, got T) *NumericAssertion[T]

ThatNumeric creates a new NumericAssertion for a numeric value. It provides all ordered comparison methods plus arithmetic-based assertions.

func (*NumericAssertion[T]) Within added in v0.2.0 

func (a *NumericAssertion[T]) Within(expected T, tolerance T) *NumericAssertion[T]

Within asserts that got is within tolerance of expected. The check passes when expected - tolerance <= got <= expected + tolerance.

type OrderedAssertion 

type OrderedAssertion[T cmp.Ordered] struct {
	// contains filtered or unexported fields
}

OrderedAssertion provides fluent assertions for ordered types that support comparison operators.

func ThatOrdered 

func ThatOrdered[T cmp.Ordered](t testing.TB, got T) *OrderedAssertion[T]

ThatOrdered creates a new OrderedAssertion for a value with an ordered type.

func (*OrderedAssertion[T]) Equals 

func (a *OrderedAssertion[T]) Equals(want T) *OrderedAssertion[T]

Equals asserts that got equals want.

func (*OrderedAssertion[T]) IsGreaterOrEqual 

func (a *OrderedAssertion[T]) IsGreaterOrEqual(v T) *OrderedAssertion[T]

IsGreaterOrEqual asserts that got >= v.

func (*OrderedAssertion[T]) IsGreaterThan 

func (a *OrderedAssertion[T]) IsGreaterThan(v T) *OrderedAssertion[T]

IsGreaterThan asserts that got > v.

func (*OrderedAssertion[T]) IsLessOrEqual 

func (a *OrderedAssertion[T]) IsLessOrEqual(v T) *OrderedAssertion[T]

IsLessOrEqual asserts that got <= v.

func (*OrderedAssertion[T]) IsLessThan 

func (a *OrderedAssertion[T]) IsLessThan(v T) *OrderedAssertion[T]

IsLessThan asserts that got < v.

func (*OrderedAssertion[T]) NotEquals 

func (a *OrderedAssertion[T]) NotEquals(want T) *OrderedAssertion[T]

NotEquals asserts that got does not equal want.

type SliceAssertion 

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

SliceAssertion provides fluent assertions for slice values.

func ThatSlice 

func ThatSlice[T any](t testing.TB, got []T) *SliceAssertion[T]

ThatSlice creates a new SliceAssertion for a slice value.

func (*SliceAssertion[T]) Contains 

func (a *SliceAssertion[T]) Contains(elem T) *SliceAssertion[T]

Contains asserts that the slice contains elem using reflect.DeepEqual.

func (*SliceAssertion[T]) HasLen 

func (a *SliceAssertion[T]) HasLen(n int) *SliceAssertion[T]

HasLen asserts that the slice has length n.

func (*SliceAssertion[T]) IsEmpty 

func (a *SliceAssertion[T]) IsEmpty() *SliceAssertion[T]

IsEmpty asserts that the slice is empty.

func (*SliceAssertion[T]) IsNotEmpty 

func (a *SliceAssertion[T]) IsNotEmpty() *SliceAssertion[T]

IsNotEmpty asserts that the slice is not empty.

type StringAssertion 

type StringAssertion struct {
	// contains filtered or unexported fields
}

StringAssertion provides fluent assertions for string values.

func ThatString 

func ThatString(t testing.TB, got string) *StringAssertion

ThatString creates a new StringAssertion for a string value.

func (*StringAssertion) Contains 

func (a *StringAssertion) Contains(substr string) *StringAssertion

Contains asserts that the string contains substr.

func (*StringAssertion) Equals 

func (a *StringAssertion) Equals(want string) *StringAssertion

Equals asserts that the string equals want.

func (*StringAssertion) HasLen 

func (a *StringAssertion) HasLen(n int) *StringAssertion

HasLen asserts that the string has length n.

func (*StringAssertion) HasPrefix 

func (a *StringAssertion) HasPrefix(prefix string) *StringAssertion

HasPrefix asserts that the string starts with prefix.

func (*StringAssertion) HasSuffix 

func (a *StringAssertion) HasSuffix(suffix string) *StringAssertion

HasSuffix asserts that the string ends with suffix.

func (*StringAssertion) IsEmpty 

func (a *StringAssertion) IsEmpty() *StringAssertion

IsEmpty asserts that the string is empty.

func (*StringAssertion) Matches 

func (a *StringAssertion) Matches(pattern string) *StringAssertion

Matches asserts that the string matches the regular expression pattern.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.