solidity-coverage/docs/advanced.md

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

// Mocha test to skip
it("is a gas usage simulation [ @skip-on-coverage ]", async function(){
 ...
})

//.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

// .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.