Home

Awesome

solidity-coverage

Gitter chat npm (tag) CircleCI codecov Hardhat

Code coverage for Solidity testing

coverage example

Requirements

Install

$ yarn add solidity-coverage --dev

Require the plugin in hardhat.config.js (Hardhat docs)

require('solidity-coverage')

Or, if you are using TypeScript, add this to your hardhat.config.ts:

import 'solidity-coverage'

Resources:

Run

npx hardhat coverage [command-options]

Trouble shooting

Missing or unexpected coverage? Make sure you're using the latest plugin version and run:

$ npx hardhat clean
$ npx hardhat compile
$ npx hardhat coverage

Typescript compilation errors?

$ npx hardhat compile
$ TS_NODE_TRANSPILE_ONLY=true npx hardhat coverage

Weird test failures or plugin conflicts?

# Setting the `SOLIDITY_COVERAGE` env variable tells the coverage plugin to configure the provider
# early in the hardhat task cycle, minimizing conflicts with other plugins or `extendEnvironment` hooks

$ SOLIDITY_COVERAGE=true npx hardhat coverage

Additional Help

Command Options

Option <img width=200/>Example <img width=750/>Description <img width=1000/>
testfiles--testfiles "test/registry/*.ts"Test file(s) to run. (Globs must be enclosed by quotes and use globby matching patterns)
sources--sources myFolder or --sources myFile.solPath to single folder or file to target for coverage. Path is relative to Hardhat's paths.sources (usually contracts/)
solcoverjs--solcoverjs ./../.solcover.jsRelative path from working directory to config. Useful for monorepo packages that share settings. (Path must be "./" prefixed)
matrix--matrixGenerate a JSON object that maps which mocha tests hit which lines of code. (Useful as an input for some fuzzing, mutation testing and fault-localization algorithms.) More...

<sup>*</sup> Advanced use

Config Options

Additional options can be specified in a .solcover.js config file located in the root directory of your project.

Example:

module.exports = {
  skipFiles: ['Routers/EtherRouter.sol']
};
Option <img width=200/>Type <img width=200/>Default <img width=1000/>Description <img width=1000/>
skipFilesArray[]Array of contracts or folders (with paths expressed relative to the contracts directory) that should be skipped when doing instrumentation.(ex: [ "Routers", "Networks/Polygon.sol"]) :warning: RUN THE HARDHAT CLEAN COMMAND AFTER UPDATING THIS
modifierWhitelistString[][]List of modifier names (ex: onlyOwner) to exclude from branch measurement. (Useful for modifiers which prepare something instead of acting as a gate.))
mochaObject{ }Mocha options to merge into existing mocha config. grep and invert are useful for skipping certain tests under coverage using tags in the test descriptions. More...
measureStatementCoveragebooleantrueComputes statement (in addition to line) coverage. More...
measureFunctionCoveragebooleantrueComputes function coverage. More...
measureModifierCoveragebooleantrueComputes each modifier invocation as a code branch. More...
:printer: OUTPUT
matrixOutputPathString./testMatrix.jsonRelative path to write test matrix JSON object to. More...
mochaJsonOutputPathString./mochaOutput.jsonRelative path to write mocha JSON reporter object to. More...
abiOutputPathString./humanReadableAbis.jsonRelative path to write diff-able ABI data to
istanbulFolderString./coverageFolder location for Istanbul coverage reports.
istanbulReporterArray['html', 'lcov', 'text', 'json']Istanbul coverage reporters
silentBooleanfalseSuppress logging output
:recycle: WORKFLOW HOOKS
onServerReady<sup>*</sup>FunctionHook run after server is launched, before the tests execute. Useful if you need to use the Oraclize bridge or have setup scripts which rely on the server's availability. More...
onPreCompile<sup>*</sup>FunctionHook run after instrumentation is performed, before the compiler is run. Can be used with the other hooks to be able to generate coverage reports on non-standard / customized directory structures, as well as contracts with absolute import paths. More...
onCompileComplete<sup>*</sup>FunctionHook run after compilation completes, before tests are run. Useful if you have secondary compilation steps or need to modify built artifacts. More...
onTestsComplete<sup>*</sup>FunctionHook run after the tests complete, before Istanbul reports are generated. More...
onIstanbulComplete<sup>*</sup>FunctionHook run after the Istanbul reports are generated, before the coverage task completes. Useful if you need to clean resources up. More...
:warning: DEPRECATED
configureYulOptimizerBooleanfalse(Deprecated since 0.8.7) Setting to true should resolve "stack too deep" compiler errors in large projects using ABIEncoderV2
solcOptimizerDetailsObjectundefined(Deprecated since 0.8.7)) Must be used in combination with configureYulOptimizer. Allows you to configure solc's optimizer details. Useful if the default remedy for stack-too-deep errors doesn't work in your case (See FAQ: Running out of stack ).

<sup>*</sup> Advanced use

Viewing the reports:

API

Solidity-coverage's core methods and many utilities are available as an API.

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

Documentation available here.

Detecting solidity-coverage from another task

If you're writing another plugin or task, it can be helpful to detect whether coverage is running or not. The coverage plugin sets a boolean variable on the globally injected hardhat environment object for this purpose.

hre.__SOLIDITY_COVERAGE_RUNNING === true

Example reports

Funding

You can help fund solidity-coverage development through DRIPS. It's a public goods protocol which helps distribute money to packages in your dependency tree. (It's great, check it out.)

Contribution Guidelines

Contributions are welcome! If you're opening a PR that adds features or options please consider writing full unit tests for them. (We've built simple fixtures for almost everything and are happy to add some for your case if necessary).

Set up the development environment with:

$ git clone https://github.com/sc-forks/solidity-coverage.git
$ yarn