Crate ibc_test_framework

IBC Relayer Integration Test Framework

Overview

The ibc-test-framework crate provides the infrastructure and framework for writing end-to-end (E2E) tests that include the spawning of the relayer together with Cosmos full nodes running as child processes inside the tests.

Installation

Other than Rust, the test suite assumes the gaiad binary is present in $PATH. You can install Gaia by either building from source, or load it using Cosmos.nix:

nix shell github:informalsystems/cosmos.nix#gaia11

Alternatively, you can use $CHAIN_COMMAND_PATH to override with a different executable that is compatible with gaiad.

Examples

Example tests written using ibc-test-framework can be found in the ibc-rs project repository

Diagrams

Some diagrams have been prepared to ease the understanding of the test framework:

• Tagged Identifiers and Data Structures
• Test Data Structures
• Test Framework Traits

Overview

This IBC test framework gives developers working on relayer software in Rust a robust yet flexible suite of functionality to test the correctness of their relayer implementations, as well as verify the expected state of chains in response to relayed messages and packets.

Running Tests

We can run tests via the command line as follows:

RUST_LOG=info RUST_BACKTRACE=1 \
    cargo test -p ibc-integration-test --features example -- --test-threads=1 \
    example_test

The environment variable RUST_LOG controls log filtering for Hermes and, besides the global log level, can be used to pass more elaborate directives for the tracing framework. The RUST_BACKTRACE variable displays a backtrace when errors occur in a test. The test flag --test-threads=1 is set so that tests are run serially (this makes it easier to follow what is going on via the log output). Take a look at the TestConfig type for more information about configuring how tests can be run.

For this example, we disable the test from running by default, since it calls the suspend function and will thus never pass. We explicitly pass --features example so that the example feature is activated such that this test will run. Finally, we specify the name of the test so that only our example test is run.

After starting the test run, we may see logs such as the following:

$ cargo test -p ibc-integration-test --features example -- --nocapture --test-threads=1 example_test
...
INFO created new chain/client/connection/channel from ibc-alpha-c4aed8f9/07-tendermint-4/connection-6/channel-1 to ibc-beta-fcb867bb/07-tendermint-6/connection-1/channel-6
INFO written channel environment to /path/to/ibc-rs/tools/integration-test/data/test-1094235493/binary-channels.env
WARN suspending the test indefinitely. you can still interact with any spawned chains and relayers
...

The INFO lines are notifying us of the path environment variables exported by the test. The WARN line states that the test has been suspended indefinitely, as we knew it would. Note that the chains are created with random IDs and are listening on random ports.

Using the logs, we can for example use gaiad to query for the balance of the accounts created by the test by running:

$ source /path/to/ibc-rs/tools/integration-test/data/test-1094235493/binary-channels.env
$ gaiad --home "$NODE_A_HOME" --node $NODE_A_RPC_ADDR query bank balances $NODE_A_WALLETS_USER1_ADDRESS
balances:
- amount: "6902395390297"
denom: coin95143d31
- amount: "6902395390297"
denom: stake
pagination:
next_key: null
total: "0"

The test data and configuration files are stored at the absolute path shown in the log, which looks something like /path/to/ibc-rs/tools/integration-test/data/test-1094235493. The sub-directory test-1094235493 is randomly generated at the beginning of a test case such that all data related to that test lives in the same directory.

Modules

• bootstrap
  Helper functions for setting up test cases in an imperative way.
• chain
  Constructs for spawning and managing full nodes, e.g. the Gaia chains.
• docs
  Documentation-only module containing long-form docs and walkthroughs.
• error
  Error type used for the tests.
• framework
  Framework code for making it easier to write test cases.
• ibc
  Code that may belong to the ibc module, but are currently in this crate for easier review or maintenance.
• prelude
  Re-export of common constructs that are used by test cases.
• relayer
  Code that may belong to the ibc_relayer module, but are currently in this crate for easier review or maintenance.
• types
  This module contains definitions of core data structures that are used in the test suite.
• util
  Utility and helper functions used in the tests.