Usage Guide

This guide provides a comprehensive overview of how to use solidity-coverage, including its command-line options and detailed configuration settings.

Running Coverage

Once installed and configured in your Hardhat project, you can generate a coverage report by running:

npx hardhat coverage [command-options]

This command will:

Instrument your Solidity contracts.
Compile the instrumented contracts.
Launch a HardhatEVM instance with coverage-enabled monitors.
Run your test suite against the instrumented contracts.
Generate and save coverage reports.

Command-Line Options

You can modify the behavior of the coverage task with the following command-line flags:

Option	Example	Description
`testfiles`	`--testfiles "test/registry/*.ts"`	Specifies which test file(s) to run. Globs must be enclosed in quotes.
`sources`	`--sources myFolder` or `--sources myFile.sol`	Targets a single folder or file for coverage, relative to Hardhat's `paths.sources` (usually `contracts/`).
`solcoverjs`	`--solcoverjs ./../.solcover.js`	Sets a relative path to the `.solcover.js` config file. Useful for monorepos. Path must be `./` prefixed.
`matrix`	`--matrix`	Generates a JSON map of which tests hit which lines of code. See Advanced Topics.

Configuration File (`.solcover.js`)

For more advanced configuration, you can create a .solcover.js file in the root of your project. This file exports a JavaScript object with your desired options.

Example .solcover.js:

module.exports = {
  skipFiles: ['mocks/MockContract.sol', 'utils/'],
  mocha: {
    grep: "@skip-on-coverage",
    invert: true
  }
};

All Configuration Options

Option	Type	Default	Description
`skipFiles`	`Array`	`[]`	An array of contracts or folder paths (relative to `contracts/`) to exclude from instrumentation. Remember to run `npx hardhat clean` after updating this option.
`irMinimum`	`Boolean`	`false`	Speeds up tests when `solc` is run in `viaIR` mode. It might not compile for all projects, but it's worth trying if `viaIR` is enabled.
`modifierWhitelist`	`String[]`	`[]`	A list of modifier names (e.g., `onlyOwner`) to exclude from branch coverage measurement. Useful for modifiers that prepare state rather than acting as gates.
`mocha`	`Object`	`{}`	Mocha options to merge into the existing Mocha config. `grep` and `invert` are useful for skipping specific tests. See Skipping Tests.
`measureStatementCoverage`	`boolean`	`true`	Computes statement coverage in addition to line coverage. See Reducing Instrumentation.
`measureFunctionCoverage`	`boolean`	`true`	Computes function coverage. See Reducing Instrumentation.
`measureModifierCoverage`	`boolean`	`true`	Computes each modifier invocation as a code branch. See Reducing Instrumentation.
Output Options
`matrixOutputPath`	`String`	`./testMatrix.json`	Relative path to write the test matrix JSON file to. See Advanced Topics.
`mochaJsonOutputPath`	`String`	`./mochaOutput.json`	Relative path to write the Mocha JSON reporter output to.
`abiOutputPath`	`String`	`./humanReadableAbis.json`	Relative path to write human-readable ABI data to, for diffing purposes.
`istanbulFolder`	`String`	`./coverage`	The folder where Istanbul coverage reports will be written.
`istanbulReporter`	`Array`	`['html', 'lcov', 'text', 'json']`	An array of Istanbul coverage reporters to use.
`silent`	`Boolean`	`false`	Suppresses logging output from `solidity-coverage`.
Workflow Hooks
`onServerReady`	`Function`		Hook that runs after the server is launched but before tests execute.
`onPreCompile`	`Function`		Hook that runs after instrumentation but before compilation.
`onCompileComplete`	`Function`		Hook that runs after compilation but before tests are run.
`onTestsComplete`	`Function`		Hook that runs after tests complete but before Istanbul reports are generated.
`onIstanbulComplete`	`Function`		Hook that runs after Istanbul reports are generated but before the coverage task completes.
Low-Level Options
`configureYulOptimizer`	`Boolean`	`false`	Set to `true` to enable Yul optimizer details configuration. This can help with "stack too deep" errors.
`solcOptimizerDetails`	`Object`	`undefined`	Allows you to configure solc's optimizer details when `configureYulOptimizer` is true. See the FAQ for examples.

Viewing the Reports

After a successful run, solidity-coverage generates reports in the ./coverage/ directory by default. The most user-friendly report is the HTML version.

To view it, open the following file in your browser:

coverage/index.html

This will open an interactive report where you can navigate through your contracts and see exactly which lines, branches, and functions were covered by your tests.