0
# Scalac Scoverage Plugin
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: scalac-scoverage-plugin (multi-module project)
7
- **Package Type**: Maven/SBT
8
- **Language**: Scala  
9
- **Installation**: 
10
  - **SBT Plugin**: `addSbtPlugin("org.scoverage" % "sbt-scoverage" % "2.3.0")`
11
  - **Direct Dependencies**:
12
    - Plugin: `"org.scoverage" %% "scalac-scoverage-plugin" % "2.3.0"`
13
    - Reporter: `"org.scoverage" %% "scalac-scoverage-reporter" % "2.3.0"`
14
    - Domain: `"org.scoverage" %% "scalac-scoverage-domain" % "2.3.0"`
15
    - Runtime: `"org.scoverage" %% "scalac-scoverage-runtime" % "2.3.0"`
16
    - Serializer: `"org.scoverage" %% "scalac-scoverage-serializer" % "2.3.0"`
17

18
## Core Imports
19

20
```scala
21
// Compiler plugin (used automatically when enabled)
22
import scoverage.{ScoveragePlugin, ScoverageOptions}
23

24
// Reporter module for generating reports
25
import scoverage.reporter._
26

27
// Domain model for coverage data
28
import scoverage.domain._
29

30
// Serialization support
31
import scoverage.serialize.Serializer
32

33
// Runtime instrumentation
34
import scoverage.Invoker
35
```
36

37
## Basic Usage
38

39
### SBT Plugin Setup (Recommended)
40

41
```scala
42
// project/plugins.sbt
43
addSbtPlugin("org.scoverage" % "sbt-scoverage" % "2.3.0")
44

45
// Run coverage
46
sbt clean coverage test coverageReport
47
```
48

49
### Manual Report Generation
50

51
```scala
52
import java.io.File
53
import scoverage.reporter.{ScoverageHtmlWriter, ScoverageXmlWriter}
54
import scoverage.serialize.Serializer
55

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

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

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

72
// Generate XML report  
73
val xmlWriter = new ScoverageXmlWriter(Seq(sourceRoot), outputDir, false, None)
74
xmlWriter.write(coverage)
75
```
76

77
### Compiler Plugin Configuration
78

79
```scala
80
// Enable compiler plugin with options
81
scalacOptions ++= Seq(
82
  "-Xplugin:path/to/scalac-scoverage-plugin.jar",
83
  "-P:scoverage:dataDir:target/scoverage-data",
84
  "-P:scoverage:reportTestName:true",
85
  "-P:scoverage:excludedPackages:.*\\.test\\..*"
86
)
87
```
88

89
## Architecture
90

91
The project consists of five main modules working together:
92

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

99
## Capabilities
100

101
### Compiler Plugin
102

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

105
```scala { .api }
106
class ScoveragePlugin(val global: Global) extends Plugin {
107
  val name: String
108
  val description: String
109
  val components: List[PluginComponent]
110
  def init(opts: List[String], error: String => Unit): Boolean
111
  val optionsHelp: Option[String]
112
}
113

114
case class ScoverageOptions(
115
  excludedPackages: Seq[String],
116
  excludedFiles: Seq[String], 
117
  excludedSymbols: Seq[String],
118
  dataDir: String,
119
  reportTestName: Boolean,
120
  sourceRoot: String
121
)
122
```
123

124
[Compiler Plugin](./plugin.md)
125

126
### Runtime Instrumentation
127

128
Runtime support for collecting coverage measurements during test execution.
129

130
```scala { .api }
131
object Invoker {
132
  def invoked(id: Int, dataDir: String, reportTestName: Boolean = false): Unit
133
  def measurementFile(dataDir: File): File
134
  def findMeasurementFiles(dataDir: File): Array[File]
135
  def invoked(files: Seq[File]): Set[Int]
136
}
137
```
138

139
[Runtime Support](./runtime.md)
140

141
### HTML Report Generation
142

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

145
```scala { .api }
146
class ScoverageHtmlWriter(
147
  sourceDirectories: Seq[File], 
148
  outputDir: File, 
149
  sourceEncoding: Option[String]
150
) extends BaseReportWriter {
151
  def write(coverage: Coverage): Unit
152
}
153
```
154

155
[HTML Report Generation](./html-reports.md)
156

157
### XML Report Generation
158

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

161
```scala { .api }
162
class ScoverageXmlWriter(
163
  sourceDirectories: Seq[File],
164
  outputDir: File, 
165
  debug: Boolean,
166
  sourceEncoding: Option[String]
167
) extends BaseReportWriter {
168
  def write(coverage: Coverage): Unit
169
}
170
```
171

172
[XML Report Generation](./xml-reports.md)
173

174
### Cobertura XML Reports
175

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

178
```scala { .api }
179
class CoberturaXmlWriter(
180
  sourceDirectories: Seq[File],
181
  outputDir: File,
182
  sourceEncoding: Option[String]
183
) extends BaseReportWriter {
184
  def write(coverage: Coverage): Unit
185
}
186
```
187

188
[Cobertura XML Reports](./cobertura-reports.md)
189

190
### Coverage Data Model
191

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

194
```scala { .api }
195
case class Coverage() extends CoverageMetrics with MethodBuilders 
196
    with ClassBuilders with PackageBuilders with FileBuilders {
197
  def add(stmt: Statement): Unit
198
  def addIgnoredStatement(stmt: Statement): Unit
199
  def apply(ids: Iterable[(Int, String)]): Unit
200
  def invoked(id: (Int, String)): Unit
201
  def risks(limit: Int): Seq[MeasuredClass]
202
}
203

204
case class Statement(
205
  location: Location,
206
  id: Int,
207
  start: Int,
208
  end: Int,
209
  line: Int,
210
  desc: String,
211
  symbolName: String,
212
  treeName: String,
213
  branch: Boolean,
214
  var count: Int = 0,
215
  ignored: Boolean = false,
216
  tests: mutable.Set[String] = mutable.Set[String]()
217
) {
218
  def source: String
219
  def invoked(test: String): Unit
220
  def isInvoked: Boolean
221
}
222
```
223

224
[Coverage Data Model](./coverage-model.md)
225

226
### Coverage Aggregation
227

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

230
```scala { .api }
231
object CoverageAggregator {
232
  def aggregate(dataDirs: Seq[File], sourceRoot: File): Option[Coverage]
233
  def aggregatedCoverage(dataDirs: Seq[File], sourceRoot: File): Coverage
234
}
235
```
236

237
[Coverage Aggregation](./aggregation.md)
238

239
### Data Serialization
240

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

243
```scala { .api }
244
object Serializer {
245
  def serialize(coverage: Coverage, file: File, sourceRoot: File): Unit
246
  def serialize(coverage: Coverage, dataDir: String, sourceRoot: String): Unit
247
  def deserialize(file: File, sourceRoot: File): Coverage
248
  def coverageFile(dataDir: File): File
249
}
250
```
251

252
[Data Serialization](./serialization.md)
253

254
### File I/O Utilities
255

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

258
```scala { .api }
259
object IOUtils {
260
  def findMeasurementFiles(dataDir: File): Array[File]
261
  def invoked(files: Seq[File], encoding: String = "UTF-8"): Set[(Int, String)]
262
  def writeToFile(file: File, str: String, encoding: Option[String]): Unit
263
  def clean(dataDir: File): Unit
264
  def reportFile(outputDir: File, debug: Boolean = false): File
265
}
266
```
267

268
[File I/O Utilities](./io-utils.md)
269

270
## Types
271

272
### Core Coverage Types
273

274
```scala { .api }
275
trait CoverageMetrics {
276
  def statements: Iterable[Statement]
277
  def statementCount: Int
278
  def ignoredStatements: Iterable[Statement]
279
  def ignoredStatementCount: Int
280
  def invokedStatements: Iterable[Statement]
281
  def invokedStatementCount: Int
282
  def statementCoverage: Double
283
  def statementCoveragePercent: Double
284
  def statementCoverageFormatted: String
285
  def branches: Iterable[Statement]
286
  def branchCount: Int
287
  def invokedBranches: Iterable[Statement]
288
  def invokedBranchesCount: Int
289
  def branchCoverage: Double
290
  def branchCoveragePercent: Double
291
  def branchCoverageFormatted: String
292
}
293

294
case class Location(
295
  packageName: String,
296
  className: String,
297
  fullClassName: String,
298
  classType: ClassType,
299
  method: String,
300
  sourcePath: String
301
)
302

303
sealed trait ClassType
304
object ClassType {
305
  case object Object extends ClassType
306
  case object Class extends ClassType
307
  case object Trait extends ClassType
308
  def fromString(str: String): ClassType
309
}
310
```
311

312
### Measured Coverage Types
313

314
```scala { .api }
315
case class MeasuredClass(fullClassName: String, statements: Iterable[Statement]) 
316
    extends CoverageMetrics with MethodBuilders {
317
  def source: String
318
  def loc: Int
319
  def displayClassName: String
320
}
321

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

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

327
case class MeasuredFile(source: String, statements: Iterable[Statement]) 
328
    extends CoverageMetrics with ClassCoverage with ClassBuilders {
329
  def filename: String
330
  def loc: Int
331
}
332
```
333

334
### Utility Types
335

336
```scala { .api }
337
sealed trait StatementStatus
338
case object Invoked extends StatementStatus
339
case object NotInvoked extends StatementStatus
340
case object NoData extends StatementStatus
341

342
case class ClassRef(name: String) {
343
  lazy val simpleName: String
344
  lazy val getPackage: String
345
}
346

347
object ClassRef {
348
  def fromFilepath(path: String): ClassRef
349
  def apply(_package: String, className: String): ClassRef
350
}
351
```
352

353
### Filter Types
354

355
```scala { .api }
356
trait CoverageFilter {
357
  def isClassIncluded(className: String): Boolean
358
  def isFileIncluded(file: SourceFile): Boolean
359
  def isLineIncluded(position: Position): Boolean
360
  def isSymbolIncluded(symbolName: String): Boolean
361
  def getExcludedLineNumbers(sourceFile: SourceFile): List[Range]
362
}
363

364
class RegexCoverageFilter(
365
  excludedPackages: Seq[String],
366
  excludedFiles: Seq[String],
367
  excludedSymbols: Seq[String], 
368
  reporter: Reporter
369
) extends CoverageFilter
370
```
371

372
## Error Handling
373

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