Skip to content

Latest commit

 

History

History
159 lines (126 loc) · 12.4 KB

README.md

File metadata and controls

159 lines (126 loc) · 12.4 KB
Raw

Catch2 and Google Test Explorer for Visual Studio Code

Build Status Build status GitHub issues GitHub license Visual Studio Marketplace Visual Studio Marketplace

This extension allows you to run your Catch2 and Google Test tests using the Test Explorer for VS Code.

Configuration

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: below
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". (Resolves: ${workspaceFolder})
catch2TestExplorer.defaultEnv Default environment variables to be set when running the tests, if it isn't provided in 'executables'. (Resolves: ${workspaceFolder})
catch2TestExplorer.debugConfigTemplate Set the necessary debug configuraitons and the debug button will work. Details: below
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 Catch2: --rng-seed <number> or "time"; Google Test: --gtest_random_seed=<number>;
catch2TestExplorer.defaultWatchTimeoutSec Test executables are being watched. In case of one compiles too much this variable can help with it. Unit: second. It applies instantly.
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.
catch2TestExplorer.workerMaxNumber The variable maximize the number of the parallel test execution. It applies instantly.
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

catch2TestExplorer.executables

This variable can be string, an array of strings, an array of objects or an array of strings and objects.

If it is an object it can contains the following properties:

Property Description
name (optional) The name of the test suite (file). Can contains variables related to pattern.
pattern (requierd) 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). ⚠️Avoid backslash! (Details). Example: {build,out}/**/test[1-9]*
path (alias) Alias of pattern.
cwd (optional) 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.
env (optional) 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.

Remark: 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!).

Variables which can be used in name, cwd and env of executables:

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}

Examples:

"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": {}
	}
]

catch2TestExplorer.debugConfigTemplate

If catch2TestExplorer.debugConfigTemplate value is null (default), it will look after vadimcn.vscode-lldb and ms-vscode.cpptools extensions. If it founds one of it, it will use it automatically.

or user can manually fill it

See here for details.

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
${args} The arguments for the executable. string[]
${cwd} The current working directory for execution. string
${envObj} The environment variables as object properties. { [prop: string]: any }

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.

Example:

{
  "type": "cppdbg",
  "MIMode": "lldb",
  "program": "${exec}",
  "args": "${args}",
  "cwd": "${cwd}",
  "env": "${envObj}",
  "externalConsole": false
}

License

The Unlicense

Known issues

  • (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

TODOs

  • Remove deprecated catch2TestExplorer.enableSourceDecoration.
  • Test cases: google test, catch2: info, warn, fail, stdout, stderr, capture

Contribution guideline here