Added assertion reference in documentation
This commit is contained in:
Snaipe
parent
565ed9a672
commit
8ac4911f19
3 changed files with 99 additions and 39 deletions
96
doc/assert.rst
Normal file
96
doc/assert.rst
Normal file
|
|
@ -0,0 +1,96 @@
|
|||
.. _assertions-ref:
|
||||
|
||||
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.
|
||||
|
||||
Common Assertions
|
||||
-----------------
|
||||
|
||||
======================================================================= =========================================================================== ===========================================
|
||||
Macro Passes if and only if Notes
|
||||
======================================================================= =========================================================================== ===========================================
|
||||
cr_assert(Condition, [Message, [Args...]]) ``Condition`` is true.
|
||||
----------------------------------------------------------------------- --------------------------------------------------------------------------- -------------------------------------------
|
||||
cr_assert_not(Condition, [Message, [Args...]]) ``Condition`` is false.
|
||||
----------------------------------------------------------------------- --------------------------------------------------------------------------- -------------------------------------------
|
||||
cr_assert_null(Value, [Message, [Args...]]) ``Value`` is ``NULL``.
|
||||
----------------------------------------------------------------------- --------------------------------------------------------------------------- -------------------------------------------
|
||||
cr_assert_not_null(Value, [Message, [Args...]]) ``Value`` is not ``NULL``.
|
||||
----------------------------------------------------------------------- --------------------------------------------------------------------------- -------------------------------------------
|
||||
cr_assert_eq(Actual, Expected, [Message, [Args...]]) ``Actual`` is equal to ``Expected``. Compatible with C++ operator overloading
|
||||
----------------------------------------------------------------------- --------------------------------------------------------------------------- -------------------------------------------
|
||||
cr_assert_neq(Actual, Unexpected, [Message, [Args...]]) ``Actual`` is not equal to ``Unexpected``. Compatible with C++ operator overloading
|
||||
----------------------------------------------------------------------- --------------------------------------------------------------------------- -------------------------------------------
|
||||
cr_assert_lt(Actual, Reference, [Message, [Args...]]) ``Actual`` is less than ``Reference``. Compatible with C++ operator overloading
|
||||
----------------------------------------------------------------------- --------------------------------------------------------------------------- -------------------------------------------
|
||||
cr_assert_leq(Actual, Reference, [Message, [Args...]]) ``Actual`` is less or equal to ``Reference``. Compatible with C++ operator overloading
|
||||
----------------------------------------------------------------------- --------------------------------------------------------------------------- -------------------------------------------
|
||||
cr_assert_gt(Actual, Reference, [Message, [Args...]]) ``Actual`` is greater than ``Reference``. Compatible with C++ operator overloading
|
||||
----------------------------------------------------------------------- --------------------------------------------------------------------------- -------------------------------------------
|
||||
cr_assert_geq(Actual, Reference, [Message, [Args...]]) ``Actual`` is greater or equal to ``Reference``. Compatible with C++ operator overloading
|
||||
----------------------------------------------------------------------- --------------------------------------------------------------------------- -------------------------------------------
|
||||
cr_assert_float_eq(Actual, Expected, Epsilon, [Message, [Args...]]) ``Actual`` is equal to ``Expected`` with a tolerance of ``Epsilon``. Use this to test equality between floats
|
||||
----------------------------------------------------------------------- --------------------------------------------------------------------------- -------------------------------------------
|
||||
cr_assert_float_neq(Actual, Unexpected, Epsilon, [Message, [Args...]]) ``Actual`` is not equal to ``Unexpected`` with a tolerance of ``Epsilon``. Use this to test inequality between floats
|
||||
======================================================================= =========================================================================== ===========================================
|
||||
|
||||
String Assertions
|
||||
-----------------
|
||||
|
||||
Note: these macros are meant to deal with *native* strings, i.e. char arrays.
|
||||
Most of them won't work on ``std::string`` in C++, with some exceptions -- for
|
||||
``std::string``, you should use regular comparison assersions, as listed above.
|
||||
|
||||
=========================================================== =================================================================== ===========================================
|
||||
Macro Passes if and only if Notes
|
||||
=========================================================== =================================================================== ===========================================
|
||||
cr_assert_str_empty(Value, [Message, [Args...]]) ``Value`` is an empty string. Also works on std::string
|
||||
----------------------------------------------------------- ------------------------------------------------------------------- -------------------------------------------
|
||||
cr_assert_str_not_empty(Value, [Message, [Args...]]) ``Value`` is not an empty string. Also works on std::string
|
||||
----------------------------------------------------------- ------------------------------------------------------------------- -------------------------------------------
|
||||
cr_assert_str_eq(Actual, Expected, [Message, [Args...]]) ``Actual`` is lexicographically equal to ``Expected``.
|
||||
----------------------------------------------------------- ------------------------------------------------------------------- -------------------------------------------
|
||||
cr_assert_str_neq(Actual, Unexpected, [Message, [Args...]]) ``Actual`` is not lexicographically equal to ``Unexpected``.
|
||||
----------------------------------------------------------- ------------------------------------------------------------------- -------------------------------------------
|
||||
cr_assert_str_lt(Actual, Reference, [Message, [Args...]]) ``Actual`` is lexicographically less than ``Reference``.
|
||||
----------------------------------------------------------- ------------------------------------------------------------------- -------------------------------------------
|
||||
cr_assert_str_leq(Actual, Reference, [Message, [Args...]]) ``Actual`` is lexicographically less or equal to ``Reference``.
|
||||
----------------------------------------------------------- ------------------------------------------------------------------- -------------------------------------------
|
||||
cr_assert_str_gt(Actual, Reference, [Message, [Args...]]) ``Actual`` is lexicographically greater than ``Reference``.
|
||||
----------------------------------------------------------- ------------------------------------------------------------------- -------------------------------------------
|
||||
cr_assert_str_geq(Actual, Reference, [Message, [Args...]]) ``Actual`` is lexicographically greater or equal to ``Reference``.
|
||||
=========================================================== =================================================================== ===========================================
|
||||
|
||||
Array Assertions
|
||||
-----------------
|
||||
|
||||
=========================================================================== =========================================================================== ===========================================
|
||||
Macro Passes if and only if Notes
|
||||
=========================================================================== =========================================================================== ===========================================
|
||||
cr_assert_arr_eq(Actual, Expected, [Message, [Args...]]) ``Actual`` is byte-to-byte equal to ``Expected``. This should not be used on struct arrays,
|
||||
consider using ``cr_assert_arr_eq_cmp``
|
||||
instead.
|
||||
--------------------------------------------------------------------------- --------------------------------------------------------------------------- -------------------------------------------
|
||||
cr_assert_arr_neq(Actual, Unexpected, [Message, [Args...]]) ``Actual`` is not byte-to-byte equal to ``Unexpected``. This should not be used on struct arrays,
|
||||
consider using ``cr_assert_arr_neq_cmp``
|
||||
instead.
|
||||
--------------------------------------------------------------------------- --------------------------------------------------------------------------- -------------------------------------------
|
||||
cr_assert_arr_eq_cmp(Actual, Expected, Size, Cmp, [Message, [Args...]]) ``Actual`` is comparatively equal to ``Expected`` Only available in C++ and GNU C99
|
||||
--------------------------------------------------------------------------- --------------------------------------------------------------------------- -------------------------------------------
|
||||
cr_assert_arr_neq_cmp(Actual, Unexpected, Size, Cmp, [Message, [Args...]]) ``Actual`` is not comparatively equal to ``Expected`` Only available in C++ and GNU C99
|
||||
--------------------------------------------------------------------------- --------------------------------------------------------------------------- -------------------------------------------
|
||||
cr_assert_arr_lt_cmp(Actual, Reference, Size, Cmp, [Message, [Args...]]) ``Actual`` is comparatively less than ``Reference`` Only available in C++ and GNU C99
|
||||
--------------------------------------------------------------------------- --------------------------------------------------------------------------- -------------------------------------------
|
||||
cr_assert_arr_leq_cmp(Actual, Reference, Size, Cmp, [Message, [Args...]]) ``Actual`` is comparatively less or equal to ``Reference`` Only available in C++ and GNU C99
|
||||
--------------------------------------------------------------------------- --------------------------------------------------------------------------- -------------------------------------------
|
||||
cr_assert_arr_gt_cmp(Actual, Reference, Size, Cmp, [Message, [Args...]]) ``Actual`` is comparatively greater than ``Reference`` Only available in C++ and GNU C99
|
||||
--------------------------------------------------------------------------- --------------------------------------------------------------------------- -------------------------------------------
|
||||
cr_assert_arr_geq_cmp(Actual, Reference, Size, Cmp, [Message, [Args...]]) ``Actual`` is comparatively greater or equal to ``Reference`` Only available in C++ and GNU C99
|
||||
=========================================================================== =========================================================================== ===========================================
|
||||
|
||||
|
|
@ -7,6 +7,7 @@ Criterion
|
|||
intro
|
||||
setup
|
||||
starter
|
||||
assert
|
||||
hooks
|
||||
env
|
||||
theories
|
||||
|
|
|
|||
|
|
@ -48,45 +48,8 @@ parameter, and an optional failure message:
|
|||
cr_assert(strlen("") == 0);
|
||||
}
|
||||
|
||||
On top of those, more assertions are available for common operations:
|
||||
|
||||
* ``cr_assert_null(Ptr, [Message])``: passes if Ptr is NULL.
|
||||
* ``cr_assert_eq(Actual, Expected, [Message])``: passes if Actual == Expected.
|
||||
* ``cr_assert_lt(Actual, Expected, [Message])``: passes if Actual < Expected.
|
||||
* ``cr_assert_leq(Actual, Expected, [Message])``: passes if Actual <= Expected.
|
||||
* ``cr_assert_gt(Actual, Expected, [Message])``: passes if Actual > Expected.
|
||||
* ``cr_assert_geq(Actual, Expected, [Message])``: passes if Actual >= Expected.
|
||||
* ``cr_assert_float_eq(Actual, Expected, Epsilon, [Message])``:
|
||||
passes if Actual == Expected with an error of Epsilon.
|
||||
* ``cr_assert_arrays_eq(Actual, Expected, Size, [Message])``:
|
||||
passes if all elements of Actual (from 0 to Size - 1) are equals to those
|
||||
of Expected.
|
||||
* ``cr_assert_arrays_eq_cmp(Actual, Expected, Size, Cmp, [Message])``:
|
||||
Same as ``arrays_eq`` but equality is defined by the result of the binary
|
||||
Cmp function.
|
||||
|
||||
Equality and lexical comparison assertions are also available for strings:
|
||||
|
||||
* ``cr_assert_strings_eq(Actual, Expected, [Message])``
|
||||
* ``cr_assert_strings_lt(Actual, Expected, [Message])``
|
||||
* ``cr_assert_strings_leq(Actual, Expected, [Message])``
|
||||
* ``cr_assert_strings_gt(Actual, Expected, [Message])``
|
||||
* ``cr_assert_strings_geq(Actual, Expected, [Message])``
|
||||
|
||||
And some assertions have a logical negative counterpart:
|
||||
|
||||
* ``cr_assert_not(Condition, [Message])``
|
||||
* ``cr_assert_not_null(Ptr, [Message])``
|
||||
* ``cr_assert_neq(Actual, Unexpected, [Message])``
|
||||
* ``cr_assert_float_neq(Actual, Unexpected, Epsilon, [Message])``
|
||||
* ``cr_assert_strings_neq(Actual, Unexpected, [Message])``
|
||||
* ``cr_assert_arrays_neq(Actual, Unexpected, Size, [Message])``
|
||||
* ``cr_assert_arrays_neq_cmp(Actual, Unexpected, Size, Cmp, [Message])``
|
||||
|
||||
Of course, every ``assert`` has an ``expect`` counterpart.
|
||||
|
||||
Please note that ``arrays_(n)eq`` assertions should not be used on padded
|
||||
structures -- please use ``arrays_(n)eq_cmp`` instead.
|
||||
On top of those, more assertions are available for common operations. See
|
||||
:ref:`assertions-ref` for a complete list.
|
||||
|
||||
Configuring tests
|
||||
-----------------
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue