Home

sbt-jacoco - Code Coverage via JaCoCo in sbt

This is an sbt plugin for code coverage analysis via JaCoCo. JaCoCo is a Java code coverage library developed by the makers of EclEmma (thanks, guys!).

Why use JaCoCo instead of a different code coverage tool?

• it's bytecode-based, so it works for Java and Scala.
• branch coverage (emma and scct have line coverage only).
• under active development (in contrast to emma and cobertura).

Usage

Install the plugin by adding the following to project/plugins.sbt:

addSbtPlugin("com.github.sbt" % "sbt-jacoco" % "<version>")

And then execute the plugin with sbt jacoco. This will instrument and run the unit tests and output the coverage metrics:

[info] ------- Jacoco Coverage Report --------
[info]
[info] Lines: 66.67% (>= required 0.0%) covered, 2 of 6 missed, OK
[info] Instructions: 83.54% (>= required 0.0%) covered, 13 of 79 missed, OK
[info] Branches: 0% (>= required 0.0%) covered, 0 of 0 missed, OK
[info] Methods: 57.14% (>= required 0.0%) covered, 3 of 7 missed, OK
[info] Complexity: 57.14% (>= required 0.0%) covered, 3 of 7 missed, OK
[info] Class: 50% (>= required 0.0%) covered, 2 of 4 missed, OK
[info]
[info] Check /home/example/jacoco-test/target/scala-2.11/jacoco/report for detailed report

A detailed HTML report will also be generated in the directory shown that includes line level details of coverage.

Integration Testing

For integration testing enable the the plugin using:

enablePlugins(JacocoItPlugin)

You will also need to remove the following lines from your config if you have them:

configs(IntegrationTest)
Defaults.itSettings

(this is due to a limitation in SBT where it's difficult for plugins to configure themselves for integration tests).

Once you have enabled the integration test plugin you will be able to cover the integration tests using sbt it:jacoco. Unit and integration tests will get merged automatically leaving you with the following reports:

• target/scala-2.10/jacoco/report/test/html/index.html
• target/scala-2.10/jacoco/report/it/html/index.html
• target/scala-2.10/jacoco/report/merged/html/index.html

Multi-Project Builds

TODO

Tasks

jacoco

Run the unit tests, save coverage data and generate coverage reports. This combines jacocoCheck and jacocoReport.

jacocoCheck

Run the unit tests and save coverage data.

jacocoReport

Generate coverage reports.

jacocoAggregate

Runs jacoco and aggregates the coverage reports. This combines jacoco and jacocoAggregateReport.

jacocoAggregateReport

Aggregate previously run coverage reports.

jacocoMergeData (integration test only)

Merge the coverage data saved from jacocoCheck and it:jacocoCheck. This is only needed if jacoco is run after it:jacoco.

jacocoMergedReport (integration test only)

Merge the coverage reports saved from jacocoReport and it:jacocoReport. This is only needed if jacoco is run after it:jacoco.

Settings

jacocoDirectory

• Description: Where JaCoCo should store its execution data and reports.
• Accepts: java.io.File
• Default: crossTarget / "jacoco"

jacocoReportDirectory

• Description: Where JaCoCo should output reports to.
• Accepts: java.io.File
• Default: jacocoDirectory / "report"

jacocoDataFile

• Description: Execution data output file.
• Accepts: java.io.File
• Default: jacocoDirectory / "data" / "jacoco.exec"

jacocoSourceSettings

• Description: Input source code settings (encoding etc) for reporting.
• Accepts: JacocoSourceSettings
• Default: JacocoSourceSettings(2, "utf-8")

JacocoSourceSettings parameters:

• tabWidth: tab width of source files.
• fileEncoding: file encoding of source files.

jacocoReportSettings

• Description: Settings for JaCoCo report (format, title etc).
• Accepts: JacocoReportSettings
• Default: JacocoReportSettings("Jacoco Coverage Report", None, JacocoThresholds(), Seq(JacocoReportFormats.ScalaHTML), "utf-8")

Note: jacocoReportSettings for integration tests has a title of "Jacoco Integration Test Coverage Report".

JacocoReportSettings parameters:

• title: title of the report.
• subDirectory: sub-directory under jacocoReportDirectory to store the report.
• thresholds: required coverage levels.
• formats: list of report fomats to use:
  • JacocoReportFormats.ScalaHTML
  • `JacocoReportFormats.HTML
  • JacocoReportFormats.XML
  • JacocoReportFormats.CSV
• fileEncoding: file encoding to use for reports.

jacocoAggregateReportSettings

• Description: Settings for aggregate JaCoCo report (format, title etc).
• Accepts: JacocoReportSettings
• Default: JacocoReportSettings("Jacoco Merged Coverage Report", None, JacocoThresholds(), Seq(JacocoReportFormats.ScalaHTML), "utf-8")

jacocoIncludes

• Description: Glob patterns specifying which classes to cover.
• Accepts: Seq[String]
• Default: all classes

Note: jacocoExcludes overrides jacocoIncludes.

jacocoExcludes

• Description: Glob patterns specifying which classes not to cover.
• Accepts: Seq[String]
• Default: none

jacocoInstrumentedDirectory

• Description: Directory containing the instrumented classes.
• Accepts: java.io.File
• Default: jacocoDirectory / "instrumented-classes"

jacocoMergedDataFile (integration test only)

• Description: Execution data file contain unit test and integration test data.
• Accepts: java.io.File
• Default: jacocoDirectory / "jacoco-it.exec"

jacocoMergedReportSettings (integration test only)

• Description: Settings for merged JaCoCo report (format, title etc).
• Accepts: JacocoReportSettings
• Default: JacocoReportSettings("Jacoco Merged Coverage Report", None, JacocoThresholds(), Seq(JacocoReportFormats.ScalaHTML), "utf-8")`

jacocoAutoMerge (integration test only)

• Description: whether to merge the unittest and integration test reports.
• Accepts: Boolean
• Default: true

Contributors

Many thanks to Alexey Pismenskiy, Andreas Flierl, Jason Zaugg, Joost den Boer and Patrick Mahoney for their awesome contributions!

License

This program and the accompanying materials are made available under the terms of the Eclipse Public License v1.0 which accompanies this distribution, and is available at http://www.eclipse.org/legal/epl-v10.html