solidity-coverage/README.md

SolCover

Code coverage for Solidity testing

For more details about what this is, how it work and potential limitations, see the accompanying article.

This branch is an attempt to prepare solcover for npm publication and simplify its use as a command line utility. Gas cost issues etc are managed under the hood and the tool cleans up after itself if (when) it crashes.

Configuration

By default, solcover generates a stub truffle.js that accomodates its special gas needs and connects to a modified version of testrpc on port 8555. If your tests can run on the development network using a standard truffle.js, you shouldn't have to do any configuration. If your tests depend on logic added to truffle.js - for example: zeppelin-solidity uses the file to expose a babel polyfill that its suite needs to run correctly - you can override the default behavior by specifying a coverage network in truffle.js.

Example coverage network config

module.exports = {
  networks: {
    development: {
      host: "localhost",
      port: 8545,
      network_id: "*" // Match any network id
    },
    coverage: {
      host: "localhost",
      network_id: "*", 
      port: 8555,         // <-- Use this port only 
      gas: 0xfffffffffff, // <-- Use this high gas value
      gasPrice: 0x01      // <-- Use this low gas price
    }
  }
};

Install

$ npm install --save-dev https://github.com/JoinColony/solcover.git#truffle3

Run

$ ./node_modules/solcover/exec.js

Tests run signficantly slower while coverage is being generated. A 1 to 2 minute delay between the end of Truffle compilation and the beginning of test execution is not impossible if your test suite is large.

Note that if you have hardcoded gas costs into your tests some of them may fail when using SolCover. This is because the instrumentation process increases the gas costs for using the contracts, due to the extra events. If this is the case, then the coverage may be incomplete. To avoid this, using estimateGas to estimate your gas costs should be more resilient in most cases.

TODO

• Turn into a true command line tool, rather than just a hacked-together script
• Allow the use of a dedicated coverage network in truffle.js
• Release on NPM
• Support for arbitrary testing commands
• You tell me