Docs for beta release (#415)
cgewecke
5 years ago
parent
fab8aaa543
commit
00f32f68d2
@ -1,3 +1,4 @@ |
|||||||
test/ |
test/ |
||||||
.circleci/ |
.circleci/ |
||||||
docs/ |
docs/ |
||||||
|
.nyc_output/ |
||||||
|
|||||||
@ -0,0 +1,88 @@ |
|||||||
|
# Advanced Use |
||||||
|
|
||||||
|
## Skipping tests |
||||||
|
|
||||||
|
Sometimes it's convenient to skip specific tests when running coverage. You can do this by |
||||||
|
tagging your test descriptions and setting appropriate filters in the `.solcover.js` mocha options. |
||||||
|
|
||||||
|
**Example** |
||||||
|
```javascript |
||||||
|
// Mocha test to skip |
||||||
|
it("is a gas usage simulation [ @skip-on-coverage ]", async function(){ |
||||||
|
... |
||||||
|
}) |
||||||
|
``` |
||||||
|
|
||||||
|
```javascript |
||||||
|
//.solcover.js |
||||||
|
module.exports = { |
||||||
|
mocha: { |
||||||
|
grep: "@skip-on-coverage", // Find everything with this tag |
||||||
|
invert: true // Run the grep's inverse set. |
||||||
|
} |
||||||
|
} |
||||||
|
``` |
||||||
|
|
||||||
|
## Workflow hooks |
||||||
|
|
||||||
|
The plugin exposes a set of workflow hooks that let you run arbitrary async logic between the main |
||||||
|
stages of the coverage generation process. These are useful for tasks like launching secondary |
||||||
|
services which need to connect to a running ganache instance (ex: the Oraclize/Provable bridge), |
||||||
|
or reading data from the compilation artifacts to run special preparatory steps for your tests. |
||||||
|
|
||||||
|
The stages/hooks are (in order of execution): |
||||||
|
|
||||||
|
| Stage | Post-stage hook | |
||||||
|
|----------------------------------------|--------------------| |
||||||
|
| Launch server | onServerReady | |
||||||
|
| Instrument and compile contracts | onCompileComplete | |
||||||
|
| Run tests using instrumented artifacts | onTestsComplete | |
||||||
|
| Generate istanbul coverage reports | onIstanbulComplete | |
||||||
|
|
||||||
|
The tool's general workflow is: |
||||||
|
|
||||||
|
+ Launch an ethereum client, attaching special listeners that monitor each opcode execution step |
||||||
|
+ Read Solidity contract sources from a standard contracts directory |
||||||
|
+ Rewrite the sources so the code execution path can be tracked by the opcode monitors. |
||||||
|
+ Compile the modified sources, without optimization |
||||||
|
+ Save the compilation artifacts to a temporary folder |
||||||
|
+ Tell the testing framework to use the instrumented artifacts & run tests to completion. |
||||||
|
+ Transfer collected data to a coverage reporter & report. |
||||||
|
|
||||||
|
Each hook is passed a `config` object provided by your plugin's dev platform which will contain |
||||||
|
relevant source/artifact paths and network info for that stage. |
||||||
|
|
||||||
|
**Example** |
||||||
|
|
||||||
|
```javascript |
||||||
|
// .solcover.js |
||||||
|
const { provableBridge } = require('./helpers'); |
||||||
|
|
||||||
|
async function serverReadyHandler(config){ |
||||||
|
await provableBridge(config.port); |
||||||
|
} |
||||||
|
|
||||||
|
module.exports = { |
||||||
|
onServerReady: serverReadyHandler, |
||||||
|
} |
||||||
|
``` |
||||||
|
|
||||||
|
## Setting the temporary artifacts directory |
||||||
|
|
||||||
|
The `temp` command line option lets you to specify the name of a disposable folder to |
||||||
|
stage the compilation artifacts of instrumented contracts in before the tests are run. |
||||||
|
|
||||||
|
**Example** |
||||||
|
``` |
||||||
|
$ truffle run coverage --temp build |
||||||
|
``` |
||||||
|
|
||||||
|
By default this folder is called `.coverage_artifacts`. If you already have |
||||||
|
preparatory scripts which run between compilation and the tests, you'll probably |
||||||
|
find it inconvenient to modify them to handle an alternate path. |
||||||
|
|
||||||
|
This option allows you to avoid that but it's important to realise that the temp |
||||||
|
folder is **automatically deleted** when coverage completes. You shouldn't use it if your preferred |
||||||
|
build target contains information you want to preserve between test runs. |
||||||
|
|
||||||
|
|
||||||
@ -1,91 +0,0 @@ |
|||||||
# How to upgrade testrpc-sc |
|
||||||
|
|
||||||
Warning: this is a birds nest. Any ideas for improvement, however small, are welcome. |
|
||||||
|
|
||||||
### testrpc-sc: |
|
||||||
+ published on `npm` as `ethereumjs-testrpc-sc` |
|
||||||
+ published **from the coverage branch** of [`sc-forks/testrpc-sc`](https://github.com/sc-forks/testrpc-sc/tree/coverage) |
|
||||||
+ a webpack bundle of `sc-forks/ganache-core-sc#coverage` and all of its dependencies. |
|
||||||
+ changes to `sc-forks/ganache-core` do not propagate until `testrpc-sc` is rebuilt and published |
|
||||||
+ publishing `testrpc-sc` does not propagate until `solidity-coverage`s deps are updated. |
|
||||||
|
|
||||||
To publish a new version: |
|
||||||
|
|
||||||
``` |
|
||||||
$ git checkout develop |
|
||||||
$ git pull upstream develop |
|
||||||
$ git checkout coverage |
|
||||||
$ git rebase develop |
|
||||||
|
|
||||||
> Update your ganache-core hash |
|
||||||
> NOTE TO CGEWECKE: MAKE SURE YOU RENAMED THE PACKAGE (and the .bin command)!!!! |
|
||||||
> OTHERWISE YOU WILL PUBLISH OVER THE REAL GANACHE-CLI |
|
||||||
> |
|
||||||
|
|
||||||
$ rm -rf node_modules |
|
||||||
$ yarn install // This step seems to be absolutely necessary. |
|
||||||
$ npm run build // Check build, just to make sure |
|
||||||
$ npm version patch // If helpful. If you're tracking the upstream with a ganache-core sync, use theirs. |
|
||||||
$ git push |
|
||||||
$ npm publish // This also runs build. |
|
||||||
|
|
||||||
// Go to `solidity-coverage` and pin its `testrpc-sc` dependency to the new version. |
|
||||||
``` |
|
||||||
### sc-forks/ganache-core-sc: |
|
||||||
+ is what testrpc-sc used to be |
|
||||||
+ set by default to [its `coverage` branch](https://github.com/sc-forks/ganache-core-sc) |
|
||||||
+ depends on `sc-forks/ethereumjs-vm-sc.git` |
|
||||||
+ depends on `sc-forks/provider-engine-sc.git#8.1.19` |
|
||||||
+ differs from `truffle-suite/ganache-core` by these deps and |
|
||||||
[two lines](https://github.com/sc-forks/ganache-core/blob/ae31080cdc581fef416a1c68cbe28ff71b6fb7c9/lib/blockchain_double.js#L36-L37) |
|
||||||
in `blockchain_double.js` which set the block and transaction default gas limits. |
|
||||||
|
|
||||||
To sync `ganache-core-sc` with its upstream parent at `truffle-suite` |
|
||||||
``` |
|
||||||
$ git checkout master |
|
||||||
$ git remote add upstream https://github.com/trufflesuite/ganache-core.git |
|
||||||
$ git pull upstream master |
|
||||||
$ git push |
|
||||||
$ git checkout coverage |
|
||||||
$ git rebase -i master (there will probably be conflicts) |
|
||||||
$ git push |
|
||||||
``` |
|
||||||
|
|
||||||
### How can I modify ethereumjs-vm-sc and test the changes at `solidity-coverage`? |
|
||||||
|
|
||||||
Since `solidity-coverage@0.1.10`, ethereumjs-vm-sc is an independent dev dependency, |
|
||||||
required by the coverage unit tests. The new testrpc has a separate webpacked copy. The simplest |
|
||||||
thing to do is open a branch at `solidity-coverage` and develop directly on the `vm` dep. |
|
||||||
When you're satisfied that tests pass with your changes, copy your work over to the `ethereumjs-vm-sc` repo itself. |
|
||||||
|
|
||||||
In `test/util/vm.js` the `results` object passed back by `vm.runTx` at [callMethod](https://github.com/sc-forks/solidity-coverage/blob/master/test/util/vm.js#L120) |
|
||||||
also contains things like the runState and the logs: ex: `results.vm.runState.logs`. |
|
||||||
|
|
||||||
+ To merge / publish the changes: |
|
||||||
+ Merge `ethereumjs-vm-sc#my-new-vm` to master. |
|
||||||
+ follow the `testrpc-sc` publication steps above. |
|
||||||
|
|
||||||
There's no reason to worry about changing ethereumjs-vm-sc at master. If that affects anyone (unlikely) |
|
||||||
they have safe harbour at any solidity-coverage installation @0.1.9 and up. They can update. |
|
||||||
|
|
||||||
### E2E Testing |
|
||||||
|
|
||||||
[sc-forks/zeppelin-solidity](https://github.com/sc-forks/zeppelin-solidity) has been configured to |
|
||||||
serve as a simple pre-publication E2E test. By default the package pulls solidity-coverage from the repo's master branch. |
|
||||||
You can trigger a [CI build](https://travis-ci.org/sc-forks/zeppelin-solidity) and [Coveralls report](https://coveralls.io/github/sc-forks/zeppelin-solidity) by running: |
|
||||||
|
|
||||||
``` |
|
||||||
$ npm run ci |
|
||||||
``` |
|
||||||
|
|
||||||
### solidity-parser-sc |
|
||||||
|
|
||||||
We also publish `solidity-parser-sc` because `consensys/solidity-parser` in its .pegjs form has been |
|
||||||
left to die in the wild, unloved by all. Publish at the publish branch by running `npm version patch`, `npm publish`. |
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
@ -0,0 +1,138 @@ |
|||||||
|
# How to install 0.7.0 |
||||||
|
|
||||||
|
**Install** |
||||||
|
``` |
||||||
|
$ npm install --save-dev solidity-coverage@beta |
||||||
|
``` |
||||||
|
|
||||||
|
**Add** this package to your plugins array in `truffle-config.js` |
||||||
|
```javascript |
||||||
|
module.exports = { |
||||||
|
networks: {...}, |
||||||
|
plugins: ["solidity-coverage"] |
||||||
|
} |
||||||
|
``` |
||||||
|
**Run** |
||||||
|
``` |
||||||
|
truffle run coverage [command-options] |
||||||
|
``` |
||||||
|
|
||||||
|
A full list of options and other information are [available here][8] |
||||||
|
|
||||||
|
# Upgrading from 0.6.x to 0.7.0-beta.x |
||||||
|
|
||||||
|
First, follow [the installation instructions](#how-to-install-070) and see if it works. |
||||||
|
|
||||||
|
:rabbit2: It does!? Bye. |
||||||
|
|
||||||
|
:elephant: It does not. Good... |
||||||
|
|
||||||
|
#### Are you using Truffle V5? |
||||||
|
|
||||||
|
+ Everything works best with Truffle versions >= 5.0.31. |
||||||
|
|
||||||
|
#### Are you launching testrpc-sc yourself as a stand-alone client? |
||||||
|
|
||||||
|
+ Stop launching it. The coverage plugin needs to initialize the client itself so it can hook into the EVM. |
||||||
|
|
||||||
|
+ By default it uses the ganache bundled with Truffle, but you can use any version (see below). |
||||||
|
|
||||||
|
#### Were you passing testrpc-sc lots of options as flags? :jp: :jp: :jp: :jp: :jp: |
||||||
|
|
||||||
|
+ If the flags were `allowUnlimitedContractSize`, `gasLimit`, `gasPrice` or `emitFreeLogs`, |
||||||
|
you can safely ignore them. Ditto if your port was `8555`. |
||||||
|
|
||||||
|
+ If the flags were things like `accounts` or `network_id`, you'll need to transfer them as |
||||||
|
[ganache-core options][1] to the `providerOptions` key in .solcover.js. |
||||||
|
|
||||||
|
+ Ganache's "cli flag" and "js option" formats are slightly different. Check out [their docs][1] |
||||||
|
|
||||||
|
**Example** |
||||||
|
|
||||||
|
*Before (at the command line)* |
||||||
|
``` |
||||||
|
$ testrpc-sc --account="0x2b...7cd,1000000000000000000000000" -i 1999 --noVmErrorsOnRPCResponse |
||||||
|
``` |
||||||
|
|
||||||
|
*Now (in .solcover.js)* |
||||||
|
```javascript |
||||||
|
providerOptions: { |
||||||
|
accounts: [{ |
||||||
|
secretKey: "0x2b.............7cd", |
||||||
|
balance: "0xD3C21BCECCEDA1000000" // <-- Must be hex |
||||||
|
}], |
||||||
|
network_id: 1999, |
||||||
|
vmErrorsOnRPCResponse: false |
||||||
|
} |
||||||
|
|
||||||
|
#### Do you have a 'coverage' network in truffle-config.js? |
||||||
|
|
||||||
|
+ If you copy-pasted it from the <= 0.6.x docs, **you can safely delete it**. |
||||||
|
|
||||||
|
+ You should be able to `truffle run coverage --network <network-name>` and use the same config you |
||||||
|
run your regular tests with. |
||||||
|
|
||||||
|
+ You can also omit the network flag and you'll be given default settings which look like this: |
||||||
|
```javascript |
||||||
|
'soliditycoverage': { |
||||||
|
port: 8555, |
||||||
|
host: "127.0.0.1", |
||||||
|
network_id: "*", |
||||||
|
} |
||||||
|
``` |
||||||
|
#### Do your tests depend on the specific ganache version you have as a local dependency? |
||||||
|
|
||||||
|
+ Declare it in .solcover.js using the client option |
||||||
|
```javascript |
||||||
|
client: require('ganache-cli'), |
||||||
|
``` |
||||||
|
|
||||||
|
#### Does your config contain any deprecated options? |
||||||
|
+ They are: |
||||||
|
``` |
||||||
|
accounts, # Now: `providerOptions: { total_accounts: <number> }` |
||||||
|
buildDirPath, # Now: `--temp <path>` (At the command line, see Advanced Use) |
||||||
|
copyPackages, |
||||||
|
copyNodeModules, |
||||||
|
deepSkip, |
||||||
|
testCommand, |
||||||
|
compileCommand, |
||||||
|
noRpc |
||||||
|
``` |
||||||
|
|
||||||
|
+ You can delete them. |
||||||
|
|
||||||
|
#### Do you usually: (1) launch testrpc-sc, (2) do something special, (3) run solidity-coverage? |
||||||
|
|
||||||
|
+ See [the workflow hooks documentation][3]. The "something special" will likely need to run within |
||||||
|
an async function declared in .solcover.js |
||||||
|
|
||||||
|
#### Are you what some might call an 'advanced user'? |
||||||
|
|
||||||
|
+ See [Advanced Use][2] |
||||||
|
|
||||||
|
#### Would you like to see some real-world installation examples? |
||||||
|
|
||||||
|
+ [metacoin][4] |
||||||
|
+ [openzeppelin-contracts][5] |
||||||
|
+ [joinColony/colonyNetwork][6] |
||||||
|
+ [aragon/aragon-court][7] |
||||||
|
|
||||||
|
#### :tada: It's still not working!! :tada: |
||||||
|
|
||||||
|
+ If your project is public, please open an issue linking to it and we will advise and/or |
||||||
|
open a PR into your repo installing solidity-coverage after patching any relevant bugs here. |
||||||
|
|
||||||
|
+ If your project is private, see if you can generate a reproduction case for the |
||||||
|
problem and we'll try to fix that. |
||||||
|
|
||||||
|
|
||||||
|
[1]: https://github.com/trufflesuite/ganache-core#options |
||||||
|
[2]: https://github.com/sc-forks/solidity-coverage/blob/beta/docs/advanced.md |
||||||
|
[3]: https://github.com/sc-forks/solidity-coverage/blob/beta/docs/advanced.md#workflow-hooks |
||||||
|
[4]: https://github.com/sc-forks/metacoin |
||||||
|
[5]: https://github.com/OpenZeppelin/openzeppelin-contracts/pull/1923 |
||||||
|
[6]: https://github.com/JoinColony/colonyNetwork/pull/716 |
||||||
|
[7]: https://github.com/aragon/aragon-court/pull/123 |
||||||
|
[8]: https://github.com/sc-forks/solidity-coverage/tree/beta#command-options |
||||||
|
|
||||||
Loading…
Reference in new issue