ic_testkit/pic/
baseline.rs

1use super::{
2    CanisterSnapshotTarget, ControllerSnapshotError, ControllerSnapshots, PocketIcInstance,
3    PocketIcSnapshotExt, SnapshotRestoreFunding,
4};
5use ic_platform::pocket_ic::PocketIc;
6use ic_platform::principal::ExternalPrincipal as Principal;
7
8/// One owned `PocketIC` instance/server record with snapshots and caller metadata.
9///
10/// The value contains no synchronization. A [`super::PocketIcBaselineRecipe`]
11/// can own it as its fixture in a [`super::CachedPocketIcBaselinePool`].
12pub struct CachedPocketIcBaseline<T> {
13    instance: PocketIcInstance<PocketIc>,
14    snapshots: ControllerSnapshots,
15    metadata: T,
16}
17
18impl<T> CachedPocketIcBaseline<T> {
19    /// Capture a cached baseline with an explicit sender for every canister.
20    ///
21    /// Empty inputs are rejected before capture. Capture is ordered and transactional as documented by
22    /// [`PocketIcSnapshotExt::capture_snapshots`]. No sender fallback is performed.
23    ///
24    /// # Errors
25    /// Returns a controller snapshot error if target admission or snapshot capture fails.
26    pub fn capture<I>(
27        instance: PocketIcInstance<PocketIc>,
28        targets: I,
29        metadata: T,
30    ) -> Result<Self, ControllerSnapshotError>
31    where
32        I: IntoIterator<Item = CanisterSnapshotTarget>,
33    {
34        let mut targets = targets.into_iter().peekable();
35        if targets.peek().is_none() {
36            return Err(ControllerSnapshotError::EmptyCanisterSet);
37        }
38        let snapshots = instance.instance().capture_snapshots(targets)?;
39        Ok(Self {
40            instance,
41            snapshots,
42            metadata,
43        })
44    }
45
46    /// Restore with exactly the captured senders and selected cycle funding.
47    /// Success means the complete captured set was restored.
48    ///
49    /// # Errors
50    /// Returns a controller snapshot error if funding or snapshot restoration fails.
51    pub fn restore(&self, funding: SnapshotRestoreFunding) -> Result<(), ControllerSnapshotError> {
52        self.instance
53            .instance()
54            .restore_snapshots(&self.snapshots, funding)
55    }
56
57    /// Borrow the owned `PocketIC` instance behind this cached baseline.
58    #[must_use]
59    pub const fn pocket_ic(&self) -> &PocketIc {
60        self.instance.instance()
61    }
62
63    /// Return the number of canisters captured by this baseline.
64    #[must_use]
65    pub fn snapshot_count(&self) -> usize {
66        self.snapshots.len()
67    }
68
69    /// Iterate over captured canister ids in deterministic principal order.
70    pub fn snapshot_canister_ids(&self) -> impl Iterator<Item = Principal> + '_ {
71        self.snapshots.canister_ids()
72    }
73
74    /// Borrow the captured metadata associated with this cached baseline.
75    #[must_use]
76    pub const fn metadata(&self) -> &T {
77        &self.metadata
78    }
79
80    /// Mutably borrow the captured metadata associated with this cached baseline.
81    #[must_use]
82    pub const fn metadata_mut(&mut self) -> &mut T {
83        &mut self.metadata
84    }
85}
ic_testkit/pic/baseline.rs

ic_testkit/pic/
baseline.rs
