Docs for beta release (#415)
cgewecke
5 years ago
parent
fab8aaa543
commit
00f32f68d2
@ -1,3 +1,4 @@ |
||||
test/ |
||||
.circleci/ |
||||
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