package assert

import "github.com/antithesishq/antithesis-sdk-go/assert"

Package assert enables defining test properties about your program or workload. It is part of the Antithesis Go SDK, which enables Go applications to integrate with the Antithesis platform.

Code that uses this package should be instrumented with the antithesis-go-generator utility. This step is required for the Always, Sometime, and Reachable methods. It is not required for the Unreachable and AlwaysOrUnreachable methods, but it will improve the experience of using them.

These functions are no-ops with minimal performance overhead when called outside of the Antithesis environment. However, if the environment variable ANTITHESIS_SDK_LOCAL_OUTPUT is set, these functions will log to the file pointed to by that variable using a structured JSON format defined here. This allows you to make use of the Antithesis assertions package in your regular testing, or even in production. In particular, very few assertions frameworks offer a convenient way to define Sometimes assertions, but they can be quite useful even outside Antithesis.

Each function in this package takes a parameter called message, which is a human readable identifier used to aggregate assertions. Antithesis generates one test property per unique message and this test property will be named "<message>" in the triage report.

This test property either passes or fails, which depends upon the evaluation of every assertion that shares its message. Different assertions in different parts of the code should have different message, but the same assertion should always have the same message even if it is moved to a different file.

Each function also takes a parameter called details, which is a key-value map of optional additional information provided by the user to add context for assertion failures. The information that is logged will appear in the triage report, under the details section of the corresponding property. Normally the values passed to details are evaluated at runtime.

Index

• func Always(condition bool, message string, details map[string]any)
• func AlwaysGreaterThan(left, right T, message string, details map[string]any)
• func AlwaysGreaterThanOrEqualTo(left, right T, message string, details map[string]any)
• func AlwaysLessThan(left, right T, message string, details map[string]any)
• func AlwaysLessThanOrEqualTo(left, right T, message string, details map[string]any)
• func AlwaysOrUnreachable(condition bool, message string, details map[string]any)
• func AlwaysSome(named_bools []NamedBool, message string, details map[string]any)
• func AssertRaw(cond bool, message string, details map[string]any, ...)
• func BooleanGuidanceRaw(named_bools []NamedBool, message, id string, ...)
• func NumericGuidanceRaw(left, right T, message, id string, classname, funcname, filename string, ...)
• func Reachable(message string, details map[string]any)
• func Sometimes(condition bool, message string, details map[string]any)
• func SometimesAll(named_bools []NamedBool, message string, details map[string]any)
• func SometimesGreaterThan(left, right T, message string, details map[string]any)
• func SometimesGreaterThanOrEqualTo(left, right T, message string, details map[string]any)
• func SometimesLessThan(left, right T, message string, details map[string]any)
• func SometimesLessThanOrEqualTo(left, right T, message string, details map[string]any)
• func Unreachable(message string, details map[string]any)
• type NamedBool
  • func NewNamedBool(first string, second bool) *NamedBool
• type Number

Functions

func Always

func Always(condition bool, message string, details map[string]any)

Always asserts that condition is true every time this function is called, and that it is called at least once. The corresponding test property will be viewable in the Antithesis SDK: Always group of your triage report.

func AlwaysGreaterThan

func AlwaysGreaterThan[T Number](left, right T, message string, details map[string]any)

Equivalent to asserting Always(left > right, message, details). Information about left and right will automatically be added to the details parameter, with keys left and right. If you use this function for assertions that compare numeric quantities, you may help Antithesis find more bugs.

func AlwaysGreaterThanOrEqualTo

func AlwaysGreaterThanOrEqualTo[T Number](left, right T, message string, details map[string]any)

Equivalent to asserting Always(left >= right, message, details). Information about left and right will automatically be added to the details parameter, with keys left and right. If you use this function for assertions that compare numeric quantities, you may help Antithesis find more bugs.

func AlwaysLessThan

func AlwaysLessThan[T Number](left, right T, message string, details map[string]any)

Equivalent to asserting Always(left < right, message, details). Information about left and right will automatically be added to the details parameter, with keys left and right. If you use this function for assertions that compare numeric quantities, you may help Antithesis find more bugs.

func AlwaysLessThanOrEqualTo

func AlwaysLessThanOrEqualTo[T Number](left, right T, message string, details map[string]any)

Equivalent to asserting Always(left <= right, message, details). Information about left and right will automatically be added to the details parameter, with keys left and right. If you use this function for assertions that compare numeric quantities, you may help Antithesis find more bugs.

func AlwaysOrUnreachable

func AlwaysOrUnreachable(condition bool, message string, details map[string]any)

AlwaysOrUnreachable asserts that condition is true every time this function is called. The corresponding test property will pass if the assertion is never encountered (unlike Always assertion types). This test property will be viewable in the “Antithesis SDK: Always” group of your triage report.

func AlwaysSome

func AlwaysSome(named_bools []NamedBool, message string, details map[string]any)

Asserts that every time this is called, at least one bool in named_bools is true. Equivalent to Always(named_bools[0].second || named_bools[1].second || ..., message, details). If you use this for assertions about the behavior of booleans, you may help Antithesis find more bugs. Information about named_bools will automatically be added to the details parameter, and the keys will be the names of the bools.

func AssertRaw

func AssertRaw(cond bool, message string, details map[string]any,
	classname, funcname, filename string, line int,
	hit bool, mustHit bool,
	assertType string, displayType string,
	id string,
)

AssertRaw is a low-level method designed to be used by third-party frameworks. Regular users of the assert package should not call it.

func BooleanGuidanceRaw

func BooleanGuidanceRaw(
	named_bools []NamedBool,
	message, id string,
	classname, funcname, filename string,
	line int,
	behavior string,
	hit bool,
)

BooleanGuidanceRaw is a low-level method designed to be used by third-party frameworks. Regular users of the assert package should not call it.

func NumericGuidanceRaw

func NumericGuidanceRaw[T Number](
	left, right T,
	message, id string,
	classname, funcname, filename string,
	line int,
	behavior string,
	hit bool,
)

NumericGuidanceRaw is a low-level method designed to be used by third-party frameworks. Regular users of the assert package should not call it.

func Reachable

func Reachable(message string, details map[string]any)

Reachable asserts that a line of code is reached at least once. The corresponding test property will pass if this function is ever called. (If it is never called the test property will therefore fail.) This test property will be viewable in the “Antithesis SDK: Reachablity assertions” group.

func Sometimes

func Sometimes(condition bool, message string, details map[string]any)

Sometimes asserts that condition is true at least one time that this function was called. (If the assertion is never encountered, the test property will therefore fail.) This test property will be viewable in the “Antithesis SDK: Sometimes” group.

func SometimesAll

func SometimesAll(named_bools []NamedBool, message string, details map[string]any)

Asserts that at least one time this is called, every bool in named_bools is true. Equivalent to Sometimes(named_bools[0].second && named_bools[1].second && ..., message, details). If you use this for assertions about the behavior of booleans, you may help Antithesis find more bugs. Information about named_bools will automatically be added to the details parameter, and the keys will be the names of the bools.

func SometimesGreaterThan

func SometimesGreaterThan[T Number](left, right T, message string, details map[string]any)

Equivalent to asserting Sometimes(T left > T right, message, details). Information about left and right will automatically be added to the details parameter, with keys left and right. If you use this function for assertions that compare numeric quantities, you may help Antithesis find more bugs.

func SometimesGreaterThanOrEqualTo

func SometimesGreaterThanOrEqualTo[T Number](left, right T, message string, details map[string]any)

Equivalent to asserting Sometimes(T left >= T right, message, details). Information about left and right will automatically be added to the details parameter, with keys left and right. If you use this function for assertions that compare numeric quantities, you may help Antithesis find more bugs.

func SometimesLessThan

func SometimesLessThan[T Number](left, right T, message string, details map[string]any)

Equivalent to asserting Sometimes(T left < T right, message, details). Information about left and right will automatically be added to the details parameter, with keys left and right. If you use this function for assertions that compare numeric quantities, you may help Antithesis find more bugs.

func SometimesLessThanOrEqualTo

func SometimesLessThanOrEqualTo[T Number](left, right T, message string, details map[string]any)

Equivalent to asserting Sometimes(T left <= T right, message, details). Information about left and right will automatically be added to the details parameter, with keys left and right. If you use this function for assertions that compare numeric quantities, you may help Antithesis find more bugs.

func Unreachable

func Unreachable(message string, details map[string]any)

Unreachable asserts that a line of code is never reached. The corresponding test property will fail if this function is ever called. (If it is never called the test property will therefore pass.) This test property will be viewable in the “Antithesis SDK: Reachablity assertions” group.

Types

type NamedBool

type NamedBool struct {
	First  string `json:"first"`
	Second bool   `json:"second"`
}

Used for boolean assertions

func NewNamedBool

func NewNamedBool(first string, second bool) *NamedBool

Convenience function to construct a NamedBool used for boolean assertions

type Number

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

Allowable numeric types of comparison parameters