0.0.1 • Published 2 years ago

solidity-coverages v0.0.1

Weekly downloads
-
License
ISC
Repository
github
Last release
2 years ago

solidity-coverage

Gitter chat npm (tag) CircleCI codecov buidler

Code coverage for Solidity testing

coverage example

Install

$ npm install --save-dev solidity-coverage

Resources:

Truffle V5

Add this package to your plugins array in truffle-config.js (Truffle docs)

module.exports = {
  networks: {...},
  plugins: ["solidity-coverage"]
}

Run

truffle run coverage [command-options]

Hardhat

Beginning with v0.7.12, this tool supports Hardhat and runs directly on HardhatEVM.

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

require('solidity-coverage')

Run

npx hardhat coverage [command-options]

(Additional Hardhat-specific info can be found here)

@openzeppelin/test-environment

OpenZeppelin have written their own coverage generation scripts for test-environment using the solidity-coverage API. A working example can be found at openzeppelin-contracts, here.

Usage notes:

  • Coverage runs tests a little more slowly.
  • Coverage launches its own in-process ganache server.
  • You can set ganache options using the providerOptions key in your .solcover.js config.
  • Coverage distorts gas consumption. Tests that check exact gas consumption should be skipped.
  • :warning: Contracts are compiled without optimization. Please report unexpected compilation faults to issue 417

Command Options

Option Example Description
file--file="test/registry/*.js"(Truffle) Filename or glob describing a subset of tests to run. (Globs must be enclosed by quotes and use globby matching patterns)
testfiles--testfiles "test/registry/*.ts"(Buidler) Test file(s) to run. (Globs must be enclosed by quotes and use globby matching patterns)
solcoverjs--solcoverjs ./../.solcover.jsRelative path from working directory to config. Useful for monorepo packages that share settings. (Path must be "./" prefixed)
network--network developmentUse network settings defined in the Truffle or Buidler config
temp*--temp build:warning: Caution :warning: 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...

* 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 Type Default Description
silentBooleanfalseSuppress logging output
clientObjectrequire("ganache-core")Useful if you need a specific ganache version.
providerOptionsObject{ }ganache-core options
skipFilesArray['Migrations.sol']Array of contracts or folders (with paths expressed relative to the contracts directory) that should be skipped when doing instrumentation.
measureStatementCoveragebooleantrueComputes statement (in addition to line) coverage. More...
measureFunctionCoveragebooleantrueComputes function coverage. More...
istanbulFolderString./coverageFolder location for Istanbul coverage reports.
istanbulReporterArray['html', 'lcov', 'text', 'json']Istanbul coverage reporters
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.
coverageContractsTempString.coverage_contractsTemporary folder location for instrumented contracts - Note that this directory will automatically be deleted when coverage completes.
onServerReady*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*FunctionHook run after filesystem and compiler configuration is applied, 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*FunctionHook run after compilation completes, before tests are run. Useful if you have secondary compilation steps or need to modify built artifacts. More...
onTestsComplete*FunctionHook run after the tests complete, before Istanbul reports are generated. More...
onIstanbulComplete*FunctionHook run after the Istanbul reports are generated, before the ganache server is shut down. Useful if you need to clean resources up. More...
configureYulOptimizerBooleanfalse(Experimental) Setting to true should resolve "stack too deep" compiler errors in large projects using ABIEncoderV2
solcOptimizerDetailsObjectundefined(Experimental) Must be used in combination with configureYulOptimizer. Allows you configure solc's optimizer details. Useful if the default remedy for stack-too-deep errors doesn't work in your case (See FAQ below).

* Advanced use

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

FAQ

Common problems & questions:

Example reports

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

Contributors