doctest works quite nicely without any command line options at all - but for more control a bunch are available.
Query flags - after the result is printed the program quits without executing any test cases (and if the framework is integrated into a client codebase which supplies it's own main()
entry point - the program should check the result of doctest::Context::shouldExit()
after calling doctest::Context::run()
and should exit - this is left up to the user).
Int/String options - they require a value after the =
sign - without spaces! For example: --order-by=rand
.
Bool options - they expect 1
/yes
/on
/true
or 0
/no
/off
/false
after the =
sign - but they can also be used like flags and the =value
part can be skipped - then true
is assumed.
Filters use wildcards for matching values - where *
means "match any sequence" and ?
means "match any one character".
To pass a pattern with an interval use ""
like this: --test-case="*no sound*,vaguely named test number ?"
.
All the options can also be set with code (defaults/overrides) if the user supplies the main()
function.
Query Flags | Description |
---|---|
-? --help -h |
Prints a help message listing all these flags/options |
-v --version |
Prints the version of the doctest framework |
-c --count |
Prints the number of test cases matching the current filters (see below) |
-ltc --list-test-cases |
Lists all test cases by name which match the current filters (see below) |
-lts --list-test-suites |
Lists all test suites by name which have at least one test case matching the current filters (see below) |
Int/String Options | |
-tc --test-case=<filters> |
Filters test cases based on their name. By default all test cases match but if a value is given to this filter like --test-case=*math*,*sound* then only test cases who match atleast one of the patterns in the comma-separated list with wildcards will get executed/counted/listed |
-tce --test-case-exclude=<filters> |
Same as the -test-case=<filters> option but if any of the patterns in the comma-separated list of values matches - then the test case is skipped |
-sf --source-file=<filters> |
Same as --test-case=<filters> but filters based on the file in which test cases are written |
-sfe --source-file-exclude=<filters> |
Same as --test-case-exclude=<filters> but filters based on the file in which test cases are written |
-ts --test-suite=<filters> |
Same as --test-case=<filters> but filters based on the test suite in which test cases are in |
-tse --test-suite-exclude=<filters> |
Same as --test-case-exclude=<filters> but filters based on the test suite in which test cases are in |
-ob --order-by=<string> |
Test cases will be sorted before being executed either by the file in which they are / the test suite they are in / their name / random. The possible values of <string> are file /suite /name /rand . The default is file |
-rs --rand-seed=<int> |
The seed for random ordering |
-f --first=<int> |
The first test case to execute which passes the current filters - for range-based execution - see the example (the run.py script) |
-l --last=<int> |
The last test case to execute which passes the current filters - for range-based execution - see the example (the run.py script) |
-aa --abort-after=<int> |
The testing framework will stop executing test cases/assertions after this many failed assertions. The default is 0 which means don't stop at all |
Bool Options | |
-s --success=<bool> |
To include successful assertions in the output |
-cs --case-sensitive=<bool> |
Filters being treated as case sensitive |
-e --exit=<bool> |
Exits after the tests finish - this is meaningful only when the client has provided the main() entry point - the program should check doctest::Context::shouldExit() after calling doctest::Context::run() and should exit - this is left up to the user. The idea is to be able to execute just the tests in a client program and to not continue with it's execution |
-nt --no-throw=<bool> |
Skips exceptions-related assertion checks |
-ne --no-exitcode=<bool> |
Always returns a successful exit code - even if a test case has failed |
-nr --no-run=<bool> |
Skips all runtime doctest operations (except the test registering which happens before the program enters main() ). This is useful if the testing framework is integrated into a client codebase which has provided the main() entry point and the user wants to skip running the tests and just use the program |
-nv --no-version=<bool> |
Omits the framework version in the output |
-nc --no-colors=<bool> |
Disables colors in the output |
-fc --force-colors=<bool> |
Forces the use of colors even when a tty cannot be detected |
-nb --no-breaks=<bool> |
Disables breakpoints in debuggers when an assertion fails |
-npf --no-path-filenames=<bool> |
Paths are removed from the output when a filename is printed - useful if you want the same output from the testing framework on different environments |
All the flags/options also come with a prefixed version (with --dt-
at the front) - for example --version
can be used also with --dt-version
or --dt-v
.
All the unprefixed versions listed here can be disabled with the DOCTEST_CONFIG_NO_UNPREFIXED_OPTIONS
define.
This is done for easy interoperability with client command line option handling when the testing framework is integrated within a client codebase - all doctest related flags/options can be prefixed so there are no clashes and so that the user can exclude everything starting with --dt-
from their option parsing.
If there isn't an option to exclude everything starting with --dt-
then the removing_doctest_options example might help.