Added documentation on logging functions
This commit is contained in:
parent
99b10d443c
commit
4b093d2a3e
2 changed files with 62 additions and 0 deletions
|
@ -9,6 +9,7 @@ Criterion
|
|||
starter
|
||||
assert
|
||||
hooks
|
||||
logging
|
||||
env
|
||||
output
|
||||
parameterized
|
||||
|
|
61
doc/logging.rst
Normal file
61
doc/logging.rst
Normal file
|
@ -0,0 +1,61 @@
|
|||
Logging messages
|
||||
================
|
||||
|
||||
Sometimes, it might be useful to print some output from within a test
|
||||
or fixture -- and while this can be done trivially with a ``printf``,
|
||||
it doesn't integrate well with the current output, nor does it work
|
||||
*at all* when the process is testing a redirected stdout.
|
||||
|
||||
For these cases, Criterion exposes a logging facility:
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
#include <criterion/criterion.h>
|
||||
#include <criterion/logging.h>
|
||||
|
||||
Test(suite_name, test_name) {
|
||||
cr_log_info("This is an informational message. They are not displayed "
|
||||
"by default.");
|
||||
cr_log_warn("This is a warning. They indicate some possible malfunction "
|
||||
"or misconfiguration in the test.");
|
||||
cr_log_error("This is an error. They indicate serious problems and "
|
||||
"are usually shown before the test is aborted.");
|
||||
}
|
||||
|
||||
``cr_log_info``, ``cr_log_warn`` and ``cr_log_error`` are all macros expanding
|
||||
to a call to the ``cr_log`` function. All of them take a mandatory format string,
|
||||
followed by optional parameters; for instance:
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
cr_log_info("%d + %d = %d", 1, 2, 3);
|
||||
|
||||
If using C++, the output stream objects ``info``, ``warn`` and ``error`` are
|
||||
defined within the ``criterion::logging`` namespace, and can be used in
|
||||
conjunction with ``operator<<``:
|
||||
|
||||
.. code-block:: c++
|
||||
|
||||
#include <criterion/criterion.h>
|
||||
#include <criterion/logging.h>
|
||||
|
||||
using criterion::logging::info;
|
||||
using criterion::logging::warn;
|
||||
using criterion::logging::error;
|
||||
|
||||
Test(suite_name, test_name) {
|
||||
info << "This is an informational message. "
|
||||
<< "They are not displayed by default."
|
||||
<< std::flush;
|
||||
warn << "This is a warning. "
|
||||
<< "They indicate some possible malfunction "
|
||||
<< "or misconfiguration in the test."
|
||||
<< std::flush;
|
||||
error << "This is an error. "
|
||||
<< "They indicate serious problems and "
|
||||
<< "are usually shown before the test is aborted."
|
||||
<< std::flush;
|
||||
}
|
||||
|
||||
Note that empty messages are ignored, and newlines in the log message splits
|
||||
the passed string into as many messages are there are lines.
|
Loading…
Add table
Reference in a new issue