Adding new options and example scenarios (#28976)
* fixing formatting issues, * formatting issues, * adding new options, * re-ordering args/options list to match with the cli, * Adding sample scenarios, * small changes, * Update docs/core/additional-tools/dotnet-coverage.md Co-authored-by: Genevieve Warren <24882762+gewarren@users.noreply.github.com> * Update docs/core/additional-tools/dotnet-coverage.md Co-authored-by: Genevieve Warren <24882762+gewarren@users.noreply.github.com> * Update docs/core/additional-tools/dotnet-coverage.md Co-authored-by: Genevieve Warren <24882762+gewarren@users.noreply.github.com> * Update docs/core/additional-tools/dotnet-coverage.md Co-authored-by: Genevieve Warren <24882762+gewarren@users.noreply.github.com> * Update docs/core/additional-tools/dotnet-coverage.md Co-authored-by: Genevieve Warren <24882762+gewarren@users.noreply.github.com> * Update docs/core/additional-tools/dotnet-coverage.md Co-authored-by: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Co-authored-by: Genevieve Warren <24882762+gewarren@users.noreply.github.com>
This commit is contained in:
fhnaseer
GitHub
Родитель
cfa920d11e
Коммит
f66d91af3a
|
|
@ -51,6 +51,7 @@
|
|||
"assistive",
|
||||
"Asynchronicity",
|
||||
"Asynchrony",
|
||||
"atlmfc",
|
||||
"attributelist",
|
||||
"attributename",
|
||||
"Authenticode",
|
||||
|
|
@ -109,6 +110,7 @@
|
|||
"cnabs",
|
||||
"CNCF",
|
||||
"coalescer",
|
||||
"cobertura",
|
||||
"coclass",
|
||||
"Coclasses",
|
||||
"codebases",
|
||||
|
|
@ -949,6 +951,7 @@
|
|||
"vbcr",
|
||||
"vbcrlf",
|
||||
"vbruntime",
|
||||
"vctools",
|
||||
"vectorized",
|
||||
"verifiably",
|
||||
"versionnumber",
|
||||
|
|
|
|||
|
|
@ -8,14 +8,6 @@ ms.topic: reference
|
|||
|
||||
**This article applies to:** ✔️ .NET Core 3.1 SDK and later versions
|
||||
|
||||
## Install
|
||||
|
||||
To install the latest release version of the `dotnet-coverage` [NuGet package](https://www.nuget.org/packages/dotnet-coverage), use the [dotnet tool install](../tools/dotnet-tool-install.md) command:
|
||||
|
||||
```dotnetcli
|
||||
dotnet tool install --global dotnet-coverage
|
||||
```
|
||||
|
||||
## Synopsis
|
||||
|
||||
```console
|
||||
|
|
@ -31,24 +23,82 @@ The `dotnet-coverage` tool:
|
|||
|
||||
## Options
|
||||
|
||||
- **`-h|--help`**
|
||||
* **`-h|--help`**
|
||||
|
||||
Shows command-line help.
|
||||
|
||||
- **`--version`**
|
||||
* **`--version`**
|
||||
|
||||
Displays the version of the dotnet-coverage utility.
|
||||
|
||||
## Install
|
||||
|
||||
To install the latest release version of the `dotnet-coverage` [NuGet package](https://www.nuget.org/packages/dotnet-coverage), use the [dotnet tool install](../tools/dotnet-tool-install.md) command:
|
||||
|
||||
```dotnetcli
|
||||
dotnet tool install --global dotnet-coverage
|
||||
```
|
||||
|
||||
## Commands
|
||||
|
||||
| Command |
|
||||
|-----------------------------------------------------------|
|
||||
| [dotnet-coverage merge](#dotnet-coverage-merge) |
|
||||
| [dotnet-coverage collect](#dotnet-coverage-collect) |
|
||||
| [dotnet-coverage connect](#dotnet-coverage-connect) |
|
||||
| [dotnet-coverage merge](#dotnet-coverage-merge) |
|
||||
| [dotnet-coverage snapshot](#dotnet-coverage-snapshot) |
|
||||
| [dotnet-coverage shutdown](#dotnet-coverage-shutdown) |
|
||||
|
||||
## dotnet-coverage merge
|
||||
|
||||
The `merge` command is used to merge several code coverage reports into one. This command is available on all platforms. This command supports the following code coverage report formats:
|
||||
|
||||
* `coverage`
|
||||
* `cobertura`
|
||||
* `xml`
|
||||
|
||||
### Synopsis
|
||||
|
||||
```console
|
||||
dotnet-coverage merge
|
||||
[--remove-input-files] [-r|--recursive]
|
||||
[-o|--output <output>] [-f|--output-format <output-format>]
|
||||
[-l|--log-file <log-file>] [-ll|--log-level <log-level>] [-?|-h|--help]
|
||||
<files>
|
||||
```
|
||||
|
||||
### Arguments
|
||||
|
||||
* **`<files>`**
|
||||
|
||||
The input code coverage reports.
|
||||
|
||||
### Options
|
||||
|
||||
* **`--remove-input-files`**
|
||||
|
||||
Removes all input coverage reports that were merged.
|
||||
|
||||
* **`-r, --recursive`**
|
||||
|
||||
Search for coverage reports in subdirectories.
|
||||
|
||||
* **`-o|--output <output>`**
|
||||
|
||||
Sets the code coverage report output file.
|
||||
|
||||
* **`-f|--output-format <output-format>`**
|
||||
|
||||
The output file format. Supported values: `coverage`, `xml`, and `cobertura`. Default is `coverage` (binary format that can be opened in Visual Studio).
|
||||
|
||||
* **`-l|--log-file <log-file>`**
|
||||
|
||||
Sets the log file path. When you provide a directory (with a path separator at the end), a new log file is generated for each process under analysis.
|
||||
|
||||
* **`-ll|--log-level <log-level>`**
|
||||
|
||||
Sets the log level. Supported values: `Error`, `Info`, and `Verbose`.
|
||||
|
||||
## dotnet-coverage collect
|
||||
|
||||
The `collect` command is used to collect code coverage data for any .NET process and its subprocesses. For example, you can collect code coverage data for a console application or a Blazor application. This command is available on Windows (x86 and x64), Linux (x64), and macOS (x64). The command supports only .NET modules. Native modules are not supported.
|
||||
|
|
@ -62,10 +112,11 @@ The `collect` command can run in two modes.
|
|||
The `collect` command will collect code coverage for the given process executed by the `command` argument.
|
||||
|
||||
```console
|
||||
dotnet-coverage collect [-?|-h|--help] [-l|--log-file <log-file>] [-ll|--log-level <log-level>]
|
||||
[-o|--output <output>] [-f|--output-format <output-format>]
|
||||
dotnet-coverage collect
|
||||
[-s|--settings <settings>] [-id|--session-id <session-id>]
|
||||
<command>
|
||||
[-o|--output <output>] [-f|--output-format <output-format>]
|
||||
[-l|--log-file <log-file>] [-ll|--log-level <log-level>] [-?|-h|--help]
|
||||
<command> <args>
|
||||
```
|
||||
|
||||
#### Server Mode
|
||||
|
|
@ -73,47 +124,60 @@ dotnet-coverage collect [-?|-h|--help] [-l|--log-file <log-file>] [-ll|--log-lev
|
|||
The `collect` command hosts a server for code coverage collection. Clients can connect to the server via `connect` command.
|
||||
|
||||
```console
|
||||
dotnet-coverage collect [-?|-h|--help] [-l|--log-file <log-file>] [-ll|--log-level <log-level>]
|
||||
[-o|--output <output>] [-f|--output-format <output-format>]
|
||||
dotnet-coverage collect
|
||||
[-s|--settings <settings>] [-id|--session-id <session-id>]
|
||||
[-sv|--server-mode]
|
||||
[-sv|--server-mode] [-b|--background] [-t|--timeout]
|
||||
[-o|--output <output>] [-f|--output-format <output-format>]
|
||||
[-l|--log-file <log-file>] [-ll|--log-level <log-level>] [-?|-h|--help]
|
||||
```
|
||||
|
||||
### Arguments
|
||||
|
||||
- **`<command>`**
|
||||
* **`<command>`**
|
||||
|
||||
The command for which to collect code coverage data.
|
||||
|
||||
* **`<args>`**
|
||||
|
||||
The command line arguments for the command.
|
||||
|
||||
### Options
|
||||
|
||||
- **`-l|--log-file <log-file>`**
|
||||
|
||||
Sets the log file path. When you provide a directory (with a path separator at the end), a new log file is generated for each process under analysis.
|
||||
|
||||
- **`-ll|--log-level <log-level>`**
|
||||
|
||||
Sets the log level. Supported values: `Error`, `Info`, and `Verbose`.
|
||||
|
||||
- **`-o|--output <output>`**
|
||||
|
||||
Sets the code coverage report output file.
|
||||
|
||||
- **`-f|--output-format <output-format>`**
|
||||
|
||||
The output file format. Supported values: `coverage`, `xml`, and `cobertura`. Default is `coverage` (binary format that can be opened in Visual Studio).
|
||||
|
||||
- **`-id|--session-id <session-id>`**
|
||||
|
||||
Specifies the code coverage session ID. If not provided, the tool will generate a random GUID.
|
||||
|
||||
- **`-s|--settings <settings>`**
|
||||
* **`-s|--settings <settings>`**
|
||||
|
||||
Sets the path to the XML code coverage settings.
|
||||
|
||||
- **`-sv|--server-mode`**
|
||||
* **`-id|--session-id <session-id>`**
|
||||
|
||||
Starts the collector in server mode. Clients can connect to the server with `connect` command.
|
||||
Specifies the code coverage session ID. If not provided, the tool will generate a random GUID.
|
||||
|
||||
* **`-sv|--server-mode`**
|
||||
|
||||
Starts the collector in server mode. Clients can connect to the server with the `connect` command.
|
||||
|
||||
* **`-b|--background`**
|
||||
|
||||
Starts code coverage collection server in a new background process. Clients can connect to the server with the `connect` command.
|
||||
|
||||
* **`-t|--timeout`**
|
||||
|
||||
Timeout (in milliseconds) for interprocess communication between clients and the server.
|
||||
|
||||
* **`-o|--output <output>`**
|
||||
|
||||
Sets the code coverage report output file.
|
||||
|
||||
* **`-f|--output-format <output-format>`**
|
||||
|
||||
The output file format. Supported values: `coverage`, `xml`, and `cobertura`. Default is `coverage` (binary format that can be opened in Visual Studio).
|
||||
|
||||
* **`-l|--log-file <log-file>`**
|
||||
|
||||
Sets the log file path. When you provide a directory (with a path separator at the end), a new log file is generated for each process under analysis.
|
||||
|
||||
* **`-ll|--log-level <log-level>`**
|
||||
|
||||
Sets the log level. Supported values: `Error`, `Info`, and `Verbose`.
|
||||
|
||||
## dotnet-coverage connect
|
||||
|
||||
|
|
@ -122,80 +186,43 @@ The `connect` command is used to connect with the existing server and collects c
|
|||
### Synopsis
|
||||
|
||||
```console
|
||||
dotnet-coverage connect [-?|-h|--help] [-l|--log-file <log-file>] [-ll|--log-level <log-level>]
|
||||
dotnet-coverage connect
|
||||
[-b|--background] [-t|--timeout]
|
||||
[-l|--log-file <log-file>] [-ll|--log-level <log-level>] [-?|-h|--help]
|
||||
<session>
|
||||
<command>
|
||||
<command> <args>
|
||||
```
|
||||
|
||||
### Arguments
|
||||
|
||||
- **`<session>`**
|
||||
* **`<session>`**
|
||||
|
||||
The session ID of the server hosted by the `collect` command.
|
||||
|
||||
- **`<command>`**
|
||||
* **`<command>`**
|
||||
|
||||
The command for which to collect code coverage data.
|
||||
|
||||
### Options
|
||||
* **`<args>`**
|
||||
|
||||
- **`-l|--log-file <log-file>`**
|
||||
|
||||
Sets the log file path. When you provide a directory (with a path separator at the end), a new log file is generated for each process under analysis.
|
||||
|
||||
- **`-ll|--log-level <log-level>`**
|
||||
|
||||
Sets the log level. Supported values: `Error`, `Info`, and `Verbose`.
|
||||
|
||||
## dotnet-coverage merge
|
||||
|
||||
The `merge` command is used to merge several code coverage reports into one. This command is available on all platforms. This command supports the following code coverage report formats:
|
||||
|
||||
- `coverage`
|
||||
- `cobertura`
|
||||
- `xml`
|
||||
|
||||
### Synopsis
|
||||
|
||||
```console
|
||||
dotnet-coverage merge [-?|-h|--help] [-l|--log-file <log-file>] [-ll|--log-level <log-level>]
|
||||
[-o|--output <output>] [-f|--output-format <output-format>]
|
||||
[-r|--recursive] [--remove-input-files]
|
||||
<files>
|
||||
```
|
||||
|
||||
### Arguments
|
||||
|
||||
- **`<files>`**
|
||||
|
||||
The input code coverage reports.
|
||||
The command line arguments for the command.
|
||||
|
||||
### Options
|
||||
|
||||
- **`-l|--log-file <log-file>`**
|
||||
* **`-b|--background`**
|
||||
|
||||
Starts the client in a new background process.
|
||||
|
||||
* **`-t|--timeout`**
|
||||
|
||||
Timeout (in milliseconds) for interprocess communication between the client and the server.* **`-l|--log-file <log-file>`**
|
||||
|
||||
Sets the log file path. When you provide a directory (with a path separator at the end), a new log file is generated for each process under analysis.
|
||||
|
||||
- **`-ll|--log-level <log-level>`**
|
||||
* **`-ll|--log-level <log-level>`**
|
||||
|
||||
Sets the log level. Supported values: `Error`, `Info`, and `Verbose`.
|
||||
|
||||
- **`-o|--output <output>`**
|
||||
|
||||
Sets the code coverage report output file.
|
||||
|
||||
- **`-f|--output-format <output-format>`**
|
||||
|
||||
The output file format. Supported values: `coverage`, `xml`, and `cobertura`. Default is `coverage` (binary format that can be opened in Visual Studio).
|
||||
|
||||
- **`-r, --recursive`**
|
||||
|
||||
Search for coverage reports in subdirectories.
|
||||
|
||||
- **`--remove-input-files`**
|
||||
|
||||
Removes all input coverage reports that were merged.
|
||||
|
||||
## dotnet-coverage snapshot
|
||||
|
||||
Creates a coverage file for existing code coverage collection.
|
||||
|
|
@ -203,33 +230,39 @@ Creates a coverage file for existing code coverage collection.
|
|||
### Synopsis
|
||||
|
||||
```console
|
||||
dotnet-coverage snapshot [-?|-h|--help] [-l|--log-file <log-file>] [-ll|--log-level <log-level>]
|
||||
[-o|--output <output>] [-r|--reset] <session>
|
||||
dotnet-coverage snapshot
|
||||
[-r|--reset] [-o|--output <output>] [-t|--timeout]
|
||||
[-l|--log-file <log-file>] [-ll|--log-level <log-level>] [-?|-h|--help]
|
||||
<session>
|
||||
```
|
||||
|
||||
### Arguments
|
||||
|
||||
- **`<session>`**
|
||||
* **`<session>`**
|
||||
|
||||
The session ID of the collection for which a coverage file is to be generated.
|
||||
|
||||
### Options
|
||||
|
||||
- **`-l|--log-file <log-file>`**
|
||||
* **`-r|--reset <reset>`**
|
||||
|
||||
Sets the log file path. When you provide a directory (with a path separator at the end), a new log file is generated for each process under analysis.
|
||||
Clears existing coverage information after a coverage file is created.
|
||||
|
||||
- **`-ll|--log-level <log-level>`**
|
||||
|
||||
Sets the log level. Supported values: `Error`, `Info`, and `Verbose`.
|
||||
|
||||
- **`-o|--output <output>`**
|
||||
* **`-o|--output <output>`**
|
||||
|
||||
Sets the code coverage report output file. If not provided, it's generated automatically with a timestamp.
|
||||
|
||||
- **`-r|--reset <reset>`**
|
||||
* **`-t|--timeout`**
|
||||
|
||||
Clears existing coverage information after a coverage file is created.
|
||||
Timeout (in milliseconds) for interprocess communication between the client and the server.
|
||||
|
||||
* **`-l|--log-file <log-file>`**
|
||||
|
||||
Sets the log file path. When you provide a directory (with a path separator at the end), a new log file is generated for each process under analysis.
|
||||
|
||||
* **`-ll|--log-level <log-level>`**
|
||||
|
||||
Sets the log level. Supported values: `Error`, `Info`, and `Verbose`.
|
||||
|
||||
## dotnet-coverage shutdown
|
||||
|
||||
|
|
@ -238,31 +271,40 @@ Closes existing code coverage collection.
|
|||
### Synopsis
|
||||
|
||||
```console
|
||||
dotnet-coverage shutdown [-?|-h|--help] [-l|--log-file <log-file>] [-ll|--log-level <log-level>] <session>
|
||||
dotnet-coverage shutdown
|
||||
[-t|--timeout]
|
||||
[-l|--log-file <log-file>] [-ll|--log-level <log-level>] [-?|-h|--help]
|
||||
<session>
|
||||
```
|
||||
|
||||
### Arguments
|
||||
|
||||
- **`<session>`**
|
||||
* **`<session>`**
|
||||
|
||||
The session ID of the collection to be closed.
|
||||
|
||||
### Options
|
||||
|
||||
- **`-l|--log-file <log-file>`**
|
||||
* **`-t|--timeout`**
|
||||
|
||||
Timeout (in milliseconds) for interprocess communication with the server.
|
||||
|
||||
* **`-l|--log-file <log-file>`**
|
||||
|
||||
Sets the log file path. When you provide a directory (with a path separator at the end), a new log file is generated for each process under analysis.
|
||||
|
||||
- **`-ll|--log-level <log-level>`**
|
||||
* **`-ll|--log-level <log-level>`**
|
||||
|
||||
Sets the log level. Supported values: `Error`, `Info`, and `Verbose`.
|
||||
|
||||
## Sample scenarios
|
||||
|
||||
## Collecting code coverage
|
||||
|
||||
Collect code coverage data for any .NET application (such as console or Blazor) by using the following command:
|
||||
|
||||
```console
|
||||
dotnet-coverage collect "dotnet run"
|
||||
dotnet-coverage collect dotnet run
|
||||
```
|
||||
|
||||
In case of an application that requires a signal to terminate, you can use <kbd>Ctrl</kbd>+<kbd>C</kbd>, which will still let you collect code coverage data. For the argument, you can provide any command that will eventually start a .NET app. For example, it can be a PowerShell script.
|
||||
|
|
@ -307,11 +349,67 @@ Waiting for a connection... Code coverage results: output.coverage.
|
|||
D:\serverexample\server>
|
||||
```
|
||||
|
||||
### Server and client mode
|
||||
|
||||
Code coverage collection can be done in server-client mode as well. In this scenario, a code coverage collection server starts, and multiple clients can connect with the server. Code coverage is collected for all the clients collectively.
|
||||
|
||||
Start the code coverage server using the following command:
|
||||
|
||||
```condole
|
||||
dotnet-coverage collect --session-id serverdemo --server-mode
|
||||
```
|
||||
|
||||
In this example, the session ID was specified as `serverdemo` for the server. A client can connect to the server using this session ID using the following command:
|
||||
|
||||
```condole
|
||||
dotnet-coverage connect serverdemo dotnet run
|
||||
```
|
||||
|
||||
Finally, you can close the session `serverdemo` and the server using the following command:
|
||||
|
||||
```console
|
||||
dotnet-coverage shutdown serverdemo
|
||||
```
|
||||
|
||||
The server process creates a collective code coverage report for all clients and exits.
|
||||
|
||||
Following is an example of full output on the server side:
|
||||
|
||||
```console
|
||||
D:\serverexample\server> dotnet-coverage collect --session-id serverdemo --server-mode
|
||||
SessionId: serverdemo
|
||||
// Server will be in idle state and wait for connect and shutdown commands
|
||||
Code coverage results: output.coverage.
|
||||
D:\serverexample\server>
|
||||
```
|
||||
|
||||
Following is an example of full output on the client side:
|
||||
|
||||
```console
|
||||
D:\serverexample\server> dotnet-coverage connect serverdemo ConsoleApplication.exe World
|
||||
Hello World!!
|
||||
D:\serverexample\server> dotnet-coverage connect serverdemo WpfApplication.exe
|
||||
D:\serverexample\server> dotnet-coverage shutdown serverdemo
|
||||
D:\serverexample\server>
|
||||
```
|
||||
|
||||
You can also start both server and client in background mode. Another process starts in the background and returns control back to the user.
|
||||
|
||||
Following is an example of full output in background server client mode:
|
||||
|
||||
```console
|
||||
D:\serverexample\server> dotnet-coverage collect --session-id serverdemo --server-mode --background
|
||||
D:\serverexample\server> dotnet-coverage connect --background serverdemo ConsoleApplication.exe World
|
||||
D:\serverexample\server> dotnet-coverage connect --background serverdemo WpfApplication.exe
|
||||
D:\serverexample\server> dotnet-coverage shutdown serverdemo
|
||||
D:\serverexample\server>
|
||||
```
|
||||
|
||||
### Settings
|
||||
|
||||
You can specify a file with settings when you use the `collect` command. The settings file can be used to exclude some modules or methods from code coverage analysis. The format is the same as the data collector configuration inside a *runsettings* file. For more information, see [Customize code coverage analysis](/visualstudio/test/customizing-code-coverage-analysis). Here's an example:
|
||||
|
||||
```
|
||||
```xml
|
||||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<Configuration>
|
||||
<CodeCoverage>
|
||||
|
|
@ -428,5 +526,5 @@ dotnet-coverage merge -o output.xml -f xml input.coverage
|
|||
|
||||
## See also
|
||||
|
||||
- [Customize code coverage analysis](/visualstudio/test/customizing-code-coverage-analysis)
|
||||
- [Publish Code Coverage Results task](/azure/devops/pipelines/tasks/test/publish-code-coverage-results)
|
||||
* [Customize code coverage analysis](/visualstudio/test/customizing-code-coverage-analysis)
|
||||
* [Publish Code Coverage Results task](/azure/devops/pipelines/tasks/test/publish-code-coverage-results)
|
||||
|
|
|
|||
Загрузка…
Ссылка в новой задаче