match

Documentation

Index

• func All[T any](children ...it.Match[T]) func(T) it.Result
• func Any[T any]() it.Match[T]
• func BeGreater[T constraints.Ordered](expected T) func(T) it.Result
• func BeLess[T constraints.Ordered](expected T) func(T) it.Result
• func BeZero[T comparable](actual T) it.Result
• func DeepEqual[T any](expected T) func(T) it.Result
• func Equal[T comparable](expected T) func(T) it.Result
• func Eventually[T any](m it.Match[T], opts ...AsyncOption) it.Match[func() T]
• func HaveChanLen[T any](length int) func(chan T) it.Result
• func HaveMapLen[T comparable, U any](length int) func(map[T]U) it.Result
• func HaveSliceLen[T any](length int) func([]T) it.Result
• func HaveStrLen(length int) func(string) it.Result
• func Map[T, U any](mapper func(T) U, opts ...MapOption) func(it.Match[U]) it.Match[T]
• func Not[T any](match it.Match[T]) func(T) it.Result
• func NotErr(err error) it.Result
• func Receive[T any](m it.Match[T], opts ...AsyncOption) it.Match[chan T]
• func WrapErr(expected error) it.Match[error]
• type Actual
• type ActualWithErr
• type ActualWithOK
• type AsyncOption
  • func Freq(d time.Duration) AsyncOption
  • func Timeout(d time.Duration) AsyncOption
• type AsyncPrefs
• type MapOption
  • func DescribeMap(desc string) MapOption

Examples

• Map (Atoi)

Functions

func All

func All[T any](children ...it.Match[T]) func(T) it.Result

All checks that an actual value satisfies all match functions passed to it. This is helpful for applying multiple checks to a single value.

All will always call all children in sequence. This means that later children may rely previous children being done, but not necessarily successful.

The returned it.Result contains results from all children wrapped up using result.Many(). This can be useful to get output from multiple failed assertions on a single value - e.g. showing that multiple arguments in a mock method call failed their checks.

All panics if len(children) == 0, since it has no way to return a valid result with no child matchers.

func Any

func Any[T any]() it.Match[T]

Any returns a matcher that matches any value. This is useful for matchers which wrap another matcher (like Receive or Eventually), to assert that their condition was satisfied without performing any further checks.

func BeGreater

func BeGreater[T constraints.Ordered](expected T) func(T) it.Result

BeGreater returns a matcher that passes if the actual is greater than expected.

func BeLess

func BeLess[T constraints.Ordered](expected T) func(T) it.Result

BeLess returns a matcher that passes if the actual is less than expected.

func BeZero

func BeZero[T comparable](actual T) it.Result

BeZero is a match function which tests that an actual value is equal to its zero value. This covers the BeNil comparison as well, ensuring that we're never comparing typed nil against untyped nil.

func DeepEqual

func DeepEqual[T any](expected T) func(T) it.Result

DeepEqual uses reflect.DeepEqual to compare two values. This is useful for types that do not satisfy comparable.

func Equal

func Equal[T comparable](expected T) func(T) it.Result

Equal returns a match function to test that an actual value is equal to an expected value.

func Eventually

func Eventually[T any](m it.Match[T], opts ...AsyncOption) it.Match[func() T]

Eventually returns a match function which polls a function until the return value passes the provided match function. By default, Eventually polls every millisecond and times out after one second.

func HaveChanLen

func HaveChanLen[T any](length int) func(chan T) it.Result

HaveChanLen matches a channel's length (i.e. how many items are buffered in the channel).

See HaveSliceLen for reasons that there is no general HaveLen matcher.

func HaveMapLen

func HaveMapLen[T comparable, U any](length int) func(map[T]U) it.Result

HaveMapLen matches a map's length.

See HaveSliceLen for reasons that there is no general HaveLen matcher.

func HaveSliceLen

func HaveSliceLen[T any](length int) func([]T) it.Result

HaveSliceLen matches a slice's length.

A single HaveLen matcher that works for all lengthable types (e.g. HaveLen(...)) causes a very ugly matcher, where you have to pass both the collection type and its element types as type parameters. The best we could do is HaveLen[[]string, struct{}, string](...).

Rather than force ugly type parameters, we provide multiple length matchers and only require type parameters for the element type(s). HaveSliceLen[string](...) is much cleaner.

func HaveStrLen

func HaveStrLen(length int) func(string) it.Result

HaveStrLen matches a string's length.

See HaveSliceLen for reasons that there is no general HaveLen matcher.

func Map

func Map[T, U any](mapper func(T) U, opts ...MapOption) func(it.Match[U]) it.Match[T]

Map takes a function to translate from one value to another, returning a function which will translate match functions to accept the translated type. This should look similar to higher-order map functions in functional programming.

Map may be used to extract fields from structs, unmarshal (or marshal) JSON, or really do any other logic that must perform some logic or translation before applying a matcher.

Example (Atoi)

package main

import (
	"context"
	"fmt"
	"strconv"

	"git.sr.ht/~nelsam/correct/it"
	"git.sr.ht/~nelsam/correct/match"
	"git.sr.ht/~nelsam/correct/result"
)

type printingT struct{}

func (t printingT) Helper() {}

func (t printingT) Logf(s string, args ...any) {
	fmt.Printf("logged: "+s+"\n", args...)
}

func (t printingT) Fatalf(s string, args ...any) {
	fmt.Printf("fataled: "+s+"\n", args...)
}

var exampleTheme = func() result.Theme {
	t := result.DefaultTheme()
	t.Actual = result.SimpleSprinter{Fn: func(v ...any) string { return fmt.Sprintf("actual(%v)", v[0]) }}
	t.Expected = result.SimpleSprinter{Fn: func(v ...any) string { return fmt.Sprintf("expected(%v)", v[0]) }}
	return t
}()

func main() {
	var t printingT
	actual := "12"
	toInt := match.Map(func(v string) int {
		i, err := strconv.Atoi(v)
		it.Must(t, err, match.NotErr)
		return i
	})
	ctx := exampleTheme.WithContext(context.Background())
	it.Must(t, actual, toInt(match.BeGreater(20)), it.WithCtx(ctx))
}

Output:

fataled: FAIL: actual(12) <= expected(20)

func Not

func Not[T any](match it.Match[T]) func(T) it.Result

Not negates the match function passed in.

func NotErr

func NotErr(err error) it.Result

NotErr is sugar for BeZero[error], with a more error-focused description.

func Receive

func Receive[T any](m it.Match[T], opts ...AsyncOption) it.Match[chan T]

Receive returns a matcher that checks that a channel receives a value.

By default, Receive will block indefinitely. Use Timeout(-1) to force a default case, or Timeout(someDuration) to use a timer.

func WrapErr

func WrapErr(expected error) it.Match[error]

WrapErr checks that errors.Is(actual, expected) returns true.

Types

type Actual

type Actual[T any] interface {
	Value() T
}

Actual represents an actual value, typically from actual.Val(someValue).

type ActualWithErr

type ActualWithErr[T any] interface {
	Actual[T]
	Err() error
}

ActualWithErr represents an actual value and an error, typically from actual.AndErr(someFn()).

type ActualWithOK

type ActualWithOK[T any] interface {
	Actual[T]
	OK() bool
}

ActualWithOK represents an actual value and an error, typically from actual.AndOK(someFn()).

type AsyncOption

type AsyncOption func(AsyncPrefs) AsyncPrefs

AsyncOption is a general asynchronous option function type, for matchers which may run asynchronously with application logic. They may need to wait for the application logic to catch up, either by polling or by waiting on a channel.

func Freq

func Freq(d time.Duration) AsyncOption

Freq returns an AsyncOption which sets how frequently the matcher should poll. This won't impact matchers that are applied to channels.

func Timeout

func Timeout(d time.Duration) AsyncOption

Timeout returns an AsyncOption which sets the timeout of the matcher.

type AsyncPrefs

type AsyncPrefs struct {
	Timeout   time.Duration
	Frequency time.Duration
}

AsyncPrefs is a preferences type for asynchronous matchers. It is exported so that custom matchers may make use of AsyncOption functions.

type MapOption

type MapOption func(mapPrefs) mapPrefs

MapOption is an option for adding information to map results.

func DescribeMap

func DescribeMap(desc string) MapOption

DescribeMap returns a MapOption which adds a description to a result, like it.Describe but for just the mapped value.