conformance

Documentation

Overview

Package conformance exposes a Test function that can be imported into other packages' tests.

The exported Test function is intended to be a stable API that calls other Test* functions, which are not guaranteed to remain a stable API.

External packages that intend to run IBC tests against their relayer implementation should define their own implementation of ibc.RelayerFactory, and in most cases should use an instance of ibc.BuiltinChainFactory.

package myrelayer_test

import (
  "testing"

  "github.com/strangelove-ventures/ibctest/conformance"
  "github.com/strangelove-ventures/ibctest/ibc"
)

func TestMyRelayer(t *testing.T) {
  conformance.Test(t, ibc.NewBuiltinChainFactory([]ibc.BuiltinChainFactoryEntry{
    {Name: "foo_bar" /* ... */},
  }, MyRelayerFactory(), getTestReporter())
}

Although the conformance package is made available as a convenience for other projects, the ibctest project should be considered the canonical definition of tests and configuration.

Index

• func Test(t *testing.T, ctx context.Context, cfs []ibctest.ChainFactory, ...)
• func TestChainPair(t *testing.T, ctx context.Context, client *client.Client, network string, ...)
• func TestRelayerFlushing(t *testing.T, ctx context.Context, cf ibctest.ChainFactory, ...)
• func TestRelayerSetup(t *testing.T, ctx context.Context, cf ibctest.ChainFactory, ...)
• type RelayerTestCase
• type RelayerTestCaseConfig
• type TxCache

Functions

func Test

func Test(t *testing.T, ctx context.Context, cfs []ibctest.ChainFactory, rfs []ibctest.RelayerFactory, rep *testreporter.Reporter)

Test is the stable API exposed by the conformance package. This is intended to be used by Go unit tests.

This function accepts the full set of chain factories and relayer factories to use, so that it can properly group subtests in a single invocation. If the subtest configuration does not meet your needs, you can directly call one of the other exported Test functions, such as TestChainPair.

func TestChainPair

func TestChainPair(
	t *testing.T,
	ctx context.Context,
	client *client.Client,
	network string,
	srcChain, dstChain ibc.Chain,
	rf ibctest.RelayerFactory,
	rep *testreporter.Reporter,
	relayerImpl ibc.Relayer,
	pathNames ...string,
)

TestChainPair runs the conformance tests for two chains and one relayer. This test asserts bidirectional behavior between both chains.

Given 2 chains, Chain A and Chain B, this test asserts: 1. Successful IBC transfer from A -> B and B -> A. 2. Proper handling of no timeout from A -> B and B -> A. 3. Proper handling of height timeout from A -> B and B -> A. 4. Proper handling of timestamp timeout from A -> B and B -> A. If a non-nil relayerImpl is passed, it is assumed that the chains are already started.

func TestRelayerFlushing

func TestRelayerFlushing(t *testing.T, ctx context.Context, cf ibctest.ChainFactory, rf ibctest.RelayerFactory, rep *testreporter.Reporter)

func TestRelayerSetup

func TestRelayerSetup(t *testing.T, ctx context.Context, cf ibctest.ChainFactory, rf ibctest.RelayerFactory, rep *testreporter.Reporter)

TestRelayerSetup contains a series of subtests that configure a relayer step-by-step.

Types

type RelayerTestCase

type RelayerTestCase struct {
	Config RelayerTestCaseConfig
	// user on source chain
	Users []*ibc.Wallet
	// temp storage in between test phases
	TxCache TxCache
}

type RelayerTestCaseConfig

type RelayerTestCaseConfig struct {
	Name string
	// which relayer capabilities are required to run this test
	RequiredRelayerCapabilities []relayer.Capability
	// function to run after the chains are started but before the relayer is started
	// e.g. send a transfer and wait for it to timeout so that the relayer will handle it once it is timed out
	PreRelayerStart func(context.Context, *testing.T, *RelayerTestCase, ibc.Chain, ibc.Chain, []ibc.ChannelOutput)
	// test after chains and relayers are started
	Test func(context.Context, *testing.T, *RelayerTestCase, *testreporter.Reporter, ibc.Chain, ibc.Chain, []ibc.ChannelOutput)

	// Test-specific labels.
	TestLabels []label.Test
}

type TxCache

type TxCache struct {
	Src []ibc.Tx
	Dst []ibc.Tx
}