Ido David
144 lines
5.0 KiB
Markdown
144 lines
5.0 KiB
Markdown
# coverlet [](https://www.travis-ci.org/tonerdo/coverlet) [](https://ci.appveyor.com/project/tonerdo/coverlet) [](https://coveralls.io/github/tonerdo/coverlet?branch=master) [](LICENSE)
|
|
|
|
Coverlet is a cross platform code coverage library for .NET Core, with support for line, branch and method coverage.
|
|
|
|
## Installation
|
|
|
|
Available on [NuGet](https://www.nuget.org/packages/coverlet.msbuild/)
|
|
|
|
Visual Studio:
|
|
|
|
```powershell
|
|
PM> Install-Package coverlet.msbuild
|
|
```
|
|
|
|
.NET Core CLI:
|
|
|
|
```bash
|
|
dotnet add package coverlet.msbuild
|
|
```
|
|
|
|
## How It Works
|
|
|
|
Coverlet integrates with the MSBuild system and that allows it to go through the following process:
|
|
|
|
### Before Tests Run
|
|
|
|
* Locates the unit test assembly and selects all the referenced assemblies that have PDBs.
|
|
* Instruments the selected assemblies by inserting code to record sequence point hits to a temporary file.
|
|
|
|
### After Tests Run
|
|
|
|
* Restore the original non-instrumented assembly files.
|
|
* Read the recorded hits information from the temporary file.
|
|
* Generate the coverage result from the hits information and write it to a file.
|
|
|
|
_Note: The assembly you'd like to get coverage for must be different from the assembly that contains the tests_
|
|
|
|
## Usage
|
|
|
|
Coverlet doesn't require any additional setup other than including the NuGet package. It integrates with the `dotnet test` infrastructure built into the .NET Core CLI and when enabled, will automatically generate coverage results after tests are run.
|
|
|
|
### Code Coverage
|
|
|
|
Enabling code coverage is as simple as setting the `CollectCoverage` property to `true`
|
|
|
|
```bash
|
|
dotnet test /p:CollectCoverage=true
|
|
```
|
|
|
|
After the above command is run, a `coverage.json` file containing the results will be generated in the root directory of the test project. A summary of the results will also be displayed in the terminal.
|
|
|
|
### Coverage Output
|
|
|
|
Coverlet can generate coverage results in multiple formats, which is specified using the `CoverletOutputFormat` property. For example, the following command emits coverage results in the `opencover` format:
|
|
|
|
```bash
|
|
dotnet test /p:CollectCoverage=true /p:CoverletOutputFormat=opencover
|
|
```
|
|
|
|
Supported Formats:
|
|
|
|
* json (default)
|
|
* lcov
|
|
* opencover
|
|
* cobertura
|
|
|
|
The output folder of the coverage result file can also be specified using the `CoverletOutputDirectory` property.
|
|
|
|
### Threshold
|
|
|
|
Coverlet allows you to specify a coverage threshold below which it fails the build. This allows you to enforce a minimum coverage percent on all changes to your project.
|
|
|
|
```bash
|
|
dotnet test /p:CollectCoverage=true /p:Threshold=80
|
|
```
|
|
|
|
The above command will automatically fail the build if the average code coverage of all instrumented modules falls below 80%.
|
|
|
|
### Excluding From Coverage
|
|
|
|
#### Attributes
|
|
You can ignore a method or an entire class from code coverage by creating and applying any of the following attributes:
|
|
|
|
* ExcludeFromCoverage
|
|
* ExcludeFromCoverageAttribute
|
|
|
|
Coverlet just uses the type name, so the attributes can be created under any namespace of your choosing.
|
|
|
|
#### File Path
|
|
You can also ignore specific source files from code coverage using the `Exclude` property
|
|
- Use single or multiple paths (separate by comma)
|
|
- Use absolute or relative paths (relative to the project directory)
|
|
- Use file path or directory path with globbing (e.g `dir1/*.cs`)
|
|
|
|
```bash
|
|
dotnet test /p:CollectCoverage=true /p:Exclude=\"../dir1/class1.cs,../dir2/*.cs,../dir3/**/*.cs,\"
|
|
```
|
|
|
|
## Roadmap
|
|
|
|
* Filter modules to be instrumented
|
|
* Support for more output formats (e.g. JaCoCo)
|
|
* Console runner (removes the need for requiring a NuGet package)
|
|
|
|
## Issues & Contributions
|
|
|
|
If you find a bug or have a feature request, please report them at this repository's issues section. Contributions are highly welcome, however, except for very small changes, kindly file an issue and let's have a discussion before you open a pull request.
|
|
|
|
### Building The Project
|
|
|
|
Clone this repo:
|
|
|
|
```bash
|
|
git clone https://github.com/tonerdo/coverlet
|
|
```
|
|
|
|
Change directory to repo root:
|
|
|
|
```bash
|
|
cd coverlet
|
|
```
|
|
|
|
Execute build script:
|
|
|
|
```bash
|
|
dotnet msbuild build.proj
|
|
```
|
|
|
|
This will result in the following:
|
|
|
|
* Restore all NuGet packages required for building
|
|
* Build and publish all projects. Final binaries are placed into `<repo_root>\build\<Configuration>`
|
|
* Build and run tests
|
|
|
|
These steps must be followed before you attempt to open the solution in an IDE (e.g. Visual Studio, Rider) for all projects to be loaded successfully.
|
|
|
|
## Code of Conduct
|
|
|
|
This project enforces a code of conduct in line with the contributor covenant. See [CODE OF CONDUCT](CODE_OF_CONDUCT.md) for details.
|
|
|
|
## License
|
|
|
|
This project is licensed under the MIT license. See the [LICENSE](LICENSE) file for more info.
|