update integration test readme

integration-tests/README.md

@@ -2,59 +2,106 @@
 
 ## Description
 
-Moonwall - Test framework for testing chain networks.
+Integation testing for ZeitgeistPM using
+[Moonwall](https://github.com/Moonsong-Labs/moonwall).
+
+Consider the documentation of the
+[Moonwall repository](https://github.com/Moonsong-Labs/moonwall) for more
+information.
 
 ## Installation
 
 ### NPM Installation
 
-> Package manager `pnpm` is required for the integration tests. You can install it with `npm install -g pnpm` or otherwise following [their instructions](https://pnpm.io/installation).
+> Package manager `pnpm` is required for the integration tests. You can install
+> it with `npm install -g pnpm` or otherwise following
+> [their instructions](https://pnpm.io/installation).
 
+#### Go to the `integration-tests` directory:
+
+```bash
+cd integration-tests
 ```
-pnpm -g i @moonwall/cli
-```
 
-From here you can import the items you need from moonwall packages in your code:
+The following commands all assume you are in the `integration-tests` directory.
+
+Run `pnpm install` in the `integration-tests` folder before running any of the
+following commands.
+
 ```
-import { describeSuite , beforeAll, expect, ALITH_ADDRESS } from "@moonwall/cli";
-import { ALITH_ADDRESS } from "@moonwall/util";
+pnpm install
 ```
 
-## Functions
+You should have installed `python` for using `sqlite3` and then used
+`pnpm rebuild && pnpm rebuild sqlite3`.
 
-- Init: Generates a new config file.
-- Run: Runs a network.
-- Test: Executes tests, and runs a network if neccesary.
-- Download: Gets node binaries for polkadot, moonbeam from GH.
+### Running the test environments
 
-> :information_source: Use `--help` for more information about arguments for each command
+#### Deploy a local, running relay-parachain network for zombienet:
 
-### Usage Examples (non-exhaustive)
+This is useful for testing the parachain client. It starts producing blocks of
+the relay and parachain from genesis.
 
-You should have installed `python` for using `sqlite3` and then used `pnpm rebuild && pnpm rebuild sqlite3`.
+```bash
+./scripts/download-polkadot.sh
+cd ../
+./integration-tests/scripts/deploy-zombienet.sh
+```
 
-Run `pnpm install` in the `integration-tests` folder before running any of the following commands.
+It is expected to see the following output multiple times before the network is launched:
 
-Useful for integration testing:
+```text
+Error fetching metrics from: http://127.0.0.1:<port>/metrics
+```
 
-- `./integration-tests/scripts/deploy-zombienet.sh` - Deploy a local relay-parachain network for zombienet.
-- `pnpm chopsticks xcm -r polkadot -p ./configs/hydradx.yml -p ./configs/zeitgeist.yml` - Deploy a local relay-parachain fork network via chopsticks to test XCM.
-- `./integration-tests/scripts/deploy-zombienet.sh --test` - Run ZNDSL zombienet tests on a local relay-parachain network.
-- `pnpm exec moonwall test zombienet_zeitgeist_upgrade` - Test Zeitgeist runtime upgrade on zombienet for the local network.
-- `pnpm exec moonwall test chopsticks_zeitgeist_upgrade` - Test Zeitgeist runtime upgrade on chopsticks for the live network.
-- `pnpm exec moonwall test chopsticks_battery_station_upgrade` - Test Battery Station runtime upgrade on chopsticks for the test network.
+##### Run ZNDSL zombienet tests on a local relay-parachain network:
 
-Possible moonwall commands:
+Using the additional `--test` flag, you can run the ZNDSL tests on the network.
 
-- `moonwall` : If you have globally installed moonwall, here is the most minimal entrypoint
+```bash
+./scripts/download-polkadot.sh
+cd ../
+./integration-tests/scripts/deploy-zombienet.sh --test
+```
 
-- `pnpm moonwall` : This can be used if locally installed, and will launch the main menu.. However, there were many bugs experienced when using this cli.
+#### Deploy a local, running relay-parachain fork network via chopsticks (e. g. to test XCM):
 
-- `pnpx @moonwall/cli run <ENV_NAME>` : To download and run the latest moonwall binary from npm.js repository, and run a network specified in your config file.
+This is useful for testing XCM or any other runtime interaction that needs to be
+tested on the state of the production network.
 
-- `pnpm exec moonwall test <ENV_NAME>` : To run the locally compiled version of the binary, to start network and run tests against it.
+```bash
+pnpm chopsticks xcm -r polkadot -p ./configs/hydradx.yml -p ./configs/zeitgeist.yml
+```
 
-- `pnpm moonwall download <ARTIFACT NAME> <VERSION> <PATH>` : To run the locally compiled version of the binary, to download an artifact directly from github.
+The expected output looks like this:
+
+```text
+Unable to map [u8; 32] to a lookup index
+[16:36:13.005] INFO (xcm/24440): HydraDX RPC listening on port 8000
+Unable to map [u8; 32] to a lookup index
+[16:36:14.895] INFO (xcm/24440): Zeitgeist RPC listening on port 8001
+[16:36:14.964] INFO (xcm/24440): Connected parachains [2034,2092]
+[16:36:14.964] INFO (24440): Loading config file https://raw.githubusercontent.com/AcalaNetwork/chopsticks/master/configs/polkadot.yml
+Unable to map [u8; 32] to a lookup index
+[16:36:16.944] INFO (xcm/24440): Polkadot RPC listening on port 8002
+[16:36:17.112] INFO (xcm/24440): Connected relaychain 'Polkadot' with parachain 'HydraDX'
+[16:36:17.240] INFO (xcm/24440): Connected relaychain 'Polkadot' with parachain 'Zeitgeist'
+```
+
+#### Test the upgrade to the WASM from `./target/release/wbuild/zeitgeist-runtime` on zombienet:
+
+```bash
+pnpm exec moonwall test zombienet_zeitgeist_upgrade
+```
 
+#### Test the upgrade to the WASM from `./target/release/wbuild/zeitgeist-runtime` on the live main-net fork using chopsticks:
 
-The combinations are endless, for more information you can see the pnpm docs [here](https://pnpm.io/cli/run).
+```bash
+pnpm exec moonwall test chopsticks_zeitgeist_upgrade
+```
+
+#### Test the upgrade to the WASM from `./target/release/wbuild/battery-station-runtime` on the live test-net fork using chopsticks:
+
+```bash
+pnpm exec moonwall test chopsticks_battery_station_upgrade
+```