Migrating from 2.x to 3.x

Note: 3.0 is currently in pre-release and things are likely to change.

sbt-jacoco 3.0 is a major overhaul of the plugin to bring it inline with the current SBT Plugins Best Practices. These changes mean upgrading from jacoco4sbt 2.x to sbt-jacoco 3.0 requires a number of configuration changes.

Artefact Name Change

The jacoco4sbt project has been renamed to sbt-jacoco and the artefacts renamed to match. You will need to update your plugins.sbt to:

addSbtPlugin("com.github.sbt" % "sbt-jacoco" % "3.0.1")

Changes to Plugin Loading

With jacoco4sbt 2.x you needed to add the settings to your build.sbt with:

jacoco.settings

// and if you are using integration tests:
itJacoco.settings

In sbt-jacoco 3.0 this step is no longer necessary as the plugin settings are automatically added and the build enabled for unit tests. For integration tests you will need to enable a separate plugin using:

enablePlugins(JacocoItPlugin)

Note: due to current limitations in SBT the JacocoItPlugin won't work if you have the following in your build.sbt:

configs(IntegrationTest)
Defaults.itSettings

The JacocoItPlugin automatically adds the IntegrationTest configuration and itSettings.

Configuration, Setting & Task Key Changes

Configurations

These have been removed and the tasks moved to the built in Test and IntegrationTest configs.

Tasks

Old Name	New Name
cover	jacoco
check	jacocoCheck
report	jacocoReport
clean	removed
aggregateCover	jacocoAggregate
aggregateReport	jacocoAggregateReport
conditionalMerge	jacocoMergeData
forceMerge	jacocoMergeData
new	jacocoMergedReport

Settings

Old Name	New Name
outputDirectory	jacocoDirectory
executionDataFile	jacocoDataFile
reportTitle	jacocoReportSettings1
reportFormats	jacocoReportSettings1
sourceTabWidth	jacocoSourceSettings2
sourceEncoding	jacocoSourceSettings2
thresholds	jacocoReportSettings1
includes	jacocoIncludes
excludes	jacocoExcludes
aggregateReportDirectory	jacocoAggregateReportDirectory
aggregateReportTitle	jacocoAggregateReportSettings1
aggregateThresholds	jacocoAggregateReportSettings1
mergeReports	jacocoAutoMerge
new	jacocoMergedDataFile

1. See JacocoReportSettings below for details.
2. See JacocoSourceSettings below.

JacocoReportSettings

These can be set for single report using jacocoReportSettings and jacocoAggregateReportSettings for aggregate reports.

• withTitle - replaces reportTitle and aggregateReportTitle
• withThresholds - replaces thresholds and aggregateThresholds
• withFormats - replaces reportFormats
• withFileEncoding - new

eg:

jacocoReportSettings := JacocoReportSettings().withTitle("My JaCoCo Report")

JacocoSourceSettings

These can be set for using jacocoSourceSettings.

• withTabWidth - replaces sourceTabWidth.
• withFileEncoding - replaces sourceEncoding.

eg:

jacocoSourceSettings := JacocoSourceSettings().withTabWidth(4)

Directory Structure Changes

The output directory structure has been updated to be more consistent and to remove conflicts between different reports.

Single project example

target/scala-2.12/jacoco
├── data
│   └── jacoco.exec
├── instrumented-classes
│   └── <class files>
└── report
    ├── html
    │   ├── index.html
    │   └── <supporting files>
    ├── jacoco.csv
    └── jacoco.xml

Project with integration tests example

target/scala-2.12/jacoco
├── data
│   ├── jacoco-it.exec
│   ├── jacoco-merged.exec
│   └── jacoco.exec
├── instrumented-classes
│   └── <class files>
└── report
    ├── it
    │   └── html
    │       ├── index.html
    │       └── <supporting files>
    ├── merged
    │   └── html
    │       ├── index.html
    │       └── <supporting files>
    └── test
        └── html
            ├── index.html
            └── <supporting files>

Multi-project example

base
├── common
│   └── target
│       └── scala-2.12
│           └── jacoco
│               ├── data
│               │   └── jacoco.exec
│               ├── instrumented-classes
│               │   └── <class files>
│               └── report
│                   └── html
│                       ├── index.html
│                       └── <supporting files>
├── extras
│   └── target
│       └── scala-2.12
│           ├── classes
│           └── jacoco
│               ├── data
│               │   └── jacoco.exec
│               ├── instrumented-classes
│               │   └── <class files>
│               └── report
│                   └── html
│                       ├── index.html
│                       └── <supporting files>
└── target
    └── scala-2.12
        └── jacoco
            └── report
                └── aggregate
                    └── html
                        ├── index.html
                        └── <supporting files>