diff options
| -rw-r--r-- | packages/website/md/docs/sol_cov/usage.md | 48 | ||||
| -rw-r--r-- | packages/website/ts/containers/sol_cov_documentation.ts | 36 |
2 files changed, 78 insertions, 6 deletions
diff --git a/packages/website/md/docs/sol_cov/usage.md b/packages/website/md/docs/sol_cov/usage.md index 63a88f595..59638f611 100644 --- a/packages/website/md/docs/sol_cov/usage.md +++ b/packages/website/md/docs/sol_cov/usage.md @@ -2,8 +2,47 @@ Sol-cov uses transaction traces in order to figure out which lines of Solidity s The CoverageSubprovider eavesdrops on the `eth_sendTransaction` and `eth_call` RPC calls and collects traces after each call using `debug_traceTransaction`. `eth_call`'s' don't generate traces - so we take a snapshot, re-submit it as a transaction, get the trace and then revert the snapshot. +Coverage subprovider needs some info about your contracts (`srcMap`, `bytecode`). It gets that info from your project's artifacts. Some frameworks have their own artifact format. Some artifact formats don't actually contain all the neccessary data. + +In order to use `CoverageSubprovider` with your favorite framework you need to pass an `artifactsAdapter` to it. + +### Sol-compiler + +If you are generating your artifacts with [@0xproject/sol-compiler](LINK) you can use the `SolCompilerArtifactsAdapter` we've implemented for you. + +```typescript +<<<<<<< HEAD +import { CoverageSubprovider } from '@0xproject/sol-cov'; +======= +import { SolCompilerArtifactsAdapter } from '@0xproject/sol-cov'; +const artifactsPath = 'src/artifacts'; +const contractsPath = 'src/contracts'; +const artifactsAdapter = new SolCompilerArtifactsAdapter(artifactsPath, contractsPath); +``` + +### Truffle + +If your project is using [Truffle](LINK), we've written a `TruffleArtifactsAdapter`for you. + +```typescript +import { TruffleArtifactAdapter } from '@0xproject/sol-cov'; +const contractsPath = 'src/contracts'; +const artifactAdapter = new TruffleArtifactAdapter(contractsDir); +``` + +Because truffle artifacts don't have all the data we need - we actually will recompile your contracts under the hood. That's why you don't need to pass an `artifactsPath`. + +### Other framework/toolset + +You'll need to write your own artifacts adapter. It should extend `AbstractArtifactsAdapter`. +Look at the code of the two adapters above for examples. + +### Usage + ```typescript import { CoverageSubprovider } from '@0xproject/sol-cov'; +import ProviderEngine = require('web3-provider-engine'); +>>>>>>> Improve sol-cov docs const provider = new ProviderEngine(); @@ -12,15 +51,20 @@ const contractsPath = 'src/contracts'; const networkId = 50; // Some calls might not have `from` address specified. Nevertheless - transactions need to be submitted from an address with at least some funds. defaultFromAddress is the address that will be used to submit those calls as transactions from. const defaultFromAddress = '0x5409ed021d9299bf6814279a6a1411a7e866a631'; +<<<<<<< HEAD const coverageSubprovider = new CoverageSubprovider(artifactsPath, contractsPath, defaultFromAddress); +======= +const isVerbose = true; +const coverageSubprovider = new CoverageSubprovider(artifactsAdapter, defaultFromAddress, isVerbose); +>>>>>>> Improve sol-cov docs provider.addProvider(coverageSubprovider); ``` -After your test suite is complete (e.g global `after` hook), you'll need to call: +After your test suite is complete (e.g in the Mocha global `after` hook), you'll need to call: ```typescript await coverageSubprovider.writeCoverageAsync(); ``` -This will create a `coverage.json` file in the `coverage` directory. This file has an [Istanbul format](https://github.com/gotwarlost/istanbul/blob/master/coverage.json.md) - so you can use any of the existing Instanbul reporters. +This will create a `coverage.json` file in a `coverage` directory. This file has an [Istanbul format](https://github.com/gotwarlost/istanbul/blob/master/coverage.json.md) - so you can use it with any of the existing Istanbul reporters. diff --git a/packages/website/ts/containers/sol_cov_documentation.ts b/packages/website/ts/containers/sol_cov_documentation.ts index 58755c1e0..bc05b6854 100644 --- a/packages/website/ts/containers/sol_cov_documentation.ts +++ b/packages/website/ts/containers/sol_cov_documentation.ts @@ -22,6 +22,9 @@ const docSections = { installation: 'installation', usage: 'usage', coverageSubprovider: 'coverageSubprovider', + abstractArtifactAdapter: 'abstractArtifactAdapter', + solCompilerArtifactAdapter: 'solCompilerArtifactAdapter', + truffleArtifactAdapter: 'truffleArtifactAdapter', types: docConstants.TYPES_SECTION_NAME, }; @@ -34,7 +37,10 @@ const docsInfoConfig: DocsInfoConfig = { introduction: [docSections.introduction], install: [docSections.installation], usage: [docSections.usage], - coverageSubprovider: [docSections.coverageSubprovider], + 'coverage-subprovider': [docSections.coverageSubprovider], + 'abstract-artifact-adapter': [docSections.abstractArtifactAdapter], + 'sol-compiler-artifact-adapter': [docSections.solCompilerArtifactAdapter], + 'truffle-artifact-adapter': [docSections.truffleArtifactAdapter], types: [docSections.types], }, sectionNameToMarkdown: { @@ -44,18 +50,40 @@ const docsInfoConfig: DocsInfoConfig = { }, sectionNameToModulePath: { [docSections.coverageSubprovider]: ['"sol-cov/src/coverage_subprovider"'], + [docSections.abstractArtifactAdapter]: ['"sol-cov/src/artifact_adapters/abstract_artifact_adapter"'], + [docSections.solCompilerArtifactAdapter]: ['"sol-cov/src/artifact_adapters/sol_compiler_artifact_adapter"'], + [docSections.truffleArtifactAdapter]: ['"sol-cov/src/artifact_adapters/truffle_artifact_adapter"'], [docSections.types]: ['"subproviders/src/types"', '"types/src/index"'], }, menuSubsectionToVersionWhenIntroduced: {}, sections: docSections, - visibleConstructors: [docSections.coverageSubprovider], + visibleConstructors: [ + docSections.coverageSubprovider, + docSections.abstractArtifactAdapter, + docSections.solCompilerArtifactAdapter, + docSections.truffleArtifactAdapter, + ], typeConfigs: { // Note: This needs to be kept in sync with the types exported in index.ts. Unfortunately there is // currently no way to extract the re-exported types from index.ts via TypeDoc :( - publicTypes: ['NextCallback', 'OnNextCompleted', 'ErrorCallback', 'JSONRPCRequestPayload'], + publicTypes: [ + 'JSONRPCRequestPayload', + 'NextCallback', + 'ErrorCallback', + 'AbstractArtifactAdapter', + 'CoverageSubprovider', + 'TruffleArtifactAdapter', + 'SolCompilerArtifactAdapter', + 'ContractData', + ], typeNameToExternalLink: {}, typeNameToPrefix: {}, - typeNameToDocSection: {}, + typeNameToDocSection: { + AbstractArtifactAdapter: docSections.abstractArtifactAdapter, + CoverageSubprovider: docSections.coverageSubprovider, + TruffleArtifactAdapter: docSections.truffleArtifactAdapter, + SolCompilerArtifactAdapter: docSections.solCompilerArtifactAdapter, + }, }, }; const docsInfo = new DocsInfo(docsInfoConfig); |