0
# HTML Report Generation
1

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

4
## Core API
5

6
### ScoverageHtmlWriter Class
7

8
```scala { .api }
9
class ScoverageHtmlWriter(
10
  sourceDirectories: Seq[File],
11
  outputDir: File, 
12
  sourceEncoding: Option[String]
13
) extends BaseReportWriter(sourceDirectories, outputDir, sourceEncoding) {
14
  def write(coverage: Coverage): Unit
15
}
16
```
17

18
**Constructor Parameters:**
19
- `sourceDirectories`: Sequence of source directories for relative path calculation
20
- `outputDir`: Directory where HTML report files will be generated
21
- `sourceEncoding`: Optional character encoding for source files (defaults to UTF-8)
22

23
**Methods:**
24
- `write(coverage: Coverage): Unit` - Generates complete HTML report structure
25

26
### Alternative Constructors
27

28
```scala { .api }
29
// For Gradle plugin compatibility
30
class ScoverageHtmlWriter(
31
  sourceDirectories: Array[File],
32
  outputDir: File,
33
  sourceEncoding: Option[String]
34
)
35

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

39
// Backward compatibility - single source directory
40
class ScoverageHtmlWriter(sourceDirectory: File, outputDir: File)
41
```
42

43
## Usage Examples
44

45
### Basic HTML Report Generation
46

47
```scala
48
import java.io.File
49
import scoverage.reporter.ScoverageHtmlWriter
50
import scoverage.domain.Coverage
51

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

56
// Coverage object should be populated with data
57
val coverage: Coverage = loadCoverageData()
58
writer.write(coverage)
59
```
60

61
### Multi-Module Project with Multiple Source Directories
62

63
```scala
64
import java.io.File
65
import scoverage.reporter.ScoverageHtmlWriter
66

67
val sourceDirectories = Seq(
68
  new File("module1/src/main/scala"),
69
  new File("module2/src/main/scala"),
70
  new File("shared/src/main/scala")
71
)
72
val outputDir = new File("target/aggregated-coverage-report")
73
val writer = new ScoverageHtmlWriter(sourceDirectories, outputDir, Some("UTF-8"))
74

75
val aggregatedCoverage: Coverage = aggregateCoverageFromModules()
76
writer.write(aggregatedCoverage)
77
```
78

79
### Working with Different Character Encodings
80

81
```scala
82
// For projects using ISO-8859-1 encoding
83
val writer = new ScoverageHtmlWriter(
84
  sourceDirectories,
85
  outputDir,
86
  Some("ISO-8859-1")
87
)
88

89
// Using default UTF-8 encoding
90
val writerDefault = new ScoverageHtmlWriter(sourceDirectories, outputDir, None)
91
```
92

93
## Generated Report Structure
94

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

97
```
98
outputDir/
99
├── index.html          # Main entry point (frameset)
100
├── overview.html       # Overall coverage statistics
101
├── packages.html       # Package list with coverage
102
├── pure-min.css        # CSS styles
103
├── [package].html      # Package overview pages
104
└── [source-path].html  # Individual source file pages
105
```
106

107
### Report Components
108

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

115
## Report Features
116

117
### Coverage Highlighting
118
- **Green highlighting**: Covered statements and branches
119
- **Red highlighting**: Uncovered statements and branches  
120
- **Line numbers**: Displayed for easy navigation
121

122
### Interactive Elements
123
- **Sortable tables**: Click column headers to sort by coverage metrics
124
- **Navigation tabs**: Switch between code grid and statement list views
125
- **Clickable links**: Navigate between packages, classes, and source files
126

127
### Coverage Metrics Display
128
- Statement coverage percentages with visual progress bars
129
- Branch coverage percentages with visual progress bars
130
- Lines of code, method counts, and other statistics
131
- Risk analysis showing classes with lowest coverage
132

133
## Customization
134

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

138
### Source Code Display
139
Source code is displayed with:
140
- Syntax highlighting through coverage status
141
- Line numbers for easy reference
142
- Statement details including tree names and symbol names
143
- Test information showing which tests covered each statement
144

145
## Error Handling
146

147
**Common Issues:**
148
- `RuntimeException`: Thrown when source directories cannot be resolved to canonical paths
149
- `IOException`: File writing issues due to permissions or disk space
150
- `FileNotFoundException`: Source files referenced in coverage data but not found in source directories
151

152
**Best Practices:**
153
- Ensure output directory is writable
154
- Verify source directories exist and contain the expected source files
155
- Use appropriate character encoding matching your source files