/avalanche-testing

An end-to-end testing suite for Avalanche nodes

Primary LanguageGo

Avalanche End-to-End Tests

This repo contains end-to-end tests for the Avalanche network and avalanchego client using the Kurtosis testing framework

Requirements

Running Locally

  1. Clone this repository
  2. Run scripts/full_rebuild_and_run.sh and wait for it to finish (which will take a while)

This command will spin up multiple Docker containers during its operation, and you can examine container logs via either your Docker engine dashboard GUI or the docker container ls and docker container logs.

NOTE: The Avalanche E2E test suite defaults to running 4 tests in parallel to speed up test suite execution time. If your machine has less cores, you should reduce this parallelism to at maximum the number of cores on your machine, else the extra context-switching will slow down test execution and potentially cause spurious failures. To set the paralleism, pass the --parallelism=N argument to full_rebuild_and_run.sh (where "N" is the desired number of threads).

Once full_rebuild_and_run.sh has finished, you can now execute scripts/run.sh to re-run the testing suite without needing to rebuild. run.sh will accept arguments to modify test suite execution; to see the full list of supported arguments, pass in the --help flag.

Developing Locally

This repo uses the Kurtosis architecture, so you should first go through the tutorial there to familiarize yourself with the core Kurtosis concepts.

In this implementation of Kurtosis, we have:

  • NodeService interface to represent the actions a test can take against a generic node exposing a staking socket and implementing the Kurtosis services.Service interface
  • AvalancheService interface to represent the actions a test can take against an avalanchego client participating in the Avalanche network being tested
  • AvalancheServiceInitializerCore and AvalancheServiceAvailabilityChecker for instantiating avalanchego clients in test networks
    • AvalancheCertProvider to allow controlling the cert that a avalanchego node starts with, to allow for writing duplicate-node-ID tests
  • TestAvalancheNetwork to encapsulate a test Avalanche network of avalanchego nodes of arbitrary size
  • Several tests
  • AvalancheTestSuite to contain all the tests Kurtosis can run
  • A main.go for running a controller Docker image under the controller package
  • A main.go for running the Kurtosis initializer under the initializer package

Additionally, for ease of writing tests, this repo also contains a Go client for interacting with the JSON RPC API of an Avalanche node (which will be moved to an external repo).

Adding A Test

  1. Create a new file in commons/testsuite for your test
  2. Create a struct that implements the testsuite.Test interface from Kurtosis
  3. Fill in the interface's functions
  4. Register the test in AvalancheTestSuite's GetTests method

Running Your Code

The scripts/full_rebuild_and_run.sh will rebuild and rerun both the initializer and controller Docker image; rerun this every time that you make a change. Arguments passed to this script will get passed to the initializer binary CLI as-is.

Keeping Your Dev Environment Clean

Kurtosis intentionally doesn't delete containers and volumes, which means your local Docker environment will accumulate images, containers, and volumes; you can use the script here to clean old containers and images. For further information, read the Notes section of the Kurtosis README for more details on how to keep your local environment clean while you develop.