65 lines
2.2 KiB
ReStructuredText
65 lines
2.2 KiB
ReStructuredText
Report Hooks
|
|
============
|
|
|
|
Report hooks are functions that are called at key moments during the testing
|
|
process. These are useful to report statistics gathered during the execution.
|
|
|
|
A report hook can be declared using the ``ReportHook`` macro:
|
|
|
|
.. code-block:: c
|
|
|
|
#include <criterion/criterion.h>
|
|
#include <criterion/hooks.h>
|
|
|
|
ReportHook(Phase)() {
|
|
}
|
|
|
|
The macro takes a Phase parameter that indicates the phase at which the function
|
|
shall be run. Valid phases are described below.
|
|
|
|
**Note**: there are no guarantees regarding the order of execution of report hooks
|
|
on the same phase. In other words, all report hooks of a specific phase could
|
|
be executed in any order.
|
|
|
|
Testing Phases
|
|
--------------
|
|
|
|
The flow of the test process goes as follows:
|
|
|
|
1. ``PRE_ALL``: occurs before running the tests.
|
|
#. ``PRE_SUITE``: occurs before a suite is initialized.
|
|
#. ``PRE_INIT``: occurs before a test is initialized.
|
|
#. ``PRE_TEST``: occurs after the test initialization, but before the test is run.
|
|
#. ``ASSERT``: occurs when an assertion is hit
|
|
#. ``THEORY_FAIL``: occurs when a theory iteration fails.
|
|
#. ``TEST_CRASH``: occurs when a test crashes unexpectedly.
|
|
#. ``POST_TEST``: occurs after a test ends, but before the test finalization.
|
|
#. ``POST_FINI``: occurs after a test finalization.
|
|
#. ``POST_SUITE``: occurs before a suite is finalized.
|
|
#. ``POST_ALL``: occurs after all the tests are done.
|
|
|
|
Hook Parameters
|
|
---------------
|
|
|
|
A report hook takes exactly one parameter.
|
|
Valid types for each phases are:
|
|
|
|
* ``struct criterion_test_set *`` for ``PRE_ALL``.
|
|
* ``struct criterion_suite_set *`` for ``PRE_SUITE``.
|
|
* ``struct criterion_test *`` for ``PRE_INIT`` and ``PRE_TEST``.
|
|
* ``struct criterion_assert_stats *`` for ``ASSERT``.
|
|
* ``struct criterion_theory_stats *`` for ``THEORY_FAIL``.
|
|
* ``struct criterion_test_stats *`` for ``POST_TEST``, ``POST_FINI``, and ``TEST_CRASH``.
|
|
* ``struct criterion_suite_stats *`` for ``POST_SUITE``.
|
|
* ``struct criterion_global_stats *`` for ``POST_ALL``.
|
|
|
|
For instance, this is a valid report hook declaration for the ``PRE_TEST`` phase:
|
|
|
|
.. code-block:: c
|
|
|
|
#include <criterion/criterion.h>
|
|
#include <criterion/hooks.h>
|
|
|
|
ReportHook(PRE_TEST)(struct criterion_test *test) {
|
|
// using the parameter
|
|
}
|