From c4ae91c7c5aaa2d6e278448667bf828162be93bc Mon Sep 17 00:00:00 2001 From: Fabio Berger Date: Thu, 18 Oct 2018 17:31:38 +0100 Subject: Update doc ref markdown sections --- packages/website/md/docs/sol_cov/1/installation.md | 17 ++++++ packages/website/md/docs/sol_cov/1/introduction.md | 1 + packages/website/md/docs/sol_cov/1/usage.md | 62 ++++++++++++++++++++++ packages/website/md/docs/sol_cov/2/installation.md | 17 ++++++ packages/website/md/docs/sol_cov/2/introduction.md | 1 + packages/website/md/docs/sol_cov/2/usage.md | 62 ++++++++++++++++++++++ packages/website/md/docs/sol_cov/installation.md | 17 ------ packages/website/md/docs/sol_cov/introduction.md | 1 - packages/website/md/docs/sol_cov/usage.md | 62 ---------------------- 9 files changed, 160 insertions(+), 80 deletions(-) create mode 100644 packages/website/md/docs/sol_cov/1/installation.md create mode 100644 packages/website/md/docs/sol_cov/1/introduction.md create mode 100644 packages/website/md/docs/sol_cov/1/usage.md create mode 100644 packages/website/md/docs/sol_cov/2/installation.md create mode 100644 packages/website/md/docs/sol_cov/2/introduction.md create mode 100644 packages/website/md/docs/sol_cov/2/usage.md delete mode 100644 packages/website/md/docs/sol_cov/installation.md delete mode 100644 packages/website/md/docs/sol_cov/introduction.md delete mode 100644 packages/website/md/docs/sol_cov/usage.md (limited to 'packages/website/md/docs/sol_cov') diff --git a/packages/website/md/docs/sol_cov/1/installation.md b/packages/website/md/docs/sol_cov/1/installation.md new file mode 100644 index 000000000..b9ce25a5f --- /dev/null +++ b/packages/website/md/docs/sol_cov/1/installation.md @@ -0,0 +1,17 @@ +**Install** + +```bash +yarn add @0xproject/sol-cov +``` + +**Import** + +```javascript +import { CoverageSubprovider } from '@0xproject/sol-cov'; +``` + +or + +```javascript +var CoverageSubprovider = require('@0xproject/sol-cov').CoverageSubprovider; +``` diff --git a/packages/website/md/docs/sol_cov/1/introduction.md b/packages/website/md/docs/sol_cov/1/introduction.md new file mode 100644 index 000000000..7064a3554 --- /dev/null +++ b/packages/website/md/docs/sol_cov/1/introduction.md @@ -0,0 +1 @@ +Welcome to the [@0xproject/sol-cov](https://github.com/0xProject/0x-monorepo/tree/development/packages/sol-cov) documentation! Sol-cov is a Solidity coverage tool for your smart contract tests. diff --git a/packages/website/md/docs/sol_cov/1/usage.md b/packages/website/md/docs/sol_cov/1/usage.md new file mode 100644 index 000000000..c747005fb --- /dev/null +++ b/packages/website/md/docs/sol_cov/1/usage.md @@ -0,0 +1,62 @@ +Sol-cov uses transaction traces in order to figure out which lines of Solidity source code have been covered by your tests. In order for it to gather these traces, you must add the `CoverageSubprovider` to the [ProviderEngine](https://github.com/MetaMask/provider-engine) instance you use when running your Solidity tests. If you're unfamiliar with ProviderEngine, please read the [Web3 Provider explained](https://0xproject.com/wiki#Web3-Provider-Explained) wiki article. + +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](https://0xproject.com/docs/sol-compiler) you can use the `SolCompilerArtifactsAdapter` we've implemented for you. + +```typescript +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](https://truffleframework.com/), 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'); + +const provider = new ProviderEngine(); + +const artifactsPath = 'src/artifacts'; +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'; +const isVerbose = true; +const coverageSubprovider = new CoverageSubprovider(artifactsAdapter, defaultFromAddress, isVerbose); + +provider.addProvider(coverageSubprovider); +``` + +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 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/md/docs/sol_cov/2/installation.md b/packages/website/md/docs/sol_cov/2/installation.md new file mode 100644 index 000000000..1d4557cf5 --- /dev/null +++ b/packages/website/md/docs/sol_cov/2/installation.md @@ -0,0 +1,17 @@ +**Install** + +```bash +yarn add @0x/sol-cov +``` + +**Import** + +```javascript +import { CoverageSubprovider } from '@0x/sol-cov'; +``` + +or + +```javascript +var CoverageSubprovider = require('@0x/sol-cov').CoverageSubprovider; +``` diff --git a/packages/website/md/docs/sol_cov/2/introduction.md b/packages/website/md/docs/sol_cov/2/introduction.md new file mode 100644 index 000000000..ac3256845 --- /dev/null +++ b/packages/website/md/docs/sol_cov/2/introduction.md @@ -0,0 +1 @@ +Welcome to the [sol-cov](https://github.com/0xProject/0x-monorepo/tree/development/packages/sol-cov) documentation! Sol-cov is a Solidity coverage tool for your smart contract tests. diff --git a/packages/website/md/docs/sol_cov/2/usage.md b/packages/website/md/docs/sol_cov/2/usage.md new file mode 100644 index 000000000..d1c76474b --- /dev/null +++ b/packages/website/md/docs/sol_cov/2/usage.md @@ -0,0 +1,62 @@ +Sol-cov uses transaction traces in order to figure out which lines of Solidity source code have been covered by your tests. In order for it to gather these traces, you must add the `CoverageSubprovider` to the [ProviderEngine](https://github.com/MetaMask/provider-engine) instance you use when running your Solidity tests. If you're unfamiliar with ProviderEngine, please read the [Web3 Provider explained](https://0xproject.com/wiki#Web3-Provider-Explained) wiki article. + +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 [@0x/sol-compiler](https://0xproject.com/docs/sol-compiler) you can use the `SolCompilerArtifactsAdapter` we've implemented for you. + +```typescript +import { SolCompilerArtifactsAdapter } from '@0x/sol-cov'; +const artifactsPath = 'src/artifacts'; +const contractsPath = 'src/contracts'; +const artifactsAdapter = new SolCompilerArtifactsAdapter(artifactsPath, contractsPath); +``` + +### Truffle + +If your project is using [Truffle](https://truffleframework.com/), we've written a `TruffleArtifactsAdapter`for you. + +```typescript +import { TruffleArtifactAdapter } from '@0x/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 '@0x/sol-cov'; +import ProviderEngine = require('web3-provider-engine'); + +const provider = new ProviderEngine(); + +const artifactsPath = 'src/artifacts'; +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'; +const isVerbose = true; +const coverageSubprovider = new CoverageSubprovider(artifactsAdapter, defaultFromAddress, isVerbose); + +provider.addProvider(coverageSubprovider); +``` + +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 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/md/docs/sol_cov/installation.md b/packages/website/md/docs/sol_cov/installation.md deleted file mode 100644 index b9ce25a5f..000000000 --- a/packages/website/md/docs/sol_cov/installation.md +++ /dev/null @@ -1,17 +0,0 @@ -**Install** - -```bash -yarn add @0xproject/sol-cov -``` - -**Import** - -```javascript -import { CoverageSubprovider } from '@0xproject/sol-cov'; -``` - -or - -```javascript -var CoverageSubprovider = require('@0xproject/sol-cov').CoverageSubprovider; -``` diff --git a/packages/website/md/docs/sol_cov/introduction.md b/packages/website/md/docs/sol_cov/introduction.md deleted file mode 100644 index 7064a3554..000000000 --- a/packages/website/md/docs/sol_cov/introduction.md +++ /dev/null @@ -1 +0,0 @@ -Welcome to the [@0xproject/sol-cov](https://github.com/0xProject/0x-monorepo/tree/development/packages/sol-cov) documentation! Sol-cov is a Solidity coverage tool for your smart contract tests. diff --git a/packages/website/md/docs/sol_cov/usage.md b/packages/website/md/docs/sol_cov/usage.md deleted file mode 100644 index c747005fb..000000000 --- a/packages/website/md/docs/sol_cov/usage.md +++ /dev/null @@ -1,62 +0,0 @@ -Sol-cov uses transaction traces in order to figure out which lines of Solidity source code have been covered by your tests. In order for it to gather these traces, you must add the `CoverageSubprovider` to the [ProviderEngine](https://github.com/MetaMask/provider-engine) instance you use when running your Solidity tests. If you're unfamiliar with ProviderEngine, please read the [Web3 Provider explained](https://0xproject.com/wiki#Web3-Provider-Explained) wiki article. - -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](https://0xproject.com/docs/sol-compiler) you can use the `SolCompilerArtifactsAdapter` we've implemented for you. - -```typescript -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](https://truffleframework.com/), 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'); - -const provider = new ProviderEngine(); - -const artifactsPath = 'src/artifacts'; -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'; -const isVerbose = true; -const coverageSubprovider = new CoverageSubprovider(artifactsAdapter, defaultFromAddress, isVerbose); - -provider.addProvider(coverageSubprovider); -``` - -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 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. -- cgit v1.2.3