interchaintest

package module
v6.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 6, 2023 License: Apache-2.0 Imports: 34 Imported by: 2

README

interchaintest

Formerly known as ibctest.

Go Reference Go Report Card

interchaintest orchestrates Go tests that utilize Docker containers for multiple IBC-compatible blockchains.

It allows users to quickly spin up custom testnets and dev environments to test IBC, chain infrastructures, smart contracts, etc.

-- Features --

  • Built-in suite of conformance tests to test high-level IBC compatibility between chain sets
  • Easily construct customized tests in highly configurable environments
  • Deployable as CI tests in production workflows

Maintained Branches

Backport Policy:

Strangelove maintains n and n - 1 branches of interchaintest, n being current main.

We strive to keep interchaintest inline with the latest from the ibc-go and cosmos sdk teams. Once an alpha versions of the next major ibc-go version is released, we will discontinue n - 1 and branch off a new n.

Recommendation: Even if your chain uses an older version of ibc-go, try importing from main. This should work unless you are decoding transactions that require a specific ibc-go version.

If there is a feature you would like backported to an older branch, make an issue! We are happy to work with you.

Branch Name IBC-Go Cosmos-sdk Maintained
main v7 v0.47 ✅
v6 v6 v0.46 ✅
v5 v5 v0.46 ❌
(Aug 11 2023)
v4 v4 v0.45 ❌
(Aug 11 2023)
v4-ics v4 v0.45.x-ics ❌
(Aug 11 2023)
v3 v3 v0.45 ❌
(June 25 2023)
v3-ics v3 v0.45.11-ics ❌
(April 24 2023)

Table Of Contents


Building Binary

While it is not necessary to build the binary, sometimes it can be more convenient, specifically when running conformance test with custom chain sets.

Building binary:

git clone https://github.com/strangelove-ventures/interchaintest.git
cd interchaintest
make interchaintest

This places the binary in interchaintest/.bin/interchaintest

Note that this is not in your Go path.

Contributing

Contributing is encouraged.

Please read the logging style guide.

Trophies

Significant bugs that were more easily fixed with interchaintest:

Documentation

Index

Constants

View Source 
const (
	FaucetAccountKeyName = "faucet"
)

Variables

This section is empty.

Functions

func CreateLogFile 

func CreateLogFile(name string) (*os.File, error)

CreateLogFile creates a file with name in dir $HOME/.interchaintest/logs/

func DefaultBlockDatabaseFilepath 

func DefaultBlockDatabaseFilepath() string

DefaultBlockDatabaseFilepath is the default filepath to the sqlite database for tracking blocks and transactions.

func DockerSetup 

func DockerSetup(t dockerutil.DockerSetupTestingT) (*client.Client, string)

DockerSetup returns a new Docker Client and the ID of a configured network, associated with t.

If any part of the setup fails, t.Fatal is called.

func GetAndFundTestUserWithMnemonic 

func GetAndFundTestUserWithMnemonic(
	ctx context.Context,
	keyNamePrefix, mnemonic string,
	amount math.Int,
	chain ibc.Chain,
) (ibc.Wallet, error)

GetAndFundTestUserWithMnemonic restores a user using the given mnemonic and funds it with the native chain denom. The caller should wait for some blocks to complete before the funds will be accessible.

func GetAndFundTestUsers 

func GetAndFundTestUsers(
	t *testing.T,
	ctx context.Context,
	keyNamePrefix string,
	amount math.Int,
	chains ...ibc.Chain,
) []ibc.Wallet

GetAndFundTestUsers generates and funds chain users with the native chain denom. The caller should wait for some blocks to complete before the funds will be accessible.

func KeepDockerVolumesOnFailure 

func KeepDockerVolumesOnFailure(b bool)

KeepDockerVolumesOnFailure sets whether volumes associated with a particular test are retained or deleted following a test failure.

The value is false by default, but can be initialized to true by setting the environment variable IBCTEST_SKIP_FAILURE_CLEANUP to a non-empty value. Alternatively, importers of the interchaintest package may call KeepDockerVolumesOnFailure(true).

func KeepTempDirOnFailure 

func KeepTempDirOnFailure(b bool)

KeepTempDirOnFailure sets whether a directory created by TempDir is retained or deleted following a test failure.

The value is false by default, but can be initialized to true by setting the environment variable IBCTEST_SKIP_FAILURE_CLEANUP to a non-empty value. Alternatively, importers of the interchaintest package may set the variable to true.

func KeepingTempDirOnFailure 

func KeepingTempDirOnFailure() bool

KeepingTempDirOnFailure reports the current value of KeepTempDirOnFailure. This function is only intended for tests.

func StartChainPair 

func StartChainPair(
	t *testing.T,
	ctx context.Context,
	rep *testreporter.Reporter,
	cli *client.Client,
	networkID string,
	srcChain, dstChain ibc.Chain,
	f RelayerFactory,
	preRelayerStartFuncs []func([]ibc.ChannelOutput),
) (ibc.Relayer, error)

startup both chains creates wallets in the relayer for src and dst chain funds relayer src and dst wallets on respective chain in genesis creates a faucet account on the both chains (separate fullnode) funds faucet accounts in genesis

func StopStartRelayerWithPreStartFuncs 

func StopStartRelayerWithPreStartFuncs(
	t *testing.T,
	ctx context.Context,
	srcChainID string,
	relayerImpl ibc.Relayer,
	eRep *testreporter.RelayerExecReporter,
	preRelayerStartFuncs []func([]ibc.ChannelOutput),
	pathNames ...string,
) ([]ibc.ChannelOutput, error)

StopStartRelayerWithPreStartFuncs will stop the relayer if it is currently running, then execute the preRelayerStartFuncs and wait for all to complete before starting the relayer.

func TempDir 

func TempDir(t TempDirTestingT) string

TempDir resembles (*testing.T).TempDir, except that it conditionally keeps the temporary directory on disk, and it uses a new temporary directory on each invocation instead of adjacent directories with an incrementing numeric suffix.

If the test passes, or if KeepTempDirOnFailure is set to false, the directory will be removed.

Types

type BuiltinChainFactory 

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

BuiltinChainFactory implements ChainFactory to return a fixed set of chains. Use NewBuiltinChainFactory to create an instance.

func NewBuiltinChainFactory 

func NewBuiltinChainFactory(log *zap.Logger, specs []*ChainSpec) *BuiltinChainFactory

NewBuiltinChainFactory returns a BuiltinChainFactory that returns chains defined by entries.

func (*BuiltinChainFactory) Chains 

func (f *BuiltinChainFactory) Chains(testName string) ([]ibc.Chain, error)

func (*BuiltinChainFactory) Count 

func (f *BuiltinChainFactory) Count() int

func (*BuiltinChainFactory) Name 

func (f *BuiltinChainFactory) Name() string

type ChainFactory 

type ChainFactory interface {
	// Count reports how many chains this factory will produce from its Chains method.
	Count() int

	// Chains returns a set of chains.
	Chains(testName string) ([]ibc.Chain, error)

	// Name returns a descriptive name of the factory,
	// indicating all of its chains.
	// Depending on how the factory was configured,
	// this may report more than two chains.
	Name() string
}

ChainFactory describes how to get chains for tests. This type currently supports a Pair method, but it may be expanded to a Triplet method in the future.

type ChainSpec 

type ChainSpec struct {
	// Name is the name of the built-in config to use as a basis for this chain spec.
	// Required unless every other field is set.
	Name string

	// ChainName sets the Name of the embedded ibc.ChainConfig, i.e. the name of the chain.
	ChainName string

	// Version of the docker image to use.
	// Must be set.
	Version string

	// GasAdjustment and NoHostMount are pointers in ChainSpec
	// so zero-overrides can be detected from omitted overrides.
	GasAdjustment *float64
	NoHostMount   *bool

	// Embedded ChainConfig to allow for simple JSON definition of a ChainSpec.
	ibc.ChainConfig

	// How many validators and how many full nodes to use
	// when instantiating the chain.
	// If unspecified, NumValidators defaults to 2 and NumFullNodes defaults to 1.
	NumValidators, NumFullNodes *int
	// contains filtered or unexported fields
}

ChainSpec is a wrapper around an ibc.ChainConfig that allows callers to easily reference one of the built-in chain configs and optionally provide overrides for some settings.

func (*ChainSpec) Config 

func (s *ChainSpec) Config(log *zap.Logger) (*ibc.ChainConfig, error)

Config returns the underlying ChainConfig, with any overrides applied.

type Interchain 

type Interchain struct {

	// Map of chain to additional genesis wallets to include at chain start.
	AdditionalGenesisWallets map[ibc.Chain][]ibc.WalletAmount
	// contains filtered or unexported fields
}

Interchain represents a full IBC network, encompassing a collection of one or more chains, one or more relayer instances, and initial account configuration.

func NewInterchain 

func NewInterchain() *Interchain

NewInterchain returns a new Interchain.

Typical usage involves multiple calls to AddChain, one or more calls to AddRelayer, one or more calls to AddLink, and then finally a single call to Build.

func (*Interchain) AddChain 

func (ic *Interchain) AddChain(chain ibc.Chain, additionalGenesisWallets ...ibc.WalletAmount) *Interchain

AddChain adds the given chain to the Interchain, using the chain ID reported by the chain's config. If the given chain already exists, or if another chain with the same configured chain ID exists, AddChain panics. 

func (ic *Interchain) AddLink(link InterchainLink) *Interchain

AddLink adds the given link to the Interchain. If any validation fails, AddLink panics.

func (*Interchain) AddRelayer 

func (ic *Interchain) AddRelayer(relayer ibc.Relayer, name string) *Interchain

AddRelayer adds the given relayer with the given name to the Interchain.

func (*Interchain) Build 

func (ic *Interchain) Build(ctx context.Context, rep *testreporter.RelayerExecReporter, opts InterchainBuildOptions) error

Build starts all the chains and configures the relayers associated with the Interchain. It is the caller's responsibility to directly call StartRelayer on the relayer implementations.

Calling Build more than once will cause a panic.

func (*Interchain) Close 

func (ic *Interchain) Close() error

Close cleans up any resources created during Build, and returns any relevant errors.

func (*Interchain) WithLog 

func (ic *Interchain) WithLog(log *zap.Logger) *Interchain

WithLog sets the logger on the interchain object. Usually the default nop logger is fine, but sometimes it can be helpful to see more verbose logs, typically by passing zaptest.NewLogger(t).

type InterchainBuildOptions 

type InterchainBuildOptions struct {
	TestName string

	Client    *client.Client
	NetworkID string

	// If set, ic.Build does not create paths or links in the relayer,
	// but it does still configure keys and wallets for declared relayer-chain links.
	// This is useful for tests that need lower-level access to configuring relayers.
	SkipPathCreation bool

	// Optional. Git sha for test invocation. Once Go 1.18 supported,
	// may be deprecated in favor of runtime/debug.ReadBuildInfo.
	GitSha string

	// If set, saves block history to a sqlite3 database to aid debugging.
	BlockDatabaseFile string
}

InterchainBuildOptions describes configuration for (*Interchain).Build. 

type InterchainLink struct {
	// Chains involved.
	Chain1, Chain2 ibc.Chain

	// Relayer to use for link.
	Relayer ibc.Relayer

	// Name of path to create.
	Path string

	// If set, these options will be used when creating the client in the path link step.
	// If a zero value initialization is used, e.g. CreateClientOptions{},
	// then the default values will be used via ibc.DefaultClientOpts.
	CreateClientOpts ibc.CreateClientOptions

	// If set, these options will be used when creating the channel in the path link step.
	// If a zero value initialization is used, e.g. CreateChannelOptions{},
	// then the default values will be used via ibc.DefaultChannelOpts.
	CreateChannelOpts ibc.CreateChannelOptions
}

InterchainLink describes a link between two chains, by specifying the chain names, the relayer name, and the name of the path to create.

type RelayerFactory 

type RelayerFactory interface {
	// Build returns a Relayer associated with the given arguments.
	Build(
		t TestName,
		cli *client.Client,
		networkID string,
	) ibc.Relayer

	// Name returns a descriptive name of the factory,
	// indicating details of the Relayer that will be built.
	Name() string

	// Capabilities is an indication of the features this relayer supports.
	// Tests for any unsupported features will be skipped rather than failed.
	Capabilities() map[relayer.Capability]bool
}

RelayerFactory describes how to start a Relayer.

func NewBuiltinRelayerFactory 

func NewBuiltinRelayerFactory(impl ibc.RelayerImplementation, logger *zap.Logger, options ...relayer.RelayerOption) RelayerFactory

type TempDirTestingT 

type TempDirTestingT interface {
	Helper()

	Name() string

	Failed() bool
	Cleanup(func())

	Logf(format string, args ...any)
	Errorf(format string, args ...any)
}

TempDirTestingT is a subset of testing.TB to implement TempDir.

type TestName 

type TestName interface {
	Name() string
}

Source Files

View all Source files

Directories

Path Synopsis
chain
cosmos
Package cosmos provides an implementation of ibc.Chain backed by Cosmos-based blockchains.
 Package cosmos provides an implementation of ibc.Chain backed by Cosmos-based blockchains.
internal/tendermint
Package tendermint provides interfaces for interacting with tendermint nodes.
 Package tendermint provides interfaces for interacting with tendermint nodes.
penumbra
Package penumbra provides an implementation of ibc.Chain for the Penumbra blockchain.
 Package penumbra provides an implementation of ibc.Chain for the Penumbra blockchain.
polkadot
cmd
interchaintest
Package conformance exposes a Test function that can be imported into other packages' tests.
 Package conformance exposes a Test function that can be imported into other packages' tests.
Package ibc provides chain and relayer agnostic types and interfaces for the IBC spec.
 Package ibc provides chain and relayer agnostic types and interfaces for the IBC spec.
internal
blockdb
Package blockdb saves chain and block data for inspection later to aid in debugging interchaintest failures.
 Package blockdb saves chain and block data for inspection later to aid in debugging interchaintest failures.
blockdb/tui
blockdb/tui/presenter
dockerutil
Package dockerutil contains helpers for interacting with Docker containers.
 Package dockerutil contains helpers for interacting with Docker containers.
mocktesting
Package mocktesting contains a mock instance of *testing.T which is useful for testing interchaintest's interactions with Go tests.
 Package mocktesting contains a mock instance of *testing.T which is useful for testing interchaintest's interactions with Go tests.
version
Package relayer contains general functionality relevant to individual relayer implementations.
 Package relayer contains general functionality relevant to individual relayer implementations.
hermes
rly
Package rly provides an interface to the cosmos relayer running in a Docker container.
 Package rly provides an interface to the cosmos relayer running in a Docker container.
Package testreporter contains a Reporter for collecting detailed test reports.
 Package testreporter contains a Reporter for collecting detailed test reports.
Package testutil includes convenience functions and types to help with testing
 Package testutil includes convenience functions and types to help with testing

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.