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::{Principal, encode_one};
use pocket_ic::PocketIc;

// 2T cycles
const INIT_CYCLES: u128 = 2_000_000_000_000;

#[test]
fn test_counter_canister() {
    let pic = PocketIc::new();

    // Create a canister and charge it with 2T cycles.
    let canister_id = pic.create_canister();
    pic.add_cycles(canister_id, INIT_CYCLES);

    // Install the counter canister wasm file on the canister.
    let counter_wasm = todo!();
    pic.install_canister(canister_id, counter_wasm, vec![], None);

    // Make some calls to the canister.
    let reply = call_counter_can(&pic, canister_id, "read");
    assert_eq!(reply, vec![0, 0, 0, 0]);
    let reply = call_counter_can(&pic, canister_id, "write");
    assert_eq!(reply, vec![1, 0, 0, 0]);
    let reply = call_counter_can(&pic, canister_id, "write");
    assert_eq!(reply, vec![2, 0, 0, 0]);
    let reply = call_counter_can(&pic, canister_id, "read");
    assert_eq!(reply, vec![2, 0, 0, 0]);
}

fn call_counter_can(pic: &PocketIc, canister_id: Principal, method: &str) -> Vec<u8> {
    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 that is compatible with the library version you're using.
• Ungzip the downloaded file.
• On UNIX: make the downloaded file executable.
• Specify the path to the binary by using the function PocketIcBuilder::with_server_binary or the environment variable POCKET_IC_BIN.
• 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 simple but complete examples, see integration tests.

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
• PocketIC server compatibility
• Why PocketIC
• Changelog
• Source code

Contributing

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