Crate pocket_ic

Crate pocket_ic 

Source
Expand description

§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

§Contributing

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

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.
nonblocking

Structs§

ErrorCodeIter
An iterator over the variants of ErrorCode
PocketIc
Main entry point for interacting with PocketIC.
PocketIcBuilder
PocketIcState
RejectCodeIter
An iterator over the variants of RejectCode
RejectResponse
User-facing type describing an unsuccessful (also called reject) call response.
StartServerParams
Time
Representation of system time as duration since UNIX epoch with cross-platform nanosecond precision.

Enums§

DefaultEffectiveCanisterIdError
ErrorCode
User-facing error codes.
IngressStatusResult
This enum describes the result of retrieving ingress status. The IngressStatusResult::Forbidden variant is produced if an optional caller is provided and a corresponding read state request for the status of the same update call signed by that specified caller was rejected because the update call was submitted by a different caller.
RejectCode
User-facing reject codes.
TryFromError
Error type for TryFrom<u64>.

Constants§

LATEST_SERVER_VERSION
Public to facilitate downloading the PocketIC server.

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.
copy_dir
get_default_effective_canister_id
Retrieves a default effective canister id for canister creation on a PocketIC instance characterized by:
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_server
Attempt to start a new PocketIC server.
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.