networktest

README

Network test

Network tests provide standard structures for running functional, load and scenario tests against a network.

They are designed to be network agnostic, able to run against both local dev networks and remote testnets.

Actions

Tests are structured using "Actions" which can be run in series of parallel in a nested tree down to very small steps.

Action's Run() method takes a context and a network connector, it returns a context and potential error.

Actions can use the context to pass values to tests that are running later in the flow, so properties that an action require from the context are part of that action's API. We use the ActionKey type for the context keys.

Running tests

All tests can be found under the /tests directory. They are grouped into a few packages to try to keep similarly used tests together.

/helpful

These are ad-hoc helpers, for example:

• running a local network indefinitely
• smoke test that checks a network isn't completely broken

/load

These tests are designed to apply simulated user activity for a period of time to stress the network.

/nodescenario

These tests require a network that provides access to its nodes through the NodeOperator interface.

They can be used to test scenarios such as rejoining the network after a restart, sequencer failover, nodes losing connectivity.

/ci

These are the only tests that will run during the CI builds by default, they should be quick and not fragile.

UserWallet

In /userwallet is a high-level client that bundles a simulated user's private key, an RPC client and manages the nonce and viewing key.

It aims to make testing easier by mimicking the functionality of software and hardware wallets in the real world (a high-level interface for interacting with the crypto chain for a user's account(s))

Documentation

Index

• Constants
• func EnsureTestLogsSetUp(testName string) *os.File
• func NodeHealthCheck(rpcAddress string) error
• func Run(testName string, t *testing.T, env Environment, action Action)
• func TestOnlyRunsInIDE(t *testing.T)
• type Action
• type Environment
• type NetworkConnector
• type NodeOperator

Constants

const IDEFlag = "IDE"

IDEFlag is used as an environnment variable to allow tests to run that are designed not to run in CI todo (@matt) - come up with a better method, perhaps using directory-based ignore/include mechanism for `ci` dir only

const (
	LogFileKey contextKey = 0
)

Functions

func EnsureTestLogsSetUp

func EnsureTestLogsSetUp(testName string) *os.File

EnsureTestLogsSetUp calls Setup if it hasn't already been called (some tests run tests within themselves, we don't want the log folder flipping around for every subtest, so we assume this is called for the top level test that is running and ignore subsequent calls

func NodeHealthCheck

func NodeHealthCheck(rpcAddress string) error

func Run

func Run(testName string, t *testing.T, env Environment, action Action)

Run provides a standardised way to run tests and provides a single place for changing logging/output styles, etc.

The tests in `/tests` should typically only contain a single line, executing this method. The Environment and NetworkTest implementations and how they're configured define the test to be run.

Example usage:

networktest.Run(t, env.DevTestnet(), tests.smokeTest())
networktest.Run(t, env.LocalDevNetwork(WithNumValidators(8)), traffic.RunnerTest(traffic.NativeFundsTransfers(), 30*time.Second)

func TestOnlyRunsInIDE

func TestOnlyRunsInIDE(t *testing.T)

Types

type Action

type Action interface {
	Run(ctx context.Context, network NetworkConnector) (context.Context, error)
	Verify(ctx context.Context, network NetworkConnector) error
}

Action is any step in a test, they will typically be either minimally small steps in the test or they will be containers that coordinate the running of multiple sub-actions (e.g. SeriesAction/ParallelAction)

With these action containers a tree of actions is built to form a test.

A test will call Run on an action (triggering the run of the tree of subactions), and then Verify (orchestrating the verification step on all sub actions)

Conventions:

• if an action name begins with `Verify` then its `Run` method will be a no-op, these should be at the end of a test run (since they only test the post-test state)

type Environment

type Environment interface {
	Prepare() (NetworkConnector, func(), error)
}

Environment abstraction allows the test runner to prepare the network connector with optional config and steps and to handle the clean-up so that different types of NetworkConnector can be configured in the same style (see runner.go) (local network requires setup and teardown for example, whereas a connector to a Testnet is ready to go)

type NetworkConnector

type NetworkConnector interface {
	ChainID() int64
	// AllocateFaucetFunds uses the networks default faucet mechanism for allocating funds to a test account
	AllocateFaucetFunds(ctx context.Context, account common.Address) error
	SequencerRPCAddress() string
	ValidatorRPCAddress(idx int) string
	NumValidators() int
	GetSequencerNode() NodeOperator
	GetValidatorNode(idx int) NodeOperator
	GetL1Client() (ethadapter.EthClient, error)
	GetMCOwnerWallet() (wallet.Wallet, error) // wallet that owns the management contract (network admin)
	GetGatewayURL() (string, error)
	GetGatewayWSURL() (string, error)
}

NetworkConnector represents the network being tested against, e.g. testnet, dev-testnet, dev-sim

It provides network details (standard contract addresses) and easy client setup for sim users

Note: some of these methods may not be available for some networks (e.g. MC Owner wallet for live testnets)

type NodeOperator

type NodeOperator interface {
	Start() error
	Stop() error

	StartEnclave(idx int) error
	StopEnclave(idx int) error
	StartHost() error
	StopHost() error

	HostRPCHTTPAddress() string
	HostRPCWSAddress() string
}

NodeOperator is used by the DevNetwork for orchestrating different scenarios

It attempts to encapsulate the data, monitoring and possible actions that would be available to a real NodeOperator in a live permissionless Obscuro network