interchaintest

package module
v10.0.1 Latest Latest
Warning

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

 Go to latest Published: Oct 28, 2025 License: Apache-2.0 Imports: 38 Imported by: 1

README ¶

interchaintest

Formerly known as ibctest, interchaintest was built and initially maintained by Strangelove Ventures.

This fork is maintained by the Interchain Operations team at Hypha Worker Co-operative.

🌌 Why use interchaintest?

In order to ship production-grade software for the Interchain, we needed sophisticated developer tooling...but IBC and Web3 have a lot of moving parts, which can lead to a steep learning curve and all sorts of pain. Recognize any of these?

  • repeatedly building repo-specific, Docker- and shell-based testing solutions,
  • duplication of effort, and
  • difficulty in repurposing existing testing harnesses for new problem domains.

We built interchaintest to extract patterns and create a generic test harness: a use-case-agnostic framework for generating repeatable, diagnostic tests for every aspect of IBC.

Read more at the Announcing interchaintest blog post.

🌌 Who benefits from interchaintest?

interchaintest is for developers who expect top-shelf testing tools when working on blockchain protocols such as Cosmos or Ethereum.

🌌 What does interchaintest do?

interchaintest is a framework for testing blockchain functionality and interoperability between chains, primarily with the Inter-Blockchain Communication (IBC) protocol.

Want to quickly spin up custom testnets and dev environments to test IBC, Relayer setup, chain infrastructure, smart contracts, etc.? interchaintest orchestrates Go tests that utilize Docker containers for multiple IBC-compatible blockchains.

🌌 How do I use it?

As a Module

Most people choose to import interchaintest as a module.

As a Binary

There's also an option to build and run interchaintest as a binary (which might be preferable, e.g., with custom chain sets). You can still run Conformance Tests.

References

🌌 Extras

Maintained Branches

Branch Name IBC-Go Cosmos-SDK
main v10 v0.53

We strive to keep interchaintest aligned to stable versions from the IBC-Go and Cosmos SDK teams.

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 ¶

View Source 
var GitSha = "unknown"

GitSha is the git commit that produced the executable. Set via the project Makefile `make interchaintest`.

Functions ¶

func CreateChainWithConfig ¶ 

func CreateChainWithConfig(t *testing.T, numVals, numFull int, name, version string, config ibc.ChainConfig) []ibc.Chain

CreateChainWithConfig builds a single chain from the given ibc config.

func CreateChainsWithChainSpecs ¶ 

func CreateChainsWithChainSpecs(t *testing.T, chainSpecs []*ChainSpec) []ibc.Chain

CreateChainsWithChainSpecs builds multiple chains from the given chain specs.

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 ICTEST_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 ICTEST_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 RegisterInterfaces ¶ 

func RegisterInterfaces(codecIR ...codecRegistry) *testutil.TestEncodingConfig

RegisterInterfaces registers the interfaces for the input codec register functions.

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

	// NoHostMount is a pointers in ChainSpec
	// so zero-overrides can be detected from omitted overrides.
	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 BuildInitialChain ¶ 

func BuildInitialChain(t *testing.T, chains []ibc.Chain, enableBlockDB bool) (context.Context, *Interchain, *client.Client, string)

func BuildInitialChainWithRelayer ¶ 

func BuildInitialChainWithRelayer(
	t *testing.T,
	chains []ibc.Chain,
	enableBlockDB bool,
	rly ibc.RelayerImplementation,
	relayerFlags []string,
	links []InterchainLink,
	skipPathCreations bool,
) (context.Context, *Interchain, ibc.Relayer, *testreporter.Reporter, *testreporter.RelayerExecReporter, *client.Client, string)

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 (ic *Interchain) AddProviderConsumerLink(link ProviderConsumerLink) *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 ProviderConsumerLink struct {
	Provider, Consumer 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
}

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.RelayerOpt) 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
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.
tui
tui/presenter
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.
cosmos/08-wasm-types
cosmos/wasm
ethereum
ethereum/foundry
ethereum/geth
internal/tendermint
Package tendermint provides interfaces for interacting with tendermint nodes.
 Package tendermint provides interfaces for interacting with tendermint nodes.
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.
contract
cosmwasm
Package dockerutil contains helpers for interacting with Docker containers.
 Package dockerutil contains helpers for interacting with Docker containers.
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.
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.
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.