Make statement and function coverage measurement optional (sc-forks#538)

Author: cgewecke

BUIDLER_README.md

@@ -46,7 +46,7 @@ npx buidler coverage --network coverage [options]
 
 | Option <img width=200/> | Example <img width=750/>| Description <img width=1000/> |
 |--------------|------------------------------------|--------------------------------|
-| testfiles  | `--testfiles="test/registry/*.ts"` | Test file(s) to run. (Globs must be enclosed by quotes.)|
+| 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` | Use network settings defined in the Buidler config |
 
@@ -99,17 +99,17 @@ More documentation, including FAQ and information about solidity-coverage's API
 [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/beta/docs/faq.md#running-out-of-gas
-[5]: https://github.com/sc-forks/solidity-coverage/blob/beta/docs/faq.md#running-out-of-memory
-[6]: https://github.com/sc-forks/solidity-coverage/blob/beta/docs/faq.md#running-out-of-time
-[7]: https://github.com/sc-forks/solidity-coverage/blob/beta/docs/faq.md#continuous-integration
-[8]: https://github.com/sc-forks/solidity-coverage/blob/beta/docs/faq.md#notes-on-branch-coverage
+[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/beta/test/units
+[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/beta/docs/faq.md#notes-on-gas-distortion
-[14]: https://github.com/sc-forks/solidity-coverage/blob/beta/docs/advanced.md
+[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
@@ -118,12 +118,16 @@ More documentation, including FAQ and information about solidity-coverage's API
 [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/beta/docs/advanced.md#workflow-hooks
-[24]: https://github.com/sc-forks/solidity-coverage/blob/beta/docs/advanced.md#skipping-tests
+[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://buidler.dev/
 [27]: https://www.trufflesuite.com/docs
-[28]: https://github.com/sc-forks/solidity-coverage/blob/beta/README.md
-[29]: https://github.com/sc-forks/buidler-e2e/tree/coverage
-[30]: https://github.com/sc-forks/moloch
+[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
 

README.md

@@ -74,7 +74,7 @@ npx buidler coverage --network coverage [command-options]
 | Option <img width=200/> | Example <img width=750/>| Description <img width=1000/> |
 |--------------|------------------------------------|--------------------------------|
 | file | `--file="test/registry/*.js"`    | (Truffle) Filename or glob describing a subset of tests to run. (Globs must be enclosed by quotes.)|
-| testfiles  | `--testfiles="test/registry/*.ts"` | (Buidler) Test file(s) to run. (Globs must be enclosed by quotes.)|
+| testfiles  | `--testfiles "test/registry/*.ts"` | (Buidler) 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` | Use network settings defined in the Truffle or Buidler config |
 | temp[<sup>*</sup>][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] |
@@ -99,6 +99,8 @@ module.exports = {
 | client | *Object* | `require("ganache-core")` | Useful if you need a specific ganache version. |
 | providerOptions | *Object* | `{ }` | [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. |
+| measureStatementCoverage | *boolean* | `true` | Computes statement (in addition to line) coverage. [More...][34] |
+| measureFunctionCoverage | *boolean* | `true` | Computes function coverage. [More...][34] |
 | 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.|
@@ -204,3 +206,5 @@ $ yarn
 [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
+

docs/advanced.md

@@ -2,7 +2,7 @@
 
 ## Skipping tests
 
-Sometimes it's convenient to skip specific tests when running coverage. You can do this by 
+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**
@@ -79,10 +79,21 @@ $ 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. 
+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 
+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.
 
+## Reducing the instrumentation footprint
+
+If your project is very large or if you have logic that's gas sensitive, it can be useful to
+minimize the amount of instrumentation the coverage tool adds to your Solidity code.
+
+Usually you're only interested in line and branch coverage but Istanbul also collects data for individual
+statements and "functions" (e.g - whether every declared function has been called).
+
+Setting the `measureStatementCoverage` and/or `measureFunctionCoverage` options to `false` can
+improve performance, lower the cost of execution and minimize complications that arise from `solc`'s
+limits on how large the compilation payload can be.
 

lib/api.js

@@ -18,13 +18,13 @@ const AppUI = require('./ui').AppUI;
  */
 class API {
   constructor(config={}) {
-    this.coverage = new Coverage();
-    this.instrumenter = new Instrumenter();
     this.validator = new ConfigValidator()
     this.config = config || {};
 
     // Validate
     this.validator.validate(this.config);
+    this.coverage = new Coverage();
+    this.instrumenter = new Instrumenter(this.config);
 
     // Options
     this.testsErrored = false;

lib/injector.js

@@ -22,7 +22,7 @@ class Injector {
   }
 
   _getMethodIdentifier(id){
-    return `coverage_${web3Utils.keccak256(id).slice(0,10)}`
+    return `c_${web3Utils.keccak256(id).slice(0,10)}`
   }
 
   _getInjectionComponents(contract, injectionPoint, id, type){

lib/instrumenter.js

@@ -12,9 +12,11 @@ const parse = require('./parse');
  */
 class Instrumenter {
 
-  constructor(){
+  constructor(config={}){
     this.instrumentationData = {};
     this.injector = new Injector();
+    this.measureStatementCoverage = (config.measureStatementCoverage === false) ? false : true;
+    this.measureFunctionCoverage = (config.measureFunctionCoverage === false) ? false: true;
   }
 
   _isRootNode(node){
@@ -58,6 +60,8 @@ class Instrumenter {
     contract.instrumented = contractSource;
 
     this._initializeCoverageFields(contract);
+    parse.configureStatementCoverage(this.measureStatementCoverage)
+    parse.configureFunctionCoverage(this.measureFunctionCoverage)
 
     // First, we run over the original contract to get the source mapping.
     let ast = SolidityParser.parse(contract.source, {loc: true, range: true});
@@ -102,7 +106,6 @@ class Instrumenter {
     retValue.runnableLines = contract.runnableLines;
     retValue.contract = contract.instrumented;
     retValue.contractName = contract.contractName;
-
     return retValue;
   }
 }

lib/parse.js

@@ -8,6 +8,16 @@ const register = new Registrar();
 
 const parse = {};
 
+// Utilities
+parse.configureStatementCoverage = function(val){
+  register.measureStatementCoverage = val;
+}
+
+parse.configureFunctionCoverage = function(val){
+  register.measureFunctionCoverage = val;
+}
+
+// Nodes
 parse.AssignmentExpression = function(contract, expression) {
   register.statement(contract, expression);
 };

lib/registrar.js

@@ -6,9 +6,14 @@
 class Registrar {
 
   constructor(){
-    // Sometimes we don't want to inject statements
-    // because they're an unnecessary expense. ex: `receive`
+    // When, at *certain nodes* we don't want to inject statements
+    // because they're an unnecessary expense. ex: `receive`, this
+    // can be toggled on/off in the parser
     this.trackStatements = true;
+
+    // These are set by user option and enable/disable the measurement completely
+    this.measureStatementCoverage = true;
+    this.measureFunctionCoverage = true;
   }
 
   /**
@@ -31,7 +36,7 @@ class Registrar {
    * @param  {Object} expression AST node
    */
   statement(contract, expression) {
-    if (!this.trackStatements) return;
+    if (!this.trackStatements || !this.measureStatementCoverage) return;
 
     const startContract = contract.instrumented.slice(0, expression.range[0]);
     const startline = ( startContract.match(/\n/g) || [] ).length + 1;
@@ -102,6 +107,8 @@ class Registrar {
    * @param  {Object} expression AST node
    */
   functionDeclaration(contract, expression) {
+    if (!this.measureFunctionCoverage) return;
+
     let start = 0;
 
     // It's possible functions will have modifiers that take string args

lib/validator.js

@@ -20,6 +20,8 @@ const configSchema = {
     silent:               {type: "boolean"},
     autoLaunchServer:     {type: "boolean"},
     istanbulFolder:       {type: "string"},
+    measureStatementCoverage: {type: "boolean"},
+    measureFunctionCoverage: {type: "boolean"},
 
     // Hooks:
     onServerReady:        {type: "function", format: "isFunction"},

test/units/truffle/standard.js

@@ -414,6 +414,25 @@ describe('Truffle Plugin: standard use cases', function() {
     );
   });
 
+  it('config: includeStatementCoverage, includeFunctionCoverage', async function(){
+    solcoverConfig.istanbulReporter = ['json-summary', 'text']
+    solcoverConfig.measureStatementCoverage = false;
+    solcoverConfig.measureFunctionCoverage = false;
+
+    mock.install('Simple', 'simple.js', solcoverConfig);
+    await plugin(truffleConfig);
+
+    const expected = [
+      {
+        file: mock.pathToContract(truffleConfig, 'Simple.sol'),
+        total: 0
+      }
+    ];
+
+    verify.statementCoverage(expected, 'total');
+    verify.functionCoverage(expected, 'total');
+  });
+
   // Fails with Truffle 5.0.31, but newer Truffle causes OOM when running whole suite.
   // Running the same test with Buidler though...
   it.skip('solc 0.6.x', async function(){