Skip to content

Home

Jump to bottom
Joachim Hofer edited this page May 10, 2014 · 12 revisions

jacoco4sbt - Code Coverage via JaCoCo from within 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 JaCoCo?

  • 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

Add the following imports to the top of your project's build.sbt file:

import de.johoop.jacoco4sbt._
import JacocoPlugin._

and the following line to an arbitrary place within the same file:

jacoco.settings

Also, you have to add the plugin dependency to your project's ./project/plugins.sbt or the global .sbt/0.13/plugins/build.sbt:

addSbtPlugin("de.johoop" % "jacoco4sbt" % "2.1.5")

Now, you can run your tests simply via sbt jacoco:cover and will receive a HTML report in the jacoco/html subdirectory of your target directory. Or you can run your tests via jacoco:test and later (as long as you stay in interactive mode) generate a report about them via jacoco:report.

There's also jacoco:check which will run your tests and save the coverage data for later use, even in non-interactive mode.

One caveat though: As you may have noticed, this plugin works in its own configuration, which is based on the test configuration. So, any settings you would normally define in the test configuration, you have to also define in the jacoco configuration for the plugin to work as expected.

One specific example of this is the parallelExecution setting, which gets set to false in the test configuration by the Play framework. However, the Play framework does not know about your using the JaCoCo plugin, of course. So you have to manually set that setting to false in the jacoco configuration:

parallelExecution in jacoco.Config := false

You can check the value of this setting (or any others) in interactive mode using

jacoco:parallelExecution

Integration Testing

For integration testing, add the following line to your project's build.sbt file:

itJacoco.settings

This will create an additional configuration it-jacoco, which can be used exactly like the jacoco configuration, only that it is based on SBT's it configuration for integration testing. All the caveats from the section above apply here, too.

There's one additional task defined in it-jacoco: Via it-jacoco:merge, you can explicitly merge the unit and integration test coverage data files. By default, this is done automatically, as long as you do not explicitly switch it off via the merge-reports setting (see below).

In order to receive a combined coverage report (with the default it-jacoco:merge-reports), the full workflow would be:

jacoco:check
itJacoco:cover

For more information about integration testing in SBT, see here.

Tasks

All tasks have to be defined within the jacoco or it-jacoco configuration. This means a prefix of jacoco: or itJacoco: in the interactive shell, or adding in jacoco.Config or in itJacoco.Config in your build file.

clean

Cleans the JaCoCo output directory selectively.

test

Runs the tests while collecting coverage data in-memory.

Note: this is only useful in interactive-mode! It does not store the collected data in a file.

check

Runs the tests while collecting coverage data, and then dumps the collected data to a file in the JaCoCo output directory.

report

Creates a report from collected coverage data.

cover

This is the all-in-one task: Runs the tests while collecting coverage data, dumps it to a file and then creates a coverage report from it.

Tasks (Integration Test only)

The following task is additionally available in the it-jacoco configuration.

merge

Explicitly merges the JaCoCo coverage data files from the unit test and integration test output directories (if available).

Settings

All settings have to be defined within the jacoco or it-jacoco configuration. This means a prefix of jacoco: or itJacoco: in the interactive shell, or adding in jacoco.Config or in itJacoco.Config in your build file.

Here's an example setting (generate the report as xml as well as html):

jacoco.reportFormats in jacoco.Config := Seq(
  XMLReport(encoding = "utf-8"), 
  ScalaHTMLReport(withBranchCoverage = true))

outputDirectory

  • Description: Base directory for JaCoCo execution data and reports.
  • Accepts: java.io.File
  • Default: crossTarget / "jacoco" (or crossTarget / "it-jacoco" for integration testing)

reportFormats

  • Description: Determines what types of reports to generate.
  • Accepts: Seq[de.johoop.jacoco4sbt.{HTML, ScalaHTML, XML, CSV}Report]
  • Default: Seq(ScalaHTMLReport(encoding = "utf-8", withBranchCoverage = false))

{HTML, XML, CSV}Report are case classes optionally accepting the additional parameter encoding (defaults to "utf-8").

includes

  • Description: Glob patterns specifying which class files to cover. The pattern is based on file paths, not on package/class names; excludes override includes
  • Accepts: Seq[String]
  • Default: Seq("*") (all classes included)

excludes

  • Description: Glob patterns specifying which class files not to cover; excludes override includes
  • Accepts: Seq[String]
  • Default: Seq() (no classes excluded)

reportTitle

  • Description: Title of the JaCoCo report to generate.
  • Accepts: String
  • Default: "JaCoCo Coverage Report"

sourceTabWidth

  • Description: How many spaces tabs in the source code should be converted to for the JaCoCo report.
  • Accepts: Int
  • Default: 2

sourceEncoding

  • Description: File encoding of the source files.
  • Accepts: Any valid encodings (as strings)
  • Default: "utf-8"

Settings (Integration Test only)

The following additional settings are only available in the it-jacoco configuration.

mergeReports

  • Description: Whether to merge unit and integration test coverage 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

Clone this wiki locally