solidity-coverage/HARDHAT_README.md

solidity-coverage

Solidity code coverage plugin for Hardhat.

What

• For more details about how it works and potential limitations, see the accompanying article.
• solidity-coverage is also JoinColony/solcover

Installation

$ npm install --save-dev solidity-coverage

And add the following to your .config.js:

require("solidity-coverage");

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

import "solidity-coverage"

⚠️ Also using hardhat-typechain? ⚠️

Please see the using with typechain section.

Tasks

This plugin implements a coverage task

npx hardhat coverage [options]

Option	Example	Description
testfiles	--testfiles "test/registry/*.ts"	Test file(s) to run. (Globs must be enclosed by quotes.)
solcoverjs	--solcoverjs ./../.solcover.js	Relative path from working directory to config. Useful for monorepo packages that share settings. (Path must be "./" prefixed)
network	--network development	Run with a ganache client over http using network settings defined in hardhat.config.js. (Hardhat is the default network)
temp*	--temp artifacts	⚠️ Caution ⚠️ Path to a disposable folder to store compilation artifacts in. Useful when your test setup scripts include hard-coded paths to a build directory. More...

Configuration

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

Config Example:

module.exports = {
  skipFiles: ['Routers/EtherRouter.sol']
};

Option	Type	Default	Description
silent	Boolean	false	Suppress logging output
client	Object	undefined	Ganache only: Useful if you need a specific ganache version. An example value is: require('ganache-cli')
providerOptions	Object	{ }	Ganache only: ganache-core options
skipFiles	Array	['Migrations.sol']	Array of contracts or folders (with paths expressed relative to the contracts directory) that should be skipped when doing instrumentation.
istanbulFolder	String	./coverage	Folder location for Istanbul coverage reports.
istanbulReporter	Array	['html', 'lcov', 'text', 'json']	Istanbul coverage reporters
mocha	Object	{ }	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.
onServerReady*	Function		Hook 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...
onCompileComplete*	Function		Hook run after compilation completes, before tests are run. Useful if you have secondary compilation steps or need to modify built artifacts. More...
onTestsComplete*	Function		Hook run after the tests complete, before Istanbul reports are generated. More...
onIstanbulComplete*	Function		Hook run after the Istanbul reports are generated, before the ganache server is shut down. Useful if you need to clean resources up. More...

^* Advanced use

Usage

• Coverage runs tests a little more slowly.
• Coverage uses the Hardhat network by default.
• Coverage distorts gas consumption. Tests that check exact gas consumption should be skipped.
• ⚠️ Contracts are compiled without optimization. Please report unexpected compilation faults to issue 417

Using with typechain

This plugin requires additional configuration when run alongside hardhat-typechain.

1. Write coverage artifacts to your project's default config.paths.artifacts path using the --temp option.

# Example
npx hardhat coverage --temp artifacts

2. Add these workflow hooks to your .solcover.js

// This is already a dependency of solidity-coverage
const shell = require('shelljs');

module.exports = {
  onCompileComplete: async function (_config) {
    await run("typechain");
  },
  // We need to do this because solcover generates bespoke artifacts.
  onIstanbulComplete: async function (_config) {
    shell.rm("-rf", "./artifacts"); // Or your config.paths.artifacts path
    shell.rm("-rf", "./typechain"); // Or the typechain `outDir` (if removable)
  },
};

Using with ganache

Begining with v0.7.12, this plugin runs directly on the Hardhat network by default (for speed).

If you want to use a ganache based http network, you can specify it by name using the --network cli option. The plugin will then launch its own coverage enabled ganache instance which can be configured in .solcover.js via the providerOptions key.

Documentation

More documentation, including FAQ and information about solidity-coverage's API is available here.