This extension allows you to run your Catch2 and Google Test tests using the Test Explorer for VS Code.
| Property | Description |
|---|---|
catch2TestExplorer.executables |
The location of your test executables (relative to the workspace folder or absolute path) and with a lot of other setting. Details |
catch2TestExplorer.defaultCwd |
The working directory where the test is run (relative to the workspace folder or absolue path), if it isn't provided in "executables". (It resolves variables.) |
catch2TestExplorer.defaultEnv |
Environment variables to be set when running the tests. (It resolves variables.) |
catch2TestExplorer.debugConfigTemplate |
Set the necessary debug configuraitons and the debug button will work. Details |
catch2TestExplorer.debugBreakOnFailure |
Debugger breaks on failure while debugging the test. Catch2: --break; Google Test: --gtest_break_on_failure; |
catch2TestExplorer.defaultNoThrow |
Skips all assertions that test that an exception is thrown, e.g. REQUIRE_THROWS. This is a Catch2 parameter: --nothrow |
catch2TestExplorer.defaultRngSeed |
Shuffles the tests with the given random. Catch2: --rng-seed ( or 'time'); Google Test: --gtest_random_seed=; |
catch2TestExplorer.defaultWatchTimeoutSec |
Test executables are being watched (only inside the workspace directory). In case of one recompiles it will try to preserve the test states. If compilation reaches timeout it will drop the suite. |
catch2TestExplorer.defaultRunningTimeoutSec |
Test executable is running in a process. In case of an inifinite loop, it will run forever, unless this parameter is set. It applies instantly. (0 means infinite) |
catch2TestExplorer.workerMaxNumber |
The variable maximize the number of the parallel test execution. It applies instantly. |
catch2TestExplorer.enableTestListCaching |
(Experimental) In case your executable took too much time to list the tests, one can set this. It will preserve the output of --gtest_list_tests --gtest_output=xml:.... (Beware: Older Google Test doesn't support xml test list format.) (Click here, if you think it is a useful feature!) |
catch2TestExplorer.logpanel |
Creates a new output channel and write the log messages there. For debugging. Enabling it could slow down your vscode. |
testExplorer.errorDecoration |
Show error messages from test failures as decorations in the editor. Details |
testExplorer.gutterDecoration |
Show the state of each test in the editor using Gutter Decorations. Details |
testExplorer.codeLens |
Show a CodeLens above each test or suite for running or debugging the tests. Details |
testExplorer.onStart |
Retire or reset all test states whenever a test run is started. Details |
testExplorer.onReload |
Retire or reset all test states whenever the test tree is reloaded. Details |
testExplorer.sort |
Sort the tests and suites by label or location. If this is not set (or set to null), they will be shown in the order that they were received from the adapter |
Note that this extension is built upon the Test Explorer so it's configuration and commands can be used.
This variable can be
- a string (ex.:
"out/**/*test.exe"), - an array of strings (ex.:
[ "out/debug/*test.exe", ... ]), - an array of objects (ex.:
[ { "pattern": "out/**/*test.exe" }, ... ]) or - an array of strings and objects (ex.:
[ "out/debug/*test.exe", { "pattern": "out/optimized/*test.exe" } ]).
If it is an object it can contains the following properties:
| Property | Description | |
|---|---|---|
name |
The name of the test suite (file). Can contains variables related to pattern. |
(optional) |
pattern |
A relative pattern (to workspace (also it has to be inside the workspace folder)) or an absolute file-path (this case it can be outside of the workspace folder too). \"; ✅"/"; Details). |
(requierd) |
cwd |
The current working directory for the test executable. If it isn't provided and defaultCwd does, then that will be used. Can contains variables related to pattern. |
(optional) |
env |
Environment variables for the test executable. If it isn't provided and defaultEnv does, then that will be used. Can contains variables related to pattern. |
(optional) |
The pattern (or the executables used as string or an array of strings)
can contains search-pattern
if it points somewhere inside of the workspace folder.
Otherwise it only can point to an executable (No search-pattern!) with a relative or absolute path
(ex.: [ "../../p1/out/test.exe", "/home/rick/repo/p1/out/test", "C:/repo/p1/out/test.exe" ]).
Test executables and patterns are being watched (only inside the workspace directory).
In case of one recompiles it will try to preserve the test states.
If compilation reaches timeout it will drop the suite (catch2TestExplorer.defaultWatchTimeoutSec).
Note that there is a mechanism which will filter out every possible executable which:
- on windows: NOT ends with
.exe. - on other platforms: ends with one of the following:
'.c', '.cmake', '.cpp', '.cxx', '.deb', '.dir', '.gz', '.h', '.hpp', '.hxx', '.ko', '.log', '.o', '.php', '.rpm', '.so', '.tar', '.txt'.
It won't filter out '.sh', '.py' (etc.) files, so that could be used for wrappers.
If the pattern is too general like out/**/*test*, it could cause unexpected executable or script execution (with --help argument)
which would not just increase the test-loading duration but also could have other unexpeced effects.
I suggest to have a stricter file-name convention and a corresponding pattern like out/**/*.test.* or out/**/Test.*
| Variable | Description |
|---|---|
${absPath} |
Absolute path of the test executable |
${relPath} |
Relative path of the test executable to the workspace folder |
${absDirpath} |
Absolute path of the test executable's parent directory |
${relDirpath} |
Relative path of the test executable's parent directory to the workspace folder |
${filename} |
Filename (Path withouth directories; "d/a.b.c" => "a.b.c") |
${baseFilename} |
Filename without extension ("d/a.b.c" => "a.b") |
${extFilename} |
Filename extension. ("d/a.b.c" => ".c") |
${base2Filename} |
Filename without second extension ("d/a.b.c" => "a") |
${ext2Filename} |
Filename's second level extension. ("d/a.b.c" => ".b") |
${base3Filename} |
Filename without third extension ("d/a.b.c" => "a") |
${ext3Filename} |
Filename's third level extension. ("d/a.b.c" => "") |
${workspaceDirectory} |
(You can only guess once.) |
${workspaceFolder} |
Alias of ${workspaceDirectory} |
${workspaceName} |
Workspace name can be custom in case of workspace file. |
${name} |
The resolved executables's name. Can be used only in cwd and env. |
${cwd} |
The resolved executables's cwd. Can be used only in env. |
"catch2TestExplorer.executables": "dir/test.exe""catch2TestExplorer.executables": ["dir/test1.exe", "dir/test2.exe"]"catch2TestExplorer.executables": {
"name": "${filename} (${relDirpath}/)",
"pattern": "{build,Build,BUILD,out,Out,OUT}/**/*{test,Test,TEST}*",
"cwd": "${absDirpath}",
"env": {
"ExampleENV1": "You can use variables here too, like ${absPath}"
}
}"catch2TestExplorer.executables": [
{
"name": "Test1 suite",
"pattern": "dir/test.exe"
},
"singleTest.exe",
{
"pattern": "dir2/{t,T}est",
"cwd": "out/tmp",
"env": {}
}
]If catch2TestExplorer.debugConfigTemplate value is null (default),
it will look after vadimcn.vscode-lldb,
webfreak.debug and
ms-vscode.cpptools extensions.
If it founds one of it, it will use it automatically.
Remark: This feature to work automatically (value: null) has a lot of requirements which are not listed here.
If it works it is good for you.
If it isn't.. I suggest to create your own "catch2TestExplorer.debugConfigTemplate" template.
If you read the Related documents and still have a question feel free to open an issue.
For vadimcn.vscode-lldb add something like this to settings.json:
"catch2TestExplorer.debugConfigTemplate": {
"type": "cppdbg",
"MIMode": "lldb",
"program": "${exec}",
"args": "${args}",
"cwd": "${cwd}",
"env": "${envObj}",
"externalConsole": false
}Related documents:
- About VSCode launch config
- About vadimcn.vscode-lldb extension
- About webfreak.debug extension
- About ms-vscode.cpptools
Usable variables:
| Variable name | Value meaning | Type |
|---|---|---|
${label} |
The name of the test. Same as in the Test Explorer. | string |
${suiteLabel} |
The name of parent suite test. Same as in the Test Explorer. | string |
${exec} |
The path of the executable. | string |
${argsArray} |
The arguments for the executable. | string[] |
${argsStr} |
Concatenated arguments for the executable. | string |
${cwd} |
The current working directory for execution. | string |
${envObj} |
The environment variables as object properties. | { [prop: string]: string } |
These variables will be substituted when a DebugConfiguration is created.
Note that name and request are filled, if they are undefined, so it is not necessary to set them.
type is necessary.
For debugging use catch2TestExplorer.logpanel: true.
- (2018-09-03) On windows the navigate to source button isn't working. It is a framework bug.
- (2018-11-17) Catch2: Long (>80 character) filename, test-name or description can cause test-list parsing failures.
Workaround:
#define CATCH_CONFIG_CONSOLE_WIDTH 300
- Remove deprecated
catch2TestExplorer.enableSourceDecoration. - Test cases: google test, catch2: info, warn, fail, stdout, stderr, capture, gtest_skip
- Update this readme because of the effects of the new fswatcher.