82 lines
4.1 KiB
ReStructuredText
82 lines
4.1 KiB
ReStructuredText
Environment and CLI
|
|
===================
|
|
|
|
Tests built with Criterion expose by default various command line switchs
|
|
and environment variables to alter their runtime behaviour.
|
|
|
|
Command line arguments
|
|
----------------------
|
|
|
|
* ``-h or --help``: Show a help message with the available switches.
|
|
* ``-v or --version``: Prints the version of criterion that has been
|
|
linked against.
|
|
* ``-l or --list``: Print all the tests in a list.
|
|
* ``-f or --fail-fast``: Exit after the first test failure.
|
|
* ``--ascii``: Don't use fancy unicode symbols or colors in the output.
|
|
* ``-jN or --jobs N``: Use ``N`` parallel jobs to run the tests. ``0`` picks
|
|
a number of jobs ideal for your hardware configuration.
|
|
* ``--pattern [PATTERN]``: Run tests whose string identifier matches
|
|
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``.
|
|
* ``-S or --short-filename``: The filenames are displayed in their short form.
|
|
* ``--always-succeed``: The process shall exit with a status of ``0``.
|
|
* ``--tap``: Enables the TAP (Test Anything Protocol) output format.
|
|
* ``--verbose[=level]``: Makes the output verbose. When provided with an integer,
|
|
sets the verbosity level to that integer.
|
|
|
|
Shell Wildcard Pattern
|
|
----------------------
|
|
|
|
Extglob patterns in criterion are matched against a test's string identifier.
|
|
This feature is only available on \*nix systems where ``PCRE`` is provided.
|
|
|
|
In the table below, a ``pattern-list`` is a list of patterns separated by ``|``.
|
|
Any extglob pattern can be constructed by combining any of the following
|
|
sub-patterns:
|
|
|
|
==================== ======================================================
|
|
Pattern Meaning
|
|
==================== ======================================================
|
|
``*`` matches everything
|
|
-------------------- ------------------------------------------------------
|
|
``?`` matches any character
|
|
-------------------- ------------------------------------------------------
|
|
``[seq]`` matches any character in *seq*
|
|
-------------------- ------------------------------------------------------
|
|
``[!seq]`` matches any character not in *seq*
|
|
-------------------- ------------------------------------------------------
|
|
``?(pattern-list)`` Matches zero or one occurrence of the given patterns
|
|
-------------------- ------------------------------------------------------
|
|
``*(pattern-list)`` Matches zero or more occurrences of the given patterns
|
|
-------------------- ------------------------------------------------------
|
|
``+(pattern-list)`` Matches one or more occurrences of the given patterns
|
|
-------------------- ------------------------------------------------------
|
|
``@(pattern-list)`` Matches one of the given patterns
|
|
-------------------- ------------------------------------------------------
|
|
``!(pattern-list)`` Matches anything except one of the given patterns
|
|
==================== ======================================================
|
|
|
|
A test string identifier is of the form ``suite-name/test-name``, so a pattern
|
|
of ``simple/*`` matches every tests in the ``simple`` suite, ``*/passing``
|
|
matches all tests named ``passing`` regardless of the suite, and ``*`` matches
|
|
every possible test.
|
|
|
|
Environment Variables
|
|
---------------------
|
|
|
|
Environment variables are alternatives to command line switches when set to 1.
|
|
|
|
* ``CRITERION_ALWAYS_SUCCEED``: Same as ``--always-succeed``.
|
|
* ``CRITERION_NO_EARLY_EXIT``: Same as ``--no-early-exit``.
|
|
* ``CRITERION_ENABLE_TAP``: Same as ``--tap``.
|
|
* ``CRITERION_FAIL_FAST``: Same as ``--fail-fast``.
|
|
* ``CRITERION_USE_ASCII``: Same as ``--ascii``.
|
|
* ``CRITERION_JOBS``: Same as ``jobs``. Sets the number of jobs to
|
|
its value.
|
|
* ``CRITERION_SHORT_FILENAME``: Same as ``--short-filename``.
|
|
* ``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. (\*nix only)
|