0
# Solidity Coverage
1

2
Solidity Coverage is a comprehensive code coverage analysis tool for Solidity smart contract testing within the Hardhat development environment. It acts as a Hardhat plugin that instruments Solidity contracts to measure statement, function, and modifier coverage during test execution, generating detailed Istanbul coverage reports in multiple formats.
3

4
## Package Information
5

6
- **Package Name**: solidity-coverage
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install --save-dev solidity-coverage`
10

11
## Core Imports
12

13
**Hardhat Plugin (Primary Usage):**
14

15
```javascript
16
require('solidity-coverage');
17
```
18

19
Or with TypeScript:
20

21
```typescript
22
import 'solidity-coverage';
23
```
24

25
**Programmatic API:**
26

27
```javascript
28
const API = require('solidity-coverage/api');
29
```
30

31
**Utility Functions:**
32

33
```javascript
34
const utils = require('solidity-coverage/utils');
35
```
36

37
## Basic Usage
38

39
**Primary Usage as Hardhat Plugin:**
40

41
Add the plugin to your `hardhat.config.js`:
42

43
```javascript
44
require('solidity-coverage');
45

46
module.exports = {
47
  solidity: "0.8.19",
48
  // other config...
49
};
50
```
51

52
Run coverage analysis:
53

54
```bash
55
npx hardhat coverage
56
```
57

58
**Configuration via .solcover.js:**
59

60
```javascript
61
module.exports = {
62
  skipFiles: ['contracts/mocks/'],
63
  istanbulReporter: ['html', 'lcov', 'text'],
64
  measureStatementCoverage: true,
65
  measureFunctionCoverage: true,
66
  measureModifierCoverage: true,
67
  measureLineCoverage: true,
68
  measureBranchCoverage: true,
69
  onServerReady: () => console.log('Coverage server ready'),
70
  onTestsComplete: () => console.log('Tests completed'),
71
};
72
```
73

74
## Architecture
75

76
Solidity Coverage is built around several key components:
77

78
- **Hardhat Plugin**: Primary interface integrating with Hardhat's compilation and testing pipeline
79
- **Instrumentation Engine**: Core `Instrumenter` class that modifies Solidity source code to inject coverage tracking calls
80
- **Data Collection System**: `DataCollector` class that hooks into Hardhat's EVM to capture execution traces during test runs
81
- **Coverage Generation**: `Coverage` class that converts execution data into Istanbul-compatible coverage reports
82
- **Configuration System**: Flexible configuration via `.solcover.js` files and CLI options with full validation
83
- **UI System**: Pluggable UI classes (`UI`, `AppUI`, `PluginUI`) for different output formats and reporting
84
- **Utility Framework**: Comprehensive utility functions for file management, path resolution, and Hardhat integration
85

86
## Capabilities
87

88
### Hardhat Plugin Interface
89

90
The primary interface for running coverage analysis within Hardhat projects. Provides the `coverage` task with extensive configuration options.
91

92
```bash { .api }
93
npx hardhat coverage [options]
94

95
Options:
96
  --testfiles <path>    # Glob path to subset of test files
97
  --solcoverjs <path>   # Relative path to .solcover.js config file
98
  --temp <path>         # Relative path to temp directory for artifacts
99
  --sources <path>      # Relative path to contracts directory
100
  --matrix             # Generate test matrix data instead of coverage
101
  --abi                # Generate human readable ABI list
102
```
103

104
[Hardhat Plugin](./hardhat-plugin.md)
105

106
### Programmatic API
107

108
Direct access to the coverage instrumentation and reporting engine for custom workflows and advanced integrations.
109

110
```javascript { .api }
111
const API = require('solidity-coverage/api');
112

113
class API {
114
  constructor(config?: CoverageConfig);
115
  instrument(targets: Target[]): InstrumentedTarget[];
116
  report(folder?: string): Promise<void>;
117
  attachToHardhatVM(provider: HardhatProvider): Promise<void>;
118
  // ... additional methods
119
}
120

121
interface Target {
122
  source: string;
123
  canonicalPath: string;
124
  relativePath?: string;
125
}
126

127
interface InstrumentedTarget {
128
  canonicalPath: string;
129
  relativePath?: string;
130
  source: string;
131
}
132
```
133

134
[Programmatic API](./programmatic-api.md)
135

136
### Utility Functions
137

138
Helper functions for common coverage-related tasks including file discovery, configuration loading, and temporary directory management.
139

140
```javascript { .api }
141
const utils = require('solidity-coverage/utils');
142

143
// File and directory utilities
144
function assembleFiles(config: Config, skipFiles?: string[]): FileAssembly;
145
function loadSolcoverJS(config?: Config): CoverageConfig;
146
function setupTempFolders(config: Config, tempContractsDir: string, tempArtifactsDir: string): void;
147

148
// Hardhat integration utilities  
149
function getAccountsHardhat(provider: HardhatProvider): Promise<string[]>;
150
function finish(config: Config, api: API): Promise<void>;
151
```
152

153
[Utility Functions](./utility-functions.md)
154

155
### Core Library Components
156

157
Low-level classes for custom coverage workflows including instrumentation, data collection, and report generation.
158

159
```javascript { .api }
160
const Instrumenter = require('solidity-coverage/lib/instrumenter');
161
const Coverage = require('solidity-coverage/lib/coverage');
162
const DataCollector = require('solidity-coverage/lib/collector');
163
const ConfigValidator = require('solidity-coverage/lib/validator');
164
const AbiUtils = require('solidity-coverage/lib/abi');
165
const { UI, AppUI, PluginUI } = require('solidity-coverage/lib/ui');
166

167
// Core instrumentation class
168
class Instrumenter {
169
  constructor(config?: object);
170
  instrument(source: string, canonicalPath: string): InstrumentationResult;
171
}
172

173
// Coverage data management
174
class Coverage {
175
  constructor();
176
  addContract(info: object, contractPath: string): void;
177
  generate(instrumentationData: object): void;
178
}
179
```
180

181
[Core Library](./core-library.md)
182

183
## Configuration Options
184

185
### CoverageConfig Interface
186

187
```javascript { .api }
188
interface CoverageConfig {
189
  // File and directory settings
190
  cwd?: string;                            // Working directory (default: process.cwd())
191
  skipFiles?: string[];                    // Files/folders to exclude from coverage
192
  
193
  // Server configuration
194
  host?: string;                           // Server host
195
  port?: number;                           // Server port
196
  client?: object;                         // Client configuration
197
  providerOptions?: object;                // Provider configuration options
198
  autoLaunchServer?: boolean;              // Auto-launch server flag
199
  
200
  // Output configuration
201
  istanbulReporter?: string[];             // Report formats: html, lcov, text, json
202
  istanbulFolder?: string;                 // Output directory for reports
203
  abiOutputPath?: string;                  // Path for ABI output file
204
  matrixOutputPath?: string;               // Path for test matrix output
205
  mochaJsonOutputPath?: string;            // Path for Mocha JSON output
206
  matrixReporterPath?: string;             // Path to matrix reporter module
207
  
208
  // Coverage measurement toggles
209
  measureStatementCoverage?: boolean;      // Enable statement coverage (default: true)
210
  measureFunctionCoverage?: boolean;       // Enable function coverage (default: true)
211
  measureModifierCoverage?: boolean;       // Enable modifier coverage (default: true)
212
  measureLineCoverage?: boolean;           // Enable line coverage (default: true)
213
  measureBranchCoverage?: boolean;         // Enable branch coverage (default: true)
214
  modifierWhitelist?: string[];            // Specific modifiers to measure
215
  
216
  // Compilation settings
217
  viaIR?: boolean;                         // Enable Solidity viaIR compilation mode
218
  usingSolcV4?: boolean;                   // Compatibility for Solidity v0.4.x
219
  irMinimum?: boolean;                     // Use minimal IR optimization
220
  solcOptimizerDetails?: object;           // Custom optimizer configuration
221
  
222
  // Hook functions for workflow integration
223
  onServerReady?: (config: Config) => void;        // Called when coverage server is ready
224
  onCompileComplete?: (config: Config) => void;    // Called after compilation
225
  onTestsComplete?: (config: Config) => void;      // Called after tests complete
226
  onIstanbulComplete?: (config: Config) => void;   // Called after report generation
227
  onPreCompile?: (config: Config) => void;         // Called before compilation
228
  
229
  // Logging and UI
230
  silent?: boolean;                        // Disable console output
231
  log?: (message: string) => void;         // Custom logging function
232
  
233
  // Mocha configuration passthrough
234
  mocha?: object;                          // Mocha test configuration options
235
}
236
```
237

238
## Error Handling
239

240
Solidity Coverage provides detailed error reporting for common issues:
241

242
- **Compilation Errors**: Invalid Solidity syntax preventing instrumentation
243
- **Configuration Errors**: Invalid .solcover.js configuration options
244
- **File System Errors**: Missing contracts directory or permission issues
245
- **Istanbul Errors**: Report generation failures
246
- **Network Errors**: Hardhat provider connection issues
247

248
Coverage failures typically throw `HardhatPluginError` with descriptive messages for debugging.