Assertion reference

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

As each assert macros have an expect counterpart with the exact same number of parameters and name suffix, there is no benefit in adding expect macros to this list. Hence only assert macros are represented here.

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: (optional) Printf-like format string
  • ...: 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: (optional) Printf-like format string
  • ...: 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: (optional) Printf-like format string
  • ...: 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: The Criterion to evaluate
  • Format: (optional) Printf-like format string
  • ...: 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: The Criterion to evaluate
  • Format: (optional) Printf-like format string
  • ...: 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: The file in which the assertion has been called.
  • Line: The line number at which the assertion has been called.
  • FailFunc: The function to call on a failed assertion.
  • Criterion: The Criterion to evaluate.
  • Format: (optional) Printf-like format string.
  • ...: 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: 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
  • ...: 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
  • ...: 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
  • ...: 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
  • Tag (optional): The type tag of the parameters
  • Actual: the actual value
  • Expected: 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
  • Tag (optional): The type tag of the parameters
  • Actual: the actual value
  • Unexpected: the unexpected value

lt(Tag, Actual, Reference)

Evaluates to Actual < Reference.

Parameters
  • Tag (optional): The type tag of the parameters
  • Actual: the actual value
  • Reference: the reference value

le(Tag, Actual, Reference)

Evaluates to Actual <= Reference.

Parameters
  • Tag (optional): The type tag of the parameters
  • Actual: the actual value
  • Reference: the reference value

gt(Tag, Actual, Reference)

Evaluates to Actual > Reference.

Parameters
  • Tag (optional): The type tag of the parameters
  • Actual: the actual value
  • Reference: the reference value

ge(Tag, Actual, Reference)

Evaluates to Actual >= Reference.

Parameters
  • Tag (optional): The type tag of the parameters
  • Actual: the actual value
  • Reference: the reference value

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
  • Tag (optional): The type tag of the parameters
  • Actual: the actual value
  • Expected: the reference value
  • Ulp: 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
  • Tag (optional): The type tag of the parameters
  • Actual: the actual value
  • Expected: the reference value
  • Ulp: 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
  • Tag (optional): The type tag of the parameters
  • Actual: the actual value
  • Expected: the reference value
  • Epsilon: 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
  • Tag (optional): The type tag of the parameters
  • Actual: the actual value
  • Expected: the reference value
  • Epsilon: 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 int8_t
i16 int16_t
i32 int32_t
i64 int64_t
u8 uint8_t
u16 uint16_t
u32 uint32_t
u64 uint64_t
sz size_t
ptr void *
iptr intptr_t
uptr uintptr_t
chr char
int int
uint unsigned int
long long
ulong unsigned long
llong long long
ullong unsigned long long
flt float
dbl double
ldbl long double
cx_flt complex float
cx_dbl complex double
cx_ldbl complex long double
mem struct cr_mem
str const char *
wcs const wchar_t *
tcs const TCHAR *
type(UserType) 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, he 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.