ic-canister-runtime

Library to abstract the canister runtime so that code making requests to canisters can be reused, e.g.:

• in production using ic_cdk,
• in unit tests by mocking this crate's Runtime trait,
• in integration tests by implementing this trait for PocketIC yourself or using the PokcetIcRuntime implementation from the ic-pocket-canister-runtime crate.

Usage

Add this to your Cargo.toml (see crates.io for the latest version):

ic-canister-runtime = "0.1.0"

Then, use the library to abstract your code making requests to canisters as follows:

use ic_canister_runtime::{IcRuntime, Runtime};

// This runtime makes calls to canisters deployed on the Internet Computer using the `ic-cdk`
let runtime = IcRuntime::new();

// Make a request to the `http_request` example canister's `make_http_post_request` endpoint
// See: https://github.com/dfinity/canhttp/tree/main/examples/http_canister
let http_request_result: String = runtime
    .update_call(canister_id, "make_http_post_request", (), 0)
    .await
    .expect("Call to `http_canister` failed");

assert!(http_request_result.contains("Hello, World!"));
assert!(http_request_result.contains("\"X-Id\": \"42\""));

The same code can then be re-used for example in unit tests by simply changing the runtime:

use ic_canister_runtime::{Runtime, StubRuntime};

// Use a mock runtime for unit testing
let runtime = StubRuntime::new()
    .add_stub_response(r#"{"data": "Hello, World!", "headers": {"X-Id": "42"}}"#);

// The code below is the same as in the previous example
let http_request_result: String = runtime
    .update_call(canister_id, "make_http_post_request", (), 0)
    .await
    .expect("Call to `http_canister` failed");

assert!(http_request_result.contains("Hello, World!"));
assert!(http_request_result.contains("\"X-Id\": \"42\""));

See the Rust documentation for more details as well as the ic-pocket-canister-runtime and ic-agent-canister-runtime crates for some further implementations of the Runtime trait.

Cargo Features

Feature wallet

Provides the CyclesWalletRuntime implementation which allows routing update calls to a canister through a cycles wallet to attach cycles to them.

License

This project is licensed under the Apache License 2.0.