Struct PocketIc 

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

Main entry point for interacting with PocketIC.

Fields

instance_id: InstanceId

The unique ID of this PocketIC instance.

Implementations

impl PocketIc

pub async fn read_canister_snapshot_metadata( &self, sender: Principal, args: ReadCanisterSnapshotMetadataArgs, limits: CallLimits, ) -> Result<ReadCanisterSnapshotMetadataResult, SnapshotError>

pub async fn read_canister_snapshot_data( &self, sender: Principal, args: ReadCanisterSnapshotDataArgs, limits: CallLimits, ) -> Result<ReadCanisterSnapshotDataResult, SnapshotError>

pub async fn upload_canister_snapshot_metadata( &self, sender: Principal, args: UploadCanisterSnapshotMetadataArgs, limits: CallLimits, ) -> Result<UploadCanisterSnapshotMetadataResult, SnapshotError>

pub async fn upload_canister_snapshot_data( &self, sender: Principal, args: UploadCanisterSnapshotDataArgs, limits: CallLimits, ) -> Result<(), SnapshotError>

impl PocketIc

pub async fn new(server_url: Url) -> Result<Self, ClientError>

Creates a new PocketIC instance with a single application subnet on the server. The caller supplies an already admitted server endpoint.

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

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 get_server_url(&self) -> Url

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

pub async fn topology(&self) -> Result<Topology, ClientError>

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

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

Upload and store a binary blob to the PocketIC server.

pub async fn set_stable_memory( &self, canister_id: CanisterId, data: Vec<u8>, compression: BlobCompression, ) -> Result<(), ClientError>

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: CanisterId, ) -> Result<Vec<u8>, ClientError>

Get stable memory of a canister.

pub async fn list_instances(server_url: Url) -> Result<Vec<String>, ClientError>

List all instances and their status.

pub async fn tick(&self) -> Result<(), ClientError>

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, ) -> Result<(), ClientError>

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

pub async fn auto_progress(&self) -> Result<Url, ClientError>

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) -> Result<bool, ClientError>

Returns whether automatic progress is enabled on the PocketIC instance.

pub async fn stop_progress(&self) -> Result<(), ClientError>

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>, ) -> Result<Url, ClientError>

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>, ) -> Result<Url, ClientError>

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) -> Result<(), ClientError>

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

pub async fn root_key(&self) -> Result<Option<Vec<u8>>, ClientError>

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

pub async fn get_time(&self) -> Result<Time, ClientError>

Get the current time of the IC.

pub async fn set_time(&self, time: Time) -> Result<(), ClientError>

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

pub async fn set_certified_time(&self, time: Time) -> Result<(), ClientError>

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

pub async fn advance_time(&self, duration: Duration) -> Result<(), ClientError>

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

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

Get the controllers of a canister. Returns a server error if the canister does not exist.

pub async fn cycle_balance( &self, canister_id: CanisterId, ) -> Result<u128, ClientError>

Get the current cycles balance of a canister.

pub async fn add_cycles( &self, canister_id: CanisterId, amount: u128, ) -> Result<u128, ClientError>

Add cycles to a canister. Returns the new balance.

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

Submit an update call (without executing it immediately).

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

Submit an update with explicit routing, retaining its accepted ingress receipt.

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

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, ) -> Result<Option<Result<Vec<u8>, RejectResponse>>, ClientError>

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, ) -> Result<IngressStatusResult, ClientError>

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>, ClientError>

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: CanisterId, sender: Principal, method: &str, payload: Vec<u8>, ) -> Result<Vec<u8>, ClientError>

Execute an update call on a canister.

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

Submit once with explicit routing, then await the accepted ingress.

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

Execute a query call on a canister.

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

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 fetch_canister_logs( &self, canister_id: CanisterId, sender: Principal, ) -> Result<Vec<CanisterLogRecord>, ClientError>

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

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

Request a canister’s status.

pub async fn create_canister(&self) -> Result<CanisterId, ClientError>

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>, ) -> Result<CanisterId, ClientError>

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: CanisterId, ) -> Result<CanisterId, ClientError>

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: SubnetId, ) -> Result<CanisterId, ClientError>

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<CanisterId, ClientError>

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: CanisterId, sender: Option<Principal>, chunk: Vec<u8>, ) -> Result<Vec<u8>, ClientError>

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: CanisterId, sender: Option<Principal>, ) -> Result<Vec<Vec<u8>>, ClientError>

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

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

Clear the WASM chunk store of a canister.

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

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

pub async fn install_canister( &self, canister_id: CanisterId, wasm_module: Vec<u8>, arg: Vec<u8>, sender: Option<Principal>, ) -> Result<(), ClientError>

Install a WASM module on an existing canister.

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

Upgrade a canister with a new WASM module.

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

Reinstall a canister WASM module.

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

Uninstall a canister.

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

Take canister snapshot.

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

Load canister snapshot.

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

List canister snapshots.

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

Delete canister snapshot.

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

Update canister settings.

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

Set canister’s controllers.

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

Start a canister.

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

Stop a canister.

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

Delete a canister.

pub async fn canister_exists( &self, canister_id: CanisterId, ) -> Result<bool, ClientError>

Checks whether the provided canister exists.

pub async fn delete_subnet( &self, subnet_id: SubnetId, ) -> Result<(), ClientError>

Deletes a subnet. Returns a server error if the subnet does not exist or is a named subnet.

pub async fn get_subnet( &self, canister_id: CanisterId, ) -> Result<Option<SubnetId>, ClientError>

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

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

Returns subnet metrics for a given subnet.

pub async fn drop(self) -> Result<(), ClientError>

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 get_canister_http( &self, ) -> Result<Vec<CanisterHttpRequest>, ClientError>

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. Flexible outcall mocking is not supported by this client. 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, ) -> Result<(), ClientError>

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.

pub async fn canister_snapshot_download( &self, canister_id: CanisterId, sender: Principal, snapshot_id: Vec<u8>, snapshot_dir: PathBuf, ) -> Result<(), ClientError>

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: CanisterId, sender: Principal, replace_snapshot: Option<Vec<u8>>, snapshot_dir: PathBuf, ) -> Result<Vec<u8>, ClientError>

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 CanisterInstallExt for PocketIc

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

Install one arbitrary wasm module from a generic install specification.

async fn wait_out_install_code_rate_limit( &self, cooldown: Duration, ) -> Result<(), ClientError>

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

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

where F: AsyncFnMut() -> Result<T, ClientError>,

Retry only while PocketIC reports install-code rate limiting.

impl PocketIcDiagnosticsExt for PocketIc

async fn collect_canister_diagnostics( &self, request: CanisterDiagnosticsRequest, ) -> CanisterDiagnosticsReport

Collect status and bounded logs using the request’s exact senders.

async fn write_canister_diagnostics( &self, request: CanisterDiagnosticsRequest, context: &str, writer: &mut dyn Write, ) -> Result<()>

Explicitly collect and write one contextual diagnostic report.

async fn collect_canister_diagnostics_batch( &self, requests: &[LabeledCanisterDiagnosticsRequest], ) -> Result<CanisterDiagnosticsBatchReport, BatchLabelError>

Collect every labeled request sequentially in its supplied order.

impl PocketIcSnapshotExt for PocketIc

async fn capture_snapshots<I>( &self, targets: I, ) -> Result<ControllerSnapshots, ControllerSnapshotError>

where I: IntoIterator<Item = CanisterSnapshotTarget>,

Capture snapshots with one explicit sender per canister.

async fn restore_snapshots( &self, snapshots: &ControllerSnapshots, funding: SnapshotRestoreFunding, ) -> Result<(), ControllerSnapshotError>

Restore each snapshot with its exact captured sender and selected funding.