Interchaintest: E2E Testing for Blockchain Infrastructure
Every blockchain project goes through the same testing evolution:
- Terminal windows — Developer runs three nodes manually, watches logs, confirms it works
- Bash scripts — Works on the author’s machine, mostly works for teammates, breaks mysteriously
- Docker-compose — Better, but still brittle. Configuration drift. “It worked yesterday”
- The search — Kubernetes? Custom orchestration? Something else?
We went through this cycle at least three times — once for the relayer, once for Horcrux, once for Sommelier. Each time, building Docker-based test harnesses from scratch. Each time, slightly different patterns. Each time, non-trivial effort that couldn’t easily transfer to the next project.
Interchaintest is the answer to “what if we extracted the patterns and stopped rewriting this?”
The Insight#
The problem isn’t spinning up containers. Docker handles that fine. The problem is:
- Chain abstraction — Different chains have different genesis formats, different CLI tools, different configuration
- Relayer abstraction — cosmos/relayer, Hermes, and others have different interfaces
- State management — Tests need to query balances, submit transactions, wait for confirmations
- Cleanup — Tests that leave containers running break the next test run
The insight: define interfaces for Chain and Relayer, let implementations handle the specifics, give test authors a clean API.
// The test author's view
chain := cosmos.NewCosmosChain("gaia", ...)
relayer := rly.NewRelayer(...)
interchain := interchaintest.NewInterchain().
AddChain(chain).
AddRelayer(relayer)
// Spin up everything, run tests, clean up
interchain.Build(ctx, t)
The framework handles container orchestration, port mapping, genesis configuration, key management. Test authors focus on what they’re actually testing.
From ibctest to Interchaintest#
The project started in February 2022 as “ibctest” — focused on IBC testing specifically. By late 2022, the scope had expanded: arbitrary chain interactions, multiple relayer types, use cases beyond IBC.
The rename to “interchaintest” reflected reality. It’s a blockchain interoperability testing framework, not just an IBC testing tool.
What It Enables#
Conformance tests — Standard test suites that any IBC-compatible chain can run to verify compatibility.
CI/CD integration — Teams import interchaintest as a module and run tests in GitHub Actions. No custom Docker orchestration per-repo.
Debugging production issues — When Juno halted in 2022, interchaintest provided the harness to reproduce the issue and verify the fix. That’s the “Trophies” section in the README — real bugs caught because the testing infrastructure existed.
Multi-chain scenarios — Spin up three chains, two relayers, test packet flow across complex topologies. The framework handles the coordination.
The Team#
This project represents a transition point. The relayer and Horcrux were largely hands-on-keyboard work. Interchaintest was about directing a team and distilling patterns.
Andrew Gouin, Dan Kanefsky, Mark Rushakoff, David Nix, and Reece Williams did the heavy lifting — 1,100+ commits building out chain support, relayer integrations, and the abstractions that make it work. The framework now supports 60+ chains.
Current State#
Interchaintest versions track ibc-go and Cosmos SDK versions:
| Branch | IBC-Go | Cosmos SDK |
|---|---|---|
| main | v8 | v0.50 |
| v7 | v7 | v0.47 |
The maintenance policy is n and n-1 branches. Most teams can import from main even if they’re on older ibc-go versions.
The pattern that started with manual terminal windows → bash scripts → Docker testing in the relayer and Horcrux eventually became infrastructure that the whole ecosystem uses. That’s the best outcome for this kind of work.