From d92dc47df83a38c3caba845ae053b39ccffd36b1 Mon Sep 17 00:00:00 2001 From: Leonid Logvinov Date: Thu, 17 Jan 2019 15:44:34 +0100 Subject: Last touches --- packages/website/md/docs/sol_profiler/usage.md | 30 +++++++++++++++----------- 1 file changed, 17 insertions(+), 13 deletions(-) (limited to 'packages/website/md/docs/sol_profiler/usage.md') diff --git a/packages/website/md/docs/sol_profiler/usage.md b/packages/website/md/docs/sol_profiler/usage.md index 35ea140da..f9bab7ebf 100644 --- a/packages/website/md/docs/sol_profiler/usage.md +++ b/packages/website/md/docs/sol_profiler/usage.md @@ -1,4 +1,4 @@ -Sol-profiler 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 `ProfilerSubprovider` 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://0x.org/wiki#Web3-Provider-Explained) wiki article. +Sol-profiler 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 `ProfilerSubprovider` 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://0x.org/wiki#Web3-Provider-Explained) wiki article. The ProfilerSubprovider 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. @@ -12,9 +12,8 @@ If you are generating your artifacts with [@0x/sol-compiler](https://0x.org/docs ```typescript import { SolCompilerArtifactsAdapter } from '@0x/sol-profiler'; -const artifactsPath = 'src/artifacts'; -const contractsPath = 'src/contracts'; -const artifactsAdapter = new SolCompilerArtifactsAdapter(artifactsPath, contractsPath); +// Both artifactsDir and contractsDir are optional and will be fetched from compiler.json if not passed in +const artifactAdapter = new SolCompilerArtifactAdapter(artifactsDir, contractsDir); ``` ### Truffle @@ -23,8 +22,9 @@ If your project is using [Truffle](https://truffleframework.com/), we've written ```typescript import { TruffleArtifactAdapter } from '@0x/sol-profiler'; -const contractsPath = 'src/contracts'; -const artifactAdapter = new TruffleArtifactAdapter(contractsDir); +const projectRoot = '.'; +const solcVersion = '0.5.0'; +const artifactAdapter = new TruffleArtifactAdapter(projectRoot, solcVersion); ``` 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`. @@ -32,7 +32,13 @@ Because truffle artifacts don't have all the data we need - we actually will rec ### 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. + +```typescript +import { AbstractArtifactAdapter } from '@0x/sol-trace'; + +class YourCustomArtifactsAdapter extends AbstractArtifactAdapter {...}; +const artifactAdapter = new YourCustomArtifactsAdapter(...); +``` ### Usage @@ -41,22 +47,20 @@ import { ProfilerSubprovider } from '@0x/sol-profiler'; 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 profilerSubprovider = new ProfilerSubprovider(artifactsAdapter, defaultFromAddress, isVerbose); provider.addProvider(profilerSubprovider); +// Add all your other providers +provider.start(); ``` After your test suite is complete (e.g in the Mocha global `after` hook), you'll need to call: ```typescript -await profilerSubprovider.writeProfilerAsync(); +await profilerSubprovider.writeProfilerOutputAsync(); ``` -This will create a `profiler.json` file in a `profiler` directory. This file has an [Istanbul format](https://github.com/gotwarlost/istanbul/blob/master/profiler.json.md) - so you can use it with any of the existing Istanbul 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/profiler.json.md) - so you can use it with any of the existing Istanbul reporters. -- cgit v1.2.3 From 1c9fb5f65f86d5df3eb3db26032f91451fc87e1b Mon Sep 17 00:00:00 2001 From: Leonid Logvinov Date: Thu, 17 Jan 2019 19:47:24 +0100 Subject: Add notes about istanbul and Geth to website docs --- packages/website/md/docs/sol_profiler/usage.md | 8 ++++++++ 1 file changed, 8 insertions(+) (limited to 'packages/website/md/docs/sol_profiler/usage.md') diff --git a/packages/website/md/docs/sol_profiler/usage.md b/packages/website/md/docs/sol_profiler/usage.md index f9bab7ebf..0fbc31bc1 100644 --- a/packages/website/md/docs/sol_profiler/usage.md +++ b/packages/website/md/docs/sol_profiler/usage.md @@ -64,3 +64,11 @@ await profilerSubprovider.writeProfilerOutputAsync(); ``` This will create a `coverage.json` file in a `coverage` directory. This file has an [Istanbul format](https://github.com/gotwarlost/istanbul/blob/master/profiler.json.md) - so you can use it with any of the existing Istanbul reporters. + +```bash +yarn add -D istanbul +istanbul report html +open coverage/index.html +``` + +Use [Geth](https://github.com/ethereum/go-ethereum) as a backing node. We recommend using our [Devnet Docker container](https://hub.docker.com/r/0xorg/devnet) which sets up a Geth node for testing purposes. Ganache support is a [work in progress](https://github.com/0xProject/0x-monorepo/issues/1520). -- cgit v1.2.3