**NB:** for most projects you'll also need to configure a 'coverage' network in
truffle-config.js. See the Network Configuration guide below.
**NB:** Most projects will also need to set a `coverage` network in
truffle-config.js. See [Network Configuration](#network-configuration).
### Usage notes:
+ Requires Solidity pragmas >= `0.5.0`.
+ For solidity pragma >= `0.5.0`.
+ Tests run more slowly while coverage is being generated.
+ Your contracts will be double-compiled and a delay between compilation and
+ Your contracts will be double-compiled and a (long) delay between compilation and
the beginning of test execution is possible if your contracts are large.
+ solidity-coverage 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](https://github.com/sc-forks/solidity-coverage/blob/master/docs/faq.md#running-truffle-as-a-local-dependency).
+ Solidity fixtures / mocks 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](https://github.com/sc-forks/solidity-coverage/issues/146)
+ Truffle should be globallly installed in your environment.. If you prefer running truffle as
a local dependency, please see [this section](https://github.com/sc-forks/solidity-coverage/blob/master/docs/faq.md#running-truffle-as-a-local-dependency) of the FAQ.
+ 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 control truffle's compilation of that folder. Mocks should be relocated to the root `contracts` directory. More on why this is necessary at issue [146](https://github.com/sc-forks/solidity-coverage/issues/146)
### Network Configuration
By default, solidity-coverage connects to a coverage-enabled fork of the ganache-cli client
called **testrpc-sc** on port 8555. (It ships with `solidity-coverage` -
there's nothing extra to download.)
By default, this tool connects to a coverage-enabled fork of ganache-cli
called **testrpc-sc** on port 8555. (It's a dependency - there's nothing extra to download.)
In `truffle-config.js`, add a coverage network following the example below.
@ -69,8 +67,8 @@ module.exports = {
```
### Options
You can also create a `.solcover.js` config file in the root directory of your project and specify
additional options if necessary:
Additional options can be specified in a `.solcover.js` config file located in
the root directory of your project.
**Example:**
```javascript
@ -102,7 +100,7 @@ module.exports = {
### FAQ
Solutions to common issues people run into using this tool:
Solutions to common problems people run into:
+ [Running out of gas](https://github.com/sc-forks/solidity-coverage/blob/master/docs/faq.md#running-out-of-gas)
+ [Running out of memory (locally and in CI)](https://github.com/sc-forks/solidity-coverage/blob/master/docs/faq.md#running-out-of-memory-locally-and-in-ci)
@ -110,7 +108,6 @@ Solutions to common issues people run into using this tool:
+ [Running on windows](https://github.com/sc-forks/solidity-coverage/blob/master/docs/faq.md#running-on-windows)
+ [Running testrpc-sc on its own](https://github.com/sc-forks/solidity-coverage/blob/master/docs/faq.md#running-testrpc-sc-on-its-own)
+ [Running truffle as a local dependency](https://github.com/sc-forks/solidity-coverage/blob/master/docs/faq.md#running-truffle-as-a-local-dependency)
+ [Integrating into CI](https://github.com/sc-forks/solidity-coverage/blob/master/docs/faq.md#continuous-integration-installing-metacoin-on-travisci-with-coveralls)
+ [Why are asserts and requires highlighted as branch points?](https://github.com/sc-forks/solidity-coverage/blob/master/docs/faq.md#why-has-my-branch-coverage-decreased-why-is-assert-being-shown-as-a-branch-point)
+ [Why are `send` and `transfer` throwing in my tests?](https://github.com/sc-forks/solidity-coverage/blob/master/docs/faq.md#why-are-send-and-transfer-throwing)
@ -119,14 +116,12 @@ Solutions to common issues people run into using this tool:
- npm run coverage && cat coverage/lcov.info | coveralls
```
**NB:** It's probably best practice to run coverage in CI as an `after_script` or in a [parallel build](https://github.com/OpenZeppelin/zeppelin-solidity/blob/master/.travis.yml) rather than assume its equivalence to `truffle test`. Solidity-coverage's `testrpc` uses gasLimits far above the current blocklimit and rewrites your contracts in ways that might affect their behavior. It's also less robust than Truffle and may fail more frequently.
**NB:** It's best practice to run coverage in a [parallel CI build](https://github.com/OpenZeppelin/zeppelin-solidity/blob/master/.travis.yml) rather than assume its equivalence to `truffle test`. Coverage's `testrpc-sc` uses gasLimits far above the current blocklimit and rewrites your contracts in ways that might affect their behavior. It's also less robust than Truffle and may fail more frequently.
**Step 4: Toggle the project on at Travis and Coveralls and push.**
@ -57,33 +58,12 @@ after_script:
### Running out of gas
If you have hardcoded gas costs into your tests some of them may fail when using solidity-coverage.
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.
(See [issue #59](https://github.com/sc-forks/solidity-coverage/issues/59)).
@ -104,55 +84,20 @@ limit to 7.5MB (ProTip courtesy of [@federicobond](https://github.com/federicobo
Truffle sets a default mocha timeout of 5 minutes. Because tests run slower under coverage, it's possible to hit this limit with a test that iterates hundreds of times before producing a result. Timeouts can be disabled by configuring the mocha option in `truffle.js` as below: (ProTip courtesy of [@cag](https://github.com/cag))
### Why has my branch coverage decreased? Why is assert being shown as a branch point?
`assert` and `require` check whether a condition is true or not. If it is, they allow execution to proceed. If not, they throw, and all changes are reverted. Indeed, prior to [Solidity 0.4.10](https://github.com/ethereum/solidity/releases/tag/v0.4.10), when `assert` and `require` were introduced, this functionality was achieved by code that looked like
@ -174,8 +119,8 @@ If an `assert` or `require` is marked with an `I` in the coverage report, then d
If you include contracts that have fallback function in the list of files to instrument and attempt to `send` or `transfer` to them,
the methods will throw because the instrumentation consumes more gas than these methods allow. See the `skipFiles` option in the
README to exclude these files and [issue 118](https://github.com/sc-forks/solidity-coverage/issues/118) for a more detailed discussion of
this problem.
README to exclude these files and [issue 118](https://github.com/sc-forks/solidity-coverage/issues/118) for a more detailed discussion.This problem persists in v0.6.x even though the vm is set to emit free logs.
(Under investigation).
### Running on windows
@ -190,15 +135,8 @@ launching `testrpc-sc` on its own from the command line before running `solidity
Sometimes its useful to launch `testrpc-sc` separately at the command line or with a script, after
setting the `norpc` config option in `.solcover.js` to true:
If you installed using npm
```
$ ./node_modules/.bin/testrpc-sc <options>
```
If you installed using yarn
```
$ ./node_modules/ethereumjs-testrpc-sc/bin/testrpc // v0.1.10 and below (testrpc v3.0.3)
$ ./node_modules/ethereumjs-testrpc-sc/build/cli.node.js // All others (testrpc v4.0.1 +)
cgewecke
5 years ago