Documentation
¶
Overview ¶
Package assert provides uniform vocabulary for invariant checks.
Every helper panics with an *AssertionError when its condition fails. The error carries the calling function's name, file, and line — captured via runtime.Callers — so callers do not have to repeat their own location in the message. The panic value is typed, so tests and top-level recover handlers can distinguish invariant breaches from unrelated runtime panics via errors.As.
These checks are not stripped from release builds. An invariant worth asserting is worth asserting in production.
Index ¶
- func Failf(format string, args ...any)
- func Must[T any](value T, err error) T
- func Nil[T any](name string, value *T)
- func NoError(context string, err error)
- func NonEmpty[T ~[]E | ~map[K]V | ~string, E any, K comparable, V any](name string, value T) T
- func NonZero[T comparable](name string, value T) T
- func True(claim string, condition bool)
- func Truef(condition bool, format string, args ...any)
- func Type[T any](name string, value any) T
- func Unimplemented(what string)
- func Unreachable(reason string)
- func Unreachablef(format string, args ...any)
- type AssertionError
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Failf ¶
Failf panics with an *AssertionError whose Message is fmt.Sprintf(format, args...).
Use when the message needs interpolation (type names, indices, registry keys, …).
Parameters:
- `format`: a fmt.Sprintf format string.
- `args`: the format arguments.
func Must ¶
Must returns `value` unless `err` is non-nil, in which case it panics with an *AssertionError.
Use to unwrap a (value, error) call whose failure indicates a bug — not a recoverable runtime condition: `silent := assert.Must(cmd.Flags().GetBool("silent"))`. Go forbids mixing a context argument with a multi-value call, so Must carries no label; the *AssertionError's captured call site supplies the location.
Parameters:
- `value`: the value to return when `err` is nil.
- `err`: the error to inspect.
Returns:
- `T`: `value`, unchanged.
func Nil ¶
Nil panics with an *AssertionError when `value` is non-nil.
Constrained to pointer types, so the nil check is type-safe; the compiler rejects non-nillable inputs (strings, ints, structs, …) at the call site rather than letting the assertion silently succeed.
For interface and function nil-checks (where the value is not addressable as `*T`), use True with an explicit predicate: `assert.True("err nil", err == nil)`, or
Parameters:
- `name`: a short identifier of the value being checked (e.g. "cache entry").
- `value`: the pointer to inspect.
func NoError ¶
NoError panics with an *AssertionError when `err` is non-nil.
Use for downstream errors that indicate a bug — not a recoverable runtime condition. The panic message has the form "<context>: <err>". For sites where `context` itself needs interpolation, build it with fmt.Sprintf at the call site or use Failf directly.
Parameters:
- `context`: a short label identifying the operation that produced `err` (e.g. "iox.Close").
- `err`: the error to inspect.
func NonEmpty ¶
func NonEmpty[T ~[]E | ~map[K]V | ~string, E any, K comparable, V any](name string, value T) T
NonEmpty panics with an *AssertionError when `value` is empty.
Constrained to collection types (slices, maps, strings), so the check is type-safe; the compiler rejects non-indexable inputs at the call site.
Parameters:
- `name`: a short identifier of the value being checked (e.g. "items", "cfg.Headers").
- `value`: the collection or string to inspect.
func NonZero ¶
func NonZero[T comparable](name string, value T) T
NonZero panics with an *AssertionError when `value` is nil.
Constrained to comparable types, so the check for non-zero is type-safe; the compiler rejects non-comparable inputs at the call site. For function pointers--which are non-comparable--you must:
var functionPointer assert.NonZero(*(*uintptr)(unsafe.Pointer(&functionPointer))))
Parameters:
- `name`: a short identifier of the value being checked (e.g. "Root", "cfg.Registry").
- `value`: the value to inspect.
func True ¶
True panics with an *AssertionError when the given condition is false.
Use for inline invariants that are not ergonomic to express as a NonZero/Unreachable check.
Parameters:
- `claim`: short prose describing the invariant that must hold (e.g. "boundary is not empty").
- `cond`: the condition; failure raises with a message "<claim>".
func Truef ¶
Truef panics with an *AssertionError whose Message is fmt.Sprintf(format, args...) when the condition is false.
Use for inline invariants whose failure message needs interpolation (type names, indices, registry keys, …).
Parameters:
- `format`: a fmt.Sprintf format string describing the invariant.
- `condition`: the condition; failure raises with the formatted message.
- `args`: the format arguments.
func Type ¶
Type returns `value` as type `T`, panicking with an *AssertionError when the dynamic type differs.
Use where a value's type is guaranteed by construction (a just-parsed document field, a registry invariant) and a mismatch is a bug: `id := assert.Type[string]("unit id", b.value)`. The labeled panic replaces the unlabeled runtime panic of a bare single-value type assertion.
Parameters:
- `name`: a short identifier of the value being checked (e.g. "unit id").
- `value`: the value whose dynamic type must be `T`.
Returns:
- `T`: `value` as `T`.
func Unimplemented ¶
func Unimplemented(what string)
Unimplemented panics unconditionally with an *AssertionError.
Use in a method that satisfies an interface but is intentionally not yet implemented — a loud stub that fails fast if reached, rather than a silent no-op or a soft error return.
Parameters:
- `what`: short prose naming the unimplemented operation (e.g. "git.Resource.Exists").
func Unreachable ¶
func Unreachable(reason string)
Unreachable panics unconditionally with an *AssertionError.
Use in default branches of exhaustive switches and on "this can't happen" paths.
Parameters:
- `reason`: short prose describing why the branch is unreachable.
func Unreachablef ¶
Unreachablef panics unconditionally with an *AssertionError.
Use in default branches of exhaustive switches and on "this can't happen" paths.
Parameters:
- `reason`: short prose describing why the branch is unreachable.
Types ¶
type AssertionError ¶
AssertionError is the typed panic value produced by every helper in this package.
Function holds the short form of the calling function (last path segment, e.g. "fsroot.OpenConfined") rather than the fully qualified import path; File and Line point at the assert function's call site.
func (*AssertionError) Error ¶
func (e *AssertionError) Error() string
Error returns the formatted invariant description prefixed by the calling function and suffixed by the call site.
Returns:
- `string`: "<Function>: <Message> (<File>:<Line>)".
Source Files