How to set up interchaintest for testing a Cosmos SDK chain?

Import interchaintest as a Go module and write custom tests using the framework's APIs to spin up testnets and run IBC transactions. The README provides links to tutorials like 'Writing Custom Tests' for detailed steps, including environment variable configurations.

What is the difference between interchaintest and manual Docker testing for IBC?

Interchaintest abstracts away the complexity of manually orchestrating Docker containers and shell scripts, providing a reusable framework for multi-chain testing. Manual testing requires more custom code and is less repeatable, whereas interchaintest offers built-in conformance tests and CI/CD integration.

Can I use interchaintest for Ethereum smart contract testing?

While interchaintest is focused on IBC and Cosmos ecosystems, it can be extended for Ethereum if integrated with IBC-compatible layers, but it's not natively optimized for pure Ethereum testing. The framework assumes IBC protocol usage, so non-IBC Ethereum tests might require significant customization.

How to run the conformance tests in interchaintest?

You can run conformance tests either by importing the library in Go tests or using the binary option, as detailed in the docs. This allows verification of IBC compatibility without writing custom tests, but requires proper Docker setup and chain configurations.

Is interchaintest suitable for CI/CD pipelines in small teams?

Yes, interchaintest is designed for CI/CD integration, with documentation on GitHub Actions setup, but it may be overkill for small teams without IBC needs. The resource demands of Docker-based testnets can strain limited infrastructure, so assess scalability first.

What happens if my chain uses an older IBC version?

Interchaintest maintains multiple branches for compatibility, but the README recommends importing from main unless specific decoding issues arise. You may need to use deprecated branches, which are no longer actively updated, potentially leading to maintenance challenges.

Open-Awesome

interchaintest

Apache-2.0Gov8.8.1

An end-to-end testing framework for blockchain interoperability, focusing on the Inter-Blockchain Communication (IBC) protocol.

Visit Website GitHub

197 stars149 forks0 contributors

What is interchaintest?

Interchaintest is an end-to-end testing framework specifically built for the Interchain ecosystem. It allows developers to test blockchain functionality and interoperability, primarily using the Inter-Blockchain Communication (IBC) protocol. The framework orchestrates Go tests that utilize Docker containers to spin up custom testnets and dev environments for comprehensive testing.

Target Audience

Developers working on blockchain protocols such as Cosmos or Ethereum who need sophisticated testing tools for IBC and Web3 applications. It is particularly useful for teams building or maintaining IBC-compatible chains, relayers, or smart contracts.

Value Proposition

Interchaintest provides a generic, reusable test harness that eliminates the need for repetitive, repo-specific testing solutions. Its ability to quickly spin up multi-chain test environments and its suite of conformance tests make it a powerful tool for ensuring IBC compatibility and catching significant bugs early in development.

Overview

e2e testing framework for the interchain

Use Cases

Best For

Testing IBC protocol implementations and relayer setups
Creating custom testnets for Cosmos SDK-based blockchains
Integrating blockchain testing into CI/CD pipelines
Developing and testing smart contracts in multi-chain environments
Reproducing and diagnosing network halts or interoperability issues
Ensuring conformance with IBC standards for new blockchain projects

Not Ideal For

Projects focused exclusively on single-chain applications without any Inter-Blockchain Communication (IBC) needs
Teams that prefer lightweight, non-Docker-based testing solutions due to resource or infrastructure constraints
Developers working on non-Go-based blockchain platforms outside the Cosmos or Ethereum ecosystems
Organizations seeking out-of-the-box testing suites without the need for custom Go test development or maintenance

Pros & Cons

Pros

Custom Testnet Orchestration

Spins up Docker-based test environments with multiple IBC-compatible blockchains, enabling realistic multi-chain simulations for comprehensive testing, as highlighted in the README's feature list.

IBC Conformance Testing

Includes built-in tests to verify high-level IBC compatibility, reducing effort for blockchain implementers and ensuring standards adherence, as mentioned in the conformance test suite documentation.

CI/CD Integration

Designed for seamless integration into GitHub CI/CD pipelines, facilitating automated testing workflows, with specific guides provided in the docs for CI/CD setup.

Diagnostic Test Generation

Creates repeatable, diagnostic tests for various IBC aspects, aiding in bug reproduction and fixes, as evidenced by the trophies section showcasing real-world bug resolutions.

Cons

Ecosystem Lock-in

Primarily targets IBC and Cosmos SDK-based chains, making it less suitable for testing other blockchain protocols or non-Interchain ecosystems, limiting its general applicability.

Complex Setup

Requires Docker and Go expertise, and setting up custom testnets can be resource-intensive and time-consuming, with multiple documentation pieces needed for full configuration.

Version Fragmentation

Maintains multiple branches for different IBC and Cosmos SDK versions, as shown in the maintained and deprecated branches table, which can lead to compatibility issues and maintenance overhead for users.

Frequently Asked Questions

Related Projects

quint

An executable specification language with delightful tooling based on the temporal logic of actions (TLA)

Stars1,662

Forks145

Last commit19 days ago

Interchain Standards

Interchain Standards (ICS) for the Cosmos network & interchain ecosystem.

Stars1,019

Forks455

Last commit16 hours ago

IBC Go

Inter-Blockchain Communication Protocol (IBC) implementation in Golang.

APALACHE: symbolic model checker for TLA+ and Quint

Stars596

Forks53