e2e

README

Avalanche e2e test suites

• Works with fixture-managed networks.
• Compiles to a single binary with customizable configurations.

Running tests

go install -v github.com/onsi/ginkgo/v2/ginkgo@v2.0.0
ACK_GINKGO_RC=true ginkgo build ./tests/e2e
./tests/e2e/e2e.test --help

./tests/e2e/e2e.test \
--metalgo-path=./build/metalgo

See tests.e2e.sh for an example.

Filtering test execution with labels

In cases where a change can be verified against only a subset of tests, it is possible to filter the tests that will be executed by the declarative labels that have been applied to them. Available labels are defined as constants in describe.go with names of the form *Label. The following example runs only those tests that primarily target the X-Chain:

./tests/e2e/e2e.test \
  --metalgo-path=./build/avalanchego \
  --ginkgo.label-filter=x

The ginkgo docs provide further detail on how to compose label queries.

Adding tests

Define any flags/configurations in e2e.go.

Create a new package to implement feature-specific tests, or add tests to an existing package. For example:

.
└── e2e
    ├── README.md
    ├── e2e.go
    ├── e2e_test.go
    └── x
        └── transfer.go
            └── virtuous.go

e2e.go defines common configuration for other test packages. x/transfer/virtuous.go defines X-Chain transfer tests, labeled with x, which can be selected by ./tests/e2e/e2e.test --ginkgo.label-filter "x".

Testing against a persistent network

By default, a new ephemeral test network will be started before each test run. When developing e2e tests, it may be helpful to create a persistent test network to test against. This can increase the speed of iteration by removing the requirement to start a new network for every invocation of the test under development.

To use a persistent network:

# From the root of the avalanchego repo

# Build the testnetctl binary
$ ./scripts/build_testnetctl.sh

# Start a new network
$ ./build/testnetctl start-network --avalanchego-path=/path/to/avalanchego
...
Started network 1000 @ /home/me/.testnetctl/networks/1000

Configure testnetctl to target this network by default with one of the following statements:
 - source /home/me/.testnetctl/networks/1000/network.env
 - export TESTNETCTL_NETWORK_DIR=/home/me/.testnetctl/networks/1000
 - export TESTNETCTL_NETWORK_DIR=/home/me/.testnetctl/networks/latest

# Start a new test run using the persistent network
ginkgo -v ./tests/e2e -- \
    --avalanchego-path=/path/to/avalanchego \
    --ginkgo-focus-file=[name of file containing test] \
    --use-persistent-network \
    --network-dir=/path/to/network

# It is also possible to set the AVALANCHEGO_PATH env var instead of supplying --avalanchego-path
# and to set TESTNETCTL_NETWORK_DIR instead of supplying --network-dir.

See the testnet fixture README for more details.

Skipping bootstrap checks

By default many tests will attempt to bootstrap a new node with the post-test network state. While this is a valuable activity to perform in CI, it can add considerable latency to test development. To disable these bootstrap checks during development, set the E2E_SKIP_BOOTSTRAP_CHECKS env var to a non-empty value:

E2E_SKIP_BOOTSTRAP_CHECKS=1 ginkgo -v ./tests/e2e ...

Documentation

Overview

e2e implements the e2e tests.

Index

• Constants
• func AddEphemeralNode(network testnet.Network, flags testnet.FlagsMap) testnet.Node
• func CheckBootstrapIsPossible(network testnet.Network)
• func ContextWithTimeout(duration time.Duration) context.Context
• func DefaultContext() context.Context
• func DescribeCChain(text string, args ...interface{}) bool
• func DescribePChain(text string, args ...interface{}) bool
• func DescribeXChain(text string, args ...interface{}) bool
• func DescribeXChainSerial(text string, args ...interface{}) bool
• func Eventually(condition func() bool, waitFor time.Duration, tick time.Duration, msg string)
• func InitTestEnvironment(envBytes []byte)
• func SendEthTransaction(ethClient ethclient.Client, signedTx *types.Transaction) *types.Receipt
• func StartLocalNetwork(avalancheGoExecPath string, networkDir string) *local.LocalNetwork
• func SuggestGasPrice(ethClient ethclient.Client) *big.Int
• func WaitForHealthy(node testnet.Node)
• func WithDefaultContext() common.Option
• func WithSuggestedGasPrice(ethClient ethclient.Client) common.Option
• type TestEnvironment
  • func (te *TestEnvironment) AllocateFundedKey() *secp256k1.PrivateKey
  • func (te *TestEnvironment) AllocateFundedKeys(count int) []*secp256k1.PrivateKey
  • func (te *TestEnvironment) GetNetwork() testnet.Network
  • func (te *TestEnvironment) GetRandomNodeURI() testnet.NodeURI
  • func (te *TestEnvironment) NewEthClient(nodeURI testnet.NodeURI) ethclient.Client
  • func (te *TestEnvironment) NewKeychain(count int) *secp256k1fx.Keychain
  • func (te *TestEnvironment) NewPrivateNetwork() testnet.Network
  • func (te *TestEnvironment) NewWallet(keychain *secp256k1fx.Keychain, nodeURI testnet.NodeURI) primary.Wallet

Constants

const (
	// A long default timeout used to timeout failed operations but
	// unlikely to induce flaking due to unexpected resource
	// contention.
	DefaultTimeout = 2 * time.Minute

	// Interval appropriate for network operations that should be
	// retried periodically but not too often.
	DefaultPollingInterval = 500 * time.Millisecond

	// Setting this env will disable post-test bootstrap
	// checks. Useful for speeding up iteration during test
	// development.
	SkipBootstrapChecksEnvName = "E2E_SKIP_BOOTSTRAP_CHECKS"

	// Validator start time must be a minimum of SyncBound from the
	// current time for validator addition to succeed, and adding 20
	// seconds provides a buffer in case of any delay in processing.
	DefaultValidatorStartTimeDiff = executor.SyncBound + 20*time.Second

	DefaultGasLimit = uint64(21000) // Standard gas limit

	// An empty string prompts the use of the default path which ensures a
	// predictable target for github's upload-artifact action.
	DefaultNetworkDir = ""

	// Directory used to store private networks (specific to a single test)
	// under the shared network dir.
	PrivateNetworksDirName = "private_networks"
)

const (

	// Label for filtering a test that is not primarily a C-Chain test
	// but nonentheless uses the C-Chain. Intended to support
	// execution of all C-Chain tests by the coreth repo in an e2e job.
	UsesCChainLabel = "uses-c"
)

Functions

func AddEphemeralNode

func AddEphemeralNode(network testnet.Network, flags testnet.FlagsMap) testnet.Node

Add an ephemeral node that is only intended to be used by a single test. Its ID and URI are not intended to be returned from the Network instance to minimize accessibility from other tests.

func CheckBootstrapIsPossible

func CheckBootstrapIsPossible(network testnet.Network)

Verify that a new node can bootstrap into the network.

func ContextWithTimeout

func ContextWithTimeout(duration time.Duration) context.Context

Helper simplifying use of a timed context by canceling the context on ginkgo teardown.

func DefaultContext

func DefaultContext() context.Context

Helper simplifying use of a timed context configured with the default timeout.

func DescribeCChain

func DescribeCChain(text string, args ...interface{}) bool

DescribeCChain annotates the tests for C-Chain.

func DescribePChain

func DescribePChain(text string, args ...interface{}) bool

DescribePChain annotates the tests for P-Chain.

func DescribeXChain

func DescribeXChain(text string, args ...interface{}) bool

DescribeXChain annotates the tests for X-Chain.

func DescribeXChainSerial

func DescribeXChainSerial(text string, args ...interface{}) bool

DescribeXChainSerial annotates serial tests for X-Chain.

func Eventually

func Eventually(condition func() bool, waitFor time.Duration, tick time.Duration, msg string)

Re-implementation of testify/require.Eventually that is compatible with ginkgo. testify's version calls the condition function with a goroutine and ginkgo assertions don't work properly in goroutines.

func InitTestEnvironment

func InitTestEnvironment(envBytes []byte)

func SendEthTransaction

func SendEthTransaction(ethClient ethclient.Client, signedTx *types.Transaction) *types.Receipt

Sends an eth transaction, waits for the transaction receipt to be issued and checks that the receipt indicates success.

func StartLocalNetwork

func StartLocalNetwork(avalancheGoExecPath string, networkDir string) *local.LocalNetwork

Start a local test-managed network with the provided avalanchego binary.

func SuggestGasPrice

func SuggestGasPrice(ethClient ethclient.Client) *big.Int

Determines the suggested gas price for the configured client that will maximize the chances of transaction acceptance.

func WaitForHealthy

func WaitForHealthy(node testnet.Node)

Wait for the given node to report healthy.

func WithDefaultContext

func WithDefaultContext() common.Option

Helper simplifying use via an option of a timed context configured with the default timeout.

func WithSuggestedGasPrice

func WithSuggestedGasPrice(ethClient ethclient.Client) common.Option

Helper simplifying use via an option of a gas price appropriate for testing.

Types

type TestEnvironment

type TestEnvironment struct {
	// The directory where the test network configuration is stored
	NetworkDir string
	// URIs used to access the API endpoints of nodes of the network
	URIs []testnet.NodeURI
	// The URI used to access the http server that allocates test data
	TestDataServerURI string
	// contains filtered or unexported fields
}

var Env *TestEnvironment

Env is used to access shared test fixture. Intended to be initialized by SynchronizedBeforeSuite.

func (*TestEnvironment) AllocateFundedKey

func (te *TestEnvironment) AllocateFundedKey() *secp256k1.PrivateKey

Retrieve a funded key allocated for the caller's exclusive use.

func (*TestEnvironment) AllocateFundedKeys

func (te *TestEnvironment) AllocateFundedKeys(count int) []*secp256k1.PrivateKey

Retrieve the specified number of funded keys allocated for the caller's exclusive use.

func (*TestEnvironment) GetNetwork

func (te *TestEnvironment) GetNetwork() testnet.Network

Retrieve the network to target for testing.

func (*TestEnvironment) GetRandomNodeURI

func (te *TestEnvironment) GetRandomNodeURI() testnet.NodeURI

Retrieve a random URI to naively attempt to spread API load across nodes.

func (*TestEnvironment) NewEthClient

func (te *TestEnvironment) NewEthClient(nodeURI testnet.NodeURI) ethclient.Client

Create a new eth client targeting the specified node URI. TODO(marun) Make this a regular function.

func (*TestEnvironment) NewKeychain

func (te *TestEnvironment) NewKeychain(count int) *secp256k1fx.Keychain

Create a new keychain with the specified number of test keys.

func (*TestEnvironment) NewPrivateNetwork

func (te *TestEnvironment) NewPrivateNetwork() testnet.Network

Create a new private network that is not shared with other tests.

func (*TestEnvironment) NewWallet

func (te *TestEnvironment) NewWallet(keychain *secp256k1fx.Keychain, nodeURI testnet.NodeURI) primary.Wallet

Create a new wallet for the provided keychain against the specified node URI. TODO(marun) Make this a regular function.