Struct PocketIc 

pub struct PocketIc { /* private fields */ }

Main entry point for interacting with PocketIC.

Implementations

impl PocketIc

pub fn new() -> PocketIc

Creates a new PocketIC instance with a single application subnet on the server. The server is started if it’s not already running.

pub fn new_from_existing_instance( server_url: Url, instance_id: usize, max_request_time_ms: Option<u64>, ) -> PocketIc

Creates a PocketIC handle to an existing instance on a running server. Note that this handle does not extend the lifetime of the existing instance, i.e., the existing instance is deleted and this handle stops working when the PocketIC handle that created the existing instance is dropped.

pub fn drop_and_take_state(self) -> Option<PocketIcState>

pub fn get_server_url(&self) -> Url

Returns the URL of the PocketIC server on which this PocketIC instance is running.

pub fn instance_id(&self) -> usize

Returns the instance ID.

pub fn topology(&self) -> Topology

Returns the topology of the different subnets of this PocketIC instance.

pub fn upload_blob(&self, blob: Vec<u8>, compression: BlobCompression) -> BlobId

Upload and store a binary blob to the PocketIC server.

pub fn set_stable_memory( &self, canister_id: Principal, data: Vec<u8>, compression: BlobCompression, )

Set stable memory of a canister. Optional GZIP compression can be used for reduced data traffic.

pub fn get_stable_memory(&self, canister_id: Principal) -> Vec<u8>

Get stable memory of a canister.

pub fn list_instances() -> Vec<String>

List all instances and their status.

pub fn verify_canister_signature( &self, msg: Vec<u8>, sig: Vec<u8>, pubkey: Vec<u8>, root_pubkey: Vec<u8>, ) -> Result<(), String>

Verify a canister signature.

pub fn tick(&self)

Make the IC produce and progress by one block. Note that multiple ticks might be necessary to observe an expected effect, e.g., if the effect depends on inter-canister calls or heartbeats.

pub fn tick_with_configs(&self, configs: TickConfigs)

Make the IC produce and progress by one block with custom configs for the round.

pub fn auto_progress(&self) -> Url

Configures the IC to make progress automatically, i.e., periodically update the time of the IC to the real time and execute rounds on the subnets. Returns the URL at which /api requests for this instance can be made.

pub fn auto_progress_enabled(&self) -> bool

Returns whether automatic progress is enabled on the PocketIC instance.

pub fn stop_progress(&self)

Stops automatic progress (see auto_progress) on the IC.

pub fn url(&self) -> Option<Url>

Returns the URL at which /api requests for this instance can be made if the HTTP gateway has been started.

pub fn make_live(&mut self, listen_at: Option<u16>) -> Url

Creates an HTTP gateway for this PocketIC instance binding to 127.0.0.1 and an optionally specified port (defaults to choosing an arbitrary unassigned port); listening on localhost; and configures the PocketIC instance to make progress automatically, i.e., periodically update the time of the PocketIC instance to the real time and process messages on the PocketIC instance. Returns the URL at which /api requests for this instance can be made.

pub fn make_live_with_params( &mut self, ip_addr: Option<IpAddr>, listen_at: Option<u16>, domains: Option<Vec<String>>, https_config: Option<HttpsConfig>, ) -> Url

Creates an HTTP gateway for this PocketIC instance binding to an optionally specified IP address (defaults to 127.0.0.1) and port (defaults to choosing an arbitrary unassigned port); listening on optionally specified domains (default to localhost); and using an optionally specified TLS certificate (if provided, an HTTPS gateway is created) and configures the PocketIC instance to make progress automatically, i.e., periodically update the time of the PocketIC instance to the real time and process messages on the PocketIC instance. Returns the URL at which /api requests for this instance can be made.

pub fn stop_live(&mut self)

Stops auto progress (automatic time updates and round executions) and the HTTP gateway for this IC instance.

pub fn root_key(&self) -> Option<Vec<u8>>

Get the root key of this IC instance. Returns None if the IC has no NNS subnet.

pub fn get_time(&self) -> Time

Get the current time of the IC.

pub fn set_time(&self, time: Time)

Set the current time of the IC, on all subnets.

pub fn set_certified_time(&self, time: Time)

Set the current certified time of the IC, on all subnets.

pub fn advance_time(&self, duration: Duration)

Advance the time on the IC on all subnets by some nanoseconds.

pub fn get_controllers(&self, canister_id: Principal) -> Vec<Principal>

Get the controllers of a canister. Panics if the canister does not exist.

pub fn cycle_balance(&self, canister_id: Principal) -> u128

Get the current cycles balance of a canister.

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

Add cycles to a canister. Returns the new balance.

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

Submit an update call (without executing it immediately).

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

Submit an update call with a provided effective principal (without executing it immediately).

pub fn submit_call_with_effective_principal_and_sender_info( &self, canister_id: Principal, effective_principal: RawEffectivePrincipal, sender: Principal, method: &str, payload: Vec<u8>, sender_info: RawSenderInfo, ) -> Result<RawMessageId, RejectResponse>

Submit an update call with a provided effective principal and sender info (without executing it immediately).

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

Submit an update call with sender info (without executing it immediately).

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

Await an update call submitted previously by submit_call or submit_call_with_effective_principal.

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

Fetch the status of an update call submitted previously by submit_call or submit_call_with_effective_principal. Note that the status of the update call can only change if the PocketIC instance is in live mode or a round has been executed due to a separate PocketIC library call, e.g., PocketIc::tick().

pub fn ingress_status_as( &self, message_id: RawMessageId, caller: Principal, ) -> IngressStatusResult

Fetch the status of an update call submitted previously by submit_call or submit_call_with_effective_principal. Note that the status of the update call can only change if the PocketIC instance is in live mode or a round has been executed due to a separate PocketIC library call, e.g., PocketIc::tick(). If the status of the update call is known, but the update call was submitted by a different caller, then an error is returned.

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

Await an update call submitted previously by submit_call or submit_call_with_effective_principal. Note that the status of the update call can only change if the PocketIC instance is in live mode or a round has been executed due to a separate PocketIC library call, e.g., PocketIc::tick().

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

Execute an update call on a canister.

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

Execute a query call on a canister.

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

Fetch canister logs via a query call to the management canister.

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

Request a canister’s status.

pub fn create_canister(&self) -> Principal

Create a canister with default settings as the anonymous principal. The canister is created with 100T cycles.

pub fn create_canister_with_settings( &self, sender: Option<Principal>, settings: Option<CanisterSettings>, ) -> Principal

Create a canister with optional custom settings and a sender. The canister is created with 100T cycles.

pub fn create_canister_with_id( &self, sender: Option<Principal>, settings: Option<CanisterSettings>, canister_id: Principal, ) -> Result<Principal, String>

Creates a canister with a specific canister ID and optional custom settings. The canister is created with 100T cycles. Returns an error if the canister ID is already in use. Creates a new subnet if the canister ID is not contained in any of the subnets.

The canister ID must be an IC mainnet canister ID that does not belong to the NNS or II subnet, otherwise the function might panic (for NNS and II canister IDs, the PocketIC instance should already be created with those subnets).

pub fn create_canister_on_subnet( &self, sender: Option<Principal>, settings: Option<CanisterSettings>, subnet_id: Principal, ) -> Principal

Create a canister on a specific subnet with optional custom settings. The canister is created with 100T cycles.

pub fn create_canister_with_params( &self, sender: Option<Principal>, params: CreateCanisterParams, ) -> Result<Principal, String>

Create a canister with optional cycles, settings, and placement. The placement specifies either a target subnet or a specific canister ID. Defaults to 100T cycles if params.cycles is None. Returns an error if the specified canister ID is already in use.

pub fn upload_chunk( &self, canister_id: Principal, sender: Option<Principal>, chunk: Vec<u8>, ) -> Result<Vec<u8>, RejectResponse>

Upload a WASM chunk to the WASM chunk store of a canister. Returns the WASM chunk hash.

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

List WASM chunk hashes in the WASM chunk store of a canister.

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

Clear the WASM chunk store of a canister.

pub fn install_chunked_canister( &self, canister_id: Principal, sender: Option<Principal>, mode: CanisterInstallMode, store_canister_id: Principal, chunk_hashes_list: Vec<Vec<u8>>, wasm_module_hash: Vec<u8>, arg: Vec<u8>, ) -> Result<(), RejectResponse>

Install a WASM module assembled from chunks on an existing canister.

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

Install a WASM module on an existing canister.

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

Upgrade a canister with a new WASM module.

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

Upgrade a Motoko EOP 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 a canister WASM module.

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

Uninstall a canister.

pub fn take_canister_snapshot( &self, canister_id: Principal, sender: Option<Principal>, replace_snapshot: Option<Vec<u8>>, ) -> Result<Snapshot, RejectResponse>

Take canister snapshot.

pub fn load_canister_snapshot( &self, canister_id: Principal, sender: Option<Principal>, snapshot_id: Vec<u8>, ) -> Result<(), RejectResponse>

Load canister snapshot.

pub fn list_canister_snapshots( &self, canister_id: Principal, sender: Option<Principal>, ) -> Result<Vec<Snapshot>, RejectResponse>

List canister snapshots.

pub fn delete_canister_snapshot( &self, canister_id: Principal, sender: Option<Principal>, snapshot_id: Vec<u8>, ) -> Result<(), RejectResponse>

Delete canister snapshot.

pub fn update_canister_settings( &self, canister_id: Principal, sender: Option<Principal>, settings: CanisterSettings, ) -> Result<(), RejectResponse>

Update canister settings.

pub fn set_controllers( &self, canister_id: Principal, sender: Option<Principal>, new_controllers: Vec<Principal>, ) -> Result<(), RejectResponse>

Set canister’s controllers.

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

Start a canister.

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

Stop a canister.

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

Delete a canister.

pub fn canister_exists(&self, canister_id: Principal) -> bool

Checks whether the provided canister exists.

pub fn delete_subnet(&self, subnet_id: Principal)

Deletes a subnet. Panics if the subnet does not exist or is a named subnet.

pub fn get_subnet(&self, canister_id: Principal) -> Option<Principal>

Returns the subnet ID of the canister if the canister exists.

pub fn get_subnet_metrics(&self, subnet_id: Principal) -> Option<SubnetMetrics>

Returns subnet metrics for a given subnet.

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

pub fn update_call_with_effective_principal_and_sender_info( &self, canister_id: Principal, effective_principal: RawEffectivePrincipal, sender: Principal, method: &str, payload: Vec<u8>, sender_info: RawSenderInfo, ) -> Result<Vec<u8>, RejectResponse>

Execute an update call with a provided effective principal and sender info on a canister.

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

Execute an update call with sender info on a canister.

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

Execute a query call on a canister explicitly specifying an effective principal to route the request: this API is useful for making generic query calls (including management canister query calls) without using dedicated functions from this library (e.g., making generic query calls in dfx to a PocketIC instance).

pub fn query_call_with_effective_principal_and_sender_info( &self, canister_id: Principal, effective_principal: RawEffectivePrincipal, sender: Principal, method: &str, payload: Vec<u8>, sender_info: RawSenderInfo, ) -> Result<Vec<u8>, RejectResponse>

Execute a query call with a provided effective principal and sender info on a canister.

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

Execute a query call with sender info on a canister.

pub fn get_canister_http(&self) -> Vec<CanisterHttpRequest>

Get the pending canister HTTP outcalls. Note that an additional PocketIc::tick is necessary after a canister executes a message making a canister HTTP outcall for the HTTP outcall to be retrievable here. Note that, unless a PocketIC instance is in auto progress mode, a response to the pending canister HTTP outcalls must be produced by the test driver and passed on to the PocketIC instace using PocketIc::mock_canister_http_response. In auto progress mode, the PocketIC server produces a response for every pending canister HTTP outcall by actually making an HTTP request to the specified URL.

pub fn mock_canister_http_response( &self, mock_canister_http_response: MockCanisterHttpResponse, )

Mock a response to a pending canister HTTP outcall.

pub fn canister_snapshot_download( &self, canister_id: Principal, sender: Principal, snapshot_id: Vec<u8>, snapshot_dir: PathBuf, )

Download a canister snapshot to a given snapshot directory. The sender must be a controller of the canister. The snapshot directory must be empty if it exists.

pub fn canister_snapshot_upload( &self, canister_id: Principal, sender: Principal, replace_snapshot: Option<Vec<u8>>, snapshot_dir: PathBuf, ) -> Vec<u8>

Upload a canister snapshot from a given snapshot directory. The sender must be a controller of the canister. Returns the snapshot ID of the uploaded snapshot.

Trait Implementations

impl CandidCallExt for PocketIc

fn update_candid<T, A>( &self, canister_id: Principal, method: &str, args: A, ) -> Result<T, CandidCallError>

where T: CandidType + DeserializeOwned, A: ArgumentEncoder,

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

fn update_candid_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 rejection or Candid codec failure.

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

fn update_candid_as<T, A>( &self, canister_id: Principal, caller: Principal, method: &str, args: A, ) -> Result<T, CandidCallError>

where T: CandidType + DeserializeOwned, A: ArgumentEncoder,

Generic update call helper with an explicit caller principal.

fn update_candid_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 rejection or Candid codec failure.

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

fn query_candid<T, A>( &self, canister_id: Principal, method: &str, args: A, ) -> Result<T, CandidCallError>

where T: CandidType + DeserializeOwned, A: ArgumentEncoder,

Generic query call helper.

fn query_candid_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 rejection or Candid codec failure.

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

fn query_candid_as<T, A>( &self, canister_id: Principal, caller: Principal, method: &str, args: A, ) -> Result<T, CandidCallError>

where T: CandidType + DeserializeOwned, A: ArgumentEncoder,

Generic query call helper with an explicit caller principal.

fn query_candid_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 rejection or Candid codec failure.

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

impl CanisterInstallExt for PocketIc

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.

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

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

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

Install one arbitrary wasm module from a generic install specification.

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

Install one arbitrary wasm module from a generic install specification.

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

where I: IntoIterator<Item = InstallSpec>,

Sequentially install multiple arbitrary wasm modules into this PocketIC instance.

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 CanisterInstallError::canister_id(), and later installs are not attempted.

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

where I: IntoIterator<Item = InstallSpec>,

Sequentially install multiple arbitrary wasm modules into this PocketIC instance.

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 CanisterInstallError::canister_id(), and later installs are not attempted.

fn wait_out_install_code_rate_limit(&self, cooldown: Duration)

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

fn retry_install_code<T, F>( &self, policy: RetryPolicy, op: F, ) -> Result<T, String>

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

Retry an operation only while PocketIC reports install-code rate limiting.

impl Default for PocketIc

fn default() -> PocketIc

Returns the “default value” for a type.

impl Drop for PocketIc

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.

impl PocketIcDiagnosticsExt for PocketIc

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

Dump basic PocketIC status and log context for one canister.

impl PocketIcSnapshotExt for PocketIc

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

where I: IntoIterator<Item = Principal>,

Capture one restorable snapshot per unique canister.

fn restore_controller_snapshots( &self, controller_id: Principal, snapshots: &ControllerSnapshots, ) -> Result<(), ControllerSnapshotError>

Restore a previously captured snapshot set using the same controller.

impl PocketIcTimeExt for PocketIc

fn tick_n(&self, times: usize)

Advance PocketIC by a fixed number of execution rounds.

fn current_time_nanos(&self) -> u64

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

fn restore_time_nanos(&self, nanos_since_epoch: u64)

Restore wall-clock and certified time from one captured value.