Struct PocketIc 

pub struct PocketIc {
    pub instance_id: usize,
    /* private fields */
}

Main entry point for interacting with PocketIC.

Fields

instance_id: usize

The unique ID of this PocketIC instance.

Implementations

impl PocketIc

pub async 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 async 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 async fn topology(&self) -> Topology

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

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

Upload and store a binary blob to the PocketIC server.

pub async 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 async fn get_stable_memory(&self, canister_id: Principal) -> Vec<u8>

Get stable memory of a canister.

pub async fn list_instances() -> Vec<String>

List all instances and their status.

pub async 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 async 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 async fn tick_with_configs(&self, configs: TickConfigs)

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

pub async 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. Only returns after the certified time of the IC has been updated for the first time. Returns the URL at which /api requests for this instance can be made.

pub async fn auto_progress_enabled(&self) -> bool

Returns whether automatic progress is enabled on the PocketIC instance.

pub async 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 async 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. Only returns after the certified time of the PocketIC instance has been updated for the first time. Returns the URL at which /api requests for this instance can be made.

pub async 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. Only returns after the certified time of the PocketIC instance has been updated for the first time. Returns the URL at which /api requests for this instance can be made.

pub async fn stop_live(&mut self)

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

pub async 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 async fn get_time(&self) -> Time

Get the current time of the IC.

pub async fn set_time(&self, time: Time)

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

pub async fn set_certified_time(&self, time: Time)

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

pub async fn advance_time(&self, duration: Duration)

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

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

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

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

Get the current cycles balance of a canister.

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

Add cycles to a canister. Returns the new balance.

pub async 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 async 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 async 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 async 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 async 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 async fn ingress_status( &self, raw_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 async fn ingress_status_as( &self, raw_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 async 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.

pub async 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 async 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 async 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 async 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 async 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 async 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 async 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 async 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 async fn canister_status( &self, canister_id: Principal, sender: Option<Principal>, ) -> Result<CanisterStatusResult, RejectResponse>

Request a canister’s status.

pub async fn create_canister(&self) -> Principal

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

pub async 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 async 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 async 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 async 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 async 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 async 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 async fn clear_chunk_store( &self, canister_id: Principal, sender: Option<Principal>, ) -> Result<(), RejectResponse>

Clear the WASM chunk store of a canister.

pub async 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 async 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 async 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 async 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 async 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 async fn uninstall_canister( &self, canister_id: Principal, sender: Option<Principal>, ) -> Result<(), RejectResponse>

Uninstall a canister.

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

Take canister snapshot.

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

Load canister snapshot.

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

List canister snapshots.

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

Delete canister snapshot.

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

Update canister settings.

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

Set canister’s controllers.

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

Start a canister.

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

Stop a canister.

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

Delete a canister.

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

Checks whether the provided canister exists.

pub async fn delete_subnet(&self, subnet_id: Principal)

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

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

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

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

Returns subnet metrics for a given subnet.

pub async fn drop(self)

This (asynchronous) drop function must be called to drop the PocketIc instance. It must be called manually as Rust doesn’t support asynchronous drop.

pub async 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 async 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, or, for a flexible outcall (CanisterHttpReplication::Flexible), using PocketIc::mock_flexible_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 async fn mock_canister_http_response( &self, mock_canister_http_response: MockCanisterHttpResponse, )

Mock a response to a pending canister HTTP outcall: the same response for every node of the subnet, or one response per node if MockCanisterHttpResponse::additional_responses is non-empty. For a flexible outcall, whose committee nodes are answered individually, see PocketIc::mock_flexible_canister_http_response.

pub async fn mock_flexible_canister_http_response( &self, mock_flexible_canister_http_response: MockFlexibleCanisterHttpResponse, )

Mock the responses of the committee nodes of a pending flexible canister HTTP outcall, i.e. one made through the flexible_http_request management canister endpoint.

This takes at most one response per node of the outcall’s committee (whose size is the total_requests of the outcall’s CanisterHttpReplication::Flexible replication). Providing fewer responses than the committee size models the remaining committee nodes never responding: with at least min_responses successful ones among them the outcall still succeeds, and with fewer it stays pending until the time is advanced past its 60 second timeout, at which point it fails with a timeout error.

All responses to an outcall must be provided in a single call: once any response to it has been mocked, the outcall no longer shows up in PocketIc::get_canister_http and further responses to it cannot be mocked.

pub async 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 async 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.