From e06809f9e5e4d36aec01c4075195d7f696faf7b8 Mon Sep 17 00:00:00 2001 From: Martin Raszyk Date: Thu, 16 Jan 2025 08:16:13 +0100 Subject: [PATCH] doc comments --- packages/pocket-ic/src/lib.rs | 103 +++++++++++++++--------------- packages/pocket-ic/tests/tests.rs | 30 ++++----- 2 files changed, 67 insertions(+), 66 deletions(-) diff --git a/packages/pocket-ic/src/lib.rs b/packages/pocket-ic/src/lib.rs index 0cda6232560..cf74dbed171 100644 --- a/packages/pocket-ic/src/lib.rs +++ b/packages/pocket-ic/src/lib.rs @@ -1,54 +1,57 @@ #![allow(clippy::test_attr_in_doctest)] -//! # PocketIC: A Canister Testing Platform -//! -//! PocketIC is the local canister smart contract testing platform for the [Internet Computer](https://internetcomputer.org/). -//! -//! 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: -//! -//! ```rust -//! 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 = counter_wasm(); -//! 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 { -//! pic.update_call( -//! canister_id, -//! Principal::anonymous(), -//! method, -//! encode_one(()).unwrap(), -//! ) -//! .expect("Failed to call counter canister") -//! } -//! ``` -//! For more information, see the [README](https://crates.io/crates/pocket-ic). -//! +/// # PocketIC: A Canister Testing Platform +/// +/// PocketIC is the local canister smart contract testing platform for the [Internet Computer](https://internetcomputer.org/). +/// +/// 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: +/// +/// ```rust +/// use candid::{Principal, encode_one}; +/// use pocket_ic::PocketIc; +/// +/// // 2T cycles +/// const INIT_CYCLES: u128 = 2_000_000_000_000; +/// +/// // Create a counter canister and charge it with 2T cycles. +/// fn deploy_counter_canister(pic: &PocketIc) -> Principal { +/// let canister_id = pic.create_canister(); +/// pic.add_cycles(canister_id, INIT_CYCLES); +/// let counter_wasm = todo!(); +/// pic.install_canister(canister_id, counter_wasm, vec![], None); +/// canister_id +/// } +/// +/// // Call a method on the counter canister as the anonymous principal. +/// fn call_counter_canister(pic: &PocketIc, canister_id: Principal, method: &str) -> Vec { +/// pic.update_call( +/// canister_id, +/// Principal::anonymous(), +/// method, +/// encode_one(()).unwrap(), +/// ) +/// .expect("Failed to call counter canister") +/// } +/// +/// #[test] +/// fn test_counter_canister() { +/// let pic = PocketIc::new(); +/// let canister_id = deploy_counter_canister(&pic); +/// +/// // Make some calls to the counter canister. +/// let reply = call_counter_canister(&pic, canister_id, "read"); +/// assert_eq!(reply, vec![0, 0, 0, 0]); +/// let reply = call_counter_canister(&pic, canister_id, "write"); +/// assert_eq!(reply, vec![1, 0, 0, 0]); +/// let reply = call_counter_canister(&pic, canister_id, "write"); +/// assert_eq!(reply, vec![2, 0, 0, 0]); +/// let reply = call_counter_canister(&pic, canister_id, "read"); +/// assert_eq!(reply, vec![2, 0, 0, 0]); +/// } +/// ``` +/// For more information, see the [README](https://crates.io/crates/pocket-ic). +/// use crate::{ common::rest::{ BlobCompression, BlobId, CanisterHttpRequest, ExtendedSubnetConfigSet, HttpsConfig, diff --git a/packages/pocket-ic/tests/tests.rs b/packages/pocket-ic/tests/tests.rs index 2534f4632bb..a872790851b 100644 --- a/packages/pocket-ic/tests/tests.rs +++ b/packages/pocket-ic/tests/tests.rs @@ -43,12 +43,23 @@ fn deploy_counter_canister(pic: &PocketIc) -> Principal { canister_id } +// Call a method on the counter canister as the anonymous principal. +fn call_counter_canister(pic: &PocketIc, canister_id: Principal, method: &str) -> Vec { + pic.update_call( + canister_id, + Principal::anonymous(), + method, + encode_one(()).unwrap(), + ) + .expect("Failed to call counter canister") +} + #[test] fn test_counter_canister() { let pic = PocketIc::new(); let canister_id = deploy_counter_canister(&pic); - // Make some calls to the canister. + // Make some calls to the counter canister. let reply = call_counter_canister(&pic, canister_id, "read"); assert_eq!(reply, vec![0, 0, 0, 0]); let reply = call_counter_canister(&pic, canister_id, "write"); @@ -63,12 +74,9 @@ fn counter_wasm() -> Vec { const COUNTER_WAT: &str = r#" (module (import "ic0" "msg_reply" (func $msg_reply)) - (import "ic0" "msg_reply_data_append" - (func $msg_reply_data_append (param i32 i32))) + (import "ic0" "msg_reply_data_append" (func $msg_reply_data_append (param i32 i32))) (func $write - (i32.store - (i32.const 0) - (i32.add (i32.load (i32.const 0)) (i32.const 1))) + (i32.store (i32.const 0) (i32.add (i32.load (i32.const 0)) (i32.const 1))) (call $read)) (func $read (call $msg_reply_data_append @@ -82,16 +90,6 @@ fn counter_wasm() -> Vec { wat::parse_str(COUNTER_WAT).unwrap() } -fn call_counter_canister(ic: &PocketIc, canister_id: Principal, method: &str) -> Vec { - ic.update_call( - canister_id, - Principal::anonymous(), - method, - encode_one(()).unwrap(), - ) - .expect("Failed to call counter canister") -} - #[test] fn test_create_canister_with_id() { let pic = PocketIcBuilder::new()