Struct ic_kit::MockContext

pub struct MockContext { /* private fields */ }

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 watch(&self) -> &Watcher

Reset the current watcher on the MockContext and return a reference to it.

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();

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();

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();

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();

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();

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();

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_consume_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_expect_cycles_handler(self, cycles: u64) -> Self

Create a mock context with a default handler that expects this amount of cycles to be passed to it.

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 with_constant_return_handler<T: CandidType>(self, value: T) -> Self

Create a mock context with a default handler that returns the given value.

pub fn with_handler<T: 'static + CallHandler>(self, handler: T) -> Self

Add the given handler to the handlers pipeline.

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

Use this context as the default context for this thread.

pub fn sign(data: &[u8]) -> Vec<u8>

Sign a data and return the certificate, this is the method used in set_certified_data to set the data certificate for the given certified data.

impl MockContext

pub fn call_state_reset(&self)

Reset the state after a call.

pub fn clear_storage(&self)

Clear the storage.

pub fn update_balance(&self, cycles: u64)

Update the balance of the canister.

pub fn update_msg_cycles(&self, cycles: u64)

Update the cycles of the next message.

pub fn update_caller(&self, caller: Principal)

Update the caller for the next message.

pub fn update_id(&self, canister_id: Principal)

Update the canister id the call happens from for the next message.

pub fn get_certified_data(&self) -> Option<Vec<u8>>

Return the certified data set on the canister.

pub fn use_handler<T: 'static + CallHandler>(&mut self, handler: T)

Add the given handler to the call handlers pipeline.

pub fn clear_handlers(&mut self)

Remove all of the call handlers that are already registered to this context.

pub fn join(&mut self)

Block the current thread until all the spawned futures are complete.

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>(&self, data: T)

Store the given data to the storage.

fn get_maybe<T: 'static>(&self) -> Option<&T>

Return the data that does not implement Default.

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 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<S: Into<String>>(
    &'static self,
    id: Principal,
    method: S,
    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 spawn<F: 'static + Future<Output = ()>>(&mut self, future: F)

Execute a future without blocking the current call.

fn stable_size(&self) -> u32

Returns the current size of the stable memory in WebAssembly pages. (One WebAssembly page is 64KiB)

fn stable_grow(&self, new_pages: u32) -> Result<u32, StableMemoryError>

Tries to grow the memory by new_pages many pages containing zeroes. This system call traps if the previous size of the memory exceeds 2^32 bytes. Errors if the new size of the memory exceeds 2^32 bytes or growing is unsuccessful. Otherwise, it grows the memory and returns the previous size of the memory in pages.

fn stable_write(&self, offset: u32, buf: &[u8])

Writes data to the stable memory location specified by an offset.

fn stable_read(&self, offset: u32, buf: &mut [u8])

Reads data from the stable memory location specified by an offset.

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

Perform the call and return the response.

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