From 1f5341561bced3af3cbaba6321e4a930f05ac4b9 Mon Sep 17 00:00:00 2001 From: cgewecke Date: Tue, 25 Jul 2017 19:02:20 -0700 Subject: [PATCH] VM / testrpc-sc doc and README updates --- README.md | 1 + docs/faq.md | 19 +++++++++++++++++++ docs/testrpc-sc.md | 39 +++++++++++++-------------------------- 3 files changed, 33 insertions(+), 26 deletions(-) diff --git a/README.md b/README.md index 70a56c1..c74effa 100644 --- a/README.md +++ b/README.md @@ -93,6 +93,7 @@ Solutions to common issues people run into using this tool: + [Using alongside HDWalletProvider](https://github.com/sc-forks/solidity-coverage/blob/master/docs/faq.md#using-alongside-hdwalletprovider) + [Integrating into CI](https://github.com/sc-forks/solidity-coverage/blob/master/docs/faq.md#continuous-integration-installing-metacoin-on-travisci-with-coveralls) + [Why are asserts and requires highlighted as branch points?](https://github.com/sc-forks/solidity-coverage/blob/master/docs/faq.md#why-has-my-branch-coverage-decreased-why-is-assert-being-shown-as-a-branch-point) ++ [Running testrpc-sc on its own](https://github.com/sc-forks/solidity-coverage/blob/master/docs/faq.md#running-testrpc-sc-on-its-own) ### Example reports + [metacoin](https://sc-forks.github.io/metacoin/) (Istanbul HTML) diff --git a/docs/faq.md b/docs/faq.md index 040bdf0..a21ca49 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -169,3 +169,22 @@ require(x) Clearly, the coverage should be the same in these situations, as the code is (functionally) identical. Older versions of solidity-coverage did not treat these as branch points, and they were not considered in the branch coverage filter. Newer versions *do* count these as branch points, so if your tests did not include failure scenarios for `assert` or `require`, you may see a decrease in your coverage figures when upgrading `solidity-coverage`. If an `assert` or `require` is marked with an `I` in the coverage report, then during your tests the conditional is never true. If it is marked with an `E`, then it is never false. + + +### Running testrpc-sc on its own + +Sometimes its useful to launch `testrpc-sc` separately at the command line or with a script, after +setting the `norpc` config option in `.solcover.js` to true: + +If you installed using npm +``` +$ ./node_modules/.bin/testrpc-sc +``` + +If you installed using yarn +``` +$ ./node_modules/ethereumjs-testrpc-sc/bin/testrpc // v0.1.10 and below (testrpc v3.0.3) +$ ./node_modules/ethereumjs-testrpc-sc/build/cli.node.js // All others (testrpc v4.0.1 +) +``` + + diff --git a/docs/testrpc-sc.md b/docs/testrpc-sc.md index e90bee3..ba41d3f 100644 --- a/docs/testrpc-sc.md +++ b/docs/testrpc-sc.md @@ -6,8 +6,8 @@ Warning: this is a birds nest. Any ideas for improvement, however small, are wel + published on `npm` as `ethereumjs-testrpc-sc` + published **from the coverage branch** of [`sc-forks/testrpc-sc`](https://github.com/sc-forks/testrpc-sc/tree/coverage) + a webpack bundle of `sc-forks/ganache-core-sc#coverage` and all of its dependencies. -+ changing `sc-forks/ganache-core#coverage` or any of its dependencies cannot harm `testrpc-sc` (until publication) -+ publishing `testrpc-sc` cannot harm `solidity-coverage` until its deps are updated. ++ changes to `sc-forks/ganache-core` do not propagate until `testrpc-sc` is rebuilt and published ++ publishing `testrpc-sc` does not propagate until `solidity-coverage`s deps are updated. To publish a new version: @@ -27,7 +27,7 @@ $ npm publish // This also runs build. + set by default to [its `coverage` branch](https://github.com/sc-forks/ganache-core-sc) + depends on `sc-forks/ethereumjs-vm-sc.git` + depends on `sc-forks/provider-engine-sc.git#8.1.19` -+ differs from `truffle-suite/ganache-core` by these deps AND ++ differs from `truffle-suite/ganache-core` by these deps and [two lines](https://github.com/sc-forks/ganache-core/blob/ae31080cdc581fef416a1c68cbe28ff71b6fb7c9/lib/blockchain_double.js#L36-L37) in `blockchain_double.js` which set the block and transaction default gas limits. @@ -44,34 +44,21 @@ $ git push ### How can I modify ethereumjs-vm-sc and test the changes at `solidity-coverage`? -Cut a channel of branches (say `#vm`) through the entire project: - -`solidity-coverage#vm` with `package.json` -``` -"ethereumjs-testrpc-sc": "https://github.com/sc-forks/testrpc-sc.git#vm" -``` - -`testrpc-sc#vm` **based on the coverage branch** with `package.json` -``` -"ganache-core": "https://github.com/sc-forks/ganache-core-sc.git#vm" -``` - -`ganache-core#vm` with `package.json` -``` -"ethereumjs-vm": "https://github.com/sc-forks/ethereumjs-vm-sc.git#vm" -``` - -`ethereumjs-vm-sc#vm` (This is where you will work). - -+ To test your changes: - + freshly install `node_modules` in testrpc-sc#vm and execute `npm run build` - + freshly install `node_modules` in `solidity-coverage#vm` +Since `solidity-coverage@0.1.10`, ethereumjs-vm-sc is an independent dev dependency, +required by the coverage unit tests. The new testrpc has a separate webpacked copy. The simplest +thing to do is open a branch at `solidity-coverage` and develop directly on the `vm` dep. +When you're satisfied that tests pass with your changes, copy your work over to the `ethereumjs-vm-sc` repo itself. +In `test/util/vm.js` the `results` object passed back by `vm.runTx` at [callMethod](https://github.com/sc-forks/solidity-coverage/blob/master/test/util/vm.js#L120) +also contains things like the runState and the logs: ex: `results.vm.runState.logs`. + To merge / publish the changes: - + Merge `ethereumjs-vm-sc#vm` to master. + + Merge `ethereumjs-vm-sc#my-new-vm` to master. + follow the `testrpc-sc` publication steps above. +There's no reason to worry about changing ethereumjs-vm-sc at master. If that affects anyone (unlikely) +they have safe harbour at any solidity-coverage installation @0.1.9 and up. They can update. +