diff --git a/doc/env.rst b/doc/env.rst index c0fc38b..1db5788 100644 --- a/doc/env.rst +++ b/doc/env.rst @@ -14,7 +14,7 @@ Command line arguments * ``-f or --fail-fast``: Exit after the first test failure. * ``--ascii``: Don't use fancy unicode symbols or colors in the output. * ``--pattern [PATTERN]``: Run tests whose string identifier matches - the given shell wildcard pattern (see dedicated section below). + the given shell wildcard pattern (see dedicated section below). (\*nix only) * ``--no-early-exit``: The test workers shall not prematurely exit when done and will properly return from the main, cleaning up their process space. This is useful when tracking memory leaks with ``valgrind --tool=memcheck``. @@ -27,7 +27,8 @@ Shell Wildcard Pattern ---------------------- Patterns in criterion are matched against a test's string identifier with -``fnmatch``. +``fnmatch``. This feature is only available on \*nix systems where ``fnmatch`` +is provided. Special characters used in shell-style wildcard patterns are: @@ -61,4 +62,4 @@ Environment variables are alternatives to command line switches when set to 1. * ``CRITERION_VERBOSITY_LEVEL``: Same as ``--verbose``. Sets the verbosity level to its value. * ``CRITERION_TEST_PATTERN``: Same as ``--pattern``. Sets the test pattern - to its value. + to its value. (\*nix only) diff --git a/doc/faq.rst b/doc/faq.rst index 82af2fc..aa15aa5 100644 --- a/doc/faq.rst +++ b/doc/faq.rst @@ -14,4 +14,5 @@ There are plenty of ways to fix that behaviour: **Q. I'm having an issue with the library, what can I do ?** A. Open a new issue on the `github issue tracker `_, -and describe the problem you are experiencing. +and describe the problem you are experiencing, along with the platform you are +running criterion on. diff --git a/doc/hooks.rst b/doc/hooks.rst index 0596a9e..a9b8bd6 100644 --- a/doc/hooks.rst +++ b/doc/hooks.rst @@ -17,6 +17,10 @@ A report hook can be declared using the ``ReportHook`` macro: 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 -------------- @@ -49,3 +53,18 @@ Valid types for each phases are: * ``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, these are valid report hook declarations for the ``PRE_TEST`` phase: + +.. code-block:: c + + #include + #include + + ReportHook(PRE_TEST)() { + // not using the parameter + } + + ReportHook(PRE_TEST)(struct criterion_test *test) { + // using the parameter + } diff --git a/doc/internal.rst b/doc/internal.rst index df3518d..8c94237 100644 --- a/doc/internal.rst +++ b/doc/internal.rst @@ -39,3 +39,16 @@ Starting the test runner The test runner can be called with ``criterion_run_all_tests``. The function returns 0 if one test or more failed, 1 otherwise. + +Implementing your own output provider +------------------------------------- + +In case you are not satisfied by the default output provider, you can implement +yours. To do so, simply set the ``output_provider`` option to your custom +output provider. + +Each function contained in the structure is called during one of the standard +phase of the criterion runner. + +For more insight on how to implement this, see other existing output providers +in ``src/log/``. diff --git a/doc/starter.rst b/doc/starter.rst index b974bdd..cd8890b 100644 --- a/doc/starter.rst +++ b/doc/starter.rst @@ -68,8 +68,16 @@ On top of those, more assertions are available for common operations: * ``{assert,expect}_arrays_eq(Actual, Expected, Size, [Message])`` * ``{assert,expect}_arrays_neq(Actual, Unexpected, Size, [Message])`` +Please note that ``arrays_(n)eq`` assertions should not be used for padded structures. + +Configuring tests +----------------- + +Tests may receive optional configuration parameters to alter their behaviour +or provide additional metadata. + Fixtures --------- +~~~~~~~~ Tests that need some setup and teardown can register functions that will run before and after the test function: @@ -91,8 +99,13 @@ run before and after the test function: // test contents } +If a setup crashes, you will get a warning message, and the test will be aborted +and marked as a failure. +Is a teardown crashes, you will get a warning message, and the test will keep +its result. + Testing signals ---------------- +~~~~~~~~~~~~~~~ If a test receives a signal, it will by default be marked as a failure. You can, however, expect a test to only pass if a special kind of signal @@ -115,3 +128,47 @@ is received: int *ptr = NULL; *ptr = 42; } + +This feature will of course not work on Windows. + +Configuration reference +~~~~~~~~~~~~~~~~~~~~~~~ + +Here is an exhaustive list of all possible configuration parameters you can +pass: + +============= =============== ============================================================== +Parameter Type Description +============= =============== ============================================================== +.description const char * Adds a description. Cannot be ``NULL``. +------------- --------------- -------------------------------------------------------------- +.init void (*)(void) Adds a setup function the be executed before the test. +------------- --------------- -------------------------------------------------------------- +.fini void (*)(void) Adds a teardown function the be executed after the test. +------------- --------------- -------------------------------------------------------------- +.disabled bool Disables the test. +------------- --------------- -------------------------------------------------------------- +.signal int Expect the test to raise the specified signal. +============= =============== ============================================================== + +Setting up suite-wise configuration +----------------------------------- + +Tests under the same suite can have a suite-wise configuration -- this is done +using the ``TestSuite`` macro: + +.. code-block:: c + + #include + + TestSuite(suite_name, [params...]); + + Test(suite_name, test_1) { + } + + Test(suite_name, test_2) { + } + +Configuration parameters are the same as above, but applied to the suite itself. + +Suite fixtures are run *along with* test fixtures.