Code coverage for Solidity smart-contracts
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 
cgewecke b88e00c14e Update changelog 6 years ago
.circleci Keep the same node version 6 years ago
bin Do not require tests to use .call() 7 years ago
docs Upgrade testrpc-sc to 6.1.6, add doc notes 6 years ago
lib Fix issue with imported packages with subfolders 6 years ago
test Support constructor keyword / bump solidity-parser 7 years ago
.eslintignore Rename "run" folders/files "cli" for consistency 8 years ago
.eslintrc Add transfer / send unit test. Use Node7 7 years ago
.gitignore Stop ignoring package-lock.json - npm version wants it 7 years ago
CHANGELOG.md Update changelog 6 years ago
LICENSE Add MIT License 8 years ago
README.md Add bingen to contributors list 6 years ago
package-lock.json 0.5.11 6 years ago
package.json 0.5.11 6 years ago

README.md

solidity-coverage

Join the chat at https://gitter.im/sc-forks/solidity-coverage npm version CircleCI codecov Stories in Ready

Code coverage for Solidity testing

coverage example

  • For more details about what this is, how it works and potential limitations, see the accompanying article.
  • solidity-coverage is in development and its accuracy is unknown. If you find discrepancies between the coverage report and your suite's behavior, please open an issue.
  • solidity-coverage is Solcover

Install

$ npm install --save-dev solidity-coverage

Run

$ ./node_modules/.bin/solidity-coverage

Tests run significantly slower while coverage is being generated. Your contracts are double-compiled and a 1 to 2 minute delay between the end of the second compilation and the beginning of test execution is possible if your test suite is large. Large Solidity files can also take a while to instrument.

Important: breaking change for versions >= 0.5.0

  • solidity-coverage requires compilation with solc >= 0.4.21. We're prefixing our own instrumentation events with the emit keyword to reduce warnings volume when running the tool.
  • Ternary conditionals (ex: (x) ? y : z;) no longer receive branch coverage. There's more info about why this isn't currently possible at solidity 3887.

Important: breaking change for versions >= 0.4.3

  • solidity-coverage now expects a globally installed truffle in your environment / on CI. If you prefer to control which Truffle version your tests are run with, please see the FAQ for running truffle as a local dependency.

  • Solidity fixtures / mocks / tests stored in the tests/ directory are no longer supported. If your suite uses native Solidity testing or accesses contracts via mocks stored in tests/ (a la Zeppelin), coverage will trigger test errors because it's unable to rewrite your contract ABIs appropriately. Mocks should be relocated to the root folder's contracts directory. More on why this is necessary at issue 146

Network Configuration

By default, solidity-coverage generates a stub truffle.js that accommodates its special gas needs and connects to a coverage-enabled fork of the ganache-cli client called testrpc-sc on port 8555. This special client ships with solidity-coverage - there's nothing extra to download. If your tests will run on truffle's development network using a standard truffle.js and ganache-cli instance, you shouldn't have to do any configuration or launch the coverage client separately. If your tests depend on logic or special options added to truffle.js you should declare a coverage network there following the example below.

Example

module.exports = {
  networks: {
    development: {
      host: "localhost",
      port: 8545,
      network_id: "*"
    },
    coverage: {
      host: "localhost",
      network_id: "*",
      port: 8555,         // <-- If you change this, also set the port option in .solcover.js.
      gas: 0xfffffffffff, // <-- Use this high gas value
      gasPrice: 0x01      // <-- Use this low gas price
    },
    ...etc...
  }
};

Options

You can also create a .solcover.js config file in the root directory of your project and specify additional options if necessary:

Example:

module.exports = {
    port: 6545,
    testrpcOptions: '-p 6545 -u 0x54fd80d6ae7584d8e9a19fe1df43f04e5282cc43',
    testCommand: 'mocha --timeout 5000',
    norpc: true,
    dir: './secretDirectory',
    copyPackages: ['zeppelin-solidity'],
    skipFiles: ['Routers/EtherRouter.sol']
};
Option Type Default Description
accounts Number 35 Number of accounts to launch testrpc with.
port Number 8555 Port to run testrpc on / have truffle connect to
norpc Boolean false Prevent solidity-coverage from launching its own testrpc. Useful if you are managing a complex test suite with a shell script
testCommand String truffle test Run an arbitrary test command. ex: mocha --timeout 5000. NB: Also set the port option to whatever your tests require (probably 8545).
testrpcOptions String --port 8555 options to append to a command line invocation of testrpc. NB: Using this overwrites the defaults so always specify a port in this string and in the port option
copyNodeModules Boolean false DEPRECATED use copyPackages instead Copies node_modules into the coverage environment. May significantly increase the time for coverage to complete if enabled. Useful if your contracts import solidity files from an npm installed package (and your node_modules is small).
copyPackages Array [] Copies specific node_modules packages into the coverage environment. May significantly reduce the time for coverage to complete compared to copyNodeModules. Useful if your contracts import solidity files from an npm installed package.
skipFiles Array ['Migrations.sol'] Array of contracts or folders (with paths expressed relative to the contracts directory) that should be skipped when doing instrumentation. Migrations.sol is skipped by default, and does not need to be added to this configuration option if it is used.
deepSkip boolean false Use this if instrumentation hangs on large, skipped files (like Oraclize). It's faster.
dir String . Solidity-coverage copies all the assets in your root directory (except node_modules) to a special folder where it instruments the contracts and executes the tests. dir allows you to define a relative path from the root directory to those assets. Useful if your contracts & tests are within their own folder as part of a larger project.
buildDirPath String /build/contracts Build directory path for compiled smart contracts

FAQ

Solutions to common issues people run into using this tool:

Example reports

Contribution Guidelines

Contributions are welcome! If you're opening a PR that adds features please consider writing some unit tests for them. You could also lint your submission with npm run lint. Bugs can be reported in the issues.

Contributors