From c1d17c83f8ee246c60b277c9c76b4eb9db1dba05 Mon Sep 17 00:00:00 2001 From: Fabio Berger Date: Sun, 18 Mar 2018 16:10:02 +0100 Subject: [PATCH] Add sol-cov docs to website --- packages/sol-cov/package.json | 2 +- .../website/md/docs/sol_cov/installation.md | 17 ++++ .../website/md/docs/sol_cov/introduction.md | 1 + packages/website/md/docs/sol_cov/usage.md | 26 ++++++ packages/website/translations/chinese.json | 1 + packages/website/translations/english.json | 1 + packages/website/translations/korean.json | 1 + packages/website/translations/russian.json | 1 + packages/website/translations/spanish.json | 1 + .../website/ts/components/sidebar_header.tsx | 1 + .../website/ts/components/top_bar/top_bar.tsx | 19 ++++ .../ts/containers/sol_cov_documentation.ts | 89 +++++++++++++++++++ packages/website/ts/index.tsx | 4 + .../ts/pages/documentation/doc_page.tsx | 2 + packages/website/ts/types.ts | 3 + 15 files changed, 168 insertions(+), 1 deletion(-) create mode 100644 packages/website/md/docs/sol_cov/installation.md create mode 100644 packages/website/md/docs/sol_cov/introduction.md create mode 100644 packages/website/md/docs/sol_cov/usage.md create mode 100644 packages/website/ts/containers/sol_cov_documentation.ts diff --git a/packages/sol-cov/package.json b/packages/sol-cov/package.json index 21852c908c..8f3b9d794b 100644 --- a/packages/sol-cov/package.json +++ b/packages/sol-cov/package.json @@ -22,7 +22,7 @@ "postpublish": { "assets": [], "docPublishConfigs": { - "extraFileIncludes": ["../types/src/index.ts"], + "extraFileIncludes": ["../subproviders/src/types.ts"], "s3BucketPath": "s3://doc-jsons/sol-cov/", "s3StagingBucketPath": "s3://staging-doc-jsons/sol-cov/" } diff --git a/packages/website/md/docs/sol_cov/installation.md b/packages/website/md/docs/sol_cov/installation.md new file mode 100644 index 0000000000..17362d89a8 --- /dev/null +++ b/packages/website/md/docs/sol_cov/installation.md @@ -0,0 +1,17 @@ +**Install** + +```bash +npm install @0xproject/sol-cov --save +``` + +**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 new file mode 100644 index 0000000000..7064a35546 --- /dev/null +++ b/packages/website/md/docs/sol_cov/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/usage.md b/packages/website/md/docs/sol_cov/usage.md new file mode 100644 index 0000000000..ea1982d97b --- /dev/null +++ b/packages/website/md/docs/sol_cov/usage.md @@ -0,0 +1,26 @@ +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. + +```typescript +import { CoverageSubprovider } from '@0xproject/sol-cov'; + +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 coverageSubprovider = new CoverageSubprovider(artifactsPath, contractsPath, networkId, defaultFromAddress); + +provider.addProvider(coverageSubprovider); +``` + +After your test suite is complete (e.g 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. diff --git a/packages/website/translations/chinese.json b/packages/website/translations/chinese.json index 4b7b3f642c..a46d12747f 100644 --- a/packages/website/translations/chinese.json +++ b/packages/website/translations/chinese.json @@ -58,6 +58,7 @@ "CONTACT": "联系方式", "DEPLOYER": "Deployer", "JSON_SCHEMAS": "JSON Schemas", + "SOL_COV": "Solidty Coverage", "BLOG": "博客", "FORUM": "论坛", "CONNECT": "0x 连接", diff --git a/packages/website/translations/english.json b/packages/website/translations/english.json index 52bf0ac9d9..3b9818909d 100644 --- a/packages/website/translations/english.json +++ b/packages/website/translations/english.json @@ -59,6 +59,7 @@ "CONTACT": "contact", "DEPLOYER": "Deployer", "JSON_SCHEMAS": "JSON Schemas", + "SOL_COV": "Solidty Coverage", "BLOG": "blog", "FORUM": "forum", "CONNECT": "0x Connect", diff --git a/packages/website/translations/korean.json b/packages/website/translations/korean.json index 66e4db9658..6bc78cd4f2 100644 --- a/packages/website/translations/korean.json +++ b/packages/website/translations/korean.json @@ -58,6 +58,7 @@ "CONTACT": "문의", "DEPLOYER": "Deployer", "JSON_SCHEMAS": "JSON Schemas", + "SOL_COV": "Solidty Coverage", "BLOG": "블로그", "FORUM": "포럼", "CONNECT": "0x Connect", diff --git a/packages/website/translations/russian.json b/packages/website/translations/russian.json index 09da6015a3..68ebed30b9 100644 --- a/packages/website/translations/russian.json +++ b/packages/website/translations/russian.json @@ -58,6 +58,7 @@ "CONTACT": "Связаться с нами", "DEPLOYER": "Deployer", "JSON_SCHEMAS": "JSON Schemas", + "SOL_COV": "Solidty Coverage", "BLOG": "Блог", "FORUM": "Форум", "CONNECT": "0x Connect", diff --git a/packages/website/translations/spanish.json b/packages/website/translations/spanish.json index 236bda339a..cd508f00ae 100644 --- a/packages/website/translations/spanish.json +++ b/packages/website/translations/spanish.json @@ -59,6 +59,7 @@ "CONTACT": "contacto", "DEPLOYER": "Deployer", "JSON_SCHEMAS": "JSON Schemas", + "SOL_COV": "Solidty Coverage", "BLOG": "blog", "FORUM": "foro", "CONNECT": "0x Connect", diff --git a/packages/website/ts/components/sidebar_header.tsx b/packages/website/ts/components/sidebar_header.tsx index 6216d2146d..6fae03691f 100644 --- a/packages/website/ts/components/sidebar_header.tsx +++ b/packages/website/ts/components/sidebar_header.tsx @@ -8,6 +8,7 @@ const titleToIcon: { [title: string]: string } = { '0x.js': 'zeroExJs.png', Web3Wrapper: 'zeroExJs.png', Deployer: 'zeroExJs.png', + 'Sol-cov': 'zeroExJs.png', 'JSON Schemas': 'zeroExJs.png', '0x Connect': 'connect.png', '0x Smart Contracts': 'contracts.png', diff --git a/packages/website/ts/components/top_bar/top_bar.tsx b/packages/website/ts/components/top_bar/top_bar.tsx index 9474311b43..fd33e86056 100644 --- a/packages/website/ts/components/top_bar/top_bar.tsx +++ b/packages/website/ts/components/top_bar/top_bar.tsx @@ -157,6 +157,12 @@ export class TopBar extends React.Component { primaryText={this.props.translate.get(Key.JsonSchemas, Deco.CapWords)} /> , + + + , ]; const bottomBorderStyle = this._shouldDisplayBottomBar() ? styles.bottomBar : {}; const fullWidthClasses = isFullWidthPage ? 'pr4' : ''; @@ -319,6 +325,14 @@ export class TopBar extends React.Component { )} + {!this._isViewingSolCovDocs() && ( + + + {this.props.translate.get(Key.SolCov, Deco.Cap)}{' '} + {this.props.translate.get(Key.Docs, Deco.Cap)} + + + )} {!this._isViewingPortal() && ( @@ -351,6 +365,7 @@ export class TopBar extends React.Component { !this._isViewingWeb3WrapperDocs() && !this._isViewingDeployerDocs() && !this._isViewingJsonSchemasDocs() && + !this._isViewingSolCovDocs() && !this._isViewingConnectDocs()) || _.isUndefined(this.props.menu) ) { @@ -448,6 +463,9 @@ export class TopBar extends React.Component { private _isViewingJsonSchemasDocs() { return _.includes(this.props.location.pathname, WebsitePaths.JSONSchemas); } + private _isViewingSolCovDocs() { + return _.includes(this.props.location.pathname, WebsitePaths.SolCov); + } private _isViewingWiki() { return _.includes(this.props.location.pathname, WebsitePaths.Wiki); } @@ -460,6 +478,7 @@ export class TopBar extends React.Component { this._isViewingWeb3WrapperDocs() || this._isViewingDeployerDocs() || this._isViewingJsonSchemasDocs() || + this._isViewingSolCovDocs() || this._isViewingConnectDocs() ); } diff --git a/packages/website/ts/containers/sol_cov_documentation.ts b/packages/website/ts/containers/sol_cov_documentation.ts new file mode 100644 index 0000000000..2b901ec6f6 --- /dev/null +++ b/packages/website/ts/containers/sol_cov_documentation.ts @@ -0,0 +1,89 @@ +import { constants as docConstants, DocsInfo, DocsInfoConfig, SupportedDocJson } from '@0xproject/react-docs'; +import * as _ from 'lodash'; +import * as React from 'react'; +import { connect } from 'react-redux'; +import { Dispatch } from 'redux'; +import { DocPage as DocPageComponent, DocPageProps } from 'ts/pages/documentation/doc_page'; +import { Dispatcher } from 'ts/redux/dispatcher'; +import { State } from 'ts/redux/reducer'; +import { DocPackages, Environments, WebsitePaths } from 'ts/types'; +import { configs } from 'ts/utils/configs'; +import { constants } from 'ts/utils/constants'; +import { Translate } from 'ts/utils/translate'; + +/* tslint:disable:no-var-requires */ +const IntroMarkdown = require('md/docs/sol_cov/introduction'); +const InstallationMarkdown = require('md/docs/sol_cov/installation'); +const UsageMarkdown = require('md/docs/sol_cov/usage'); +/* tslint:enable:no-var-requires */ + +const docSections = { + introduction: 'introduction', + installation: 'installation', + usage: 'usage', + coverageSubprovider: 'coverageSubprovider', + types: docConstants.TYPES_SECTION_NAME, +}; + +const docsInfoConfig: DocsInfoConfig = { + id: DocPackages.SolCov, + type: SupportedDocJson.TypeDoc, + displayName: 'Sol-cov', + packageUrl: 'https://github.com/0xProject/0x-monorepo', + menu: { + introduction: [docSections.introduction], + install: [docSections.installation], + usage: [docSections.usage], + coverageSubprovider: [docSections.coverageSubprovider], + types: [docSections.types], + }, + sectionNameToMarkdown: { + [docSections.introduction]: IntroMarkdown, + [docSections.installation]: InstallationMarkdown, + [docSections.usage]: UsageMarkdown, + }, + sectionNameToModulePath: { + [docSections.coverageSubprovider]: ['"sol-cov/src/coverage_subprovider"'], + [docSections.types]: ['"subproviders/src/types"'], + }, + menuSubsectionToVersionWhenIntroduced: {}, + sections: docSections, + visibleConstructors: [docSections.coverageSubprovider], + 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'], + typeNameToExternalLink: {}, + typeNameToPrefix: { + JSONRPCRequestPayload: 'Web3', + }, + typeNameToDocSection: {}, + }, +}; +const docsInfo = new DocsInfo(docsInfoConfig); + +interface ConnectedState { + docsVersion: string; + availableDocVersions: string[]; + docsInfo: DocsInfo; + translate: Translate; +} + +interface ConnectedDispatch { + dispatcher: Dispatcher; +} + +const mapStateToProps = (state: State, ownProps: DocPageProps): ConnectedState => ({ + docsVersion: state.docsVersion, + availableDocVersions: state.availableDocVersions, + translate: state.translate, + docsInfo, +}); + +const mapDispatchToProps = (dispatch: Dispatch): ConnectedDispatch => ({ + dispatcher: new Dispatcher(dispatch), +}); + +export const Documentation: React.ComponentClass = connect(mapStateToProps, mapDispatchToProps)( + DocPageComponent, +); diff --git a/packages/website/ts/index.tsx b/packages/website/ts/index.tsx index b5166ebca8..1241c222ba 100644 --- a/packages/website/ts/index.tsx +++ b/packages/website/ts/index.tsx @@ -54,6 +54,9 @@ const LazyDeployerDocumentation = createLazyComponent('Documentation', async () const LazyJSONSchemasDocumentation = createLazyComponent('Documentation', async () => System.import(/* webpackChunkName: "connectDocs" */ 'ts/containers/json_schemas_documentation'), ); +const LazySolCovDocumentation = createLazyComponent('Documentation', async () => + System.import(/* webpackChunkName: "connectDocs" */ 'ts/containers/sol_cov_documentation'), +); analytics.init(); // tslint:disable-next-line:no-floating-promises @@ -75,6 +78,7 @@ render( +