1
- # SolCover
1
+ # solidity-coverage
2
2
3
- ![ CircleCI Status ] ( https://circleci.com/gh/JoinColony/solcover .svg?style=shield&circle-token=53d5360d290ef593c7bdce505b86ae8b9414e684 )
4
- [ ![ codecov] ( https://codecov.io/gh/JoinColony/solcover /branch/master/graph/badge.svg )] ( https://codecov.io/gh/JoinColony/solcover )
3
+ [ ![ CircleCI] ( https://circleci.com/gh/sc-forks/solidity-coverage .svg?style=svg )] ( https://circleci.com/gh/sc-forks/solidity-coverage )
4
+ [ ![ codecov] ( https://codecov.io/gh/sc-forks/solidity-coverage /branch/master/graph/badge.svg )] ( https://codecov.io/gh/sc-forks/solidity-coverage )
5
5
6
6
### Code coverage for Solidity testing
7
7
![ coverage example] ( https://cdn-images-1.medium.com/max/800/1*uum8t-31bUaa6dTRVVhj6w.png )
8
8
9
9
For more details about what this is, how it works and potential limitations, see
10
10
[ the accompanying article] ( https://blog.colony.io/code-coverage-for-solidity-eecfa88668c2 ) .
11
11
12
+ (solidity-coverage is a stand-alone fork of [ Solcover] ( https://github.com/JoinColony/solcover ) )
13
+
12
14
### Install
13
15
```
14
- $ npm install --save-dev https://github.com/JoinColony/solcover .git#truffle3
16
+ $ npm install --save-dev https://github.com/sc-forks/solidity-coverage .git
15
17
```
16
18
17
19
### Run
18
20
```
19
- $ ./node_modules/solcover /exec.js
21
+ $ ./node_modules/solidity-coverage /exec.js
20
22
```
21
23
22
24
Tests run signficantly slower while coverage is being generated. A 1 to 2 minute delay
@@ -25,13 +27,13 @@ test suite is large. Large solidity files can also take a while to instrument.
25
27
26
28
### Configuration
27
29
28
- By default, Solcover generates a stub ` truffle.js ` that accomodates its special gas needs and
30
+ By default, solidity-coverage generates a stub ` truffle.js ` that accomodates its special gas needs and
29
31
connects to a modified version of testrpc on port 8555. If your tests will run on the development network
30
32
using a standard ` truffle.js ` and a testrpc instance with no special options, you shouldn't have to
31
33
do any configuration. If your tests depend on logic added to ` truffle.js ` - for example:
32
34
[ zeppelin-solidity] ( https://github.com/OpenZeppelin/zeppelin-solidity/blob/master/truffle.js )
33
35
uses the file to expose a babel polyfill that its suite requires - you can override the
34
- default behavior by declaring a coverage network in ` truffle.js ` . Solcover will use your 'truffle.js'
36
+ default behavior by declaring a coverage network in ` truffle.js ` . solidity-coverage will use your 'truffle.js'
35
37
instead of a dynamically generated one.
36
38
37
39
** Example coverage network config**
@@ -56,63 +58,87 @@ module.exports = {
56
58
57
59
You can also create a ` .solcover.js ` config file in the root directory of your project and specify
58
60
some additional options:
59
- + ** port** : <Number > The port you want Solcover to run testrpc on / have truffle connect to.
61
+ + ** port** : <Number > The port you want solidity-coverage to run testrpc on / have truffle connect to.
60
62
+ ** testrpcOptions** : <String > A string of options to be appended to a command line invocation
61
63
of testrpc.
62
64
+ Example: ` --account="0x89a...b1f',10000" --port 8777 ` ".
63
65
+ Note: you should specify the port in your ` testrpcOptions ` string AND as a ` port ` option.
64
- + ** testCommand** : <String > By default Solcover runs ` truffle test ` or ` truffle test --network coverage ` .
66
+ + ** testCommand** : <String > By default solidity-coverage runs ` truffle test ` or ` truffle test --network coverage ` .
65
67
This option lets you run tests some other way: ex: ` mocha --timeout 5000 ` . You
66
- will probably also need to make sure the web3 provider for your tests explicitly connects to the port Solcover 's
68
+ will probably also need to make sure the web3 provider for your tests explicitly connects to the port solidity-coverage 's
67
69
testrpc is set to run on, e.g:
68
- + ` var web3 = new Web3(new Web3.providers.HttpProvider("http://localhost:8555")) `
70
+ + ` var web3 = new Web3(new Web3.providers.HttpProvider("http://localhost:8555")) `
71
+ + ** norpc** : <Boolean > : By default, false. When true, solidity-coverage will not launch its own testrpc instance. This
72
+ can be useful if you are running tests using a different vm like the
73
+ [ ` sc-forks ` version of ` pyethereum ` ] ( https://github.com/sc-forks/pyethereum )
74
+ + ** dir** : <String > : By default, solidity-coverage looks for a ` contracts ` folder in your root
75
+ directory. ` dir ` allows you to define a relative path from the root directory to the contracts
76
+ folder. A ` dir ` of ` ./secretDirectory ` would tell solidity-coverage to look for ` ./secretDirectory/contracts `
69
77
70
78
** Example .solcover.js config file**
71
79
```
72
80
module.exports = {
73
81
port: 6545,
74
82
testrpcOptions: '-p 6545 -u 0x54fd80d6ae7584d8e9a19fe1df43f04e5282cc43',
75
83
testCommand: 'mocha --timeout 5000'
84
+ norpc: 'true'
85
+ dir: './secretDirectory'
76
86
};
77
87
```
78
88
79
89
### Known Issues
80
90
81
- ** Hardcoded gas costs** : If you have hardcoded gas costs into your tests some of them may fail when using SolCover .
91
+ ** Hardcoded gas costs** : If you have hardcoded gas costs into your tests some of them may fail when using solidity-coverage .
82
92
This is because the instrumentation process increases the gas costs for using the contracts, due to
83
93
the extra events. If this is the case, then the coverage may be incomplete. To avoid this, using
84
94
` estimateGas ` to estimate your gas costs should be more resilient in most cases.
85
95
86
- ** Events testing** : Because Solcover injects events into your contracts to log which lines your tests reach,
96
+ ** Events testing** : Because solidity-coverage injects events into your contracts to log which lines your tests reach,
87
97
any tests that ask how many events are fired or where the event sits in the logs array
88
98
will probably error while coverage is being generated.
89
99
90
100
** Using ` require ` in ` migrations.js ` files** : Truffle overloads Node's ` require ` function but
91
101
implements a simplified search algorithm for node_modules packages
92
102
([ see issue #383 at Truffle] ( https://github.com/trufflesuite/truffle/issues/383 ) ).
93
- Because Solcover copies an instrumented version of your project into a temporary folder, ` require `
103
+ Because solidity-coverage copies an instrumented version of your project into a temporary folder, ` require `
94
104
statements handled by Truffle internally won't resolve correctly.
95
105
96
- ** Coveralls / CodeCov** : These CI services take the Istanbul reports generated by Solcover and display
106
+ ** Coveralls / CodeCov** : These CI services take the Istanbul reports generated by solidity-coverage and display
97
107
line coverage. Istanbul's own html report publishes significantly more detail and can show whether
98
108
your tests actually reach all the conditional branches in your code. It can be found inside the
99
109
` coverage ` folder at ` index.html ` after you run the tool.
100
110
101
111
### Examples
102
112
103
- + ** Metacoin** : The default truffle project
113
+ ** WARNING** : This utility is in development and its accuracy is unknown. If you
114
+ find discrepancies between the coverage report and your suite's behavior, please open an
115
+ [ issue] ( https://github.com/sc-forks/solidity-coverage/issues ) . The purpose of
116
+ the following examples is to help you install solidity-coverage in your own project and evaluate the
117
+ coverage of your own tests. The reports below are ** not** meaningful analyses of the
118
+ the past or present state of any project's testing regime.
119
+
120
+ + ** metacoin** : The default truffle project
104
121
+ [ HTML reports] ( https://sc-forks.github.io/metacoin/ )
105
- + [ Metacoin with Solcover installed] ( https://github.com/sc-forks/metacoin ) (simple, without configuration)
122
+ + [ Metacoin with solidity-coverage installed] ( https://github.com/sc-forks/metacoin ) (simple, without configuration)
106
123
+ ** zeppelin-solidity** at commit 453a19825013a586751b87c67bebd551a252fb50
107
124
+ [ HTML reports] ( https://sc-forks.github.io/zeppelin-solidity/ )
108
- + [ Zeppelin with Solcover installed] ( https://github.com/sc-forks/zeppelin-solidity ) (declares own coverage network in truffle.js)
125
+ + [ Zeppelin with solidity-coverage installed] ( https://github.com/sc-forks/zeppelin-solidity ) (declares own coverage network in truffle.js)
109
126
+ ** numeraire** at commit 5ac3fa432c6b4192468c95a66e52ca086c804c95
110
127
+ [ HTML reports] ( https://sc-forks.github.io/contract/ )
111
- + [ Numeraire with Solcover installed] ( https://github.com/sc-forks/contract ) (uses .solcover.js)
128
+ + [ Numeraire with solidity-coverage installed] ( https://github.com/sc-forks/contract ) (uses .solcover.js)
129
+
130
+ ### Contribution Guidelines
131
+
132
+ Contributions are welcome! If you're opening a PR that adds features please consider writing some
133
+ [ unit tests] ( https://github.com/sc-forks/solidity-coverage/tree/master/test ) for them. You could
134
+ also lint your submission by running 'npm run lint'. Bugs can be reported in the
135
+ [ issues] ( https://github.com/sc-forks/solidity-coverage/issues )
136
+
137
+ ### Contributors
138
+ + [ @area ] ( https://github.com/area )
139
+ + [ @cgewecke ] ( https://github.com/cgewecke )
140
+ + [ @adriamb ] ( https://github.com/adriamb )
112
141
113
142
### TODO
114
143
115
- - [ ] Turn into a true command line tool, rather than just a hacked-together script
116
144
- [ ] Release on NPM
117
- - [ ] Support for arbitrary testing commands
118
- - [ ] [ You tell me] ( http://github.com/JoinColony/solcover/issues )
0 commit comments