created_at2023-07-21 11:45:59.453119
updated_at2024-06-25 16:45:23.311105
descriptionA crate of utils for integration testing CosmWasm smart contracts
rust-devs (github:apollodao:rust-devs)



CosmWasm Integration Testing

A crate of utils for integration testing CosmWasm smart contracts.

Note: This crate is still in early development and the API is subject to change.


The main idea of this crate is to provide a set of "Test Runners" that you can run the same set of tests against. This is accomplished by providing different structs that all implement the CwItRunner trait. This trait is based on the Runner trait from test-tube but adds some additional functionality.

This crate also includes a TestRobot trait and a set of "Test Robots", which are structs that implement the TestRobot trait and help you implement the robot testing pattern. In essence these are structs that have functions that either perform an action or make an assertion, and then return self so that you can chain them together.

Available Features and Test Runners

This crate has the following optional features:

  • osmosis
  • astroport
    • Exports the astroport module containing the AstroportTestRobot trait. You can implement this trait on a struct to get access to a set of helper functions for testing against Astroport pools.
  • rpc_runner
    • Exports the rpc_runner module containing the RpcRunner struct. This struct implements the CwItRunner trait and allows you to run your tests against an RPC node.
  • multi-test
    • Exports the multi_test module containing the MultiTestRunner struct. This struct implements the CwItRunner trait and allows you to run your tests against an instance of apollo-cw-multi-test (this is a forked version of cw-multi-test which contains changes to support CwItRunner). Running tests against cw-multi-test rather than OsmosisTestApp can be useful if you need to run a debugger or want to check code coverage.
  • astroport-multi-test
    • Exports some utility functions in the astroport module that help you instantiate an instance of Astroport with cw-multi-test.
  • chain-download
    • This feature enables the ChainCodeId and ChainContractAddress variants on the Artifact enum. This lets you download the wasm file of contracts from an RPC node by either supplying the code ID or the contract address. This is useful if you want to run tests locally against a contract that is already deployed on a chain.


Add the following to your Cargo.toml:

cw-it = "0.1.0"

Depending on your needs, you should add one or more of the features mentioned above, e.g:

cw-it = { version = "0.1.0", features = ["osmosis"] }

Then you can write tests that look like this:

struct TestingRobot<'a>(&'a TestRunner);

impl<'a> OsmosisTestRobot<'a> for TestingRobot<'a> {}

pub const TEST_RUNNER: &str = "osmosis-test-app";

fn test_my_contract() {
    let runner  = TestRunner::from_str(TEST_RUNNER).unwrap();

    let robot = TestingRobot(&runner);

            Coin::new(swap_amount, "uosmo"),
            // We should have swapped swap_amount of our uosmo
            initial_balance - swap_amount - GAS_AMOUNT,
            // We should have more than the initial balance
            // But less than the initial balance + swap amount due to slippage and a balanced pool
            initial_balance + swap_amount,

Here you can see that we first create a testing robot struct, then implement the relevant traits on it to get some useful helper functions. Then we create a TestRunner struct and pass it to the robot. The robot then uses the runner to perform the actions and assertions.

Commit count: 267

cargo fmt