From 5951e636cfb928121396723cf52cf68007199e64 Mon Sep 17 00:00:00 2001 From: Snaipe Date: Mon, 23 Mar 2015 14:46:14 +0100 Subject: [PATCH] Updated documentation and readme --- README.md | 1 + doc/env.rst | 56 ++++++++++++++++++++++++++++++++++++++++++--------- doc/intro.rst | 4 ++++ doc/setup.rst | 3 ++- 4 files changed, 53 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index c665ff3..6def28b 100644 --- a/README.md +++ b/README.md @@ -24,6 +24,7 @@ Criterion follows the KISS principle, while keeping the control the user would have with other frameworks: * [x] Tests are automatically registered when declared. +* [x] Implements a xUnit framework structure. * [x] A default entry point is provided, no need to declare a main unless you want to do special handling. * [x] Test are isolated in their own process, crashes and signals can be diff --git a/doc/env.rst b/doc/env.rst index 7946a20..c0fc38b 100644 --- a/doc/env.rst +++ b/doc/env.rst @@ -7,22 +7,58 @@ and environment variables to alter their runtime behaviour. Command line arguments ---------------------- -* `-h or --help`: Show a help message with the available switches -* `--no-early-exit`: The test workers shall not prematurely exit when done and +* ``-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. +* ``--pattern [PATTERN]``: Run tests whose string identifier matches + the given shell wildcard pattern (see dedicated section below). +* ``--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`. -* `--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, + This is useful when tracking memory leaks with ``valgrind --tool=memcheck``. +* ``--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 +---------------------- + +Patterns in criterion are matched against a test's string identifier with +``fnmatch``. + +Special characters used in shell-style wildcard patterns are: + +=========== =================================== +Pattern Meaning +=========== =================================== +``*`` matches everything +----------- ----------------------------------- +``?`` matches any character +----------- ----------------------------------- +``[seq]`` matches any character in *seq* +----------- ----------------------------------- +``[!seq]`` matches any character not in *seq* +=========== =================================== + +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_VERBOSITY_LEVEL`: Same as `--verbose`. Sets the verbosity level +* ``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_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. diff --git a/doc/intro.rst b/doc/intro.rst index e26f031..3341d0f 100644 --- a/doc/intro.rst +++ b/doc/intro.rst @@ -26,3 +26,7 @@ Features * Test are isolated in their own process, crashes and signals can be reported and tested. * Progress and statistics can be followed in real time with report hooks. +* TAP output format can be enabled with an option. +* Runs on Linux, FreeBSD, Mac OS X, and Windows (compiles only with Cygwin + for the moment). +* xUnit framework structure diff --git a/doc/setup.rst b/doc/setup.rst index aa26708..0182ec0 100644 --- a/doc/setup.rst +++ b/doc/setup.rst @@ -8,7 +8,8 @@ Currently, this library only works under \*nix systems. To compile the static library and its dependencies, GCC 4.9+ is needed. -To use the static library, GCC or Clang are needed. +To use the static library, any GNU-C compatible compiler will suffice +(GCC, Clang/LLVM, ICC, MinGW-GCC, ...). Installation ------------