Assertion reference

This is an exhaustive list of all assertion macros that Criterion provides.

Note

This documents the new (but experimental) assertion API. To see the documentation of the old API, see: Old assertion reference.

The new assertions API is centered around the use of criteria pseudo-functions to check various properties of the values being tested. Of note, there no longer are cr_assert_<xyz> macros, and instead all functionality has been merged into the cr_assert and cr_expect macros. For instance, instead of using cr_assert_eq(1, 2) one must use instead cr_assert(eq(int, 1, 2)), which involves the eq criterion and the int type tag.

To use the new assertion API, one must include the <criterion/new/assert.h> header.

All assert macros may take an optional printf format string and parameters.

Assertion API

group AssertAPI

Assertion API.

Defines

cr_fail(Format, ...)

Mark the test as failed.

The test is marked as a failure, printing the formatted string if provided, and the execution continues.

Parameters
  • Format[in] (optional) Printf-like format string

  • ...[in] Format string parameters

cr_fatal(Format, ...)

Abort and mark the test as failed.

The test is marked as a failure, printing the formatted string if provided, and the execution of the test is aborted.

Parameters
  • Format[in] (optional) Printf-like format string

  • ...[in] Format string parameters

cr_skip(Format, ...)

Abort and mark the test as skipped.

The test is marked as skipped, printing the formatted string if provided, and the execution of the test is aborted.

Parameters
  • Format[in] (optional) Printf-like format string

  • ...[in] Format string parameters

cr_assert(Criterion, Format, ...)

Assert that a criterion is true and abort if it is not.

cr_assert evaluates the passed criterion and passes if it has a non-zero value.

The criterion may be any C expression of non-void type, in which case the assertion value will be !!Criterion. Alternatively, the criterion may be any of the valid pseudo-functions described in the Criteria list.

If the evaluated criterion is zero, then cr_fatal(Format, …) is called.

Parameters
  • Criterion[in] The Criterion to evaluate

  • Format[in] (optional) Printf-like format string

  • ...[in] Format string parameters

cr_expect(Criterion, Format, ...)

Expect that a criterion is true and fail if it is not.

cr_expect evaluates the passed criterion and passes if it has a non-zero value.

The criterion may be any C expression of non-void type, in which case the assertion value will be !!Criterion. Alternatively, the criterion may be any of the valid pseudo-functions described in the Criteria list.

If the evaluated criterion is zero, then cr_fail(Format, …) is called.

Parameters
  • Criterion[in] The Criterion to evaluate

  • Format[in] (optional) Printf-like format string

  • ...[in] Format string parameters

cr_assert_user(File, Line, FailFunc, Criterion, Format, ...)

cr_assert_user is an utility macro to help users implement their own assertions easily.

Users may pass file and line information. The function behaves like cr_assert and cr_expect, in that it evaluates the criterion to determine whether a test fails or not.

When the criterion evaluates to zero, a failed assertion event is raised back to the runner, and then FailFunc is called without parameters.

Parameters
  • File[in] The file in which the assertion has been called.

  • Line[in] The line number at which the assertion has been called.

  • FailFunc[in] The function to call on a failed assertion.

  • Criterion[in] The Criterion to evaluate.

  • Format[in] (optional) Printf-like format string.

  • ...[in] Format string parameters.

Assertion Criteria

group Criteria

Criteria are pseudo-functions that evaluate to a boolean value.

Using criteria is recommended over standard C operator as they allow value pretty printing and other diagnostics on assertion failure.

Note

Criteria are neither symbols or macros, but pseudo-functions. They are only valid in the context of the assertion API when explicitely allowed and cannot be called alone.

Defines

not(Criterion)

Evaluates to !Criterion.

Parameters
  • Criterion[in] The criterion to negate

all(...)

Evaluates to true if all its arguments are true.

all() evaluates a sequence of criteria, and combines them into a single value with the logical and operator (&&).

Parameters
  • ...[in] A sequence of criteria to evaluate

any(...)

Evaluates to true if any of its arguments is true.

any() evaluates a sequence of criteria, and combines them into a single value with the logical or operator (||).

Parameters
  • ...[in] A sequence of criteria to evaluate

none(...)

Evaluates to true if none of its arguments is true.

none() evaluates a sequence of criteria, and combines their negation into a single value with the logical and operator (&&).

Parameters
  • ...[in] A sequence of criteria to evaluate

group TaggedCriteria

Tagged Criteria are special criteria that take an optional type tag as their first argument.

Unless otherwise specified, all tagged criteria generally support any of the supported tags

Defines

eq(Tag, Actual, Expected)

Evaluates to Actual == Expected.

While this operator works for flt, dbl, and ldbl, the chance of having the values being exactly equal to each other is astronomically low due to round-off errors. Instead, please use as appropriate ieee_ulp_eq and epsilon_eq

Parameters
  • (optional) (Tag) – [in] The type tag of the parameters

  • Actual[in] the actual value

  • Expected[in] the expected value

ne(Tag, Actual, Unexpected)

Evaluates to Actual != Unexpected.

While this operator works for flt, dbl, and ldbl, the chance of having the values being exactly equal to each other is astronomically low due to round-off errors. Instead, please use as appropriate ieee_ulp_ne and epsilon_ne

Parameters
  • (optional) (Tag) – [in] The type tag of the parameters

  • Actual[in] the actual value

  • Unexpected[in] the unexpected value

lt(Tag, Actual, Reference)

Evaluates to Actual < Reference.

Parameters
  • (optional) (Tag) – [in] The type tag of the parameters

  • Actual[in] the actual value

  • Reference[in] the reference value

le(Tag, Actual, Reference)

Evaluates to Actual <= Reference.

Parameters
  • (optional) (Tag) – [in] The type tag of the parameters

  • Actual[in] the actual value

  • Reference[in] the reference value

gt(Tag, Actual, Reference)

Evaluates to Actual > Reference.

Parameters
  • (optional) (Tag) – [in] The type tag of the parameters

  • Actual[in] the actual value

  • Reference[in] the reference value

ge(Tag, Actual, Reference)

Evaluates to Actual >= Reference.

Parameters
  • (optional) (Tag) – [in] The type tag of the parameters

  • Actual[in] the actual value

  • Reference[in] the reference value

zero(Tag, Value)

Evaluates to true if Value is equal to the “zero value” of its type.

The zero value for primitive types and pointer types is the constant 0.

The zero value for c-strings (char *, wchar_t *) is the empty string, “” and L”” respectively.

User-defined types may be used, but what a zero value of these types mean depend on the language used.

In C, the function bool cr_user_<type>_zero(const <type> *t) must be defined, and will be invoked to check that t is a zero value.

In C++, the type corresponding to the passed tag, or the inferred type of Value if the tag is unspecified, must be default-constructible. The zero value of that type is the default construction of that type, and the value is compared against it with ==.

Parameters
  • (optional) (Tag) – [in] The type tag of the parameter

  • Value[in] the value to compare for zeroness

ieee_ulp_eq(Tag, Actual, Expected, Ulp)

Evaluates to true if the IEEE 754 floating point numbers Actual and Expected are almost equal, by being within Ulp units from each other.

This method of comparison is more accurate when comparing two IEEE 754 floating point values when Expected is non-zero. When comparing against zero, please use epsilon_eq instead.

This tagged criterion only supports the flt, dbl and ldbl tags.

A good general-purpose value for Ulp is 4.

Parameters
  • (optional) (Tag) – [in] The type tag of the parameters

  • Actual[in] the actual value

  • Expected[in] the reference value

  • Ulp[in] the number of units in the last place used in the comparison

ieee_ulp_ne(Tag, Actual, Expected, Ulp)

Evaluates to true if the IEEE 754 floating point numbers Actual and Expected are different, by not being within Ulp units from each other.

This method of comparison is more accurate when comparing two IEEE 754 floating point values when Expected is non-zero. When comparing against zero, please use epsilon_ne instead.

This tagged criterion only supports the flt, dbl and ldbl tags.

A good general-purpose value for Ulp is 4.

Parameters
  • (optional) (Tag) – [in] The type tag of the parameters

  • Actual[in] the actual value

  • Expected[in] the reference value

  • Ulp[in] the number of units in the last place used in the comparison

epsilon_eq(Tag, Actual, Expected, Epsilon)

Evaluates to true if the floating point numbers Actual and Expected are almost equal, by being within an absolute Epsilon from each other (In other words, if fabs(Actual - Expected) <= Epsilon).

This method of comparison is more accurate when comparing two IEEE 754 floating point values that are near zero. When comparing against values that aren’t near zero, please use ieee_ulp_eq instead.

This tagged criterion only supports the flt, dbl and ldbl tags.

It is recommended to have Epsilon be equal to a small multiple of the type epsilon (FLT_EPSILON, DBL_EPSILON, LDBL_EPSILON) and the input parameters.

Parameters
  • (optional) (Tag) – [in] The type tag of the parameters

  • Actual[in] the actual value

  • Expected[in] the reference value

  • Epsilon[in] the epsilon used in the comparison

epsilon_ne(Tag, Actual, Expected, Epsilon)

Evaluates to true if the floating point numbers Actual and Expected are different, by not being within an absolute Epsilon from each other (In other words, if fabs(Actual - Expected) > Epsilon).

This method of comparison is more accurate when comparing two IEEE 754 floating point values that are near zero. When comparing against values that aren’t near zero, please use ieee_ulp_eq instead.

This tagged criterion only supports the flt, dbl and ldbl tags.

It is recommended to have Epsilon be equal to a small multiple of the type epsilon (FLT_EPSILON, DBL_EPSILON, LDBL_EPSILON) and the input parameters.

Parameters
  • (optional) (Tag) – [in] The type tag of the parameters

  • Actual[in] the actual value

  • Expected[in] the reference value

  • Epsilon[in] the epsilon used in the comparison

Tags

group Tags

Tags are special tokens representing a type, that allow Criterion to infer type information on parameters for better diagnostics on assertion failure.

Any tag may also use the square-bracket array subscript notation to denote an array type tag, like i8[16] or type(struct user)[2], in which case the criterion will apply on each element of this array.

Note

A tag is a special, Criterion-specific language token. It it neither a symbol nor a macro, and cannot be used in any other context than when explicitely allowed.

Defines

i8
i16
i32
i64
u8
u16
u32
u64
sz
ptr
iptr
uptr
chr
int
uint
long
ulong
llong
ullong
flt
dbl
ldbl
cx_flt
cx_dbl
cx_ldbl
mem
str
wcs
tcs
type(UserType)

Represent an user-defined type.

The user type must be printable, and as such must implement a “to-string” operation:

(C only) char *cr_mem_<type>_tostr(const <type> *val);
(C++ only) std::ostream &operator<<(std::ostream &os, const <type> &val);

Additionally, the user must implement the following functions to use various general-purpose criteria:

eq, ne, le, ge:

(C only) int cr_mem_<type>_eq(const <type> *lhs, const <type> *rhs);
(C++ only) bool operator==(const <type> &lhs, const <type> &rhs);

lt, le, gt, ge:

(C only) int cr_mem_<type>_lt(const <type> *lhs, const <type> *rhs);
(C++ only) bool operator<(const <type> &lhs, const <type> &rhs);

Due to implementation restrictions, UserType must either be a structure, an union, an enum, or a typedef.

For instance, these are fine:

type(foo)
type(struct foo)

and these are not:

type(foo *)
type(int (&foo)(void))

in these cases, use a typedef to alias those types to a single-word token.