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 ¶
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
)
Variables ¶
This section is empty.
Functions ¶
func EnsureTestLogsSetUp ¶
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 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 ¶
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)
}
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
Source Files
Directories