README ¶
End-to-End Testing Suite
The End-to-End (E2E) testing suite provides an environment for running end-to-end tests on Evmos. It is used for testing chain upgrades, as it allows for initializing multiple Evmos chains with different versions.
Quick Start
To run a chain upgrade test, execute:
make test-upgrade
This logic utilizes parameters that can be set manually(if necessary):
# flag to skip containers cleanup after upgrade
# should be set true with make test-e2e command if you need access to the node after upgrade
E2E_SKIP_CLEANUP := false
# version of initial evmos node that will be upgraded, tag e.g. 'v9.1.0'
INITIAL_VERSION
# version of upgraded evmos node that will replace the initial node, tag e.g. 'v10.0.0'
TARGET_VERSION
# mount point for upgraded node container, to mount new node version to previous node state folder
# by defaullt './build/.evmosd:/root/.evmosd'
# more info https://docs.docker.com/engine/reference/builder/#volume
MOUNT_PATH
# '--chain-id' evmos cli parameter, used to start nodes with specific chain-id and submit proposals
# by default 'evmos_9000-1'
CHAIN_ID
To test an upgrade to explicit target version and continue to run the upgraded node, run:
make test-e2e E2E_SKIP_CLEANUP=true INITIAL_VERSION=<tag> TARGET_VERSION=<tag>
Upgrade Process
Testing a chain upgrade is a multi-step process:
- Build a docker image for the evmos target version (local repo by default, if no explicit
TARGET_VERSION
provided as argument) (e.g.v10.0.0
) - Run tests
- The e2e test will first run an
INITIAL_VERSION
node container. - The node will submit, deposit and vote for an upgrade proposal for upgrading to the
TARGET_VERSION
. - After block
50
is reached, the test suite exports/.evmosd
folder from docker container to localbuild/
and than purge the container. - Suite will mount
TARGET_VERSION
node to localbuild/
dir and start the node. Node will get upgrade information fromupgrade-info.json
and will execute the upgrade.
Structure
e2e
Package
The e2e
package defines an integration testing suite used for full end-to-end testing functionality. This package is decoupled from depending on the Evmos codebase. It initializes the chains for testing via Docker.
As a result, the test suite may provide the desired Evmos version to Docker containers during the initialization. This design allows for the opportunity of testing chain upgrades by providing an older Evmos version to the container, performing the chain upgrade, and running the latest test suite. Here's an overview of the files:
-
e2e_suite_test.go
: defines the testing suite and contains the core bootstrapping logic that creates a testing environment via Docker containers. A testing network is created dynamically with 2 test validators. -
e2e_test.go
: contains the actual end-to-end integration tests that utilize the testing suite. -
e2e_utils_test.go
: contains suite upgrade params loading logic.
upgrade
Package
The e2e
package defines an upgrade Manager
abstraction. Suite will utilize Manager
's functions to run different versions of evmos containers, propose, vote, delegate and query nodes.
-
manager.go
: defines core manager logic for running containers, export state and create networks. -
govexec.go
: definesgov-specific
exec commands to submit/delegate/vote through nodesgov
module. -
node.go
: definesNode
strcuture responsible for setting node container parameters before run.
Version retrieve
TARGET_VERSION
by default retieved latest upgrade version from local codebase evmos/app/upgrades
folder according to sevmver scheme.
If explicit TARGET_VERSION
provided as argument, corresponding node container will be pulled from dockerhub.
INITIAL_VERSION
retrieved as one version before the latest upgrade in evmos/app/upgrades
correspondingly.
Testing Results
The make test-upgrade
script will output the test results for each testing file. In case of a successful upgrade, the script will print the following output (example):
ok github.com/evmos/evmos/v9/tests/e2e 174.137s.
if target node version failed to start, caintainers [error stream]
and [output stream]
will be printed from container to local terminal:
Error: Received unexpected error:
can't start evmos node, container exit code: 2
[error stream]:
7:03AM INF Unlocking keyring
7:03AM INF starting ABCI with Tendermint
panic: invalid minimum gas prices: invalid decimal coin expression: 0aevmos
goroutine 1 [running]:
github.com/cosmos/cosmos-sdk/baseapp.SetMinGasPrices({0xc0013563e7?, 0xc00163a3c0?})
github.com/cosmos/cosmos-sdk@v0.46.5/baseapp/options.go:29 +0xd9
main.appCreator.newApp({{{0x3399b40, 0xc000ec1db8}, {0x33ac0f8, 0xc0011314e0}, {0x33a2920, 0xc000ed2b80}, 0xc0000155f0}}, {0x3394520, 0xc001633bc0}, {0x33a5cc0, ...}, ...)
github.com/evmos/evmos/v10/cmd/evmosd/root.go:243 +0x2ca
github.com/evmos/ethermint/server.startInProcess(_, {{0x0, 0x0, 0x0}, {0x33b7490, 0xc001784c30}, 0x0, {0x7fff50b37f3d, 0xc}, {0x33ac0f8, ...}, ...}, ...)
github.com/evmos/ethermint@v0.20.0-rc2/server/start.go:304 +0x9c5
github.com/evmos/ethermint/server.StartCmd.func2(0xc001620600?, {0xc001745bd0?, 0x0?, 0x1?})
github.com/evmos/ethermint@v0.20.0-rc2/server/start.go:123 +0x1ec
github.com/spf13/cobra.(*Command).execute(0xc001620600, {0xc001745bb0, 0x1, 0x1})
github.com/spf13/cobra@v1.6.1/command.go:916 +0x862
github.com/spf13/cobra.(*Command).ExecuteC(0xc00160e000)
github.com/spf13/cobra@v1.6.1/command.go:1044 +0x3bd
github.com/spf13/cobra.(*Command).Execute(...)
github.com/spf13/cobra@v1.6.1/command.go:968
github.com/spf13/cobra.(*Command).ExecuteContext(...)
github.com/spf13/cobra@v1.6.1/command.go:961
github.com/cosmos/cosmos-sdk/server/cmd.Execute(0x2170d50?, {0x26d961f, 0x6}, {0xc00112c490, 0xd})
github.com/cosmos/cosmos-sdk@v0.46.5/server/cmd/execute.go:36 +0x20f
main.main()
github.com/evmos/evmos/v10/cmd/evmosd/main.go:20 +0x45
[output stream]:
Test: TestIntegrationTestSuite/TestUpgrade
Messages: can't mount and run upgraded node container
To get all containers run:
# check containters
docker ps -a
Container names will be listed as follows:
CONTAINER ID IMAGE
9307f5485323 evmos:local <-- upgraded node
f41c97d6ca21 evmos:v9.0.0 <-- initial node
To access containers logs directly, run:
docker logs <container-id>
For interaction with upgraded set SKIP_CLEANUP=true
flag on make command agruments and enter the container after upgrade finished:
docker exec -it <container-id> bash
If cleanup was skipped upgraded node container should be removed manually:
docker kill <container-id>
docker rm <container-id>