HTML Report Generation

The ScoverageHtmlWriter generates comprehensive visual HTML coverage reports with source code highlighting, coverage statistics tables, and interactive navigation. The generated reports include overview pages, package breakdowns, class listings, and individual source file views with line-by-line coverage highlighting.

Core API

ScoverageHtmlWriter Class

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

Constructor Parameters:

• sourceDirectories: Sequence of source directories for relative path calculation
• outputDir: Directory where HTML report files will be generated
• sourceEncoding: Optional character encoding for source files (defaults to UTF-8)

Methods:

• write(coverage: Coverage): Unit - Generates complete HTML report structure

Alternative Constructors

// For Gradle plugin compatibility
class ScoverageHtmlWriter(
  sourceDirectories: Array[File],
  outputDir: File,
  sourceEncoding: Option[String]
)

// Backward compatibility - no encoding specified
class ScoverageHtmlWriter(sourceDirectories: Seq[File], outputDir: File)

// Backward compatibility - single source directory
class ScoverageHtmlWriter(sourceDirectory: File, outputDir: File)

Usage Examples

Basic HTML Report Generation

import java.io.File
import scoverage.reporter.ScoverageHtmlWriter
import scoverage.domain.Coverage

val sourceDirectories = Seq(new File("src/main/scala"))
val outputDir = new File("target/scoverage-report")
val writer = new ScoverageHtmlWriter(sourceDirectories, outputDir, Some("UTF-8"))

// Coverage object should be populated with data
val coverage: Coverage = loadCoverageData()
writer.write(coverage)

Multi-Module Project with Multiple Source Directories

import java.io.File
import scoverage.reporter.ScoverageHtmlWriter

val sourceDirectories = Seq(
  new File("module1/src/main/scala"),
  new File("module2/src/main/scala"),
  new File("shared/src/main/scala")
)
val outputDir = new File("target/aggregated-coverage-report")
val writer = new ScoverageHtmlWriter(sourceDirectories, outputDir, Some("UTF-8"))

val aggregatedCoverage: Coverage = aggregateCoverageFromModules()
writer.write(aggregatedCoverage)

Working with Different Character Encodings

// For projects using ISO-8859-1 encoding
val writer = new ScoverageHtmlWriter(
  sourceDirectories,
  outputDir,
  Some("ISO-8859-1")
)

// Using default UTF-8 encoding
val writerDefault = new ScoverageHtmlWriter(sourceDirectories, outputDir, None)

Generated Report Structure

The HTML writer creates the following file structure in the output directory:

outputDir/
├── index.html          # Main entry point (frameset)
├── overview.html       # Overall coverage statistics
├── packages.html       # Package list with coverage
├── pure-min.css        # CSS styles
├── [package].html      # Package overview pages
└── [source-path].html  # Individual source file pages

Report Components

Main Index (index.html): Frameset-based navigation interface Overview (overview.html): Project-wide coverage statistics and class listings Packages (packages.html): Navigation list of all packages with coverage percentages Package Pages: Detailed view of classes within each package Source Pages: Individual source files with line-by-line coverage highlighting

Report Features

Coverage Highlighting

• Green highlighting: Covered statements and branches
• Red highlighting: Uncovered statements and branches
• Line numbers: Displayed for easy navigation

Interactive Elements

• Sortable tables: Click column headers to sort by coverage metrics
• Navigation tabs: Switch between code grid and statement list views
• Clickable links: Navigate between packages, classes, and source files

Coverage Metrics Display

• Statement coverage percentages with visual progress bars
• Branch coverage percentages with visual progress bars
• Lines of code, method counts, and other statistics
• Risk analysis showing classes with lowest coverage

Customization

CSS Styling

The generated reports use Bootstrap CSS and custom styling. The CSS is embedded in the report for self-contained viewing.

Source Code Display

Source code is displayed with:

• Syntax highlighting through coverage status
• Line numbers for easy reference
• Statement details including tree names and symbol names
• Test information showing which tests covered each statement

Error Handling

Common Issues:

• RuntimeException: Thrown when source directories cannot be resolved to canonical paths
• IOException: File writing issues due to permissions or disk space
• FileNotFoundException: Source files referenced in coverage data but not found in source directories

Best Practices:

• Ensure output directory is writable
• Verify source directories exist and contain the expected source files
• Use appropriate character encoding matching your source files