From 8ac4911f19573683d3ae731d4baa09d549830125 Mon Sep 17 00:00:00 2001 From: Snaipe Date: Tue, 8 Sep 2015 23:49:35 +0200 Subject: [PATCH] Added assertion reference in documentation --- doc/assert.rst | 96 +++++++++++++++++++++++++++++++++++++++++++++++++ doc/index.rst | 1 + doc/starter.rst | 41 ++------------------- 3 files changed, 99 insertions(+), 39 deletions(-) create mode 100644 doc/assert.rst diff --git a/doc/assert.rst b/doc/assert.rst new file mode 100644 index 0000000..720bcaf --- /dev/null +++ b/doc/assert.rst @@ -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 +=========================================================================== =========================================================================== =========================================== + diff --git a/doc/index.rst b/doc/index.rst index e9d55c5..56fbdf4 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -7,6 +7,7 @@ Criterion intro setup starter + assert hooks env theories diff --git a/doc/starter.rst b/doc/starter.rst index 6a9408e..4e32912 100644 --- a/doc/starter.rst +++ b/doc/starter.rst @@ -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 -----------------