Skip to content

Commit

Permalink
Release 0.11.0
Browse files Browse the repository at this point in the history
  • Loading branch information
fredericbonnet committed Nov 7, 2020
1 parent a91af89 commit 4d0fd73
Show file tree
Hide file tree
Showing 4 changed files with 85 additions and 26 deletions.
9 changes: 8 additions & 1 deletion CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

## [Unreleased]

## [0.11.0] - 2020-11-07

### Added

- Add support for linking tests with source files. This implements issue #19.

## [0.10.1] - 2020-11-04

### Fixed
Expand Down Expand Up @@ -99,7 +105,8 @@ Thanks to @andrewbridge for these contributions!

- First release.

[unreleased]: https://github.com/fredericbonnet/cmake-test-explorer/compare/v0.10.1...HEAD
[unreleased]: https://github.com/fredericbonnet/cmake-test-explorer/compare/v0.11.0...HEAD
[0.11.0]: https://github.com/fredericbonnet/cmake-test-explorer/compare/v0.10.1...v0.11.0
[0.10.1]: https://github.com/fredericbonnet/cmake-test-explorer/compare/v0.10.0...v0.10.1
[0.10.0]: https://github.com/fredericbonnet/cmake-test-explorer/compare/v0.9.0...v0.10.0
[0.9.0]: https://github.com/fredericbonnet/cmake-test-explorer/compare/v0.8.0...v0.9.0
Expand Down
98 changes: 75 additions & 23 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,12 +1,15 @@
# CMake Test Explorer for Visual Studio Code

Run your [CMake](https://cmake.org) tests using the [Test Explorer UI](https://marketplace.visualstudio.com/items?itemName=hbenl.vscode-test-explorer).
Run your [CMake](https://cmake.org) tests using the [Test Explorer
UI](https://marketplace.visualstudio.com/items?itemName=hbenl.vscode-test-explorer).

## Features

- Shows a Test Explorer in the Test view in VS Code's sidebar with all detected tests and suites and their state
- Shows a Test Explorer in the Test view in VS Code's sidebar with all detected
tests and suites and their state
- Shows a failed test's log when the test is selected in the explorer
- Forwards the console output from the test executable to a VS Code output channel
- Forwards the console output from the test executable to a VS Code output
channel

## Getting started

Expand All @@ -26,33 +29,80 @@ Run your [CMake](https://cmake.org) tests using the [Test Explorer UI](https://m
| `cmakeExplorer.extraCtestLoadArgs` | Extra command-line arguments passed to CTest at load time. For example, `-R foo` will only load the tests containing the string `foo`. Defaults to empty. |
| `cmakeExplorer.extraCtestRunArgs` | Extra command-line arguments passed to CTest at run time. For example, `-V` will enable verbose output from tests. Defaults to empty. |
| `cmakeExplorer.suiteDelimiter` | Delimiter used to split CMake test names into suite/test hierarchy. For example, if you name your tests `suite1/subsuite1/test1`, `suite1/subsuite1/test2`, `suite2/subsuite3/test4`, etc. you may set this to `/` in order to group your suites into a tree. If empty, the tests are not grouped. |
| `cmakeExplorer.suiteDelimiter` | Delimiter used to split CMake test names into suite/test hierarchy. For example, if you name your tests `suite1/subsuite1/test1`, `suite1/subsuite1/test2`, `suite2/subsuite3/test4`, etc. you may set this to `/` in order to group your suites into a tree. If empty, the tests are not grouped. |
| `cmakeExplorer.testFileVar` | CTest environment variable defined for a test, giving the path of the source file containing the test. See [Source files](#source-files) for more info. |
| `cmakeExplorer.testLineVar` | CTest environment variable defined for a test, giving the line number within the file where the test definition starts (if known). See [Source files](#source-files) for more info. |

## Variable substitution

Some options support the replacement of special values in their string value by using a `${variable}` syntax. The following built-in variables are expanded:
Some options support the replacement of special values in their string value by
using a `${variable}` syntax. The following built-in variables are expanded:

| Variable | Expansion |
| -------------------- | ---------------------------------------------- |
| `${workspaceFolder}` | The full path to the workspace root directory. |

Additionally, if the [CMake Tools](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cmake-tools) extension is active in the current workspace
and `cmakeExplorer.cmakeIntegration` is enabled, then the following variables can be used:
Additionally, if the [CMake
Tools](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cmake-tools)
extension is active in the current workspace and
`cmakeExplorer.cmakeIntegration` is enabled, then the following variables can be
used:

| Variable | Expansion |
| ------------------- | --------------------------------------------------------------------------- |
| `${buildType}` | The current CMake build type. For example: `Debug`, `Release`, `MinSizeRel` |
| `${buildDirectory}` | The full path to the current CMake build directory. |

If you want the Test Explorer to infer the right configuration automatically from CMake Tools,
simply use these settings:
If you want the Test Explorer to infer the right configuration automatically
from CMake Tools, simply use these settings:

| Property | Value |
| --------------------------- | ------------------- |
| `cmakeExplorer.buildDir` | `${buildDirectory}` |
| `cmakeExplorer.buildConfig` | `${buildType}` |

Note that any change to the CMake Tools configuration, either from the settings or the status bar,
requires a manual test reload from the Test Explorer sidebar.
Note that any change to the CMake Tools configuration, either from the settings
or the status bar, requires a manual test reload from the Test Explorer sidebar.

## Source files

The Test Explorer UI has a feature to link tests with their source files. CMake
provides the
[`set_tests_properties()`](https://cmake.org/cmake/help/latest/command/set_tests_properties.html)
command to associate tests with various metadata, however it only support a
predefined [list of
properties](https://cmake.org/cmake/help/latest/manual/cmake-properties.7.html#test-properties),
and none of them seems suitable for this purpose. To support this feature
anyway, the extension expects that the file path and line number be passed as
test environment variables using the
[`ENVIRONMENT`](https://cmake.org/cmake/help/latest/prop_test/ENVIRONMENT.html)
property, like so:

```
add_test(
NAME <name>
COMMAND <command> [<args> ...]
)
set_tests_properties(<name> PROPERTIES
ENVIRONMENT "TEST_FILE=<filename>;TEST_LINE=<line>"
)
```

Here we are using `TEST_FILE` and `TEST_LINE` environment variables but you are
free to choose other variable names. You can then edit the
`cmakeExplorer.testFileVar` and `cmakeExplorer.testLineVar` settings
accordingly, and you should see an extra '**Show source**' icon appear in the
Test Explorer panel next to all the tests where these variables are provided.
This feature also enables extra Test Explorer UI such as editor decorations in
the relevant source files (e.g. CodeLens, error messages etc).

Note that the `cmakeExplorer.testFileVar` setting must be set for these features
to work, however if the `cmakeExplorer.testLineVar` setting is missing or the
variable is not set for a given test then the '**Show source**' will still work
but the UI and commands provided by the core Test Explorer UI extension will
work differently (e.g. '**Run tests in current file**' instead of '**Run the
test at the current cursor position**', no CodeLens, etc). This can be useful
when no line number information is available (shell scripts for example).

## Debugging

Expand All @@ -78,7 +128,7 @@ The extension comes pre-configured with sensible defaults for debugging tests:
```

You can also use a custom configuration defined in the standard `launch.json`.
To do so, edit the `cmakeExplorer.debugConfig` settings with the name of the
To do so, edit the `cmakeExplorer.debugConfig` setting with the name of the
debug configuration to use.

Debugging a test will overwrite the following debug configuration fields with
Expand All @@ -92,8 +142,8 @@ values from the CTest metadata:
| `cwd` | CTest `WORKING_DIRECTORY` option |

For example, if you want the debugger to stop at the entry point of your tests,
add the following config in your `launch.json` then set `cmakeExplorer.debugConfig`
to "`myCustomDebugConfig`" :
add the following config in your `launch.json` then set
`cmakeExplorer.debugConfig` to "`myCustomDebugConfig`" :

```json
{
Expand All @@ -112,9 +162,11 @@ to "`myCustomDebugConfig`" :
The extension can run test jobs in parallel. The maximum number of jobs to run
is the first non-zero value in the following order:

- The `cmakeExplorer.parallelJobs` settings (see [Configuration](#configuration))
- The `cmakeExplorer.parallelJobs` setting (see
[Configuration](#configuration))
- The `cmake.ctest.parallelJobs` then `cmake.parallelJobs` settings if the
[CMake Tools](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cmake-tools)
[CMake
Tools](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cmake-tools)
extension is installed
- The number of processors on the machine

Expand Down Expand Up @@ -144,15 +196,15 @@ test list.

- `Error: CMake cache file /path/to/project/${buildDirectory}/CMakeCache.txt does not exist`

The `cmakeExplorer.cmakeIntegration` flag is enabled by default. This adds support
for extra variables in other settings (See
[Variable substitution](#variable-substitution) for more info). If the
extension is not installed or active then these variables are not substituted.
You can activate the extension's log panel in the settings for more details.
The `cmakeExplorer.cmakeIntegration` flag is enabled by default. This adds
support for extra variables in other settings (See [Variable
substitution](#variable-substitution) for more info). If the extension is not
installed or active then these variables are not substituted. You can activate
the extension's log panel in the settings for more details.

### The Test Explorer panel shows no error but the test list is empty

Make sure that the `cmakeExplorer.buildDir` is properly configured. By default
its value is empty, and in this case the extension shows no error if it fails
to find the `CMakeCache.txt` file, in order not to clutter the Test Explorer
panel for projects that don't use CMake.
its value is empty, and in this case the extension shows no error if it fails to
find the `CMakeCache.txt` file, in order not to clutter the Test Explorer panel
for projects that don't use CMake.
2 changes: 1 addition & 1 deletion package-lock.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion package.json
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@
"Maciej Dems (https://github.com/macdems)"
],
"publisher": "fredericbonnet",
"version": "0.10.1",
"version": "0.11.0",
"license": "BSD-3-Clause",
"homepage": "https://github.com/fredericbonnet/cmake-test-explorer",
"repository": {
Expand Down

0 comments on commit 4d0fd73

Please sign in to comment.