containertest

README

Container Tests

The containertest package provides a testing framework for testing the network as a whole. It allows writing unit tests that start up a network of nodes. Some interfaces are provided to interact with the chain.

At a high level, each unit test starts docker containers that are each running a node. The test framework interacts with these nodes by implementing functions that wrap CometBFT and gRPC clients for the node. The framework also runs an HTTP server as a goroutine, and the network is configured to use that server as the source for exchange prices.

Running the tests

The following make targets live in v4 root:

• make test-container-build: Build the docker image needed to run the tests.
• make test-container: Run the tests.
• make test-container-accept: Run the tests and accept any differing expected output.

Writing tests

Tests should use this general structure:

testnet, err := NewTestnet()
require.NoError(t, err)

// Do things prior to network start if needed, such as setting prices.

// Start the network
err = testnet.Start()
require.NoError(t, err)
defer testnet.MustCleanUp()

// Interact with the chain
node := testnet.Nodes["alice"]
Query(node, ...)
BroadcastTx(node, ...)

Use the following methods to interact with the chain. See testnet.go and node.go for details:

• Node.BroadcastTx: Broadcast a tx to a node.
• Node.Query: Send a request a node's query endpoint.
• Testnet.SetPrice: Set the external exchange price of a market. It's recommended to do this before starting the network because the oracle price uses a moving window.

See testnet_test.go for examples.

Documentation

Index

• Constants
• func BroadcastTx[M cosmos.Msg](n *Node, message M, signer string) (err error)
• func Query[Request proto.Message, Response proto.Message, Client interface{}](n *Node, clientConstructor func(gogogrpc.ClientConn) Client, ...) (proto.Message, error)
• type Node
  • func (n *Node) LatestBlockHeight() (int64, error)
  • func (n *Node) Wait(numBlocks int64) error
  • func (n *Node) WaitUntilBlockHeight(height int64) error
• type Testnet
  • func NewTestnet() (testnet *Testnet, err error)
  • func NewTestnetWithPreupgradeGenesis() (testnet *Testnet, err error)
  • func (t *Testnet) CleanUp() error
  • func (t *Testnet) MustCleanUp()
  • func (t *Testnet) Start() (err error)

Constants

const UpgradeToVersion = "v3.0.0"

The version of that we're upgrading to (aka the current commit)

Functions

func BroadcastTx

func BroadcastTx[M cosmos.Msg](n *Node, message M, signer string) (err error)

Broadcast a tx to the node given the message and a signer address.

func Query

func Query[Request proto.Message, Response proto.Message, Client interface{}](
	n *Node,
	clientConstructor func(gogogrpc.ClientConn) Client,
	requestFn func(Client, context.Context, Request, ...grpc.CallOption) (Response, error),
	request Request) (proto.Message, error)

Query the node's grpc endpoint given the client constructor, request method, and request

Types

type Node

type Node struct {
	// contains filtered or unexported fields
}

func (*Node) LatestBlockHeight

func (n *Node) LatestBlockHeight() (int64, error)

func (*Node) Wait

func (n *Node) Wait(numBlocks int64) error

Wait for current block height has advanced by at least `numBlocks`

func (*Node) WaitUntilBlockHeight

func (n *Node) WaitUntilBlockHeight(height int64) error

Wait for the current block height to reach at least `height`

type Testnet

type Testnet struct {
	Nodes map[string]*Node
	// contains filtered or unexported fields
}

func NewTestnet

func NewTestnet() (testnet *Testnet, err error)

NewTestnet returns a new Testnet. If creation fails, an error is returned. In some cases, resources could be initialized but not properly cleaned up. The error will reflect this.

func NewTestnetWithPreupgradeGenesis

func NewTestnetWithPreupgradeGenesis() (testnet *Testnet, err error)

func (*Testnet) CleanUp

func (t *Testnet) CleanUp() error

CleanUp cleans up any resources used by a Testnet. This should always be called to avoid leaking docker resources.

func (*Testnet) MustCleanUp

func (t *Testnet) MustCleanUp()

func (*Testnet) Start

func (t *Testnet) Start() (err error)