interchaintest

package module
v8.2.0 Latest Latest
Warning

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

Go to latest
Published: Mar 8, 2024 License: Apache-2.0 Imports: 39 Imported by: 10

README ยถ

interchaintest

Formerly known as ibctest.

Go Reference Go Report Card Conforms to README.lint

๐ŸŒŒ 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 v8 v0.50
v7 v7 v0.47
Deprecated Branches

These are branches that we no longer actively update or maintain but may be of use if a chain is running older versions of the Cosmos SDK or IBC Go. Please see the Backport Policy below.

Branch Name IBC-Go Cosmos-sdk Deprecated Date
v6 v6 v0.46 Sept 5 2023
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
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.

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 ErrPclientdInitialization = fmt.Errorf("failed to initialize new pclientd instance")

ErrPclientdInitialization is returned if the CreateClientNode call fails while initializing a new instance of pclientd for a newly created user account on Penumbra.

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 CreatePenumbraClient ยถ

func CreatePenumbraClient(ctx context.Context, c ibc.Chain, keyName string) error

CreatePenumbraClient should be called after a new test user account has been created on Penumbra. This function initializes a new instance of pclientd which allows private user state to be tracked and managed via a client daemon i.e. it is used to sign and broadcast txs as well as querying private user state on chain.

Note: this function cannot be called until the chain is started as pclientd attempts to dial the running pd instance, so that it can sync with the current chain tip. It also should be noted that this function should ONLY be called after a new test user has been generated via one of the GetAndFundTestUser helper functions or a call to the chain.CreateKey or chain.RecoverKey methods.

func DefaultBlockDatabaseFilepath ยถ

func DefaultBlockDatabaseFilepath() string

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

func DockerSetup ยถ

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 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 (*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 ยถ

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.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
}

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.
cmd
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
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.
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.
Package relayer contains general functionality relevant to individual relayer implementations.
Package relayer contains general functionality relevant to individual relayer implementations.
hyperspace
Package hyperspace provides an interface to the hyperspace relayer running in a Docker container.
Package hyperspace provides an interface to the hyperspace relayer running in a Docker container.
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