From a1fab68fb070f41040d3394b078ca36b48876b0c Mon Sep 17 00:00:00 2001 From: Julien Robert Date: Wed, 4 Sep 2024 17:17:50 +0200 Subject: [PATCH] docs --- tests/systemtests/README.md | 15 +++++- tests/systemtests/bank_test.go | 80 ---------------------------- tests/systemtests/getting_started.md | 12 ++++- 3 files changed, 24 insertions(+), 83 deletions(-) delete mode 100644 tests/systemtests/bank_test.go diff --git a/tests/systemtests/README.md b/tests/systemtests/README.md index ab20d155f08f..ac9fcb49cdc9 100644 --- a/tests/systemtests/README.md +++ b/tests/systemtests/README.md @@ -3,23 +3,32 @@ Test framework for system tests. Starts and interacts with a (multi node) blockchain in Go. Supports + * CLI * Servers * Events * RPC Uses: + * testify * gjson * sjson -Server and client side are executed on the host machine + +Server and client side are executed on the host machine. ## Developer + ### Test strategy + System tests cover the full stack via cli and a running (multi node) network. They are more expensive (in terms of time/ cpu) to run compared to unit or integration tests. Therefore, we focus on the **critical path** and do not cover every condition. +## How to use + +Read the [getting_started.md](getting_started.md) guide to get started. + ### Execute a single test ```sh @@ -33,7 +42,9 @@ Test cli parameters * `-nodes-count` int - number of nodes in the cluster (default 4) # Port ranges + With *n* nodes: + * `26657` - `26657+n` - RPC * `1317` - `1317+n` - API * `9090` - `9090+n` - GRPC @@ -47,4 +58,4 @@ For example Node *3* listens on `26660` for RPC calls ## Disclaimer -This is based on the system test framework in [wasmd](https://github.com/CosmWasm/wasmd) built by Confio. \ No newline at end of file +This is based on the system test framework in [wasmd](https://github.com/CosmWasm/wasmd) built by Confio. diff --git a/tests/systemtests/bank_test.go b/tests/systemtests/bank_test.go deleted file mode 100644 index 5df4953114b0..000000000000 --- a/tests/systemtests/bank_test.go +++ /dev/null @@ -1,80 +0,0 @@ -//go:build system_test - -package systemtests - -import ( - "encoding/json" - "fmt" - sdk "github.com/cosmos/cosmos-sdk/types" - "github.com/tidwall/sjson" - "testing" - - "github.com/stretchr/testify/assert" - "github.com/stretchr/testify/require" - "github.com/tidwall/gjson" -) - -func TestQueryTotalSupply(t *testing.T) { - // scenario: - // given a chain with a custom token on genesis - // when an amount is burned - // then this is reflected in the total supply - - sut.ResetChain(t) - cli := NewCLIWrapper(t, sut, verbose) - sut.ModifyGenesisJSON(t, setupGenesis(t, cli)) - sut.StartChain(t) - - raw := cli.CustomQuery("q", "bank", "total-supply") - - exp := map[string]int64{ - "stake": int64(500000000 * sut.nodesCount), - "testtoken": int64(1000000000 * sut.nodesCount), - "mytoken": 1_000_000, - } - require.Len(t, gjson.Get(raw, "supply").Array(), len(exp), raw) - - for k, v := range exp { - got := gjson.Get(raw, fmt.Sprintf("supply.#(denom==%q).amount", k)).Int() - assert.Equal(t, v, got, raw) - } - - // and when - txHash := cli.Run("tx", "bank", "burn", "node0", "400000mytoken") - RequireTxSuccess(t, txHash) - // then - exp["mytoken"] = 600_000 // update expected state - raw = cli.CustomQuery("q", "bank", "total-supply") - for k, v := range exp { - got := gjson.Get(raw, fmt.Sprintf("supply.#(denom==%q).amount", k)).Int() - assert.Equal(t, v, got, raw) - } - assert.Equal(t, int64(600_000), cli.QueryBalance(cli.GetKeyAddr("node0"), "mytoken")) -} - -func setupGenesis(t *testing.T, cli *CLIWrapper) func(genesis []byte) []byte { - return func(genesis []byte) []byte { - // disable inflation - genesis, err := sjson.SetRawBytes(genesis, "app_state.mint.minter.inflation", []byte(`"0.000000000000000000"`)) - require.NoError(t, err) - - // add new token to supply - var supply []json.RawMessage - rawSupply := gjson.Get(string(genesis), "app_state.bank.supply").String() - require.NoError(t, json.Unmarshal([]byte(rawSupply), &supply)) - supply = append(supply, json.RawMessage(`{"denom": "mytoken","amount": "1000000"}`)) - newSupply, err := json.Marshal(supply) - require.NoError(t, err) - genesis, err = sjson.SetRawBytes(genesis, "app_state.bank.supply", newSupply) - require.NoError(t, err) - - // add amount to any balance - anyAddr := cli.GetKeyAddr("node0") - newBalances := GetGenesisBalance(genesis, anyAddr).Add(sdk.NewInt64Coin("mytoken", 1000000)) - newBalancesBz, err := newBalances.MarshalJSON() - require.NoError(t, err) - newState, err := sjson.SetRawBytes(genesis, fmt.Sprintf("app_state.bank.balances.#[address==%q]#.coins", anyAddr), newBalancesBz) - require.NoError(t, err) - return newState - } -} diff --git a/tests/systemtests/getting_started.md b/tests/systemtests/getting_started.md index 3d38fdfc19a0..47bee4dafa5f 100644 --- a/tests/systemtests/getting_started.md +++ b/tests/systemtests/getting_started.md @@ -4,10 +4,13 @@ Build a new binary from current branch and copy it to the `tests/systemtests/binaries` folder by running system tests. In project root: + ```shell make test-system ``` + Or via manual steps + ```shell make build mkdir -p ./tests/systemtests/binaries @@ -39,6 +42,7 @@ func TestQueryTotalSupply(t *testing.T) { t.Log("### got: " + raw) } ``` + The file begins with a Go build tag to exclude it from regular go test runs. All tests in the `systemtests` folder build upon the *test runner* initialized in `main_test.go`. This gives you a multi node chain started on your box. @@ -57,6 +61,7 @@ go test -mod=readonly -tags='system_test' -v ./... --run TestQueryTotalSupply - This give very verbose output. You would see all simd CLI commands used for starting the server or by the client to interact. In the example code, we just log the output. Watch out for + ```shell bank_test.go:15: ### got: { "supply": [ @@ -106,6 +111,7 @@ In order to test our assumptions in the system test, we modify the code to use ` assert.Equal(t, v, got, raw) } ``` + The assumption on the staking token usually fails due to inflation minted on the staking token. Let's fix this in the next step ### Run the test @@ -158,6 +164,7 @@ of `gjson`, `sjson` and stdlib json operations. }) sut.StartChain(t) ``` + Next step is to add the new token to the assert map. But we can also make it more resilient to different node counts. ```go @@ -183,8 +190,10 @@ The CLI wrapper works similar to the query. Just pass the parameters. It uses th txHash := cli.Run("tx", "bank", "burn", "node0", "400000mytoken") RequireTxSuccess(t, txHash) ``` + `RequireTxSuccess` or `RequireTxFailure` can be used to ensure the expected result of the operation. Next, check that the changes are applied. + ```go exp["mytoken"] = 600_000 // update expected state raw = cli.CustomQuery("q", "bank", "total-supply") @@ -197,9 +206,10 @@ Next, check that the changes are applied. While tests are still more or less readable, it can gets harder the longer they are. I found it helpful to add some comments at the beginning to describe what the intention is. For example: + ```go // scenario: // given a chain with a custom token on genesis // when an amount is burned // then this is reflected in the total supply -``` \ No newline at end of file +```