DOCSEARCHbyAlgolia
Submit Docs

sbt-scoverage

repository·main·Indexed 20 days ago

https://github.com/scoverage/sbt-scoverage

An sbt plugin providing Scala code coverage support using the scoverage engine. It supports Scala 2, 2.13, and 3 (3.2.x+), allowing developers to instrument code, generate HTML, XML, and Cobertura reports, and enforce minimum coverage thresholds for statements and branches. Features include aggregated reports for multi-project builds via coverageAggregate, package and file exclusions using regular expressions, and command aliases for toggling coverage state.

Tokens
1.9K
Snippets
10
Records
12
Agent score
21%

What's inside sbt-scoverage

  1. Generate coverage reports

    main

    After running tests with coverage enabled, generate the reports using coverageReport.

    Reports are located in: target/scala-<scala-version>/scoverage-report.

    Available formats:

    • HTML: For visual browsing.
    • XML: For programmatic use or external tools.
    sbt coverageReport

  2. Install sbt-scoverage

    main

    To use sbt-scoverage, add the plugin to your project/plugins.sbt file. Requires sbt 1.2.8 or above.

    Supported Scala Versions:

    • Scala 2.12, 2.13, and 3 (Scala 3 support requires 3.2.x or higher).
    • ScalaJS and Scala Native support is limited to Scala 2.

    Note on Instrumentation: Running coverage instruments your build output. Always run clean with coverage disabled before publishing your build to avoid including instrumentation in your artifacts.

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

  3. Run tests with coverage enabled

    main

    To run your tests while collecting coverage data, use the coverage command before your test command.

    For standard tests:

    sbt clean coverage test

    For integration tests:

    sbt clean coverage it:test

    Managing Coverage State in sbt Console: If you are working within an active sbt session, the coverage command is 'sticky'. To disable it, use:

    • coverageOff
    • Or set coverageEnabled := false

  4. Generate aggregated reports for multi-project builds

    main

    By default, scoverage generates separate reports for each sub-project. To create a single merged report for the entire build, use coverageAggregate.

    Note: You do not need to run coverageReport before running coverageAggregate; it aggregates directly from the sub-projects' coverage data.

    sbt coverageAggregate

  5. Override coverage data and report locations

    main

    You can change the default directory where coverage data and reports are stored using coverageDataDir.

    // In build definition
coverageDataDir := target.value / "custom-test"

// Via sbt set directive
set coverageDataDir := file("/tmp")

  6. Configure minimum coverage thresholds

    main

    You can fail the build if coverage falls below specific thresholds. These settings are enforced when reports are generated and apply to aggregate reports if using coverageAggregate.

    Available keys:

    • coverageFailOnMinimum: Set to true to enable enforcement.
    • coverageMinimumStmtTotal: Minimum total statements.
    • coverageMinimumBranchTotal: Minimum total branches.
    • coverageMinimumStmtPerPackage: Minimum statements per package.
    • coverageMinimumBranchPerPackage: Minimum branches per package.
    • coverageMinimumStmtPerFile: Minimum statements per file.
    • coverageMinimumBranchPerFile: Minimum branches per file.
    coverageFailOnMinimum := true
coverageMinimumStmtTotal := 90
coverageMinimumBranchTotal := 90
coverageMinimumStmtPerPackage := 90
coverageMinimumBranchPerPackage := 85
coverageMinimumStmtPerFile := 85
coverageMinimumBranchPerFile := 80

  7. Exclude classes, packages, and files from coverage

    main

    You can prevent specific code from being instrumented or included in reports using regular expressions.

    Supported Scala Versions: These options work for Scala 2, Scala 3.3.4+, and Scala 3.4.2+.

    Exclude Packages/Classes

    Use coverageExcludedPackages with a semicolon-separated list of regexes. Regexes are matched against the fully qualified class name and must match the entire string.

    Exclude Files

    Use coverageExcludedFiles with a semicolon-separated list of regexes. Note: Omit the .scala extension from filenames.

    Comment-based Exclusion (Scala 2 Only)

    You can wrap code blocks in comments to exclude them from instrumentation:

    // $COVERAGE-OFF$
... code to exclude ...
// $COVERAGE-ON$
    // Exclude packages/classes
coverageExcludedPackages := "<empty>;Reverse.*;.*AuthService.*;models\\.data\\..*"

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

  8. Troubleshoot failing tests with scoverage

    main

    If tests pass normally but fail when coverage is enabled, it is likely due to the file-writing overhead required for tracking statement execution. Common causes include:

    1. Async Timing Issues: Timing issues with Futures or other async operations. Try increasing timeouts by an order of magnitude.
    2. Sandboxing: Tests running in a sandbox (e.g., java.security.PrivilegedAction). Try running tests outside the sandbox.

  9. Configure sbt-scoverage settings

    main

    sbt-scoverage provides several settings to control coverage behavior. These can be configured in your build.sbt file.

    Coverage Control

    • coverageEnabled: Boolean. Enables or disables coverage instrumentation. Defaults to false.
    • coverageFailOnMinimum: Boolean. If true, the build will fail if coverage thresholds are not met.

    Exclusions

    • coverageExcludedPackages: String. A semicolon-separated list of packages to exclude from coverage.
    • coverageExcludedFiles: String. A semicolon-separated list of files to exclude from coverage.

    Thresholds (Minimum Coverage)

    If coverageFailOnMinimum is true, the following thresholds are used:

    • coverageMinimumStmtTotal: Minimum total statement coverage percentage.
    • coverageMinimumBranchTotal: Minimum total branch coverage percentage.
    • coverageMinimumStmtPerPackage: Minimum statement coverage percentage per package.
    • coverageMinimumBranchPerPackage: Minimum branch coverage percentage per package.
    • coverageMinimumStmtPerFile: Minimum statement coverage percentage per file.
    • coverageMinimumBranchPerFile: Minimum branch coverage percentage per file.

    Output Formats

    Control which reports are generated:

    • coverageOutputXML: Boolean. Generates an XML report (defaults to true).
    • coverageOutputHTML: Boolean. Generates an HTML report (defaults to true).
    • coverageOutputCobertura: Boolean. Generates a Cobertura XML report (defaults to true).
    • coverageOutputDebug: Boolean. If true, generates a debug version of the XML report.
    • coverageOutputTeamCity: Boolean. Generates TeamCity-compatible statistics.

    Other Settings

    • coverageDataDir: The directory where coverage data and reports are stored. Defaults to crossTarget.value.
    • coverageSourceRoot: The root directory for source files. Defaults to (ThisBuild / baseDirectory).value.