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.
-
cr_fail(Format, ...)¶
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
-
not(Criterion)¶
- 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
, andldbl
, 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
, andldbl
, 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 thatt
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
andExpected
are almost equal, by being withinUlp
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
andldbl
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
andExpected
are different, by not being withinUlp
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
andldbl
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
andExpected
are almost equal, by being within an absoluteEpsilon
from each other (In other words, iffabs(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
andldbl
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
andExpected
are different, by not being within an absoluteEpsilon
from each other (In other words, iffabs(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
andldbl
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
-
eq(Tag, Actual, Expected)¶