Skip to content

Overhaul the README #346

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
May 6, 2021
Merged

Overhaul the README #346

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
144 changes: 66 additions & 78 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,21 +6,19 @@

sbt-scoverage is a plugin for sbt that integrates the scoverage code coverage
library. Find out more about
[scoverage](https://github.com/scoverage/scalac-scoverage-plugin).
[scoverage here](https://github.com/scoverage/scalac-scoverage-plugin).

## How to use
## Setup

Make sure your sbt version in project/build.properties:
```scala
sbt.version = 1.2.8
```
**Requirements**: Requires sbt 1.2.8 or above

Add the plugin in `project/plugins.sbt`:
[![Maven Central](https://maven-badges.herokuapp.com/maven-central/org.scoverage/sbt-scoverage/badge.svg?kill_cache=1)](https://search.maven.org/artifact/org.scoverage/sbt-scoverage/)
In `project/plugins.sbt`:
```scala
addSbtPlugin("org.scoverage" % "sbt-scoverage" % "x.x.x")
```

## Usage

Run the tests with enabled coverage:
```
$ sbt clean coverage test
Expand All @@ -40,58 +38,40 @@ To generate the coverage reports run
$ sbt coverageReport
```

Coverage reports will be in `target/scala-<scala-version>/scoverage-report`. There are HTML and XML reports. The XML is useful if you need to programatically use the results, or if you're writing a tool.

If you're running the coverage reports from within an sbt console session (as
opposed to one command per sbt launch), then the `coverage` command is sticky. To
turn it back off when you're done running reports, use the `coverageOff` command or reset `coverageEnabled` with `set coverageEnabled := false`.

Sample project with scoverage in both sbt and maven - [the scoverage samples project](https://github.com/scoverage/sbt-scoverage-samples).

## Notes on upgrading to version 1.6.x
* ´coverageCleanSubprojectFiles´ key has been removed
* scala version 2.12+ is required as a minimum (due to scoverage suppport)

## Notes on upgrading to version 1.6.0

* `coverageAggregate` aggregates raw coverage data, not coverage xml reports for modules.
There is no requirement to generate individual coverage reports for modules (`coverageReport`)
before generating aggregated report (`coverageAggregate`).

If only aggregated report is required, not executing `coverageReport` can reduce the build time significantly.

## Notes on upgrading to version 1.3.0

* The object containing the keys has changed from nested to top level so you might need to adjust the import. It's also an auto plugin now, so you might not need the import at all.
* There is an issue syncing the binary with the sbt-plugin-releases repo, so in the meantime add `resolvers += Resolver.url("scoverage-bintray", url("https://dl.bintray.com/sksamuel/sbt-plugins/"))(Resolver.ivyStylePatterns)` to your build.

## Notes on upgrading to version 1.0.0
Coverage reports will be in your `target/scala-<scala-version>/scoverage-report`
directory. There are HTML and XML reports. The XML is useful if you need to
programatically use the results, or if you're writing a tool.

If you are upgrading from 0.99.x then you must remove the `instrumentSettings` from your build.sbt or Build.scala, as that is no longer needed.
**NOTE**: If you're running the coverage reports from within an sbt console
session (as opposed to one command per sbt launch), then the `coverage` command
is sticky. To turn it back off when you're done running reports, use the
`coverageOff` command or reset `coverageEnabled` with `set coverageEnabled :=
false`.

Next, the keys have been renamed slightly. The new names begin with coverageXXX, eg coverageExcludedPackages and some have had their full name changed. You can see a full list of keys by opening the object ScoverageKeys.
### Multi project reports

## Multi project reports
By default, scoverage will generate reports for each project separately. You can
merge them into an aggregated report by using the following:

By default, scoverage will generate reports for each project separately. You can merge them into an aggregated report by invoking `sbt coverageAggregate`.

(Note, you must do this after all the coverage data is complete as a separate command, so you cannot do `sbt coverage test coverageAggregate` (at least until a way around this is found).)
```
$ sbt coverageAggregate
```

(You do not need to run `coverageReport` before `coverageAggregate`; it aggregates over the sub-projects' coverage data directly, not the report xml.)
**NOTE**: You do not need to run `coverageReport` before `coverageAggregate`; it
aggregates over the sub-projects' coverage data directly, not the report xml.

## Exclude classes and packages
### Exclude classes and packages

You can exclude classes from being considered for coverage measurement by providing semicolon-separated list of
regular expressions.
You can exclude classes from being considered for coverage measurement by
providing semicolon-separated list of regular expressions.

Example:
```scala
coverageExcludedPackages := "<empty>;Reverse.*;.*AuthService.*;models\\.data\\..*"
```

The regular expressions are matched against the fully qualified class name, and must match the entire string to take effect.

Any matched classes will not be instrumented or included in the coverage report.
The regular expressions are matched against the fully qualified class name, and
must match the entire string to take effect. Any matched classes will not be
instrumented or included in the coverage report.

You can also mark sections of code with comments like:

Expand All @@ -101,59 +81,67 @@ You can also mark sections of code with comments like:
// $COVERAGE-ON$
```

Any code between two such comments will not be instrumented or included in the coverage report.
Any code between two such comments will not be instrumented or included in the
coverage report.

## Minimum coverage
### Minimum coverage

Based on minimum coverage, you can fail the build with the following keys
Based on minimum coverage, you can fail the build with the following keys:

```scala
coverageMinimum := 80
coverageFailOnMinimum := true
```

These settings will be enforced when the reports are generated.
If you generate an aggregate report using `coverageAggregate` then these settings will apply to that report.
These settings will be enforced when the reports are generated. If you generate
an aggregate report using `coverageAggregate` then these settings will apply to
that report.

## Trouble-shooting failing tests

## Failing tests
Scoverage does a lot of file writing behind the scenes in order to track which statements have been executed.
If you are running into a scenario where your tests normally pass, but fail when scoverage is enabled, then the culprit can be one of the following:
scoverage does a lot of file writing behind the scenes in order to track which
statements have been executed. If you are running into a scenario where your
tests normally pass, but fail when scoverage is enabled, then the culprit can be
one of the following:

* timing issues on futures and other async operations, try upping the timeouts by an order of magnitude.
* tests are run in a sandbox mode (such as with `java.security.PrivilegedAction<T>`), try running the tests outside of the sandbox.

## Example project

[the scoverage samples project](https://github.com/scoverage/sbt-scoverage-samples).

## Integrations

### Codacy

[Codacy](https://www.codacy.com) integrates with your favorite coverage tool to provide an in-depth overlook of your project status. Scoverage information can be integrated into Codacy through the [sbt-codacy-coverage plugin](https://github.com/codacy/sbt-codacy-coverage).
[Codacy](https://www.codacy.com) integrates with your favorite coverage tool to
provide an in-depth overlook of your project status. scoverage information can
be integrated into Codacy through the
[codacy-coverage-reporter](https://github.com/codacy/codacy-coverage-reporter).

### Coveralls

If you have an open source project then you can add code coverage metrics with the excellent website https://coveralls.io/ Scoverage will integrate with coveralls using the [sbt-coveralls](https://github.com/scoverage/sbt-coveralls) plugin.

### Plugin for SonarQube
If you have an open source project then you can add code coverage metrics with
the [Coveralls](https://coveralls.io/). scoverage will integrate with coveralls
using the [sbt-coveralls](https://github.com/scoverage/sbt-coveralls) plugin.

If you want to visually browse statement coverage reports then use this [plugin for SonarQube](https://github.com/RadoBuransky/sonar-scoverage-plugin).
It allows you to review overall project statement coverage as well as dig deeper into sub-modules, directories and
source code files to see uncovered statements. Statement coverage measurement can become an integral part of your
team's continuous integration process and a required quality standard.
### Codecov

## License
```
This software is licensed under the Apache 2 license, quoted below.
You can integrate with [Codecov](https://about.codecov.io/) easily sending your
reports there via your CI. You can see an example of this here in
[codecov/example-scala](https://github.com/codecov/example-scala).

Copyright 2013-2016 Stephen Samuel and contributors
### Plugin for SonarQube

Licensed under the Apache License, Version 2.0 (the "License"); you may not
use this file except in compliance with the License. You may obtain a copy of
the License at
If you want to visually browse statement coverage reports then use this [plugin
for SonarQube](https://github.com/RadoBuransky/sonar-scoverage-plugin). It
allows you to review overall project statement coverage as well as dig deeper
into sub-modules, directories and source code files to see uncovered statements.
Statement coverage measurement can become an integral part of your team's
continuous integration process and a required quality standard.

http://www.apache.org/licenses/LICENSE-2.0
## Release Notes

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations under
the License.
```
For any information on releases and upgrading, please refer to the [release
page](https://github.com/scoverage/sbt-scoverage/releases).