diff --git a/README.md b/README.md index e8f54be..33d22b5 100644 --- a/README.md +++ b/README.md @@ -16,27 +16,11 @@ ## Install ``` -$ npm install --save-dev solidity-coverage +$ yarn add solidity-coverage --dev ``` **Resources**: -+ [0.7.0 release notes][31] -+ [A guide][29] to upgrading from 0.6.x to 0.7.x -+ [0.6.3 docs][30] - -### Truffle V5 - -**Add** this package to your plugins array in `truffle-config.js` ([Truffle docs][27]) -```javascript -module.exports = { - networks: {...}, - plugins: ["solidity-coverage"] -} -``` -**Run** -``` -truffle run coverage [command-options] -``` ++ [0.8.0 release notes][31] ### Hardhat @@ -70,10 +54,9 @@ A working example can be found at [openzeppelin-contracts, here.][35] ## Command Options | Option | Example | Description | |--------------|------------------------------------|--------------------------------| -| file | `--file="test/registry/*.js"` | (Truffle) Filename or glob describing a subset of tests to run. (Globs must be enclosed by quotes and use [globby matching patterns][38])| -| testfiles | `--testfiles "test/registry/*.ts"` | (Buidler) Test file(s) to run. (Globs must be enclosed by quotes and use [globby matching patterns][38])| +| testfiles | `--testfiles "test/registry/*.ts"` | Test file(s) to run. (Globs must be enclosed by quotes and use [globby matching patterns][38])| | 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` | Use network settings defined in the Truffle or Buidler config | +| network | `--network development` | Use network settings defined in the Hardhat config | | temp[*][14] | `--temp build` | :warning: **Caution** :warning: Path to a *disposable* folder to store compilation artifacts in. Useful when your test setup scripts include hard-coded paths to a build directory. [More...][14] | [* Advanced use][14] diff --git a/docs/advanced.md b/docs/advanced.md index f182002..9d309ef 100644 --- a/docs/advanced.md +++ b/docs/advanced.md @@ -75,7 +75,7 @@ stage the compilation artifacts of instrumented contracts in before the tests ar **Example** ``` -$ truffle run coverage --temp build +$ hardhat coverage --temp build ``` By default this folder is called `.coverage_artifacts`. If you already have diff --git a/docs/faq.md b/docs/faq.md index 4771d98..5aca8c3 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -10,52 +10,15 @@ ## Continuous Integration -An example using Truffle MetaCoin, TravisCI, and Coveralls: +**Examples** ++ [Github Actions and CodeCov][8] (OpenZeppelin) ++ [CircleCI and Coveralls with coverage split into parallelized jobs][7] (SetProtocol) -**Step 1: Create a metacoin project & install coverage tools** - -```bash -$ mkdir metacoin && cd metacoin -$ truffle unbox metacoin - -# Install coverage and development dependencies -$ npm init -$ npm install --save-dev truffle -$ npm install --save-dev coveralls -$ npm install --save-dev solidity-coverage -``` - -**Step 2: Add solidity-coverage to the plugins array in truffle-config.js:** - -```javascript -module.exports = { - networks: {...}, - plugins: ["solidity-coverage"] -} -``` - -**Step 3: Create a .travis.yml:** - -```yml -dist: trusty -language: node_js -node_js: - - '10' -install: - - npm install -script: - - npx truffle run coverage - - cat coverage/lcov.info | coveralls -``` **NB:** It's best practice to run coverage as a separate CI job rather than assume its equivalence to `test`. Coverage uses block gas settings far above the network limits, ignores [EIP 170][4] and rewrites your contracts in ways that might affect their behavior. -**Step 4: Toggle the project on at Travis and Coveralls and push.** - -[It should look like this][1] - **Appendix: Coveralls vs. Codecov** **TLDR: We recommend Coveralls for the accuracy of its branch reporting.** @@ -71,11 +34,8 @@ If your target contains dozens (and dozens) of large contracts, you may run up a contract compilation step. This can be addressed by setting the size of the memory space allocated to the command when you run it. ``` -// Truffle -$ node --max-old-space-size=4096 ./node_modules/.bin/truffle run coverage [options] - -// Buidler -$ node --max-old-space-size=4096 ./node_modules/.bin/buidler coverage [options] +// Hardhat +$ node --max-old-space-size=4096 ./node_modules/.bin/hardhat coverage [options] ``` `solcjs` also has some limits on the size of the code bundle it can process. If you see errors like: @@ -112,7 +72,7 @@ uint x = 5; uint y = 7; ## Running out of time -Truffle sets a default mocha timeout of 5 minutes. Because tests run slower under coverage, it's possible to hit this limit with a test that iterates hundreds of times before producing a result. Timeouts can be disabled by configuring the mocha option in `.solcover.js` as below: (ProTip courtesy of [@cag](https://github.com/cag)) +Because tests run slower under coverage, it's possible to hit default mocha time limits with a test that iterates hundreds of times before producing a result. Timeouts can be disabled by configuring the mocha option in `.solcover.js` as below: (ProTip courtesy of [@cag](https://github.com/cag)) ```javascript module.exports = { @@ -185,3 +145,5 @@ If an `assert` or `require` is marked with an `I` in the coverage report, then d [2]: https://codecov.io/ [3]: https://user-images.githubusercontent.com/7332026/28502310-6851f79c-6fa4-11e7-8c80-c8fd80808092.png [4]: https://github.com/ethereum/EIPs/blob/master/EIPS/eip-170.md +[7]: https://github.com/SetProtocol/set-v2-strategies/blob/29db4a3de4a6ecd55a2c86d85a002b7e1106f8b2/.circleci/config.yml#L79-L143 +[8]: https://github.com/OpenZeppelin/openzeppelin-contracts/blob/c12076fb7e3dfe48ef1d9c3bb2a58bdd3ffc0cee/.github/workflows/test.yml#L36-L56 diff --git a/docs/upgrade.md b/docs/upgrade.md deleted file mode 100644 index 0672a7e..0000000 --- a/docs/upgrade.md +++ /dev/null @@ -1,138 +0,0 @@ -# How to install 0.7.0 - -**Install** -``` -$ npm install --save-dev solidity-coverage -``` - -**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.x - -First, follow [the installation instructions](#how-to-install-070) and see if it works. - -:rabbit2: It does!? Bye. - -:elephant: It does not. - -#### 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 `--account` or `-i`, 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 ` 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: }` - buildDirPath, # Now: `--temp ` (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/master/docs/advanced.md -[3]: https://github.com/sc-forks/solidity-coverage/blob/master/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/master#command-options - diff --git a/plugins/resources/plugin.ui.js b/plugins/resources/plugin.ui.js new file mode 100644 index 0000000..e139182 --- /dev/null +++ b/plugins/resources/plugin.ui.js @@ -0,0 +1,66 @@ +const UI = require('./../../lib/ui').UI; + +/** + * Plugin logging + */ +class PluginUI extends UI { + constructor(log){ + super(log); + } + + /** + * Writes a formatted message via log + * @param {String} kind message selector + * @param {String[]} args info to inject into template + */ + report(kind, args=[]){ + const c = this.chalk; + const ct = c.bold.green('>'); + const ds = c.bold.yellow('>'); + const w = ":warning:"; + + const kinds = { + + 'instr-skip': `\n${c.bold('Coverage skipped for:')}` + + `\n${c.bold('=====================')}\n`, + + 'instr-skipped': `${ds} ${c.grey(args[0])}`, + + 'network': `\n${c.bold('Network Info')}` + + `\n${c.bold('============')}\n` + + `${ct} ${c.bold('id')}: ${args[1]}\n` + + `${ct} ${c.bold('port')}: ${args[2]}\n` + + `${ct} ${c.bold('network')}: ${args[0]}\n`, + + } + + this._write(kinds[kind]); + } + + /** + * Returns a formatted message. Useful for error message. + * @param {String} kind message selector + * @param {String[]} args info to inject into template + * @return {String} message + */ + generate(kind, args=[]){ + const c = this.chalk; + const x = ":x:"; + + const kinds = { + + 'sources-fail': `${c.red('Cannot locate expected contract sources folder: ')} ${args[0]}`, + + 'solcoverjs-fail': `${c.red('Could not load .solcover.js config file. ')}` + + `${c.red('This can happen if it has a syntax error or ')}` + + `${c.red('the path you specified for it is wrong.')}`, + + 'tests-fail': `${x} ${c.bold(args[0])} ${c.red('test(s) failed under coverage.')}`, + } + + + return this._format(kinds[kind]) + } +} + +module.exports = PluginUI; \ No newline at end of file