Code coverage for Solidity testing
- For more details about what this is, how it works and potential limitations, see the accompanying article.
solidity-coverageis in development and its accuracy is unknown. If you find discrepancies between the coverage report and your suite's behavior, please open an issue.
$ npm install --save-dev solidity-coverage
Tests run significantly slower while coverage is being generated. Your contracts are double-compiled and a 1 to 2 minute delay between the end of the second compilation and the beginning of test execution is possible if your test suite is large. Large Solidity files can also take a while to instrument.
Important: breaking change for versions >=
solidity-coveragerequires compilation with
0.4.21. We're prefixing our own instrumentation events with the
emitkeyword to reduce warnings volume when running the tool.
- Ternary conditionals (ex:
(x) ? y : z;) no longer receive branch coverage. There's more info about why this isn't currently possible at solidity 3887.
Important: breaking change for versions >=
solidity-coverage now expects a globally installed truffle in your environment / on CI. If you prefer to control which Truffle version your tests are run with, please see the FAQ for running truffle as a local dependency.
Solidity fixtures / mocks / tests stored in the
tests/directory are no longer supported. 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's unable to rewrite your contract ABIs appropriately. Mocks should be relocated to the root folder's
contractsdirectory. More on why this is necessary at issue 146
By default, solidity-coverage generates a stub
truffle.js that accommodates its special gas needs and
connects to a coverage-enabled fork of the ganache-cli client called testrpc-sc on port 8555. This special client ships with
solidity-coverage - there's nothing extra to download. If your tests will run on truffle's development network
using a standard
truffle.js and ganache-cli instance, you shouldn't have to do any configuration or launch the coverage client separately. If your tests depend on logic or special options added to
truffle.js you should declare a coverage
network there following the example below.
moduleexports =networks:development:host: "localhost"port: 8545network_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 valuegasPrice: 0x01 // <-- Use this low gas price...etc...;
You can also create a
.solcover.js config file in the root directory of your project and specify
additional options if necessary:
moduleexports =port: 6545testrpcOptions: '-p 6545 -u 0x54fd80d6ae7584d8e9a19fe1df43f04e5282cc43'testCommand: 'mocha --timeout 5000'norpc: truedir: './secretDirectory'copyPackages: 'zeppelin-solidity'skipFiles: 'Routers/EtherRouter.sol';
|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|
||Run an arbitrary test command. ex:
||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
|copyNodeModules||Boolean||false||⚠️ DEPRECATED use
||Array of contracts or folders (with paths expressed relative to the
|deepSkip||boolean||false||Use this if instrumentation hangs on large, skipped files (like Oraclize). It's faster.|
||Solidity-coverage copies all the assets in your root directory (except
||Build directory path for compiled smart contracts|
Solutions to common issues people run into using this tool:
- Running out of gas
- Running out of memory (locally and in CI)
- Running out of time (in mocha)
- Running on windows
- Running testrpc-sc on its own
- Running truffle as a local dependency
- Using alongside HDWalletProvider
- Integrating into CI
- Why are asserts and requires highlighted as branch points?
- Why are
transferthrowing in my tests?
Contributions are welcome! If you're opening a PR that adds features please consider writing some
unit tests for them. You could
also lint your submission with
npm run lint. Bugs can be reported in the