Documentation

Overview

    Package network implements and exposes a fully operational in-process Tendermint test network that consists of at least one or potentially many validators. This test network can be used primarily for integration tests or unit test suites.

    The test network utilizes SimApp as the ABCI application and uses all the modules defined in the Cosmos SDK. An in-process test network can be configured with any number of validators as well as account funds and even custom genesis state.

    When creating a test network, a series of Validator objects are returned. Each Validator object has useful information such as their address and public key. A Validator will also provide its RPC, P2P, and API addresses that can be useful for integration testing. In addition, a Tendermint local RPC client is also provided which can be handy for making direct RPC calls to Tendermint.

    Note, due to limitations in concurrency and the design of the RPC layer in Tendermint, only the first Validator object will have an RPC and API client exposed. Due to this exact same limitation, only a single test network can exist at a time. A caller must be certain it calls Cleanup after it no longer needs the network.

    A typical testing flow might look like the following:

    type IntegrationTestSuite struct {
    	suite.Suite
    
    	cfg     testutil.Config
    	network *testutil.Network
    }
    
    func (s *IntegrationTestSuite) SetupSuite() {
    	s.T().Log("setting up integration test suite")
    
    	cfg := testutil.DefaultConfig()
    	cfg.NumValidators = 1
    
    	s.cfg = cfg
    	s.network = testutil.New(s.T(), cfg)
    
    	_, err := s.network.WaitForHeight(1)
    	s.Require().NoError(err)
    }
    
    func (s *IntegrationTestSuite) TearDownSuite() {
    	s.T().Log("tearing down integration test suite")
    
    	// This is important and must be called to ensure other tests can create
    	// a network!
    	s.network.Cleanup()
    }
    
    func (s *IntegrationTestSuite) TestQueryBalancesRequestHandlerFn() {
    	val := s.network.Validators[0]
    	baseURL := val.APIAddress
    
    	// Use baseURL to make API HTTP requests or use val.RPCClient to make direct
    	// Tendermint RPC calls.
    	// ...
    }
    
    func TestIntegrationTestSuite(t *testing.T) {
    	suite.Run(t, new(IntegrationTestSuite))
    }
    

    Index

    Constants

    This section is empty.

    Variables

    This section is empty.

    Functions

    func NewSimApp

    func NewSimApp(val Validator) servertypes.Application

    Types

    type AppConstructor

    type AppConstructor = func(val Validator) servertypes.Application

      AppConstructor defines a function which accepts a network configuration and creates an ABCI Application to provide to Tendermint.

      type Config

      type Config struct {
      	Codec             codec.Marshaler
      	LegacyAmino       *codec.LegacyAmino // TODO: Remove!
      	InterfaceRegistry codectypes.InterfaceRegistry
      
      	TxConfig         client.TxConfig
      	AccountRetriever client.AccountRetriever
      	AppConstructor   AppConstructor             // the ABCI application constructor
      	GenesisState     map[string]json.RawMessage // custom gensis state to provide
      	TimeoutCommit    time.Duration              // the consensus commitment timeout
      	ChainID          string                     // the network chain-id
      	NumValidators    int                        // the total number of validators to create and bond
      	BondDenom        string                     // the staking bond denomination
      	MinGasPrices     string                     // the minimum gas prices each validator will accept
      	AccountTokens    sdk.Int                    // the amount of unique validator tokens (e.g. 1000node0)
      	StakingTokens    sdk.Int                    // the amount of tokens each validator has available to stake
      	BondedTokens     sdk.Int                    // the amount of tokens each validator stakes
      	PruningStrategy  string                     // the pruning strategy each validator will have
      	EnableLogging    bool                       // enable Tendermint logging to STDOUT
      	CleanupDir       bool                       // remove base temporary directory during cleanup
      	SigningAlgo      string                     // signing algorithm for keys
      	KeyringOptions   []keyring.Option
      }

        Config defines the necessary configuration used to bootstrap and start an in-process local testing network.

        func DefaultConfig

        func DefaultConfig() Config

          DefaultConfig returns a sane default configuration suitable for nearly all testing requirements.

          type Network

          type Network struct {
          	T          *testing.T
          	BaseDir    string
          	Validators []*Validator
          
          	Config Config
          }

            Network defines a local in-process testing network using SimApp. It can be configured to start any number of validators, each with its own RPC and API clients. Typically, this test network would be used in client and integration testing where user input is expected.

            Note, due to Tendermint constraints in regards to RPC functionality, there may only be one test network running at a time. Thus, any caller must be sure to Cleanup after testing is finished in order to allow other tests to create networks. In addition, only the first validator will have a valid RPC and API server/client.

            func New

            func New(t *testing.T, cfg Config) *Network

            func (*Network) Cleanup

            func (n *Network) Cleanup()

              Cleanup removes the root testing (temporary) directory and stops both the Tendermint and API services. It allows other callers to create and start test networks. This method must be called when a test is finished, typically in a defer.

              func (*Network) LatestHeight

              func (n *Network) LatestHeight() (int64, error)

                LatestHeight returns the latest height of the network or an error if the query fails or no validators exist.

                func (*Network) WaitForHeight

                func (n *Network) WaitForHeight(h int64) (int64, error)

                  WaitForHeight performs a blocking check where it waits for a block to be committed after a given block. If that height is not reached within a timeout, an error is returned. Regardless, the latest height queried is returned.

                  func (*Network) WaitForHeightWithTimeout

                  func (n *Network) WaitForHeightWithTimeout(h int64, t time.Duration) (int64, error)

                    WaitForHeightWithTimeout is the same as WaitForHeight except the caller can provide a custom timeout.

                    func (*Network) WaitForNextBlock

                    func (n *Network) WaitForNextBlock() error

                      WaitForNextBlock waits for the next block to be committed, returning an error upon failure.

                      type Validator

                      type Validator struct {
                      	AppConfig  *srvconfig.Config
                      	ClientCtx  client.Context
                      	Ctx        *server.Context
                      	Dir        string
                      	NodeID     string
                      	PubKey     cryptotypes.PubKey
                      	Moniker    string
                      	APIAddress string
                      	RPCAddress string
                      	P2PAddress string
                      	Address    sdk.AccAddress
                      	ValAddress sdk.ValAddress
                      	RPCClient  tmclient.Client
                      	// contains filtered or unexported fields
                      }

                        Validator defines an in-process Tendermint validator node. Through this object, a client can make RPC and API calls and interact with any client command or handler.