Struct Pic 

pub struct Pic { /* private fields */ }

Pic Thin wrapper around a PocketIC instance.

This type intentionally exposes only a minimal API surface; callers should use pic() to obtain an instance and then perform installs/calls. Callers must hold a PicSerialGuard for the full Pic lifetime.

Implementations

impl Pic

pub fn update_call<T, A>( &self, canister_id: Principal, method: &str, args: A, ) -> Result<T, PicCallError>

where T: CandidType + DeserializeOwned, A: ArgumentEncoder,

Generic update call helper (serializes args + decodes result).

pub fn update_call_or_panic<T, A>( &self, canister_id: Principal, method: &str, args: A, ) -> T

where T: CandidType + DeserializeOwned, A: ArgumentEncoder,

Generic update call helper that panics on transport or Candid codec failure.

This does not unwrap application-level results. For example, update_call_or_panic::<Result<T, E>, _>(...) returns Result<T, E>.

pub fn update_call_as<T, A>( &self, canister_id: Principal, caller: Principal, method: &str, args: A, ) -> Result<T, PicCallError>

where T: CandidType + DeserializeOwned, A: ArgumentEncoder,

Generic update call helper with an explicit caller principal.

pub fn update_call_as_or_panic<T, A>( &self, canister_id: Principal, caller: Principal, method: &str, args: A, ) -> T

where T: CandidType + DeserializeOwned, A: ArgumentEncoder,

Generic update call helper with an explicit caller principal that panics on transport or Candid codec failure.

This does not unwrap application-level results. For example, update_call_as_or_panic::<Result<T, E>, _>(...) returns Result<T, E>.

pub fn query_call<T, A>( &self, canister_id: Principal, method: &str, args: A, ) -> Result<T, PicCallError>

where T: CandidType + DeserializeOwned, A: ArgumentEncoder,

Generic query call helper.

pub fn query_call_or_panic<T, A>( &self, canister_id: Principal, method: &str, args: A, ) -> T

where T: CandidType + DeserializeOwned, A: ArgumentEncoder,

Generic query call helper that panics on transport or Candid codec failure.

This does not unwrap application-level results. For example, query_call_or_panic::<Result<T, E>, _>(...) returns Result<T, E>.

pub fn query_call_as<T, A>( &self, canister_id: Principal, caller: Principal, method: &str, args: A, ) -> Result<T, PicCallError>

where T: CandidType + DeserializeOwned, A: ArgumentEncoder,

Generic query call helper with an explicit caller principal.

pub fn query_call_as_or_panic<T, A>( &self, canister_id: Principal, caller: Principal, method: &str, args: A, ) -> T

where T: CandidType + DeserializeOwned, A: ArgumentEncoder,

Generic query call helper with an explicit caller principal that panics on transport or Candid codec failure.

This does not unwrap application-level results. For example, query_call_as_or_panic::<Result<T, E>, _>(...) returns Result<T, E>.

pub fn tick_n(&self, times: usize)

Advance PocketIC by a fixed number of ticks.

impl Pic

pub fn dump_canister_debug(&self, canister_id: Principal, context: &str)

Dump basic PocketIC status and log context for one canister.

impl Pic

pub fn create_and_install_with_args( &self, wasm: Vec<u8>, init_bytes: Vec<u8>, install_cycles: u128, ) -> Principal

Install one arbitrary wasm module with caller-provided init bytes.

This is the generic install path for downstreams that use ic-testkit without depending on application-specific init payload conventions.

pub fn try_create_and_install_with_args( &self, wasm: Vec<u8>, init_bytes: Vec<u8>, install_cycles: u128, ) -> Result<Principal, PicInstallError>

Install one arbitrary wasm module with caller-provided init bytes.

pub fn create_and_install(&self, spec: InstallSpec) -> Principal

Install one arbitrary wasm module from a generic install specification.

pub fn try_create_and_install( &self, spec: InstallSpec, ) -> Result<Principal, PicInstallError>

Install one arbitrary wasm module from a generic install specification.

pub fn create_and_install_many<I>(&self, specs: I) -> Vec<Principal>

where I: IntoIterator<Item = InstallSpec>,

Sequentially install multiple arbitrary wasm modules into this Pic.

Installs are attempted in iterator order. If one install fails, earlier installs remain in the PocketIC instance, the failed canister may exist with the id exposed by PicInstallError::canister_id(), and later installs are not attempted.

pub fn try_create_and_install_many<I>( &self, specs: I, ) -> Result<Vec<Principal>, PicInstallError>

where I: IntoIterator<Item = InstallSpec>,

Sequentially install multiple arbitrary wasm modules into this Pic.

Installs are attempted in iterator order. If one install fails, earlier installs remain in the PocketIC instance, the failed canister may exist with the id exposed by PicInstallError::canister_id(), and later installs are not attempted.

pub fn wait_out_install_code_rate_limit(&self, cooldown: Duration)

Wait out the PocketIC install_code cooldown window inside the same instance.

pub fn retry_install_code_ok<T, F>( &self, retry_limit: usize, cooldown: Duration, op: F, ) -> Result<T, String>

where F: FnMut() -> Result<T, String>,

Retry one install_code-like operation while PocketIC still reports rate limiting.

pub fn retry_install_code_err<F>( &self, retry_limit: usize, cooldown: Duration, first: Result<(), String>, op: F, ) -> Result<(), String>

where F: FnMut() -> Result<(), String>,

Retry one install_code-like failure path while PocketIC still reports rate limiting.

impl Pic

pub fn capture_controller_snapshots<I>( &self, controller_id: Principal, canister_ids: I, ) -> Option<ControllerSnapshots>

where I: IntoIterator<Item = Principal>,

Capture one restorable snapshot per canister using a shared controller.

pub fn restore_controller_snapshots( &self, controller_id: Principal, snapshots: &ControllerSnapshots, )

Restore a previously captured snapshot set using the same controller.

impl Pic

pub fn tick(&self)

Advance one execution round in the owned PocketIC instance.

pub fn advance_time(&self, duration: Duration)

Advance PocketIC wall-clock time by one duration.

pub fn create_canister(&self) -> Principal

Create one canister with PocketIC default settings.

pub fn add_cycles(&self, canister_id: Principal, amount: u128)

Add cycles to one existing canister.

pub fn install_canister( &self, canister_id: Principal, wasm_module: Vec<u8>, arg: Vec<u8>, sender: Option<Principal>, )

Install one wasm module on one existing canister.

pub fn upgrade_canister( &self, canister_id: Principal, wasm_module: Vec<u8>, arg: Vec<u8>, sender: Option<Principal>, ) -> Result<(), RejectResponse>

Upgrade one existing canister with a new wasm module.

pub fn reinstall_canister( &self, canister_id: Principal, wasm_module: Vec<u8>, arg: Vec<u8>, sender: Option<Principal>, ) -> Result<(), RejectResponse>

Reinstall one existing canister with a new wasm module.

pub fn submit_call( &self, canister_id: Principal, sender: Principal, method: &str, payload: Vec<u8>, ) -> Result<RawMessageId, RejectResponse>

Submit one raw update call without executing it immediately.

pub fn await_call( &self, message_id: RawMessageId, ) -> Result<Vec<u8>, RejectResponse>

Await one previously submitted raw update call.

pub fn canister_status( &self, canister_id: Principal, sender: Option<Principal>, ) -> Result<CanisterStatusResult, RejectResponse>

Fetch one canister status snapshot from PocketIC.

pub fn fetch_canister_logs( &self, canister_id: Principal, sender: Principal, ) -> Result<Vec<CanisterLogRecord>, RejectResponse>

Fetch one canister log stream from PocketIC.

pub fn current_time_nanos(&self) -> u64

Capture the current PocketIC wall-clock time as nanoseconds since epoch.

pub fn restore_time_nanos(&self, nanos_since_epoch: u64)

Restore PocketIC wall-clock and certified time from a captured nanosecond value.