Solidity-Coverage API

solidity-coverage tracks which lines of code are executed by instrumenting your contracts with special Solidity statements and detecting their execution in a coverage-enabled EVM. The API provides core methods to manage this process, allowing for custom testing workflows and integrations.

API Workflow Overview

The API methods align with the typical stages of a test run:

Test Stage API Method Description
Compilation instrument A pre-compilation step that rewrites contracts and generates an instrumentation data map.
Client Launch attachToHardhatVM A pre-test step that enables coverage collection on a HardhatEVM client.
Reporting report A post-test step that generates coverage reports from the data collected by the VM.

Example Usage

const CoverageAPI = require("solidity-coverage/api");

const options = { /* ... */ };
const api = new CoverageAPI(options);

API Methods

new CoverageAPI(options)

Creates a new coverage API instance.

Parameters:

  • options (Object): API configuration options.
Option Type Default Description
silent Boolean false Suppress logging output.
skipFiles Array [] Array of contract or folder paths (relative to contracts/) to skip during instrumentation.
istanbulFolder String ./coverage Folder location for Istanbul coverage reports.
istanbulReporter Array ['html', 'lcov', 'text', 'json'] An array of Istanbul coverage reporters to use.

instrument(contracts)

Instruments a set of Solidity source files to prepare them for compilation and coverage analysis.

Warning: Instrumented sources must be compiled with solc optimization turned OFF.

Parameters:

  • contracts (Object[]): An array of objects, where each object represents a Solidity source file.
    • source (String, required): The Solidity source code.
    • canonicalPath (String, required): The absolute path to the source file.
    • relativePath (String, optional): The relative path to the source file, used for logging.

Returns: Object[] - An array of objects in the same format, but with the source property containing the instrumented code.

attachToHardhatVM(provider)

Enables coverage data collection on a HardhatEVM provider. This should be called after the provider has been created and configured with appropriate gas settings.

Parameters:

  • provider (Object): A Hardhat provider instance.

Returns: Promise<void>

report(istanbulFolder)

Generates coverage reports using the collected data.

Parameters:

  • istanbulFolder (String, optional): Path to the folder where Istanbul will save the reports. Defaults to the istanbulFolder option set in the constructor.

Returns: Promise<void>

getInstrumentationData()

Returns a deep copy of the hit map created during the instrumentation process. This is useful if you need to manage coverage collection across multiple processes.

Returns: Object - The instrumentation data object.

setInstrumentationData(data)

Sets the hit map object. This allows you to load pre-existing instrumentation data into the API instance, either for collecting new hits or for generating a report from data collected in a separate process.

Parameters:

  • data (Object): The instrumentation data to load.

Utility Methods

These utility functions are available via require('solidity-coverage/utils') and assist with file management and configuration.

Many of these methods require a config object with the following properties:

const config = {
  workingDir: process.cwd(),
  contractsDir: path.join(process.cwd(), 'contracts'),
};

loadSolcoverJS(config)

Loads and normalizes the .solcover.js configuration file from the project.

Returns: Object - The normalized coverage configuration.

assembleFiles(config, skipFiles)

Loads all Solidity contracts from the filesystem in a format that can be passed to api.instrument().

Parameters:

  • config (Object): The project configuration object.
  • skipFiles (String[], optional): An array of file or folder paths to skip.

Returns: Object - An object with targets and skipped keys, each containing an array of contract source objects.

getTempLocations(config)

Returns a pair of absolute paths for temporary directories used to store instrumented contracts (.coverage_contracts) and their compiled artifacts (.coverage_artifacts).

Returns: Object - An object with tempContractsDir and tempArtifactsDir properties.

setupTempFolders(config, tempContractsDir, tempArtifactsDir)

Creates the temporary directories specified.

save(contracts, originalDir, tempDir)

Writes an array of instrumented source files to a temporary directory.

Parameters:

  • contracts (Object[]): Array of instrumented contracts from api.instrument().
  • originalDir (String): Absolute path to the original contracts directory.
  • tempDir (String): Absolute path to the temporary contracts directory.

finish(config, api)

Deletes temporary folders created during the coverage run.

Returns: Promise<void>