5 stable releases
2.2.0 | Feb 14, 2024 |
---|---|
2.1.0 | Feb 7, 2024 |
2.0.1 | Nov 23, 2023 |
2.0.0 | Nov 21, 2023 |
1.0.0 | Oct 12, 2023 |
#350 in Magic Beans
1,286 downloads per month
Used in ic-websocket-cdk
67KB
1.5K
SLoC
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 withlet 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.
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
Contributing
If you decide to contribute, we encourage you to announce it on the Forum!
Dependencies
~12–26MB
~387K SLoC