Repository files navigation

sbt-scoverage is an sbt plugin that offers support for Scala codecoverage usingscoverage. This plugin supports Scala 2.12, 2.13,and 3.

NOTE: ScalaJS and Scala Native support is limited to Scala 2.

NOTE: Scala 3 support starts with 3.2.x.

Requirements: Requires sbt 1.2.8 or above.

Inproject/plugins.sbt:

addSbtPlugin("org.scoverage"%"sbt-scoverage"%"x.x.x")

If you are in an enterprise environment, and the above does not work, try:

libraryDependencies+="org.scoverage"%"sbt-scoverage_2.12_1.0"%"x.x.x"

Run the tests with enabled coverage:

sbt clean coverage test

or if you have integration tests as well

sbt clean coverage it:test

This instruments standard build output so remember to clean again with coverage disabled before publishing your build to avoid including instrumentation.

To enable coverage directly in your build, use:

coverageEnabled:=true

Note that this will result in code being always instrumented which is unlikely what you want.

To generate the coverage reports run

sbt coverageReport

Coverage reports will be in yourtarget/scala-<scala-version>/scoverage-report directory. There areHTML and XML reports. The XML is useful if you need to programaticallyuse the results, or if you're writing a tool.

NOTE: If you're running the coverage reports from within an sbtconsole session (as opposed to one command per sbt launch), then thecoverage command is sticky. To turn it back off when you're donerunning reports, use thecoverageOff command or resetcoverageEnabled withset coverageEnabled := false.

By default, scoverage will generate reports for each projectseparately. You can merge them into an aggregated report by using thefollowing:

$ sbt coverageAggregate

NOTE: You do not need to runcoverageReport beforecoverageAggregate; it aggregates over the sub-projects' coveragedata directly, not the report xml.

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

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

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

You can also exclude files and file paths.

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

NOTE: The.scala file extension needs to be omitted from thefilename, if one is given.

NOTE: These two options only work for Scala2, Scala 3.3.4+ and Scala 3.4.2+.

You can also mark sections of code with comments like:

// $COVERAGE-OFF$Disabling highlighting by default until a workaround for https://issues.scala-lang.org/browse/SI-8596 is found  ...// $COVERAGE-ON$

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

NOTE: Comments exclusion works only for Scala2.

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

coverageFailOnMinimum:=truecoverageMinimumStmtTotal:=90coverageMinimumBranchTotal:=90coverageMinimumStmtPerPackage:=90coverageMinimumBranchPerPackage:=85coverageMinimumStmtPerFile:=85coverageMinimumBranchPerFile:=80

These settings will be enforced when the reports are generated. Ifyou generate an aggregate report usingcoverageAggregate then thesesettings will apply to that report.

If desired, one could override the default location for generating thesbt report and data through settingcoverageDataDir:

Example in data-dir test:

coverageDataDir:= target.value/"custom-test"

Can also be set through the sbt set directive

set coverageDataDir:= file("/tmp")

scoverage does a lot of file writing behind the scenes in order totrack which statements have been executed. If you are running into ascenario where your tests normally pass, but fail when scoverage isenabled, then the culprit can be one of the following:

• timing issues on futures and other async operations, try upping thetimeouts by an order of magnitude.
• tests are run in a sandbox mode (such as withjava.security.PrivilegedAction<T>), try running the tests outsideof the sandbox.

To see the plugin in action you can checkout the scoveragesamplesproject.

Codacy integrates with your favorite coverage tool to provide anin-depth overlook of your project status. scoverage information can beintegrated into Codacy through thecodacy-coverage-reporter.

If you have an open source project then you can publish the codecoverage metrics withCoveralls. This plugin will integrate withcoveralls using thesbt-coveralls plugin.

You can also integrate withCodecov by sending your reports therevia your CI. You can see an example incodecov-example-scala.

If you want to visually browse coverage reports then you can use theSonarQube plugin. It allows you to review overall projectstatement coverage as well as dig deeper into sub-modules, directoriesand source code files to see uncovered statements. Statement coveragemeasurement can become an integral part of your team's continuousintegration process and a required quality standard.

For any information on releases and upgrading, please refer to therelease page.