assert

package
v1.0.0-rc.5 Latest Latest
Warning

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

 Go to latest Published: Jul 9, 2025 License: MIT Imports: 7 Imported by: 0

Documentation

Overview

Package assert provides the underlying implementation for the Should assertion library. It contains the core assertion logic, which is then exposed through the top-level `should` package. This package handles value comparisons, error formatting, and detailed difference reporting.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func BeEmpty 

func BeEmpty(t testing.TB, actual any, opts ...Option)

BeEmpty reports a test failure if the value is not empty.

This assertion works with strings, slices, arrays, maps, channels, and pointers. For strings, empty means zero length. For slices/arrays/maps/channels, empty means zero length. For pointers, empty means nil. Provides detailed error messages showing the type, length, and content of non-empty values.

Example: 

should.BeEmpty(t, "")

should.BeEmpty(t, []int{}, should.WithMessage("List should be empty"))

should.BeEmpty(t, map[string]int{})

Only works with strings, slices, arrays, maps, channels, or pointers.

func BeEqual 

func BeEqual(t testing.TB, actual any, expected any, opts ...Option)

BeEqual reports a test failure if the two values are not deeply equal.

This assertion uses Go's reflect.DeepEqual for comparison and provides detailed error messages showing exactly what differs between the values. For complex objects, it shows field-by-field differences to help identify the specific mismatches.

Example: 

should.BeEqual(t, "hello", "hello")

should.BeEqual(t, 42, 42)

should.BeEqual(t, user, expectedUser, should.WithMessage("User objects should match"))

Works with any comparable types. Uses deep comparison for complex objects.

func BeFalse 

func BeFalse(t testing.TB, actual bool, opts ...Option)

BeFalse reports a test failure if the value is not false.

This assertion only works with boolean values and will fail immediately if the value is not a boolean type.

Example: 

should.BeFalse(t, false)

should.BeFalse(t, user.IsDeleted, should.WithMessage("User should not be deleted"))

func BeGreaterOrEqualTo 

func BeGreaterOrEqualTo[T Ordered](t testing.TB, actual T, expected T, opts ...Option)

BeGreaterOrEqualTo reports a test failure if the value is not greater than or equal to the expected threshold.

This assertion works with all numeric types and provides detailed error messages when the assertion fails. It supports optional custom error messages through Option.

Example: 

should.BeGreaterOrEqualTo(t, 10, 10)

should.BeGreaterOrEqualTo(t, user.Score, 0, should.WithMessage("Score cannot be negative"))

should.BeGreaterOrEqualTo(t, 3.14, 3.14)

Only works with numeric types. Both values must be of the same type.

func BeGreaterThan 

func BeGreaterThan[T Ordered](t testing.TB, actual T, expected T, opts ...Option)

BeGreaterThan reports a test failure if the value is not greater than the expected threshold.

This assertion works with all numeric types and provides detailed error messages showing the actual value, threshold, difference, and helpful hints. It supports optional custom error messages through Option.

Example: 

should.BeGreaterThan(t, 10, 5)

should.BeGreaterThan(t, user.Age, 18, should.WithMessage("User must be adult"))

should.BeGreaterThan(t, 3.14, 2.71)

Only works with numeric types. Both values must be of the same type.

func BeLessOrEqualTo 

func BeLessOrEqualTo[T Ordered](t testing.TB, actual T, expected T, opts ...Option)

BeLessOrEqualTo reports a test failure if the value is not less than or equal to the expected threshold.

This assertion works with all numeric types and provides detailed error messages when the assertion fails. It supports optional custom error messages through Option.

Example: 

should.BeLessOrEqualTo(t, 5, 10)

should.BeLessOrEqualTo(t, user.Age, 65, should.WithMessage("User must be under retirement age"))

should.BeLessOrEqualTo(t, 3.14, 3.14)

Only works with numeric types. Both values must be of the same type.

func BeLessThan 

func BeLessThan[T Ordered](t testing.TB, actual T, expected T, opts ...Option)

BeLessThan reports a test failure if the value is not less than the expected threshold.

This assertion works with all numeric types and provides detailed error messages showing the actual value, threshold, difference, and helpful hints. It supports optional custom error messages through Option.

Example: 

should.BeLessThan(t, 5, 10)

should.BeLessThan(t, user.Age, 65, should.WithMessage("User must be under retirement age"))

should.BeLessThan(t, 2.71, 3.14)

Only works with numeric types. Both values must be of the same type.

func BeNil 

func BeNil(t testing.TB, actual any, opts ...Option)

BeNil reports a test failure if the value is not nil.

This assertion works with pointers, interfaces, channels, functions, slices, and maps. It uses Go's reflection to check if the value is nil.

Example: 

var ptr *int
should.BeNil(t, ptr)

var slice []int
should.BeNil(t, slice, should.WithMessage("Slice should be nil"))

Only works with nillable types (pointers, interfaces, channels, functions, slices, maps).

func BeOfType 

func BeOfType(t testing.TB, actual, expected any, opts ...Option)

BeOfType reports a test failure if the value is not of the expected type.

This assertion checks if the type of the actual value matches the type of the expected value (using an instance of the expected type).

Example: 

type MyType struct{}
var v MyType
should.BeOfType(t, MyType{}, v)

func BeOneOf 

func BeOneOf[T any](t testing.TB, actual T, options []T, opts ...Option)

BeOneOf reports a test failure if the value is not one of the provided options.

This assertion checks if the actual value is present in the slice of allowed options. It uses deep comparison to check for equality.

Example: 

status := "pending"
allowedStatus := []string{"active", "inactive"}
should.BeOneOf(t, status, allowedStatus)

func BeTrue 

func BeTrue(t testing.TB, actual bool, opts ...Option)

BeTrue reports a test failure if the value is not true.

This assertion only works with boolean values and will fail immediately if the value is not a boolean type.

Example: 

should.BeTrue(t, true)

should.BeTrue(t, user.IsActive, should.WithMessage("User must be active"))

func Contain 

func Contain(t testing.TB, actual any, expected any, opts ...Option)

Contain reports a test failure if the slice or array does not contain the expected value.

This assertion provides intelligent error messages based on the type of collection: - For []string: Shows similar elements and typo detection - For numeric slices ([]int, []float64, etc.): Shows insertion context and sorted position - For other types: Shows formatted collection with clear error messages Supports all slice and array types.

Example: 

should.Contain(t, users, "user3")

should.Contain(t, []int{1, 2, 3}, 2)

should.Contain(t, []float64{1.1, 2.2}, 1.5, should.WithMessage("Expected value missing"))

should.Contain(t, []string{"apple", "banana"}, "apple")

If the input is not a slice or array, the test fails immediately.

func ContainFunc 

func ContainFunc[T any](t testing.TB, actual T, expected func(TItem any) bool, opts ...Option)

ContainFunc reports a test failure if no element in the slice or array matches the predicate function.

This assertion allows for custom matching logic by providing a predicate function that will be called for each element in the collection. The test passes if any element makes the predicate return true.

Example: 

should.ContainFunc(t, users, func(item any) bool {
	user := item.(User)
	return user.Age > 18
})

should.ContainFunc(t, numbers, func(item any) bool {
	return item.(int) % 2 == 0
}, should.WithMessage("No even numbers found"))

If the input is not a slice or array, the test fails immediately.

func ContainKey 

func ContainKey[K comparable, V any](t testing.TB, actual map[K]V, expectedKey K, opts ...Option)

ContainKey reports a test failure if the map does not contain the expected key.

This assertion works with maps of any key type and provides intelligent error messages: - For string keys: Shows similar keys and typo detection - For numeric keys: Shows similar keys with numeric differences - For other types: Shows formatted keys with clear error messages Supports all map types.

Example: 

userMap := map[string]int{"name": 1, "age": 2}
should.ContainKey(t, userMap, "email")

should.ContainKey(t, map[int]string{1: "one", 2: "two"}, 3, should.WithMessage("Key must exist"))

func ContainSubstring 

func ContainSubstring(t testing.TB, actual string, substring string, opts ...Option)

ContainSubstring reports a test failure if the string does not contain the expected substring.

This assertion checks if the actual string contains the expected substring. It provides a detailed error message showing the expected and actual strings, with intelligent formatting for very long strings, and includes a note if case mismatch is detected.

Example: 

should.ContainSubstring(t, "Hello, world!", "world")

should.ContainSubstring(t, "Hello, World", "WORLD", should.IgnoreCase())

should.ContainSubstring(t, longText, "keyword", should.WithMessage("Expected keyword to be present"))

Note: The assertion is case-sensitive by default. Use should.IgnoreCase() to ignore case.

func ContainValue 

func ContainValue[K comparable, V any](t testing.TB, actual map[K]V, expectedValue V, opts ...Option)

ContainValue reports a test failure if the map does not contain the expected value.

This assertion works with maps of any value type and provides intelligent error messages: - For string values: Shows similar values and typo detection - For numeric values: Shows similar values with numeric differences - For other types: Shows formatted values with clear error messages Supports all map types.

Example: 

userMap := map[string]int{"name": 1, "age": 2}
should.ContainValue(t, userMap, 3)

should.ContainValue(t, map[int]string{1: "one", 2: "two"}, "three", should.WithMessage("Value must exist"))

func EndsWith 

func EndsWith(t testing.TB, actual string, expected string, opts ...Option)

EndsWith reports a test failure if the string does not end with the expected substring.

This assertion checks if the actual string ends with the expected substring. It provides a detailed error message showing the expected and actual strings, along with a note if the case mismatch is detected.

Example: 

should.EndsWith(t, "Hello, world!", "world")

should.EndsWith(t, "Hello, world", "WORLD", should.IgnoreCase())

should.EndsWith(t, "Hello, world!", "world", should.WithMessage("Expected string to end with 'world'"))

Note: The assertion is case-sensitive by default. Use should.IgnoreCase() to ignore case.

func HaveLength 

func HaveLength(t testing.TB, actual any, expected int, opts ...Option)

HaveLength reports a test failure if the collection does not have the expected length.

This assertion works with strings, slices, arrays, and maps. It provides a detailed error message showing the expected and actual lengths, along with the difference.

Example: 

should.HaveLength(t, []int{1, 2, 3}, 3)
should.HaveLength(t, "hello", 5)

func NotBeEmpty 

func NotBeEmpty(t testing.TB, actual any, opts ...Option)

NotBeEmpty reports a test failure if the value is empty.

This assertion works with strings, slices, arrays, maps, channels, and pointers. For strings, non-empty means length > 0. For slices/arrays/maps/channels, non-empty means length > 0. For pointers, non-empty means not nil. Provides detailed error messages for empty values.

Example: 

should.NotBeEmpty(t, "hello")

should.NotBeEmpty(t, []int{1, 2, 3}, should.WithMessage("List must have items"))

should.NotBeEmpty(t, &user)

Only works with strings, slices, arrays, maps, channels, or pointers.

func NotBeEqual 

func NotBeEqual(t testing.TB, actual any, expected any, opts ...Option)

NotBeEqual reports a test failure if the two values are deeply equal.

This assertion uses Go's reflect.DeepEqual for comparison and provides detailed error messages showing exactly what differs between the values. For complex objects, it shows field-by-field differences to help identify the specific mismatches.

Example: 

should.NotBeEqual(t, "hello", "world")

should.NotBeEqual(t, 42, 43)

should.NotBeEqual(t, user, expectedUser, should.WithMessage("User objects should not match"))

func NotBeNil 

func NotBeNil(t testing.TB, actual any, opts ...Option)

NotBeNil reports a test failure if the value is nil.

This assertion works with pointers, interfaces, channels, functions, slices, and maps. It uses Go's reflection to check if the value is not nil.

Example: 

user := &User{Name: "John"}
should.NotBeNil(t, user, should.WithMessage("User must not be nil"))

should.NotBeNil(t, make([]int, 0))

Only works with nillable types (pointers, interfaces, channels, functions, slices, maps).

func NotContain 

func NotContain(t testing.TB, actual any, expected any, opts ...Option)

NotContain reports a test failure if the slice or array contains the expected value.

This assertion works with slices and arrays of any type and provides detailed error messages showing where the unexpected element was found.

Example: 

should.NotContain(t, users, "bannedUser")

should.NotContain(t, []int{1, 2, 3}, 4)

should.NotContain(t, []string{"apple", "banana"}, "orange", should.WithMessage("Should not have orange"))

If the input is not a slice or array, the test fails immediately.

func NotContainDuplicates 

func NotContainDuplicates(t testing.TB, actual any, opts ...Option)

NotContainDuplicates reports a test failure if the slice or array contains duplicate values.

This assertion works with slices and arrays of any type and provides detailed error messages showing where the duplicate values were found.

Example: 

should.NotContainDuplicates(t, []int{1, 2, 2, 3, 3, 3, 4, 4, 4, 4, 4, 4})

should.NotContainDuplicates(t, []string{"John", "John"})

If the input is not a slice or array, the test fails immediately.

func NotContainKey 

func NotContainKey[K comparable, V any](t testing.TB, actual map[K]V, expectedKey K, opts ...Option)

NotContainKey reports a test failure if the map contains the expected key.

This assertion works with maps of any key type and provides detailed error messages showing where the key was found, including the map type, size, and context around the found key. Supports all map types.

Example: 

userMap := map[string]int{"name": 1, "age": 2}
should.NotContainKey(t, userMap, "age") // This will fail

should.NotContainKey(t, map[int]string{1: "one", 2: "two"}, 3, should.WithMessage("Key should not exist"))

func NotContainValue 

func NotContainValue[K comparable, V any](t testing.TB, actual map[K]V, expectedValue V, opts ...Option)

NotContainValue reports a test failure if the map contains the expected value.

This assertion works with maps of any value type and provides detailed error messages showing where the value was found, including the map type, size, and context around the found value. Supports all map types.

Example: 

userMap := map[string]int{"name": 1, "age": 2}
should.NotContainValue(t, userMap, 2) // This will fail

should.NotContainValue(t, map[int]string{1: "one", 2: "two"}, "three", should.WithMessage("Value should not exist"))

func NotPanic 

func NotPanic(t testing.TB, fn func(), opts ...Option)

NotPanic reports a test failure if the given function panics.

This assertion executes the provided function and expects it to complete normally without panicking. If a panic occurs, it captures the panic value and includes it in the error message. Supports optional custom error messages through Option.

Example: 

should.NotPanic(t, func() {
	result := add(1, 2)
	_ = result
})

should.NotPanic(t, func() {
	user.Save()
}, should.WithMessage("Save operation should not panic"))

The function parameter must not be nil.

func Panic 

func Panic(t testing.TB, fn func(), opts ...Option)

Panic reports a test failure if the given function does not panic.

This assertion executes the provided function and expects it to panic. It captures and recovers from the panic to prevent the test from crashing. Supports optional custom error messages through Option.

Example: 

should.Panic(t, func() {
	panic("expected panic")
})

should.Panic(t, func() {
	divide(1, 0)
}, should.WithMessage("Division by zero should panic"))

The function parameter must not be nil.

func StartsWith 

func StartsWith(t testing.TB, actual string, expected string, opts ...Option)

StartsWith reports a test failure if the string does not start with the expected substring.

This assertion checks if the actual string starts with the expected substring. It provides a detailed error message showing the expected and actual strings, along with a note if the case mismatch is detected.

Example: 

should.StartsWith(t, "Hello, world!", "hello")

should.StartsWith(t, "Hello, world!", "hello", should.IgnoreCase())

should.StartsWith(t, "Hello, world!", "world", should.WithMessage("Expected string to start with 'world'"))

Note: The assertion is case-sensitive by default. Use should.IgnoreCase() to ignore case.

Types

type CloseMatch 

type CloseMatch struct {
	Value       interface{}
	Differences []string
}

CloseMatch holds information about a value that is partially similar to the target.

type Config 

type Config struct {
	Message    string
	IgnoreCase bool
}

Config provides configuration options for assertions. It allows for custom error messages and future extensibility.

type ContainResult 

type ContainResult struct {
	Found   bool
	Exact   bool
	Similar []SimilarItem
	Context []interface{}
	MaxShow int
	Total   int
}

ContainResult result of the contains search

type MapContainResult 

type MapContainResult struct {
	Found        bool
	Exact        bool
	MaxShow      int
	Total        int
	Context      []interface{}
	Similar      []SimilarItem
	CloseMatches []CloseMatch
}

MapContainResult represents the result of checking if a map contains a key or value

type Option 

type Option interface {
	Apply(config *Config)
}

Option is a functional option for configuring assertions.

func IgnoreCase 

func IgnoreCase() Option

func WithMessage 

func WithMessage(msg string) Option

WithMessage creates an option for setting a custom error message.

type Ordered 

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

Ordered is a type constraint for types that can be ordered. It includes all integer and floating-point types.

type SimilarItem 

type SimilarItem struct {
	Value      interface{}
	Index      int
	Similarity float64
	DiffType   string // "typo", "case", "prefix", "suffix", "substring"
	Details    string // description of the difference
}

SimilarItem represents a similar item found

type SliceOrArray 

type SliceOrArray[T any] interface {
	~[]T
}

SliceOrArray constraint that accepts only slices and arrays

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.