From e8461e073c3cc417840bd813370253e3164bf71d Mon Sep 17 00:00:00 2001 From: cgewecke Date: Thu, 12 Nov 2020 20:37:36 -0800 Subject: [PATCH 1/3] Add hardhat readme --- HARDHAT_README.md | 130 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 130 insertions(+) create mode 100644 HARDHAT_README.md diff --git a/HARDHAT_README.md b/HARDHAT_README.md new file mode 100644 index 00000000..cc597baf --- /dev/null +++ b/HARDHAT_README.md @@ -0,0 +1,130 @@ +[![Gitter chat](https://badges.gitter.im/sc-forks/solidity-coverage.svg)][18] +![npm (tag)](https://img.shields.io/npm/v/solidity-coverage/latest) +[![CircleCI](https://circleci.com/gh/sc-forks/solidity-coverage.svg?style=svg)][20] +[![codecov](https://codecov.io/gh/sc-forks/solidity-coverage/branch/beta/graph/badge.svg)][21] +[![hardhat](https://hardhat.org/buidler-plugin-badge.svg?1)][26] + +# solidity-coverage + +Solidity code coverage plugin for [Hardhat](http://hardhat.org). + +## What + +![coverage example][22] + ++ For more details about how it works and potential limitations, see [the accompanying article][16]. ++ `solidity-coverage` is also [JoinColony/solcover][17] + + +## Installation + +```bash +$ npm install --save-dev solidity-coverage +``` + +And add the following to your `.config.js`: + +```js +require"solidity-coverage"); +``` + +Or, if you are using TypeScript, add this to your hardhat.config.ts: + +```ts +import "solidity-coverage" +``` + +## Tasks + +This plugin implements a `coverage` task + +```bash +npx coverage [options] +``` + +| Option | Example | Description | +|--------------|------------------------------------|--------------------------------| +| testfiles | `--testfiles "test/registry/*.ts"` | Test file(s) to run. (Globs must be enclosed by quotes.)| +| solcoverjs | `--solcoverjs ./../.solcover.js` | Relative path from working directory to config. Useful for monorepo packages that share settings. (Path must be "./" prefixed) | +| network | `--network development` | Run with a ganache client over http using network settings defined in the Hardhat config | + + +## Configuration + +Options can be specified in a `.solcover.js` config file located in the root directory of your project. + +**Config Example:** +```javascript +module.exports = { + skipFiles: ['Routers/EtherRouter.sol'] +}; +``` + +| Option | Type | Default | Description | +| ------ | ---- | ------- | ----------- | +| silent | *Boolean* | false | Suppress logging output | +| client | *Object* | undefined | (Ganache only) Useful if you need a specific ganache version. An example value is: `require('ganache-cli')` | +| providerOptions | *Object* | `{ }` | (Ganache only) [ganache-core options][1] | +| skipFiles | *Array* | `['Migrations.sol']` | Array of contracts or folders (with paths expressed relative to the `contracts` directory) that should be skipped when doing instrumentation. | +| istanbulFolder | *String* | `./coverage` | Folder location for Istanbul coverage reports. | +| istanbulReporter | *Array* | `['html', 'lcov', 'text', 'json']` | [Istanbul coverage reporters][2] | +| 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.| +| onServerReady[*][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...][23] | +| onCompileComplete[*][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...][23]| +| onTestsComplete[*][14] | *Function* | | Hook run *after* the tests complete, *before* Istanbul reports are generated. [More...][23]| +| onIstanbulComplete[*][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. [More...][23]| + +[* Advanced use][14] + +## Usage + ++ Coverage runs tests a little more slowly. ++ Coverage uses the Hardhat network by default. ++ Coverage [distorts gas consumption][13]. Tests that check exact gas consumption should be [skipped][24]. ++ :warning: Contracts are compiled **without optimization**. Please report unexpected compilation faults to [issue 417][25] + +## Using with ganache + +Begining with `v0.7.12`, solidity-coverage runs directly on the Hardhat network by default (for speed). If you want to use a ganache based http network, you can specify it by name using the `--network` cli option. Solidity-coverage will launch a coverage enabled in-process ganache +instance which can be configured in `.solcover.js` via the `providerOptions` key. + +## Documentation + +More documentation, including FAQ and information about solidity-coverage's API [is available here][28]. + + +[1]: https://github.com/trufflesuite/ganache-core#options +[2]: https://istanbul.js.org/docs/advanced/alternative-reporters/ +[3]: https://mochajs.org/api/mocha +[4]: https://github.com/sc-forks/solidity-coverage/blob/master/docs/faq.md#running-out-of-gas +[5]: https://github.com/sc-forks/solidity-coverage/blob/master/docs/faq.md#running-out-of-memory +[6]: https://github.com/sc-forks/solidity-coverage/blob/master/docs/faq.md#running-out-of-time +[7]: https://github.com/sc-forks/solidity-coverage/blob/master/docs/faq.md#continuous-integration +[8]: https://github.com/sc-forks/solidity-coverage/blob/master/docs/faq.md#notes-on-branch-coverage +[9]: https://sc-forks.github.io/metacoin/ +[10]: https://coveralls.io/github/OpenZeppelin/openzeppelin-solidity?branch=master +[11]: https://github.com/sc-forks/solidity-coverage/tree/master/test/units +[12]: https://github.com/sc-forks/solidity-coverage/issues +[13]: https://github.com/sc-forks/solidity-coverage/blob/master/docs/faq.md#notes-on-gas-distortion +[14]: https://github.com/sc-forks/solidity-coverage/blob/master/docs/advanced.md +[15]: #config-options +[16]: https://blog.colony.io/code-coverage-for-solidity-eecfa88668c2 +[17]: https://github.com/JoinColony/solcover +[18]: https://gitter.im/sc-forks/solidity-coverage?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge +[19]: https://badge.fury.io/js/solidity-coverage +[20]: https://circleci.com/gh/sc-forks/solidity-coverage +[21]: https://codecov.io/gh/sc-forks/solidity-coverage +[22]: https://cdn-images-1.medium.com/max/800/1*uum8t-31bUaa6dTRVVhj6w.png +[23]: https://github.com/sc-forks/solidity-coverage/blob/master/docs/advanced.md#workflow-hooks +[24]: https://github.com/sc-forks/solidity-coverage/blob/master/docs/advanced.md#skipping-tests +[25]: https://github.com/sc-forks/solidity-coverage/issues/417 +[26]: https://hardhat.org/ +[27]: https://www.trufflesuite.com/docs +[28]: https://github.com/sc-forks/solidity-coverage/blob/master/docs/api.md +[29]: https://github.com/sc-forks/solidity-coverage/blob/master/docs/upgrade.md#upgrading-from-06x-to-070 +[30]: https://github.com/sc-forks/solidity-coverage/tree/0.6.x-final#solidity-coverage +[31]: https://github.com/sc-forks/solidity-coverage/releases/tag/v0.7.0 +[32]: https://github.com/sc-forks/buidler-e2e/tree/coverage +[33]: https://github.com/sc-forks/moloch +[34]: https://github.com/sc-forks/solidity-coverage/blob/master/docs/advanced.md#reducing-the-instrumentation-footprint + From 8281ecc36d55ea9e43bcc309bdcb0dda834e73bf Mon Sep 17 00:00:00 2001 From: cgewecke Date: Thu, 12 Nov 2020 20:52:31 -0800 Subject: [PATCH 2/3] Fixes --- HARDHAT_README.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/HARDHAT_README.md b/HARDHAT_README.md index cc597baf..8d6b7ca0 100644 --- a/HARDHAT_README.md +++ b/HARDHAT_README.md @@ -25,7 +25,7 @@ $ npm install --save-dev solidity-coverage And add the following to your `.config.js`: ```js -require"solidity-coverage"); +require("solidity-coverage"); ``` Or, if you are using TypeScript, add this to your hardhat.config.ts: @@ -39,14 +39,14 @@ import "solidity-coverage" This plugin implements a `coverage` task ```bash -npx coverage [options] +npx hardhat coverage [options] ``` | Option | Example | Description | |--------------|------------------------------------|--------------------------------| | testfiles | `--testfiles "test/registry/*.ts"` | Test file(s) to run. (Globs must be enclosed by quotes.)| | solcoverjs | `--solcoverjs ./../.solcover.js` | Relative path from working directory to config. Useful for monorepo packages that share settings. (Path must be "./" prefixed) | -| network | `--network development` | Run with a ganache client over http using network settings defined in the Hardhat config | +| network | `--network development` | Run with a ganache client over http using network settings defined in the Hardhat config. (Hardhat is the default network) | ## Configuration @@ -85,7 +85,11 @@ module.exports = { ## Using with ganache -Begining with `v0.7.12`, solidity-coverage runs directly on the Hardhat network by default (for speed). If you want to use a ganache based http network, you can specify it by name using the `--network` cli option. Solidity-coverage will launch a coverage enabled in-process ganache +Begining with `v0.7.12`, this plugin runs directly on the Hardhat network by default (for speed). + +If you want to use a ganache based http network, you can specify it by name using the `--network` cli option. + +The plugin will then launch its own coverage enabled ganache instance which can be configured in `.solcover.js` via the `providerOptions` key. ## Documentation From 508cf1dc1c1016ff59e21ceab2aa5f8d5b66a6d3 Mon Sep 17 00:00:00 2001 From: cgewecke Date: Thu, 12 Nov 2020 20:55:02 -0800 Subject: [PATCH 3/3] More fixes --- HARDHAT_README.md | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) diff --git a/HARDHAT_README.md b/HARDHAT_README.md index 8d6b7ca0..5af8efb0 100644 --- a/HARDHAT_README.md +++ b/HARDHAT_README.md @@ -63,8 +63,8 @@ module.exports = { | Option | Type | Default | Description | | ------ | ---- | ------- | ----------- | | silent | *Boolean* | false | Suppress logging output | -| client | *Object* | undefined | (Ganache only) Useful if you need a specific ganache version. An example value is: `require('ganache-cli')` | -| providerOptions | *Object* | `{ }` | (Ganache only) [ganache-core options][1] | +| client | *Object* | undefined | *Ganache only*: Useful if you need a specific ganache version. An example value is: `require('ganache-cli')` | +| providerOptions | *Object* | `{ }` | *Ganache only*: [ganache-core options][1] | | skipFiles | *Array* | `['Migrations.sol']` | Array of contracts or folders (with paths expressed relative to the `contracts` directory) that should be skipped when doing instrumentation. | | istanbulFolder | *String* | `./coverage` | Folder location for Istanbul coverage reports. | | istanbulReporter | *Array* | `['html', 'lcov', 'text', 'json']` | [Istanbul coverage reporters][2] | @@ -87,10 +87,7 @@ module.exports = { Begining with `v0.7.12`, this plugin runs directly on the Hardhat network by default (for speed). -If you want to use a ganache based http network, you can specify it by name using the `--network` cli option. - -The plugin will then launch its own coverage enabled ganache -instance which can be configured in `.solcover.js` via the `providerOptions` key. +If you want to use a ganache based http network, you can specify it by name using the `--network` cli option. The plugin will then launch its own coverage enabled ganache instance which can be configured in `.solcover.js` via the `providerOptions` key. ## Documentation