ic_testkit/
lib.rs

1//! Focused PocketIC test-harness utilities for Internet Computer canisters.
2//!
3//! `ic-testkit` keeps PocketIC itself visible: [`pocket_ic`] re-exports the
4//! complete upstream crate, while [`pic`] retains convenient runtime type
5//! re-exports and adds extension traits for typed Candid calls, generic
6//! installation, diagnostics, snapshots, startup errors, caller-owned
7//! managed-server startup, bounded readiness polling, and a small time conversion. It does not provide a
8//! simulator wrapper or a host-wide runtime lock.
9//!
10//! The crate also provides:
11//!
12//! - bounded artifact inspection through [`ic_host_artifacts`], filesystem
13//!   operations through [`ic_host_fs`], verified execution through
14//!   [`ic_host_process`];
15//! - marker parsing, aggregation, comparison, and reports in [`benchmark`];
16//! - canister-side marker emission in [`performance`];
17//! - deterministic test principals through [`Fake`].
18//!
19//! The [`pocket_ic`], [`pic`] and host-library exports are unavailable
20//! when compiling for `wasm32`; benchmark data types and marker emission remain
21//! available to canister code.
22
23pub mod benchmark;
24
25#[cfg(not(target_arch = "wasm32"))]
26mod batch;
27
28#[cfg(not(target_arch = "wasm32"))]
29mod timing;
30
31#[cfg(not(target_arch = "wasm32"))]
32pub use pocket_ic;
33
34#[cfg(not(target_arch = "wasm32"))]
35pub use {ic_host_artifacts, ic_host_fs, ic_host_process};
36
37#[cfg(not(target_arch = "wasm32"))]
38pub mod pic;
39
40pub mod performance;
41
42#[cfg(all(test, unix, not(target_arch = "wasm32")))]
43mod test_executable;
44
45use candid::Principal;
46
47/// Deterministic principal generator for tests.
48///
49/// Values are derived directly from a numeric seed, making fixtures stable
50/// without embedding textual principal literals.
51pub struct Fake;
52
53impl Fake {
54    /// Deterministically derive a [`Principal`] from `seed`.
55    #[must_use]
56    pub fn principal(seed: u32) -> Principal {
57        let mut buf = [0u8; 29];
58        buf[..4].copy_from_slice(&seed.to_be_bytes());
59
60        Principal::from_slice(&buf)
61    }
62}
63
64#[cfg(test)]
65mod tests {
66    use super::*;
67
68    #[test]
69    fn fake_principal_is_deterministic_and_unique() {
70        let p1 = Fake::principal(7);
71        let p2 = Fake::principal(7);
72        let q = Fake::principal(8);
73
74        assert_eq!(p1, p2, "Fake::principal should be deterministic");
75        assert_ne!(p1, q, "Fake::principal should differ for different seeds");
76
77        let bytes = p1.as_slice();
78        assert_eq!(bytes.len(), 29, "Principal must be 29 bytes");
79    }
80}
ic_testkit/lib.rs

ic_testkit/
lib.rs
