You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
[](https://gitter.im/sc-forks/solidity-coverage?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
+ For more details about what this is, how it works and potential limitations,
12
+
see [the accompanying article][16].
13
+
+`solidity-coverage` is [Solcover][17]
14
+
15
+
## Install
19
16
```
20
-
$ npm install --save-dev solidity-coverage
17
+
$ npm install --save-dev solidity-coverage@beta
21
18
```
22
19
23
-
### Run
24
-
Set a `coverage` network in truffle-config.js (see [Network Configuration](#network-configuration)) and then run:
20
+
## Truffle V5
21
+
22
+
**Add** this package to your plugins array in `truffle-config.js`
23
+
```javascript
24
+
module.exports= {
25
+
networks: {...},
26
+
plugins: ["solidity-coverage"]
27
+
}
25
28
```
26
-
$ npx solidity-coverage
29
+
**Run**
30
+
```
31
+
truffle run coverage [command-options]
27
32
```
28
33
29
-
### Usage notes:
30
-
+ For pragma solidity >=0.4.22 <0.6.0 / Petersburg / Truffle v4 and v5
31
-
+ Tests run more slowly while coverage is being generated.
32
-
+ Your contracts will be double-compiled and a (long) delay between compilation and
33
-
the beginning of test execution is possible if your contracts are large.
34
-
+ Truffle should be globallly installed in your environment.. If you prefer running truffle as
35
-
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.
36
-
+ 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 can't control the way truffle compiles 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)
37
-
38
-
### Network Configuration
34
+
## Usage notes:
35
+
+ Coverage runs tests a little more slowly.
36
+
+ Coverage launches its own in-process ganache server.
37
+
+ You can set [ganache options][1] using the `providerOptions` key in your `.solcover.js`[config][15].
38
+
+ Coverage [distorts gas consumption][13]. Tests that check exact gas consumption should be skipped.
39
39
40
-
By default, this tool connects to a coverage-enabled fork of ganache-cli
41
-
called **testrpc-sc** on port 8555.
42
-
+ it's a dependency - there's nothing extra to download.
43
-
+ the solidity-coverage command launches it automatically in the background. (See [this section of the FAQ](https://github.com/sc-forks/solidity-coverage/blob/master/docs/faq.md#running-testrpc-sc-on-its-own) if you need to launch it separately yourself)
40
+
## Command Options
41
+
| Option <imgwidth=200/> | Example <imgwidth=750/>| Description <imgwidth=1000/> |
| file |`--file="test/registry/*.js"`| Filename or glob describing a subset of JS tests to run. (Globs must be enclosed by quotes.)|
44
+
| solcoverjs |`--solcoverjs ./../.solcover.js`| Relative path from working directory to config. Useful for monorepo packages that share settings. (Path must be "./" prefixed) |
45
+
| network |`--network development`| Use network settings defined in the Truffle config |
46
+
| temp[<sup>*</sup>][14]|`--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...][14]|
47
+
| version || Version info |
48
+
| help || Usage notes |
44
49
45
-
In `truffle-config.js`, add a coverage network following the example below.
50
+
[<sup>*</sup> Advanced use][14]
46
51
47
-
**Example**
48
-
```javascript
49
-
module.exports= {
50
-
networks: {
51
-
development: {
52
-
host:"localhost",
53
-
port:8545,
54
-
network_id:"*"
55
-
},
56
-
coverage: {
57
-
host:"localhost",
58
-
network_id:"*",
59
-
port:8555, // <-- If you change this, also set the port option in .solcover.js.
60
-
gas:0xfffffffffff, // <-- Use this high gas value
61
-
gasPrice:0x01// <-- Use this low gas price
62
-
},
63
-
...etc...
64
-
}
65
-
};
66
-
```
67
-
### Options
52
+
## Config Options
68
53
69
-
Additional options can be specified in a `.solcover.js` config file located in
70
-
the root directory of your project.
54
+
Additional options can be specified in a `.solcover.js` config file located in the root directory
| accounts |*Number*| 35 | Number of accounts to launch testrpc with. |
89
-
| port |*Number*| 8555 | Port to run testrpc on / have truffle connect to |
90
-
| norpc |*Boolean*| false | Prevent solidity-coverage from launching its own testrpc. Useful if you are managing a complex test suite with a [shell script](https://github.com/OpenZeppelin/openzeppelin-solidity/blob/ed872ca0a11c4926f8bb91dd103bea1378a3384c/scripts/coverage.sh)|
91
-
| 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). |
92
-
| 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 |
93
-
| copyNodeModules |*Boolean*| false |:warning:**DEPRECATED** use `copyPackages` instead :warning: 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). |
94
-
| 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. |
95
-
| 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. |
96
-
| deepSkip | boolean | false | Use this if instrumentation hangs on large, skipped files (like Oraclize). It's faster. |
97
-
| 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.|
+[Running out of gas](https://github.com/sc-forks/solidity-coverage/blob/master/docs/faq.md#running-out-of-gas)
105
-
+[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)
106
-
+[Running out of time (in mocha)](https://github.com/sc-forks/solidity-coverage/blob/master/docs/faq.md#running-out-of-time-in-mocha)
107
-
+[Running on windows](https://github.com/sc-forks/solidity-coverage/blob/master/docs/faq.md#running-on-windows)
108
-
+[Running testrpc-sc on its own](https://github.com/sc-forks/solidity-coverage/blob/master/docs/faq.md#running-testrpc-sc-on-its-own)
109
-
+[Running truffle as a local dependency](https://github.com/sc-forks/solidity-coverage/blob/master/docs/faq.md#running-truffle-as-a-local-dependency)
110
-
+[Integrating into CI](https://github.com/sc-forks/solidity-coverage/blob/master/docs/faq.md#continuous-integration-installing-metacoin-on-travisci-with-coveralls)
111
-
+[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)
| skipFiles |*Array*|`['Migrations.sol']`| Array of contracts or folders (with paths expressed relative to the `contracts` directory) that should be skipped when doing instrumentation. |
| mocha |*Object*|`{ }`|[Mocha options][3] to merge into existing mocha config. `grep` and `invert` are useful for skipping certain tests under coverage using tags in the test descriptions.|
73
+
| onServerReady[<sup>*</sup>][14]|*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...][14]|
74
+
| onCompileComplete[<sup>*</sup>][14]|*Function*|| Hook run *after* compilation completes, *before* tests are run. Useful if you have secondary compilation steps or need to modify built artifacts. [More...][14]|
75
+
| onTestsComplete[<sup>*</sup>][14]|*Function*|| Hook run *after* the tests complete, *before* Istanbul reports are generated.|
76
+
| onIstanbulComplete[<sup>*</sup>][14]|*Function*|| Hook run *after* the Istanbul reports are generated, *before* the ganache server is shut down. Useful if you need to clean resources up.|
77
+
78
+
[<sup>*</sup> Advanced use][14]
79
+
80
+
## FAQ
81
+
82
+
Common problems & questions:
83
+
84
+
+[Running in CI][7]
85
+
+[Running out of gas][4]
86
+
+[Running out of time][6]
87
+
+[Running out of memory][5]
88
+
+[Why are `require` statements highlighted as branch points?][8]
89
+
90
+
91
+
## Example reports
92
+
+[metacoin][9] (Istanbul HTML)
93
+
+[openzeppelin-solidity][10](Coveralls)
94
+
95
+
## Contribution Guidelines
96
+
97
+
Contributions are welcome! If you're opening a PR that adds features or options *please consider
98
+
writing full [unit tests][11] for them*. (We've built simple fixtures for almost everything
99
+
and are happy to add some for your case if necessary).
0 commit comments