PocketIC Rust: A Canister Testing Library

PocketIC is a local canister testing solution for the Internet Computer.
This testing library works together with the PocketIC server, allowing you to interact with your local IC instances and the canisters thereon.

With PocketIC Rust, testing canisters is as simple as calling Rust functions. Here is a simple example:

use candid::encode_one;
use pocket_ic::PocketIc;

 #[test]
 fn test_counter_canister() {
    let pic = PocketIc::new();
    // Create an empty canister as the anonymous principal and add cycles.
    let canister_id = pic.create_canister();
    pic.add_cycles(canister_id, 2_000_000_000_000);
    
    let wasm_bytes = load_counter_wasm(...);
    pic.install_canister(canister_id, wasm_bytes, vec![], None);
    // 'inc' is a counter canister method.
    call_counter_canister(&pic, canister_id, "inc");
    // Check if it had the desired effect.
    let reply = call_counter_canister(&pic, canister_id, "read");
    assert_eq!(reply, WasmResult::Reply(vec![0, 0, 0, 1]));
 }

fn call_counter_canister(pic: &PocketIc, canister_id: CanisterId, method: &str) -> WasmResult {
    pic.update_call(canister_id, Principal::anonymous(), method, encode_one(()).unwrap())
        .expect("Failed to call counter canister")
}

Getting Started

Quickstart

• Download the latest PocketIC server from the PocketIC repo.
• Leave the binary in your current working directory, or specify the path to the binary by setting the POCKET_IC_BIN environment variable before running your tests.
• Add PocketIC Rust to your project with cargo add pocket-ic.
• Import PocketIC with use pocket_ic::PocketIc, and create a new PocketIC instance with let pic = PocketIc::new() in your Rust code and start testing!

Examples

For a simple but complete example with the counter canister, see here. For an example with cross canister calls on two different subnets with the ledger canister, see here.

To see a minimalistic setup of PocketIC in a Rust project, check out the ICP Hello World Rust repository.

For larger test suites with more complex test setups, consider the OpenChat integration test suite. Note that instances are shared among test cases there, which is not recommended in general.

Documentation

• How to use this library
• API documentation
• PocketIC repo
• Why PocketIC
• Changelog
• Source code

Contributing

If you decide to contribute, we encourage you to announce it on the Forum!