Skip to content

Commit 939c2bb

Browse files
authored
Merge pull request #2 from sc-forks/readme-edits
Edit readme
2 parents 4c2c9e5 + d79524f commit 939c2bb

File tree

1 file changed

+48
-22
lines changed

1 file changed

+48
-22
lines changed

README.md

Lines changed: 48 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -1,22 +1,24 @@
1-
# SolCover
1+
# solidity-coverage
22

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)
55

66
### Code coverage for Solidity testing
77
![coverage example](https://cdn-images-1.medium.com/max/800/1*uum8t-31bUaa6dTRVVhj6w.png)
88

99
For more details about what this is, how it works and potential limitations, see
1010
[the accompanying article](https://blog.colony.io/code-coverage-for-solidity-eecfa88668c2).
1111

12+
(solidity-coverage is a stand-alone fork of [Solcover](https://github.com/JoinColony/solcover))
13+
1214
### Install
1315
```
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
1517
```
1618

1719
### Run
1820
```
19-
$ ./node_modules/solcover/exec.js
21+
$ ./node_modules/solidity-coverage/exec.js
2022
```
2123

2224
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.
2527

2628
### Configuration
2729

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
2931
connects to a modified version of testrpc on port 8555. If your tests will run on the development network
3032
using a standard `truffle.js` and a testrpc instance with no special options, you shouldn't have to
3133
do any configuration. If your tests depend on logic added to `truffle.js` - for example:
3234
[zeppelin-solidity](https://github.com/OpenZeppelin/zeppelin-solidity/blob/master/truffle.js)
3335
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'
3537
instead of a dynamically generated one.
3638

3739
**Example coverage network config**
@@ -56,63 +58,87 @@ module.exports = {
5658

5759
You can also create a `.solcover.js` config file in the root directory of your project and specify
5860
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.
6062
+ **testrpcOptions**: <String> A string of options to be appended to a command line invocation
6163
of testrpc.
6264
+ Example: `--account="0x89a...b1f',10000" --port 8777`".
6365
+ 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`.
6567
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
6769
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`
6977

7078
**Example .solcover.js config file**
7179
```
7280
module.exports = {
7381
port: 6545,
7482
testrpcOptions: '-p 6545 -u 0x54fd80d6ae7584d8e9a19fe1df43f04e5282cc43',
7583
testCommand: 'mocha --timeout 5000'
84+
norpc: 'true'
85+
dir: './secretDirectory'
7686
};
7787
```
7888

7989
### Known Issues
8090

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.
8292
This is because the instrumentation process increases the gas costs for using the contracts, due to
8393
the extra events. If this is the case, then the coverage may be incomplete. To avoid this, using
8494
`estimateGas` to estimate your gas costs should be more resilient in most cases.
8595

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,
8797
any tests that ask how many events are fired or where the event sits in the logs array
8898
will probably error while coverage is being generated.
8999

90100
**Using `require` in `migrations.js` files**: Truffle overloads Node's `require` function but
91101
implements a simplified search algorithm for node_modules packages
92102
([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`
94104
statements handled by Truffle internally won't resolve correctly.
95105

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
97107
line coverage. Istanbul's own html report publishes significantly more detail and can show whether
98108
your tests actually reach all the conditional branches in your code. It can be found inside the
99109
`coverage` folder at `index.html` after you run the tool.
100110

101111
### Examples
102112

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
104121
+ [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)
106123
+ **zeppelin-solidity** at commit 453a19825013a586751b87c67bebd551a252fb50
107124
+ [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)
109126
+ **numeraire** at commit 5ac3fa432c6b4192468c95a66e52ca086c804c95
110127
+ [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)
112141

113142
### TODO
114143

115-
- [ ] Turn into a true command line tool, rather than just a hacked-together script
116144
- [ ] Release on NPM
117-
- [ ] Support for arbitrary testing commands
118-
- [ ] [You tell me](http://github.com/JoinColony/solcover/issues)

0 commit comments

Comments
 (0)