observable

README

observable

Lightweight, zero-dependency helpers for writing expressive assertions in Go tests.

Example

package example_test

import (
    "errors"
    "testing"

    . "github.com/renormlabs/observable"
)

func TestAdd(t *testing.T) {
    add := func(a, b int) int { return a + b }

    // Basic equality
    Assert(t, Equal(add(2, 3), 5))

    // Negation
    Assert(t, Not(Equal)(add(2, 2), 5))

    // Error handling
    returnsErr := func() error { return errors.New("boom") }
    obs.Assert(t, Errors(returnsErr))
}

Documentation

Overview

Package observable provides lightweight, zero-dependency helpers for writing expressive assertions in Go tests. It embraces Go's standard testing package by integrating with testing.TB and keeps the API minimal while still supporting generic, user-defined predicates.

Index

• func Assert(tb testing.TB, p Predicate) bool
• func Assertf(tb testing.TB, p Predicate, format string, args ...any) bool
• func Not[T any](a T) T
• type Predicate
  • func All(ps ...Predicate) Predicate
  • func Any(ps ...Predicate) Predicate
  • func ChanLength[T any](c chan T, want int) Predicate
  • func Contains[T comparable](slice []T, elem T) Predicate
  • func ContainsKey[K comparable, V any](m map[K]V, key K) Predicate
  • func ContainsSubstring(s, substr string) Predicate
  • func ContainsValue[K comparable, V comparable](m map[K]V, val V) Predicate
  • func ElementsMatch[T comparable](got, want []T) Predicate
  • func Empty[T any](s []T) Predicate
  • func EmptyString(s string) Predicate
  • func Equal[T comparable](got, want T) Predicate
  • func EqualFold(got, want string) Predicate
  • func ErrorIs(err, target error) Predicate
  • func Errors(f func() error) Predicate
  • func ErrorsWith(f func() error, target error) Predicate
  • func False() Predicate
  • func HasPrefix(s, prefix string) Predicate
  • func HasSuffix(s, suffix string) Predicate
  • func Length[T any](s []T, want int) Predicate
  • func MapEqual[K comparable, V any](got, want map[K]V) Predicate
  • func MapLength[K comparable, V any](m map[K]V, want int) Predicate
  • func Nil(v any) Predicate
  • func Panics(f func()) Predicate
  • func RegexpMatches[T string | *regexp.Regexp](s string, reOrString T) Predicate
  • func Returns[T comparable](f func() T, want T) Predicate
  • func RuneLength(s string, want int) Predicate
  • func SequenceDeepEqual[T any](got, want []T) Predicate
  • func SequenceEqual[T comparable](got, want []T) Predicate
  • func StringLength(s string, want int) Predicate
  • func That[T ~bool | ~func() bool](x T) Predicate
  • func True() Predicate
  • func Zero[T comparable](v T) Predicate
  • func (p Predicate) Message() string
  • func (p Predicate) Ok() bool

Functions

func Assert

func Assert(tb testing.TB, p Predicate) bool

Assert evaluates the predicate and records an error on the testing.TB when the predicate is false.

The returned bool is the evaluation result, which allows further composition or chaining inside a test when desired.

func Assertf

func Assertf(tb testing.TB, p Predicate, format string, args ...any) bool

Assertf behaves like Assert but lets the caller supply an explicit failure message via format and args, similar to fmt.Sprintf.

func Not

func Not[T any](a T) T

Not returns the logical negation of its argument.

You can negate a: - Predicate, resulting in a Predicate - A function of any arity that returns a Predicate

Negating a function of positive arity will use runtime reflection.

Calling Not with anything else will **panic**!

Types

type Predicate

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

Predicate encapsulates a lazily‑evaluated boolean condition together with a descriptive failure message.

Generally, users will construct predicates with the helper functions in this package (e.g. Nil, Equal, Panics).The zero value is NOT valid.

func All

func All(ps ...Predicate) Predicate

All returns a Predicate that is ok when all of the supplied predicates are ok.

func Any

func Any(ps ...Predicate) Predicate

Any returns a Predicate that is ok when any of the supplied predicates are ok.

func ChanLength

func ChanLength[T any](c chan T, want int) Predicate

ChanLength returns a Predicate that is ok when len(c) == want (buffered channels only).

func Contains

func Contains[T comparable](slice []T, elem T) Predicate

Contains returns a Predicate that is ok when elem is present in slice.

func ContainsKey

func ContainsKey[K comparable, V any](m map[K]V, key K) Predicate

ContainsKey returns a Predicate that is ok when key exists in map m.

func ContainsSubstring

func ContainsSubstring(s, substr string) Predicate

ContainsSubstring returns a Predicate that succeeds when strings.Contains(s, substr).

func ContainsValue

func ContainsValue[K comparable, V comparable](m map[K]V, val V) Predicate

ContainsValue returns a Predicate that is ok when val appears as a value in map m.

func ElementsMatch

func ElementsMatch[T comparable](got, want []T) Predicate

ElementsMatch returns a Predicate that is ok when the two slices contain the same multiset of elements, irrespective of order.

func Empty

func Empty[T any](s []T) Predicate

Empty returns a Predicate that is ok when len(s) == 0.

func EmptyString

func EmptyString(s string) Predicate

EmptyString returns a Predicate that succeeds when the string is "".

func Equal

func Equal[T comparable](got, want T) Predicate

Equal returns a Predicate that is ok when got == want.

func EqualFold

func EqualFold(got, want string) Predicate

EqualFold returns a Predicate that succeeds when strings.EqualFold(got, want) (case-insensitive).

func ErrorIs

func ErrorIs(err, target error) Predicate

ErrorIs returns a Predicate that is ok when errors.Is(err, target) is true.

func Errors

func Errors(f func() error) Predicate

Errors returns a Predicate that is ok when f returns a non‑nil error.

func ErrorsWith

func ErrorsWith(f func() error, target error) Predicate

ErrorsWith returns a Predicate that is ok when f returns an error that matches target according to errors.Is.

func False

func False() Predicate

False returns a Predicate that always is not ok.

func HasPrefix

func HasPrefix(s, prefix string) Predicate

HasPrefix returns a Predicate that succeeds when strings.HasPrefix(s, prefix).

func HasSuffix

func HasSuffix(s, suffix string) Predicate

HasSuffix returns a Predicate that succeeds when strings.HasSuffix(s, suffix).

func Length

func Length[T any](s []T, want int) Predicate

Length returns a Predicate that is ok when len(s) == want.

func MapEqual

func MapEqual[K comparable, V any](got, want map[K]V) Predicate

MapEqual returns a Predicate that is ok when two maps are deeply equal (reflect.DeepEqual).

func MapLength

func MapLength[K comparable, V any](m map[K]V, want int) Predicate

MapLength returns a Predicate that is ok when len(m) == want.

func Nil

func Nil(v any) Predicate

Nil returns a Predicate that is ok when v is nil.

func Panics

func Panics(f func()) Predicate

Panics returns a Predicate that is ok when f panics.

func RegexpMatches

func RegexpMatches[T string | *regexp.Regexp](s string, reOrString T) Predicate

RegexpMatches returns a Predicate that succeeds when the regular expression re matches s. The regular expression can either be a *regexp.Regexp or a string which will be compiled with regexp.MustCompile.

func Returns

func Returns[T comparable](f func() T, want T) Predicate

Returns returns a Predicate that is ok when f's return value equals want.

func RuneLength

func RuneLength(s string, want int) Predicate

RuneLength returns a Predicate that succeeds when utf8.RuneCountInString(s) == want.

func SequenceDeepEqual

func SequenceDeepEqual[T any](got, want []T) Predicate

SequenceDeepEqual returns a Predicate that is ok when want and got reflect.DeepEqual each other. Allows comparing slices with non-comparable element types.

func SequenceEqual

func SequenceEqual[T comparable](got, want []T) Predicate

SequenceEqual returns a Predicate that is ok when got and want have identical length and elements appear in the same order.

func StringLength

func StringLength(s string, want int) Predicate

StringLength returns a Predicate that succeeds when len(s) == want.

func That

func That[T ~bool | ~func() bool](x T) Predicate

That promotes a bool or bool-thunk to a Predicate.

func True

func True() Predicate

True returns a Predicate that always is ok.

func Zero

func Zero[T comparable](v T) Predicate

Zero returns a Predicate that is ok when v is the zero value of its type.

func (Predicate) Message

func (p Predicate) Message() string

Message returns the descriptive text explaining why the predicate failed.

func (Predicate) Ok

func (p Predicate) Ok() bool

Ok evaluates and returns the underlying boolean condition.