Crate pocket_ic

PocketIC: A Canister Testing Platform

PocketIC is the local canister smart contract testing platform for the Internet Computer.

It consists of the PocketIC server, which can run many independent IC instances, and a client library (this crate), which provides an interface to your IC instances.

With PocketIC, testing canisters is as simple as calling rust functions. Here is a minimal 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")
}

For more information, see the README.

Modules

• common
  Types that are shared between the PocketIC server and the PocketIC library. This module is a dependency of the server in the IC repository.

Structs

• CanisterSettings
  Canister settings.
• PocketIc
  Main entry point for interacting with PocketIC.
• PocketIcBuilder
• UserError
  The error that is sent back to users from the IC if something goes wrong. It’s designed to be copyable and serializable so that we can persist it in the ingress history.

Enums

• CallError
  This enum describes the different error types when invoking a canister.
• ErrorCode
  User-facing error codes.
• TryFromError
  Error type for TryFrom<u64>.
• WasmResult
  This struct describes the different types that executing a WASM function in a canister can produce.

Functions

• call_candid
  Call a canister candid method, anonymous. PocketIC executes update calls synchronously, so there is no need to poll for the result.
• call_candid_as
  Call a canister candid method, authenticated. The sender can be impersonated (i.e., the signature is not verified). PocketIC executes update calls synchronously, so there is no need to poll for the result.
• query_candid
  Call a canister candid query method, anonymous.
• query_candid_as
  Call a canister candid query method, authenticated. The sender can be impersonated (i.e., the signature is not verified).
• start_or_reuse_server
  Attempt to start a new PocketIC server if it’s not already running.
• update_candid
  Call a canister candid update method, anonymous.
• update_candid_as
  Call a canister candid update method, authenticated. The sender can be impersonated (i.e., the signature is not verified).
• with_candid
  A helper function that we use to implement both call_candid and query_candid.