Contents
Specifying which tests to run
Choosing a reporter to use
Breaking into the debugger
Showing results for successful tests
Aborting after a certain number of failures
Listing available tests, tags or reporters
Sending output to a file
Naming a test run
Eliding assertions expected to throw
Make whitespace visible
Warnings
Reporting timings
Load test names to run from a file
Just test names
Specify the order test cases are run
Specify a seed for the Random Number Generator
Identify framework and version according to the libIdentify standard
Wait for key before continuing
Specify multiples of clock resolution to run benchmarks for
Usage
Specify the section to run
Filenames as tags
Override output colouring
Catch works quite nicely without any command line options at all - but for those times when you want greater control the following options are available. Click one of the followings links to take you straight to that option - or scroll on to browse the available options.
<test-spec> ...
-h, -?, --help
-l, --list-tests
-t, --list-tags
-s, --success
-b, --break
-e, --nothrow
-i, --invisibles
-o, --out
-r, --reporter
-n, --name
-a, --abort
-x, --abortx
-w, --warn
-d, --durations
-f, --input-file
-c, --section
-#, --filenames-as-tags
--list-test-names-only
--list-reporters
--order
--rng-seed
--libidentify
--wait-for-keypress
--benchmark-resolution-multiple
--use-colour
Test cases, wildcarded test cases, tags and tag expressions are all passed directly as arguments. Tags are distinguished by being enclosed in square brackets.
If no test specs are supplied then all test cases, except “hidden” tests, are run. A test is hidden by giving it any tag starting with (or just) a period (.) - or, in the deprecated case, tagged [hide] or given name starting with './'. To specify hidden tests from the command line [.] or [hide] can be used regardless of how they were declared.
Specs must be enclosed in quotes if they contain spaces. If they do not contain spaces the quotes are optional.
Wildcards consist of the * character at the beginning and/or end of test case names and can substitute for any number of any characters (including none).
Test specs are case insensitive.
If a spec is prefixed with exclude: or the ~ character then the pattern matches an exclusion. This means that tests matching the pattern are excluded from the set - even if a prior inclusion spec included them. Subsequent inclusion specs will take precedence, however. Inclusions and exclusions are evaluated in left-to-right order.
Test case examples:
Names within square brackets are interpreted as tags. A series of tags form an AND expression whereas a comma-separated sequence forms an OR expression. e.g.:
This matches all tests tagged [one] and [two], as well as all tests tagged [three]
Test names containing special characters, such as , or [ can specify them on the command line using \. \ also escapes itself.
A reporter is an object that formats and structures the output of running tests, and potentially summarises the results. By default a console reporter is used that writes, IDE friendly, textual output. Catch comes bundled with some alternative reporters, but more can be added in client code.
The bundled reporters are:
The JUnit reporter is an xml format that follows the structure of the JUnit XML Report ANT task, as consumed by a number of third-party tools, including Continuous Integration servers such as Hudson. If not otherwise needed, the standard XML reporter is preferred as this is a streaming reporter, whereas the Junit reporter needs to hold all its results until the end so it can write the overall results into attributes of the root node.
Under most debuggers Catch2 is capable of automatically breaking on a test failure. This allows the user to see the current state of the test during failure.
Usually you only want to see reporting for failed tests. Sometimes it‘s useful to see all the output (especially when you don’t trust that that test you just added worked first time!). To see successful, as well as failing, test results just pass this option. Note that each reporter may treat this option differently. The Junit reporter, for example, logs all results regardless.
If a REQUIRE assertion fails the test case aborts, but subsequent test cases are still run. If a CHECK assertion fails even the current test case is not aborted.
Sometimes this results in a flood of failure messages and you'd rather just see the first few. Specifying -a or --abort on its own will abort the whole test run on the first failed assertion of any kind. Use -x or --abortx followed by a number to abort after that number of assertion failures.
-l or --list-tests will list all registered tests, along with any tags. If one or more test-specs have been supplied too then only the matching tests will be listed.
-t or --list-tags lists all available tags, along with the number of test cases they match. Again, supplying test specs limits the tags that match.
--list-reporters lists the available reporters.
Use this option to send all output to a file. By default output is sent to stdout (note that uses of stdout and stderr from within test cases are redirected and included in the report - so even stderr will effectively end up on stdout).
If a name is supplied it will be used by the reporter to provide an overall name for the test run. This can be useful if you are sending to a file, for example, and need to distinguish different test runs - either from different Catch executables or runs of the same executable with different options. If not supplied the name is defaulted to the name of the executable.
Skips all assertions that test that an exception is thrown, e.g. REQUIRE_THROWS.
These can be a nuisance in certain debugging environments that may break when exceptions are thrown (while this is usually optional for handled exceptions, it can be useful to have enabled if you are trying to track down something unexpected).
Sometimes exceptions are expected outside of one of the assertions that tests for them (perhaps thrown and caught within the code-under-test). The whole test case can be skipped when using -e by marking it with the [!throws] tag.
When running with this option any throw checking assertions are skipped so as not to contribute additional noise. Be careful if this affects the behaviour of subsequent tests.
If a string comparison fails due to differences in whitespace - especially leading or trailing whitespace - it can be hard to see what's going on. This option transforms tabs and newline characters into \t and \n respectively when printing.
Enables reporting of suspicious test states. There are currently two available warnings
NoAssertions // Fail test case / leaf section if no assertions
// (e.g. `REQUIRE`) is encountered.
NoTests // Return non-zero exit code when no test cases were run
// Also calls reporter's noMatchingTestCases method
When set to yes Catch will report the duration of each test case, in milliseconds. Note that it does this regardless of whether a test case passes or fails. Note, also, the certain reporters (e.g. Junit) always report test case durations regardless of this option being set or not.
Provide the name of a file that contains a list of test case names - one per line. Blank lines are skipped and anything after the comment character, #, is ignored.
A useful way to generate an initial instance of this file is to use the list-test-names-only option. This can then be manually curated to specify a specific subset of tests - or in a specific order.
This option lists all available tests in a non-indented form, one on each line. This makes it ideal for saving to a file and feeding back into the -f or --input-file option.
Test cases are ordered one of three ways:
Declaration order. The order the tests were originally declared in. Note that ordering between files is not guaranteed and is implementation dependent.
Lexicographically sorted. Tests are sorted, alpha-numerically, by name.
Randomly sorted. Test names are sorted using std::random_shuffle(). By default the random number generator is seeded with 0 - and so the order is repeatable. To control the random seed see rng-seed.
Sets a seed for the random number generator using std::srand(). If a number is provided this is used directly as the seed so the random pattern is repeatable. Alternatively if the keyword time is provided then the result of calling std::time(0) is used and so the pattern becomes unpredictable.
In either case the actual value for the seed is printed as part of Catch's output so if an issue is discovered that is sensitive to test ordering the ordering can be reproduced - even if it was originally seeded from std::time(0).
See The LibIdentify repo for more information and examples.
Will cause the executable to print a message and wait until the return/ enter key is pressed before continuing - either before running any tests, after running all tests - or both, depending on the argument.
When running benchmarks the clock resolution is estimated. Benchmarks are then run for exponentially increasing numbers of iterations until some multiple of the estimated resolution is exceed. By default that multiple is 100, but it can be overridden here.
Prints the command line arguments to stdout
To limit execution to a specific section within a test case, use this option one or more times. To narrow to sub-sections use multiple instances, where each subsequent instance specifies a deeper nesting level.
E.g. if you have:
Then you can run sb with:
Or run just sd with:
To run all of sa, including sb and sc use:
There are some limitations of this feature to be aware of:
When this option is used then every test is given an additional tag which is formed of the unqualified filename it is found in, with any extension stripped, prefixed with the # character.
So, for example, tests within the file ~\Dev\MyProject\Ferrets.cpp would be tagged [#Ferrets].
Catch colours output for terminals, but omits colouring when it detects that output is being sent to a pipe. This is done to avoid interfering with automated processing of output.
--use-colour yes forces coloured output, --use-colour no disables coloured output. The default behaviour is --use-colour auto.