ic_testkit/pic/
standalone.rs

1use super::{
2    Pic, PicSerialGuard, StandaloneCanisterFixtureError, try_acquire_pic_serial_guard, try_pic,
3};
4
5const DEFAULT_EXTRA_INSTALL_CYCLES: u128 = 0;
6
7///
8/// StandaloneCanisterFixture
9///
10
11pub struct StandaloneCanisterFixture {
12    pic: Pic,
13    canister_id: candid::Principal,
14    _serial_guard: PicSerialGuard,
15}
16
17impl StandaloneCanisterFixture {
18    /// Borrow the PocketIC instance that owns this standalone fixture.
19    #[must_use]
20    pub const fn pic(&self) -> &Pic {
21        &self.pic
22    }
23
24    /// Mutably borrow the PocketIC instance that owns this standalone fixture.
25    #[must_use]
26    pub const fn pic_mut(&mut self) -> &mut Pic {
27        &mut self.pic
28    }
29
30    /// Read the installed canister id for this standalone fixture.
31    #[must_use]
32    pub const fn canister_id(&self) -> candid::Principal {
33        self.canister_id
34    }
35
36    /// Consume the fixture and return the owned PocketIC instance and canister id.
37    #[must_use]
38    pub fn into_parts(self) -> (Pic, candid::Principal) {
39        (self.pic, self.canister_id)
40    }
41}
42
43// Install one already-built wasm module into a fresh PocketIC instance with
44// caller-provided init args and no application-specific bootstrap assumptions.
45#[must_use]
46pub fn install_prebuilt_canister(wasm: Vec<u8>, init_bytes: Vec<u8>) -> StandaloneCanisterFixture {
47    try_install_prebuilt_canister(wasm, init_bytes)
48        .unwrap_or_else(|err| panic!("failed to install prebuilt canister fixture: {err}"))
49}
50
51// Install one already-built wasm module into a fresh PocketIC instance with
52// caller-provided init args and no application-specific bootstrap assumptions.
53pub fn try_install_prebuilt_canister(
54    wasm: Vec<u8>,
55    init_bytes: Vec<u8>,
56) -> Result<StandaloneCanisterFixture, StandaloneCanisterFixtureError> {
57    try_install_prebuilt_canister_with_cycles(wasm, init_bytes, DEFAULT_EXTRA_INSTALL_CYCLES)
58}
59
60// Install one already-built wasm module into a fresh PocketIC instance with
61// caller-provided init args and explicit install cycles.
62#[must_use]
63pub fn install_prebuilt_canister_with_cycles(
64    wasm: Vec<u8>,
65    init_bytes: Vec<u8>,
66    install_cycles: u128,
67) -> StandaloneCanisterFixture {
68    try_install_prebuilt_canister_with_cycles(wasm, init_bytes, install_cycles)
69        .unwrap_or_else(|err| panic!("failed to install prebuilt canister fixture: {err}"))
70}
71
72// Install one already-built wasm module into a fresh PocketIC instance with
73// caller-provided init args and explicit install cycles.
74pub fn try_install_prebuilt_canister_with_cycles(
75    wasm: Vec<u8>,
76    init_bytes: Vec<u8>,
77    install_cycles: u128,
78) -> Result<StandaloneCanisterFixture, StandaloneCanisterFixtureError> {
79    let serial_guard =
80        try_acquire_pic_serial_guard().map_err(StandaloneCanisterFixtureError::SerialGuard)?;
81    let pic = try_pic().map_err(StandaloneCanisterFixtureError::Start)?;
82    let canister_id = pic
83        .try_create_and_install_with_args(wasm, init_bytes, install_cycles)
84        .map_err(StandaloneCanisterFixtureError::Install)?;
85
86    Ok(StandaloneCanisterFixture {
87        pic,
88        canister_id,
89        _serial_guard: serial_guard,
90    })
91}
ic_testkit/pic/standalone.rs

ic_testkit/pic/
standalone.rs
