Skip to content
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

Jump to bottom

Fix version-badge to display the most recent version #546

Merged
merged 2 commits into from
Jul 23, 2024
Merged

Fix version-badge to display the most recent version #546

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
9adae9a
README: Fix maven badge. Use footnotes for links. Reformat/Refresh.
rolandtritsch Jul 23, 2024
a211ec5
README: Fix maven badge. Use footnotes for links. Reformat/Refresh.
rolandtritsch Jul 23, 2024
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
143 changes: 84 additions & 59 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,19 +1,20 @@
# sbt-scoverage

[![Gitter](https://img.shields.io/gitter/room/scoverage/scoverage.svg)](https://gitter.im/scoverage/scoverage)
[![Maven Central](https://img.shields.io/github/v/release/scoverage/sbt-scoverage?label=maven-central)](https://search.maven.org/artifact/org.scoverage/sbt-scoverage/)
[![License](http://img.shields.io/:license-Apache%202-red.svg)](http://www.apache.org/licenses/LICENSE-2.0.txt)
[![gitter-badge][]][gitter]
[![maven-badge][]][maven]
[![license-badge][]][license]

sbt-scoverage is an sbt plugin that offers support for Scala code coverage using
[scoverage](https://github.com/scoverage/scalac-scoverage-plugin). This plugin
supports Scala 2.12, 2.13, and 3.
sbt-scoverage is an sbt plugin that offers support for Scala code
coverage using [scoverage][]. This plugin supports Scala 2.12, 2.13,
and 3.

**NOTE**: that ScalaJS and Scala Native support is limited to Scala 2.
**NOTE**: that Scala 3 support starts with 3.2.x.
**NOTE**: ScalaJS and Scala Native support is limited to Scala 2.

**NOTE**: Scala 3 support starts with 3.2.x.

## Setup

**Requirements**: Requires sbt 1.2.8 or above
**Requirements**: Requires sbt 1.2.8 or above.

In `project/plugins.sbt`:
```scala
Expand Down Expand Up @@ -46,50 +47,54 @@ To generate the coverage reports run
sbt coverageReport
```

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.
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.

**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`.
**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`.

### 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 using the
following:

```
$ sbt coverageAggregate
```

**NOTE**: 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 and files

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.

```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 exclude files and file paths.

```scala
coverageExcludedFiles := ".*\\/two\\/GoodCoverage;.*\\/three\\/.*"
```

Note: The `.scala` file extension needs to be omitted from the filename, if one is given.
**NOTE**: The `.scala` file extension needs to be omitted from the
filename, if one is given.

Note: These two options only work for Scala2 and Scala 3.4.2+.
**NOTE**: These two options only work for Scala2 and Scala 3.4.2+.

You can also mark sections of code with comments like:

Expand All @@ -102,7 +107,7 @@ You can also mark sections of code with comments like:
Any code between two such comments will not be instrumented or included in the
coverage report.

Note: Comments exclusion works only for Scala2.
**NOTE**: Comments exclusion works only for Scala2.

### Minimum coverage

Expand All @@ -118,13 +123,14 @@ coverageMinimumStmtPerFile := 85
coverageMinimumBranchPerFile := 80
```

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.

### Override Location for Coverage Data And Report

If desired, one could override the default location for generating the sbt report and data through setting `coverageDataDir`:
If desired, one could override the default location for generating the
sbt report and data through setting `coverageDataDir`:

Example in data-dir test:
```scala
Expand All @@ -138,49 +144,68 @@ set coverageDataDir := file("/tmp")

## Trouble-shooting 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.
* 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).
To see the plugin in action you can checkout the scoverage [samples][]
project.

## 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
[codacy-coverage-reporter](https://github.com/codacy/codacy-coverage-reporter).
[Codacy][] 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][].

### Coveralls

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 have an open source project then you can publish the code
coverage metrics with [Coveralls][]. This plugin will integrate with
coveralls using the [sbt-coveralls][] plugin.

### Codecov

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).
You can also integrate with [Codecov][] by sending your reports there
via your CI. You can see an example in [codecov-example-scala][].

### Plugin for SonarQube
### SonarQube

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.
If you want to visually browse coverage reports then you can use the
[SonarQube][] 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.

## Release Notes

For any information on releases and upgrading, please refer to the [release
page](https://github.com/scoverage/sbt-scoverage/releases).
For any information on releases and upgrading, please refer to the
[release][] page.

[Codacy]: https://www.codacy.com
[Codecov]: https://about.codecov.io
[Coveralls]: https://coveralls.io
[SonarQube]: https://github.com/RadoBuransky/sonar-scoverage-plugin
[codacy-coverage-reporter]: https://github.com/codacy/codacy-coverage-reporter
[codecov-example-scala]: https://github.com/codecov/example-scala
[gitter-badge]: https://img.shields.io/gitter/room/scoverage/scoverage.svg
[gitter]: https://gitter.im/scoverage/scoverage
[license-badge]: http://img.shields.io/:license-Apache%202-red.svg
[license]: http://www.apache.org/licenses/LICENSE-2.0.txt
[maven-badge]: https://index.scala-lang.org/scoverage/sbt-scoverage/sbt-scoverage/latest.svg
[maven]: https://search.maven.org/artifact/org.scoverage/sbt-scoverage
[release]: https://github.com/scoverage/sbt-scoverage/releases
[samples]: https://github.com/scoverage/sbt-scoverage-samples
[sbt-coveralls]: https://github.com/scoverage/sbt-coveralls
[scoverage]: https://github.com/scoverage/scalac-scoverage-plugin