From 766ccf8d1093ab664dcb8d0e1bb2a8453e30fd39 Mon Sep 17 00:00:00 2001 From: cgewecke Date: Fri, 29 Nov 2019 23:46:23 -0800 Subject: [PATCH 1/6] Improve API docs overview --- docs/api.md | 49 ++++++++++++++++++++++++++----------------------- 1 file changed, 26 insertions(+), 23 deletions(-) diff --git a/docs/api.md b/docs/api.md index 8c8d7c63..df986cab 100644 --- a/docs/api.md +++ b/docs/api.md @@ -1,32 +1,33 @@ -# Solidity-Coverage API Documentation +# Solidity-Coverage API -`solidity-coverage`'s API provides test coverage measurement for the Solidity language. -The repository contains two complete coverage tool/plugin implementations (for Buidler and Truffle) -which can be used as sources if you're building something similar. +`solidity-coverage`'s API provides test coverage measurement for the Solidity language. Its +algorithm resembles the one used by [Istanbul][3] for javascript programs. +It tracks line and branch locations by instrumenting solidity contracts with special solidity +statements and detecting their execution in a coverage-enabled EVM. -`solidity-coverage`'s core algorithm resembles the one used by [Istanbul][3] for javascript programs. -It tracks line and branch locations by 'instrumenting' solidity contracts with special solidity -statements and detecting their execution in a coverage-enabled EVM. As such, its API spans the -full set of tasks typically required to run a solidity test suite. +As such, the API spans the full set of tasks typically required to run a solidity test suite. The +table below shows how its core methods relate to the stages of a test run: -+ compile -+ ethereum client launch -+ test -+ report outcome and exit +| Test Stage | API Method | Description | +|---------------|--------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| compilation | `instrument` | A *pre-compilation* step: Rewrites contracts and generates an instrumentation data map. | +| client launch | `ganache` | A *substitute* step: Launches a ganache client with coverage collection enabled in its VM. As the client,runs it will mark line/branch hits on the instrumentation data map. | +| test | `report` | A *post-test* step: Generates a coverage report from the data collected by the VM after tests complete. Converts,the instrumentation data map into an object Istanbul can process. | +| exit | `finish` | A *substitute* step: Shuts client down | [3]: https://github.com/gotwarlost/istanbul -The API's corresponding methods are: +**Additional Resources:** + ++ the library includes file system [utilities](#Utils) for managing the +disposable set of contracts/artifacts which coverage must use in lieu of the 'real' (uninstrumented) +contracts. -+ `instrument`: Rewrites contracts for instrumented compilation. Generates an instrumentation data map. -+ `ganache`: Launches a ganache client with coverage collection enabled in its VM. As the client - runs it will mark line/branch hits on the instrumentation data map. -+ `report`: Generates a coverage report from the data collected by the VM after tests complete. Converts - the instrumentation data map into an object IstanbulJS can process. -+ `finish`: Shuts client down ++ there are two complete [coverage tool/plugin implementations][5] (for Buidler and Truffle) +which can be used as sources if you're building something similar. + +[5]: https://github.com/sc-forks/solidity-coverage/tree/beta/plugins -The library also includes some file system [utilities](#Utils) which are helpful for managing the -disposable set of contracts/artifacts which coverage must use in lieu of the 'real' contracts/artifacts. # Table of Contents @@ -226,8 +227,8 @@ const config = { ## loadSolcoverJS -Loads `.solcoverjs`. Users may specify options described in the README in `.solcover.js` config -file which your application needs to consume. +Loads `.solcoverjs`. Users may specify [options][7] in `.solcover.js` config file which your +application needs to consume. **Parameters** @@ -242,6 +243,8 @@ const solcoverJS = utils.loadSolcoverJS(config); const api = new CoverageAPI(solcoverJS); ``` +[7]: https://github.com/sc-forks/solidity-coverage/tree/beta#config-options + ------------- ## assembleFiles From 86e75a41377edd067b8524473b8efe12cb485d40 Mon Sep 17 00:00:00 2001 From: cgewecke Date: Fri, 29 Nov 2019 23:55:13 -0800 Subject: [PATCH 2/6] Fix title headers, small styling --- docs/api.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/api.md b/docs/api.md index df986cab..31a8965b 100644 --- a/docs/api.md +++ b/docs/api.md @@ -8,18 +8,18 @@ statements and detecting their execution in a coverage-enabled EVM. As such, the API spans the full set of tasks typically required to run a solidity test suite. The table below shows how its core methods relate to the stages of a test run: -| Test Stage | API Method | Description | +| Test Stage | API Method | Description | |---------------|--------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| compilation | `instrument` | A *pre-compilation* step: Rewrites contracts and generates an instrumentation data map. | -| client launch | `ganache` | A *substitute* step: Launches a ganache client with coverage collection enabled in its VM. As the client,runs it will mark line/branch hits on the instrumentation data map. | -| test | `report` | A *post-test* step: Generates a coverage report from the data collected by the VM after tests complete. Converts,the instrumentation data map into an object Istanbul can process. | -| exit | `finish` | A *substitute* step: Shuts client down | +| compilation | `instrument` | A **pre-compilation** step: Rewrites contracts and generates an instrumentation data map. | +| client launch | `ganache` | A **substitute** step: Launches a ganache client with coverage collection enabled in its VM. As the client,runs it will mark line/branch hits on the instrumentation data map. | +| test | `report` | A **post-test** step: Generates a coverage report from the data collected by the VM after tests complete. | +| exit | `finish` | A **substitute** step: Shuts client down | [3]: https://github.com/gotwarlost/istanbul **Additional Resources:** -+ the library includes file system [utilities](#Utils) for managing the ++ the library includes [file system utilities](#Utils) for managing the disposable set of contracts/artifacts which coverage must use in lieu of the 'real' (uninstrumented) contracts. From 247881f167776d57dbc747c9763450fd1fea2e11 Mon Sep 17 00:00:00 2001 From: cgewecke Date: Fri, 29 Nov 2019 23:56:17 -0800 Subject: [PATCH 3/6] ++Column width --- docs/api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api.md b/docs/api.md index 31a8965b..1c16244e 100644 --- a/docs/api.md +++ b/docs/api.md @@ -8,7 +8,7 @@ statements and detecting their execution in a coverage-enabled EVM. As such, the API spans the full set of tasks typically required to run a solidity test suite. The table below shows how its core methods relate to the stages of a test run: -| Test Stage | API Method | Description | +| Test Stage | API Method | Description | |---------------|--------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | compilation | `instrument` | A **pre-compilation** step: Rewrites contracts and generates an instrumentation data map. | | client launch | `ganache` | A **substitute** step: Launches a ganache client with coverage collection enabled in its VM. As the client,runs it will mark line/branch hits on the instrumentation data map. | From 1d5dce5a5e15894d03662ab09f7d83a27fe8e5c4 Mon Sep 17 00:00:00 2001 From: cgewecke Date: Sat, 30 Nov 2019 00:03:53 -0800 Subject: [PATCH 4/6] Fix utils.finish example --- docs/api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api.md b/docs/api.md index 1c16244e..1afbd570 100644 --- a/docs/api.md +++ b/docs/api.md @@ -363,7 +363,7 @@ Returns **Promise** **Example** ```javascript -await utils.finish(); +await utils.finish(config, api); ``` From 48ed0a8ffb386e0d8c6a972705083f6308b3aa5e Mon Sep 17 00:00:00 2001 From: cgewecke Date: Sat, 30 Nov 2019 00:09:30 -0800 Subject: [PATCH 5/6] Simplify opening sentence --- docs/api.md | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/docs/api.md b/docs/api.md index 1afbd570..403019ed 100644 --- a/docs/api.md +++ b/docs/api.md @@ -1,9 +1,6 @@ # Solidity-Coverage API -`solidity-coverage`'s API provides test coverage measurement for the Solidity language. Its -algorithm resembles the one used by [Istanbul][3] for javascript programs. -It tracks line and branch locations by instrumenting solidity contracts with special solidity -statements and detecting their execution in a coverage-enabled EVM. +solidity-coverage tracks the code lines which are hit as your tests run by instrumenting solidity contracts with special solidity statements and detecting their execution in a coverage-enabled EVM. As such, the API spans the full set of tasks typically required to run a solidity test suite. The table below shows how its core methods relate to the stages of a test run: From a74d28f2f338af740f9c6d29bedcf6fc6610ce22 Mon Sep 17 00:00:00 2001 From: cgewecke Date: Sat, 30 Nov 2019 01:21:02 -0800 Subject: [PATCH 6/6] Reword again... --- docs/api.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/api.md b/docs/api.md index 403019ed..eac6c08e 100644 --- a/docs/api.md +++ b/docs/api.md @@ -1,6 +1,6 @@ # Solidity-Coverage API -solidity-coverage tracks the code lines which are hit as your tests run by instrumenting solidity contracts with special solidity statements and detecting their execution in a coverage-enabled EVM. +solidity-coverage tracks which lines are hit as your tests run by instrumenting the contracts with special solidity statements and detecting their execution in a coverage-enabled EVM. As such, the API spans the full set of tasks typically required to run a solidity test suite. The table below shows how its core methods relate to the stages of a test run: @@ -365,4 +365,3 @@ await utils.finish(config, api); -