aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--packages/website/md/docs/sol_cov/usage.md48
-rw-r--r--packages/website/ts/containers/sol_cov_documentation.ts36
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);