or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

aggregation.mdcobertura-reports.mdcoverage-model.mdhtml-reports.mdindex.mdio-utils.mdplugin.mdruntime.mdserialization.mdxml-reports.md
tile.json

tessl/maven-org-scoverage--scalac-scoverage-plugin

Comprehensive code coverage tool for Scala providing statement and branch coverage through compiler plugin instrumentation and report generation

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/org.scoverage/scalac-scoverage-plugin_2.13@2.3.x

To install, run

npx @tessl/cli install tessl/maven-org-scoverage--scalac-scoverage-plugin@2.3.0

index.mddocs/

Scalac Scoverage Plugin

Scalac Scoverage Plugin is a comprehensive code coverage tool for Scala that provides statement and branch coverage through compiler plugin instrumentation. It offers multiple modules working together to instrument code during compilation, collect coverage data during test execution, and generate detailed coverage reports in various formats including HTML, XML, and Cobertura.

Package Information

  • Package Name: scalac-scoverage-plugin (multi-module project)
  • Package Type: Maven/SBT
  • Language: Scala
  • Installation:
    • SBT Plugin: addSbtPlugin("org.scoverage" % "sbt-scoverage" % "2.3.0")
    • Direct Dependencies:
      • Plugin: "org.scoverage" %% "scalac-scoverage-plugin" % "2.3.0"
      • Reporter: "org.scoverage" %% "scalac-scoverage-reporter" % "2.3.0"
      • Domain: "org.scoverage" %% "scalac-scoverage-domain" % "2.3.0"
      • Runtime: "org.scoverage" %% "scalac-scoverage-runtime" % "2.3.0"
      • Serializer: "org.scoverage" %% "scalac-scoverage-serializer" % "2.3.0"

Core Imports

// Compiler plugin (used automatically when enabled)
import scoverage.{ScoveragePlugin, ScoverageOptions}

// Reporter module for generating reports
import scoverage.reporter._

// Domain model for coverage data
import scoverage.domain._

// Serialization support
import scoverage.serialize.Serializer

// Runtime instrumentation
import scoverage.Invoker

Basic Usage

SBT Plugin Setup (Recommended)

// project/plugins.sbt
addSbtPlugin("org.scoverage" % "sbt-scoverage" % "2.3.0")

// Run coverage
sbt clean coverage test coverageReport

Manual Report Generation

import java.io.File
import scoverage.reporter.{ScoverageHtmlWriter, ScoverageXmlWriter}
import scoverage.serialize.Serializer

// Load coverage data from serialized file
val dataDir = new File("target/scoverage-data")
val sourceRoot = new File("src/main/scala")
val coverageFile = Serializer.coverageFile(dataDir)
val coverage = Serializer.deserialize(coverageFile, sourceRoot)

// Apply measurement data
val measurementFiles = scoverage.reporter.IOUtils.findMeasurementFiles(dataDir)
val measurements = scoverage.reporter.IOUtils.invoked(measurementFiles.toIndexedSeq)
coverage.apply(measurements)

// Generate HTML report
val outputDir = new File("target/scoverage-report")
val htmlWriter = new ScoverageHtmlWriter(Seq(sourceRoot), outputDir, None)
htmlWriter.write(coverage)

// Generate XML report  
val xmlWriter = new ScoverageXmlWriter(Seq(sourceRoot), outputDir, false, None)
xmlWriter.write(coverage)

Compiler Plugin Configuration

// Enable compiler plugin with options
scalacOptions ++= Seq(
  "-Xplugin:path/to/scalac-scoverage-plugin.jar",
  "-P:scoverage:dataDir:target/scoverage-data",
  "-P:scoverage:reportTestName:true",
  "-P:scoverage:excludedPackages:.*\\.test\\..*"
)

Architecture

The project consists of five main modules working together:

  • Plugin Module (scoverage): Scala compiler plugin that instruments source code during compilation
  • Runtime Module (scoverage): Runtime support for collecting coverage measurements during execution
  • Domain Module (scoverage.domain): Core data model for coverage metrics, statements, and files
  • Serializer Module (scoverage.serialize): Coverage data persistence and loading utilities
  • Reporter Module (scoverage.reporter): Report generation in HTML, XML, and Cobertura formats

Capabilities

Compiler Plugin

Scala compiler plugin that instruments source code with coverage measurement calls during compilation.

class ScoveragePlugin(val global: Global) extends Plugin {
  val name: String
  val description: String
  val components: List[PluginComponent]
  def init(opts: List[String], error: String => Unit): Boolean
  val optionsHelp: Option[String]
}

case class ScoverageOptions(
  excludedPackages: Seq[String],
  excludedFiles: Seq[String], 
  excludedSymbols: Seq[String],
  dataDir: String,
  reportTestName: Boolean,
  sourceRoot: String
)

Compiler Plugin

Runtime Instrumentation

Runtime support for collecting coverage measurements during test execution.

object Invoker {
  def invoked(id: Int, dataDir: String, reportTestName: Boolean = false): Unit
  def measurementFile(dataDir: File): File
  def findMeasurementFiles(dataDir: File): Array[File]
  def invoked(files: Seq[File]): Set[Int]
}

Runtime Support

HTML Report Generation

Generates comprehensive visual HTML coverage reports with source code highlighting, coverage statistics, and interactive navigation.

class ScoverageHtmlWriter(
  sourceDirectories: Seq[File], 
  outputDir: File, 
  sourceEncoding: Option[String]
) extends BaseReportWriter {
  def write(coverage: Coverage): Unit
}

HTML Report Generation

XML Report Generation

Generates structured XML coverage reports in scoverage format for programmatic consumption and CI/CD integration.

class ScoverageXmlWriter(
  sourceDirectories: Seq[File],
  outputDir: File, 
  debug: Boolean,
  sourceEncoding: Option[String]
) extends BaseReportWriter {
  def write(coverage: Coverage): Unit
}

XML Report Generation

Cobertura XML Reports

Generates Cobertura-compatible XML reports for integration with build systems and coverage analysis tools.

class CoberturaXmlWriter(
  sourceDirectories: Seq[File],
  outputDir: File,
  sourceEncoding: Option[String]
) extends BaseReportWriter {
  def write(coverage: Coverage): Unit
}

Cobertura XML Reports

Coverage Data Model

Core data structures representing coverage information including statements, classes, methods, packages, and files with coverage metrics.

case class Coverage() extends CoverageMetrics with MethodBuilders 
    with ClassBuilders with PackageBuilders with FileBuilders {
  def add(stmt: Statement): Unit
  def addIgnoredStatement(stmt: Statement): Unit
  def apply(ids: Iterable[(Int, String)]): Unit
  def invoked(id: (Int, String)): Unit
  def risks(limit: Int): Seq[MeasuredClass]
}

case class Statement(
  location: Location,
  id: Int,
  start: Int,
  end: Int,
  line: Int,
  desc: String,
  symbolName: String,
  treeName: String,
  branch: Boolean,
  var count: Int = 0,
  ignored: Boolean = false,
  tests: mutable.Set[String] = mutable.Set[String]()
) {
  def source: String
  def invoked(test: String): Unit
  def isInvoked: Boolean
}

Coverage Data Model

Coverage Aggregation

Combines coverage data from multiple subprojects or test runs into unified reports.

object CoverageAggregator {
  def aggregate(dataDirs: Seq[File], sourceRoot: File): Option[Coverage]
  def aggregatedCoverage(dataDirs: Seq[File], sourceRoot: File): Coverage
}

Coverage Aggregation

Data Serialization

Persists and loads coverage data to/from files for report generation and analysis.

object Serializer {
  def serialize(coverage: Coverage, file: File, sourceRoot: File): Unit
  def serialize(coverage: Coverage, dataDir: String, sourceRoot: String): Unit
  def deserialize(file: File, sourceRoot: File): Coverage
  def coverageFile(dataDir: File): File
}

Data Serialization

File I/O Utilities

Provides utilities for working with coverage data files, measurement files, and report output.

object IOUtils {
  def findMeasurementFiles(dataDir: File): Array[File]
  def invoked(files: Seq[File], encoding: String = "UTF-8"): Set[(Int, String)]
  def writeToFile(file: File, str: String, encoding: Option[String]): Unit
  def clean(dataDir: File): Unit
  def reportFile(outputDir: File, debug: Boolean = false): File
}

File I/O Utilities

Types

Core Coverage Types

trait CoverageMetrics {
  def statements: Iterable[Statement]
  def statementCount: Int
  def ignoredStatements: Iterable[Statement]
  def ignoredStatementCount: Int
  def invokedStatements: Iterable[Statement]
  def invokedStatementCount: Int
  def statementCoverage: Double
  def statementCoveragePercent: Double
  def statementCoverageFormatted: String
  def branches: Iterable[Statement]
  def branchCount: Int
  def invokedBranches: Iterable[Statement]
  def invokedBranchesCount: Int
  def branchCoverage: Double
  def branchCoveragePercent: Double
  def branchCoverageFormatted: String
}

case class Location(
  packageName: String,
  className: String,
  fullClassName: String,
  classType: ClassType,
  method: String,
  sourcePath: String
)

sealed trait ClassType
object ClassType {
  case object Object extends ClassType
  case object Class extends ClassType
  case object Trait extends ClassType
  def fromString(str: String): ClassType
}

Measured Coverage Types

case class MeasuredClass(fullClassName: String, statements: Iterable[Statement]) 
    extends CoverageMetrics with MethodBuilders {
  def source: String
  def loc: Int
  def displayClassName: String
}

case class MeasuredMethod(name: String, statements: Iterable[Statement]) extends CoverageMetrics

case class MeasuredPackage(name: String, statements: Iterable[Statement]) 
    extends CoverageMetrics with ClassCoverage with ClassBuilders with FileBuilders

case class MeasuredFile(source: String, statements: Iterable[Statement]) 
    extends CoverageMetrics with ClassCoverage with ClassBuilders {
  def filename: String
  def loc: Int
}

Utility Types

sealed trait StatementStatus
case object Invoked extends StatementStatus
case object NotInvoked extends StatementStatus
case object NoData extends StatementStatus

case class ClassRef(name: String) {
  lazy val simpleName: String
  lazy val getPackage: String
}

object ClassRef {
  def fromFilepath(path: String): ClassRef
  def apply(_package: String, className: String): ClassRef
}

Filter Types

trait CoverageFilter {
  def isClassIncluded(className: String): Boolean
  def isFileIncluded(file: SourceFile): Boolean
  def isLineIncluded(position: Position): Boolean
  def isSymbolIncluded(symbolName: String): Boolean
  def getExcludedLineNumbers(sourceFile: SourceFile): List[Range]
}

class RegexCoverageFilter(
  excludedPackages: Seq[String],
  excludedFiles: Seq[String],
  excludedSymbols: Seq[String], 
  reporter: Reporter
) extends CoverageFilter

Error Handling

  • IOException: File I/O operations may throw IOException for invalid paths or permission issues
  • RuntimeException: Thrown when source roots cannot be found for relative path conversion
  • IllegalArgumentException: Thrown for malformed coverage data during deserialization
  • FileNotFoundException: Thrown when coverage files or measurement files are missing
  • CompilerException: Plugin initialization errors when invalid options are provided