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 #include 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 #include ReportHook(PRE_TEST)(struct criterion_test *test) { // using the parameter }