Struct ic_kit::MockContext

pub struct MockContext { /* fields omitted */ }

A context that could be used to fake/control the behaviour of the IC when testing the canister.

Implementations

impl MockContext

pub fn new() -> Self

Create a new mock context which could be injected for testing.

pub fn with_id(self, id: Principal) -> Self

Set the ID of the canister.

Example

use ic_kit::*;

let id = Principal::from_text("ai7t5-aibaq-aaaaa-aaaaa-c").unwrap();

MockContext::new()
    .with_id(id.clone())
    .inject();

let ic = get_context();
assert_eq!(ic.id(), id);

pub fn with_balance(self, cycles: u64) -> Self

Set the balance of the canister.

Example

use ic_kit::*;

MockContext::new()
    .with_balance(1000)
    .inject();

let ic = get_context();
assert_eq!(ic.balance(), 1000);

pub fn with_caller(self, caller: Principal) -> Self

Set the caller for the current call.

Example

use ic_kit::*;

let alice = Principal::from_text("ai7t5-aibaq-aaaaa-aaaaa-c").unwrap();

MockContext::new()
    .with_caller(alice.clone())
    .inject();

let ic = get_context();
assert_eq!(ic.caller(), alice);

pub fn with_msg_cycles(self, cycles: u64) -> Self

Make the given amount of cycles available for the call. This amount of cycles will be deduced if the call accepts them or will be refunded. If the canister accepts any cycles the balance of the canister will be increased.

Example

use ic_kit::*;

MockContext::new()
    .with_msg_cycles(1000)
    .inject();

let ic = get_context();
assert_eq!(ic.msg_cycles_available(), 1000);
ic.msg_cycles_accept(300);
assert_eq!(ic.msg_cycles_available(), 700);

pub fn with_data<T: 'static>(self, data: T) -> Self

Initialize the context with the given value inserted in the storage.

Example

use ic_kit::*;

MockContext::new()
    .with_data(String::from("Hello"))
    .inject();

let ic = get_context();
assert_eq!(ic.get::<String>(), &"Hello".to_string());

pub fn with_stable<T: Serialize>(self, data: T) -> Self where
    T: ArgumentEncoder, 

Initialize the context with the given value inserted into the stable storage.

Example

use ic_kit::*;

MockContext::new()
    .with_stable(("Bella".to_string(), ))
    .inject();

let ic = get_context();
assert_eq!(ic.stable_restore::<(String, )>(), Ok(("Bella".to_string(), )));

pub fn with_certified_data(self, data: Vec<u8>) -> Self

Set the certified data of the canister.

pub fn with_canister(self, id: Principal, canister: MockCanister) -> Self

Add the given canister with the given id to this context.

pub fn with_default_handler<T: for<'de> ArgumentDecoder<'de>, R: ArgumentEncoder, F: 'static + Fn(&mut MockContext, String, T) -> CallResult<R>>(
    self,
    handler: F
) -> Self

Define a call handler that could be used for any canister/method that is not found in the registered canisters.

pub fn with_accept_cycles_handler(self, cycles: u64) -> Self

Creates a mock context with a default handler that accepts the given amount of cycles on every request.

pub fn with_refund_cycles_handler(self, cycles: u64) -> Self

Creates a mock context with a default handler that refunds the given amount of cycles on every request.

pub fn inject(self) -> &'static mut Self

Use this context as the default context for this thread.

impl MockContext

pub fn call_state_reset(&mut self)

Reset the state after a call.

pub fn clear_storage(&mut self)

Clear the storage.

pub fn update_balance(&mut self, cycles: u64)

Update the balance of the canister.

pub fn update_msg_cycles(&mut self, cycles: u64)

Update the cycles of the next message.

pub fn update_caller(&mut self, caller: Principal)

Update the caller for the next message.

pub fn use_accept_cycles_handler(&mut self, cycles: u64)

Set the default handler to be a method that accepts the given amount of cycles on every request.

pub fn use_refund_cycles_handler(&mut self, cycles: u64)

Set the default handler to be a method that refunds the given amount of cycles on every request.

Trait Implementations

impl Context for MockContext

fn trap(&self, message: &str) -> !

Trap the code.

fn print<S: AsRef<str>>(&self, s: S)

Print a message.

fn id(&self) -> Principal

ID of the current canister.

fn time(&self) -> u64

The time in nanoseconds.

fn balance(&self) -> u64

The balance of the canister.

fn caller(&self) -> Principal

The caller who has invoked this method on the canister.

fn msg_cycles_available(&self) -> u64

Return the number of available cycles that is sent by the caller.

fn msg_cycles_accept(&self, cycles: u64) -> u64

Accept the given amount of cycles, returns the actual amount of accepted cycles.

fn msg_cycles_refunded(&self) -> u64

Return the cycles that were sent back by the canister that was just called. This method should only be called right after an inter-canister call.

fn store<T: 'static + Default>(&self, data: T)

Store the given data to the storage.

fn get_mut<T: 'static + Default>(&self) -> &mut T

Return a mutable reference to the given data type, if the data is not present the default value of the type is constructed and stored. The changes made to the data during updates is preserved.

fn delete<T: 'static + Default>(&self) -> bool

Remove the data associated with the given data type.

fn stable_store<T>(&self, data: T) -> Result<(), Error> where
    T: ArgumentEncoder, 

Store the given data to the stable storage.

fn stable_restore<T>(&self) -> Result<T, String> where
    T: for<'de> ArgumentDecoder<'de>, 

Restore the data from the stable storage. If the data is not already stored the None value is returned.

fn call_raw(
    &'static self,
    id: Principal,
    method: &'static str,
    args_raw: Vec<u8>,
    cycles: u64
) -> CallResponse<Vec<u8>>

Perform a call.

fn set_certified_data(&self, data: &[u8])

Set the certified data of the canister, this method traps if data.len > 32.

fn data_certificate(&self) -> Option<Vec<u8>>

Returns the data certificate authenticating certified_data set by this canister.

fn get<T: 'static + Default>(&self) -> &T

Return the data associated with the given type. If the data is not present the default value of the type is returned.

fn call<T: ArgumentEncoder, R: for<'a> ArgumentDecoder<'a>>(
    &'static self,
    id: Principal,
    method: &'static str,
    args: T
) -> CallResponse<R>

Perform the call and return the response.

fn call_with_payment<T: ArgumentEncoder, R: for<'a> ArgumentDecoder<'a>>(
    &'static self,
    id: Principal,
    method: &'static str,
    args: T,
    cycles: u64
) -> CallResponse<R>