From 49d7f3fe99e8edc10c15ed2cd0f63017c34ba37a Mon Sep 17 00:00:00 2001 From: cgewecke Date: Tue, 10 Sep 2019 15:19:30 -0700 Subject: [PATCH 1/4] Initial README edit --- README.md | 91 ++++++++++++++++++------------------------------------ lib/app.js | 2 +- 2 files changed, 31 insertions(+), 62 deletions(-) diff --git a/README.md b/README.md index 9b87527..7ec29c6 100644 --- a/README.md +++ b/README.md @@ -19,52 +19,38 @@ find discrepancies between the coverage report and your suite's behavior, please ``` $ npm install --save-dev solidity-coverage ``` - -### Run -Set a `coverage` network in truffle-config.js (see [Network Configuration](#network-configuration)) and then run: -``` -$ npx solidity-coverage -``` - ### Usage notes: -+ For pragma solidity >=0.4.22 <0.6.0 / Petersburg / Truffle v4 and v5 ++ For pragma solidity >=0.4.22 <0.6.0 / Petersburg + Tests run more slowly while coverage is being generated. -+ Your contracts will be double-compiled and a (long) delay between compilation and -the beginning of test execution is possible if your contracts are large. -+ Truffle should be globallly installed in your environment.. If you prefer running truffle as -a local dependency, please see [this section](https://github.com/sc-forks/solidity-coverage/blob/master/docs/faq.md#running-truffle-as-a-local-dependency) of the FAQ. -+ If your suite uses native Solidity testing or accesses contracts via mocks stored in `tests/` (a la Zeppelin), coverage will trigger test errors because it can't control the way truffle compiles that folder. Mocks should be relocated to the root `contracts` directory. More on why this is necessary at issue [146](https://github.com/sc-forks/solidity-coverage/issues/146) - -### Network Configuration - -By default, this tool connects to a coverage-enabled fork of ganache-cli -called **testrpc-sc** on port 8555. -+ it's a dependency - there's nothing extra to download. -+ the solidity-coverage command launches it automatically in the background. (See [this section of the FAQ](https://github.com/sc-forks/solidity-coverage/blob/master/docs/faq.md#running-testrpc-sc-on-its-own) if you need to launch it separately yourself) ++ Contracts consume more gas while coverage is being generated. ++ solidity-coverage launches its own in-process ganache instance. You can + set its [options] via the `providerOptions` key in your .solcover.js + config file. -In `truffle-config.js`, add a coverage network following the example below. +### Truffle >= V5: setup and run -**Example** +Add "solidity-coverage" to your plugins array in `truffle-config.js` ```javascript module.exports = { - networks: { - development: { - host: "localhost", - port: 8545, - network_id: "*" - }, - coverage: { - host: "localhost", - network_id: "*", - port: 8555, // <-- If you change this, also set the port option in .solcover.js. - gas: 0xfffffffffff, // <-- Use this high gas value - gasPrice: 0x01 // <-- Use this low gas price - }, - ...etc... - } -}; + networks: {...}, + plugins: ["solidity-coverage"] +} +``` +Run +``` +truffle run coverage [options] ``` -### Options + + +### Command Options +| Option | Example | Description | +|--------------|--------------------------------|--------------------------------------------------------------------------------------------------------------------------------| +| --file | --file="test/registry/*.js" | Filename or glob describing a subset of JS tests 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) | +| --version | | Version info | +| --help | | Usage notes | + +### Config Options Additional options can be specified in a `.solcover.js` config file located in the root directory of your project. @@ -72,43 +58,26 @@ the root directory of your project. **Example:** ```javascript module.exports = { - port: 6545, - testrpcOptions: '-p 6545 -u 0x54fd80d6ae7584d8e9a19fe1df43f04e5282cc43', - testCommand: 'mocha --timeout 5000', - norpc: true, - dir: './secretDirectory', - copyPackages: ['openzeppelin-solidity'], - skipFiles: ['Routers/EtherRouter.sol'] + skipFiles: ['Routers/EtherRouter.sol'] }; ``` | Option | Type | Default | Description | | ------ | ---- | ------- | ----------- | -| accounts | *Number* | 35 | Number of accounts to launch testrpc with. | -| port | *Number* | 8555 | Port to run testrpc on / have truffle connect to | -| norpc | *Boolean* | false | Prevent solidity-coverage from launching its own testrpc. Useful if you are managing a complex test suite with a [shell script](https://github.com/OpenZeppelin/openzeppelin-solidity/blob/ed872ca0a11c4926f8bb91dd103bea1378a3384c/scripts/coverage.sh) | -| testCommand | *String* | `truffle test` | Run an arbitrary test command. ex: `mocha --timeout 5000`. NB: Also set the `port` option to whatever your tests require (probably 8545). | -| testrpcOptions | *String* | `--port 8555` | options to append to a command line invocation of testrpc. NB: Using this overwrites the defaults so always specify a port in this string *and* in the `port` option | -| copyNodeModules | *Boolean* | false | :warning: **DEPRECATED** use `copyPackages` instead :warning: Copies `node_modules` into the coverage environment. May significantly increase the time for coverage to complete if enabled. Useful if your contracts import solidity files from an npm installed package (and your node_modules is small). | -| copyPackages | *Array* | `[]` | Copies specific `node_modules` packages into the coverage environment. May significantly reduce the time for coverage to complete compared to `copyNodeModules`. Useful if your contracts import solidity files from an npm installed package. | +| client | *Object* | require("truffle").ganache | Useful if you need a specific ganache version. (usage: `client: require("ganache-core")`)| +| providerOptions | *Object* | {} | ganache-core options (ex: `network_id: 55`). Complete list of options [here](https://github.com/trufflesuite/ganache-core#options). | | skipFiles | *Array* | `['Migrations.sol']` | Array of contracts or folders (with paths expressed relative to the `contracts` directory) that should be skipped when doing instrumentation. `Migrations.sol` is skipped by default, and does not need to be added to this configuration option if it is used. | -| deepSkip | boolean | false | Use this if instrumentation hangs on large, skipped files (like Oraclize). It's faster. | -| dir | *String* | `.` | Solidity-coverage copies all the assets in your root directory (except `node_modules`) to a special folder where it instruments the contracts and executes the tests. `dir` allows you to define a relative path from the root directory to those assets. Useful if your contracts & tests are within their own folder as part of a larger project.| -| buildDirPath | *String* | `/build/contracts` | Build directory path for compiled smart contracts | | istanbulReporter | *Array* | ['html', 'lcov', 'text'] | Coverage reporters for Istanbul. Optional reporter replaces the default reporters. | ### FAQ -Solutions to common problems people run into: +Common problems & questions: + [Running out of gas](https://github.com/sc-forks/solidity-coverage/blob/master/docs/faq.md#running-out-of-gas) + [Running out of memory (locally and in CI)](https://github.com/sc-forks/solidity-coverage/blob/master/docs/faq.md#running-out-of-memory-locally-and-in-ci) + [Running out of time (in mocha)](https://github.com/sc-forks/solidity-coverage/blob/master/docs/faq.md#running-out-of-time-in-mocha) -+ [Running on windows](https://github.com/sc-forks/solidity-coverage/blob/master/docs/faq.md#running-on-windows) -+ [Running testrpc-sc on its own](https://github.com/sc-forks/solidity-coverage/blob/master/docs/faq.md#running-testrpc-sc-on-its-own) -+ [Running truffle as a local dependency](https://github.com/sc-forks/solidity-coverage/blob/master/docs/faq.md#running-truffle-as-a-local-dependency) -+ [Integrating into CI](https://github.com/sc-forks/solidity-coverage/blob/master/docs/faq.md#continuous-integration-installing-metacoin-on-travisci-with-coveralls) ++ [Running in CI](https://github.com/sc-forks/solidity-coverage/blob/master/docs/faq.md#continuous-integration-installing-metacoin-on-travisci-with-coveralls) + [Why are asserts and requires highlighted as branch points?](https://github.com/sc-forks/solidity-coverage/blob/master/docs/faq.md#why-has-my-branch-coverage-decreased-why-is-assert-being-shown-as-a-branch-point) diff --git a/lib/app.js b/lib/app.js index 57dff5d..2d11723 100644 --- a/lib/app.js +++ b/lib/app.js @@ -32,7 +32,7 @@ class App { this.originalContractsDir = config.originalContractsDir - this.client = config.provider; + this.client = config.client; this.providerOptions = config.providerOptions || {}; this.skippedFolders = []; From d80eb051fe00447221fda4abb48637965d86407f Mon Sep 17 00:00:00 2001 From: cgewecke Date: Tue, 10 Sep 2019 15:39:47 -0700 Subject: [PATCH 2/4] Add --version cli flag --- README.md | 4 ++-- dist/truffle.plugin.js | 7 ++++++- lib/ui.js | 10 ++++++---- test/units/app.js | 7 +++++++ 4 files changed, 21 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 7ec29c6..cdfd1e5 100644 --- a/README.md +++ b/README.md @@ -24,8 +24,8 @@ $ npm install --save-dev solidity-coverage + Tests run more slowly while coverage is being generated. + Contracts consume more gas while coverage is being generated. + solidity-coverage launches its own in-process ganache instance. You can - set its [options] via the `providerOptions` key in your .solcover.js - config file. + set its [options](https://github.com/trufflesuite/ganache-core#options) via + the `providerOptions` key in your `.solcover.js` config file. ### Truffle >= V5: setup and run diff --git a/dist/truffle.plugin.js b/dist/truffle.plugin.js index 85d8bb0..945c1f6 100644 --- a/dist/truffle.plugin.js +++ b/dist/truffle.plugin.js @@ -26,6 +26,7 @@ */ const App = require('./../lib/app'); +const pkg = require('./../package.json'); const req = require('req-cwd'); const death = require('death'); const path = require('path'); @@ -66,7 +67,7 @@ async function plugin(truffleConfig){ // Instrument and test.. try { - death(app.cleanUp); + death(app.cleanUp); // This doesn't work... // Launch in-process provider const provider = await app.provider(truffle.ganache); @@ -77,6 +78,10 @@ async function plugin(truffleConfig){ app.ui.report('truffle-version', [truffle.version]); app.ui.report('ganache-version', [ganacheVersion]); + app.ui.report('coverage-version',[pkg.version]); + + // Bail early if user ran: --version + if (truffleConfig.version) return; // Write instrumented sources to temp folder app.instrument(); diff --git a/lib/ui.js b/lib/ui.js index 4ec4142..eae47a1 100644 --- a/lib/ui.js +++ b/lib/ui.js @@ -28,11 +28,13 @@ class UI { 'truffle-help': `Usage: truffle run coverage [options]\n\n` + `Options:\n` + - ` --file: path (or glob) to run subset of JS test files\n` + - ` --solcoverjs: relative path to .solcover.js (ex: ./../.solcover.js)\n`, + ` --file: path (or glob) to subset of JS test files. (Quote your globs)\n` + + ` --solcoverjs: relative path to .solcover.js (ex: ./../.solcover.js)\n` + + ` --version: version info\n`, - 'truffle-version': `${ct} ${c.bold('truffle')}: v${args[0]}`, - 'ganache-version': `${ct} ${c.bold('ganache-core')}: ${args[0]}`, + 'truffle-version': `${ct} ${c.bold('truffle')}: v${args[0]}`, + 'ganache-version': `${ct} ${c.bold('ganache-core')}: ${args[0]}`, + 'coverage-version': `${ct} ${c.bold('solidity-coverage')}: v${args[0]}`, 'instr-start': `\n${c.bold('Instrumenting for coverage...')}` + `\n${c.bold('=============================')}\n`, diff --git a/test/units/app.js b/test/units/app.js index 1323806..c3422f5 100644 --- a/test/units/app.js +++ b/test/units/app.js @@ -183,6 +183,13 @@ describe('app', function() { await plugin(truffleConfig); }) + it('truffle run coverage --version', async function(){ + assertCleanInitialState(); + truffleConfig.version = "true"; + mock.install('Simple', 'simple.js', solcoverConfig); + await plugin(truffleConfig); + }) + it('truffle run coverage --file test/', async function() { assertCleanInitialState(); From caa5b4bc677f52787b1221a34c25367dc9993f28 Mon Sep 17 00:00:00 2001 From: cgewecke Date: Tue, 10 Sep 2019 16:01:26 -0700 Subject: [PATCH 3/4] More README edits --- README.md | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index cdfd1e5..810a3eb 100644 --- a/README.md +++ b/README.md @@ -21,10 +21,10 @@ $ npm install --save-dev solidity-coverage ``` ### Usage notes: + For pragma solidity >=0.4.22 <0.6.0 / Petersburg -+ Tests run more slowly while coverage is being generated. -+ Contracts consume more gas while coverage is being generated. -+ solidity-coverage launches its own in-process ganache instance. You can - set its [options](https://github.com/trufflesuite/ganache-core#options) via ++ Coverage runs tests a little more slowly. ++ Coverage distorts gas consumption. ++ Coverage launches its own in-process ganache instance. You can + set [ganache options](https://github.com/trufflesuite/ganache-core#options) via the `providerOptions` key in your `.solcover.js` config file. ### Truffle >= V5: setup and run @@ -43,12 +43,13 @@ truffle run coverage [options] ### Command Options -| Option | Example | Description | -|--------------|--------------------------------|--------------------------------------------------------------------------------------------------------------------------------| -| --file | --file="test/registry/*.js" | Filename or glob describing a subset of JS tests to run. (Globs must be enclosed by quotes.) | +| Option | Example | Description | +|--------------|--------------------------------|-------------| +| --file | --file="test/registry/*.js" | Filename or glob describing a subset of JS tests 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) | -| --version | | Version info | -| --help | | Usage notes | +| --version | | Version info | +| --help | | Usage notes | +|| || ### Config Options From eeff9a8ef09986a6abebe230a6407950863ecc4d Mon Sep 17 00:00:00 2001 From: cgewecke Date: Tue, 10 Sep 2019 16:13:20 -0700 Subject: [PATCH 4/4] Even more edits --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 810a3eb..937322f 100644 --- a/README.md +++ b/README.md @@ -27,7 +27,7 @@ $ npm install --save-dev solidity-coverage set [ganache options](https://github.com/trufflesuite/ganache-core#options) via the `providerOptions` key in your `.solcover.js` config file. -### Truffle >= V5: setup and run +### Truffle V5 Add "solidity-coverage" to your plugins array in `truffle-config.js` ```javascript @@ -49,7 +49,7 @@ truffle run coverage [options] | --solcoverjs | --solcoverjs ./../.solcover.js | Relative path from working directory to config. Useful for monorepo packages that share settings. (Path must be "./" prefixed) | | --version | | Version info | | --help | | Usage notes | -|| || +|| || ### Config Options