Struct Pic 

pub struct Pic(/* private fields */);

Pic Thin wrapper around the global PocketIC instance.

This type intentionally exposes only a minimal API surface; callers should use pic() to obtain the singleton and then perform installs/calls.

Implementations

impl Pic

pub fn create_and_install_root_canister( &self, wasm: Vec<u8>, ) -> Result<Principal, Error>

Install a root canister with the default root init arguments.

pub fn create_and_install_canister( &self, role: CanisterRole, wasm: Vec<u8>, ) -> Result<Principal, Error>

Install a canister with the given type and wasm bytes.

Install failures are treated as fatal in tests.

pub fn create_and_install_canister_with_directories( &self, role: CanisterRole, wasm: Vec<u8>, app_directory: AppDirectoryArgs, subnet_directory: SubnetDirectoryArgs, ) -> Result<Principal, Error>

Install a canister with a custom directory snapshot (local-only helper).

Use this when a test exercises directory-dependent auth/endpoints and cannot rely on root to provide a snapshot.

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

where T: CandidType + DeserializeOwned, A: ArgumentEncoder,

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

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

where T: CandidType + DeserializeOwned, A: ArgumentEncoder,

Generic update call helper with an explicit caller principal.

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

where T: CandidType + DeserializeOwned, A: ArgumentEncoder,

Generic query call helper.

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

where T: CandidType + DeserializeOwned, A: ArgumentEncoder,

Generic query call helper with an explicit caller principal.

pub fn tick_n(&self, times: usize)

pub fn certify_time(&self)

Methods from Deref<Target = PocketIc>

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

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

Create a canister with optional custom settings and a sender.

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

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 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 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 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 Deref for Pic

type Target = PocketIc

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl DerefMut for Pic

fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.