Struct PocketIc

pub struct PocketIc { /* private fields */ }

Main entry point for interacting with PocketIC.

Implementations

impl PocketIc

pub fn new() -> Self

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 instance_id(&self) -> InstanceId

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: CanisterId, 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: CanisterId) -> 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 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/v2 requests for this instance can be made.

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/v2 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 IC instance listening on an optionally specified port and configures the IC instance 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/v2 requests for this instance can be made.

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

Creates an HTTP gateway for this PocketIC instance listening on an optionally specified port (defaults to choosing an arbitrary unassigned port) and 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 execute rounds on the subnets. Returns the URL at which /api/v2 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 make_deterministic(&mut self)

👎Deprecated: Use stop_live instead.

Use stop_live instead.

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) -> SystemTime

Get the current time of the IC.

pub fn set_time(&self, time: SystemTime)

Set the current 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: CanisterId) -> Vec<Principal>

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

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

Get the current cycles balance of a canister.

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

Add cycles to a canister. Returns the new balance.

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

Submit an update call (without executing it immediately).

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

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

pub fn await_call( &self, message_id: RawMessageId, ) -> Result<WasmResult, UserError>

Await an update call submitted previously by submit_call_with_effective_principal.

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

Execute an update call on a canister.

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

Execute a query call on a canister.

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

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

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

Request a canister’s status.

pub fn create_canister(&self) -> CanisterId

Create a canister with default settings as the anonymous principal.

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

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

Create a canister on a specific subnet with optional custom settings.

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

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

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

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

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

Clear the WASM chunk store of a canister.

pub 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<(), CallError>

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

pub fn install_canister( &self, canister_id: CanisterId, 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: CanisterId, wasm_module: Vec<u8>, arg: Vec<u8>, sender: Option<Principal>, ) -> Result<(), CallError>

Upgrade a canister with a new WASM module.

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

Reinstall a canister WASM module.

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

Uninstall a canister.

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

Take canister snapshot.

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

Load canister snapshot.

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

List canister snapshots.

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

Delete canister snapshot.

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

Update canister settings.

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

Set canister’s controllers.

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

Start a canister.

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

Stop a canister.

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

Delete a canister.

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

Checks whether the provided canister exists.

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

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

Trait Implementations

impl Default for PocketIc

fn default() -> Self

Returns the “default value” for a type.

impl Drop for PocketIc

fn drop(&mut self)

Executes the destructor for this type.