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//! - host-only transactional artifacts, Wasm builds, and freshness helpers in
13//!   [`artifacts`];
14//! - bounded artifact inspection through [`ic_host_artifacts`], filesystem
15//!   operations through [`ic_host_fs`], verified execution through
16//!   [`ic_host_process`], and IC-specific helpers through [`ic_host_tools`];
17//! - marker parsing, aggregation, comparison, and reports in [`benchmark`];
18//! - canister-side marker emission in [`performance`];
19//! - deterministic test principals through [`Fake`].
20//!
21//! The [`pocket_ic`], [`pic`], [`artifacts`] and host-library exports are unavailable
22//! when compiling for `wasm32`; benchmark data types and marker emission remain
23//! available to canister code.
24
25pub mod benchmark;
26
27#[cfg(not(target_arch = "wasm32"))]
28mod batch;
29
30#[cfg(not(target_arch = "wasm32"))]
31mod timing;
32
33#[cfg(not(target_arch = "wasm32"))]
34pub mod artifacts;
35
36#[cfg(not(target_arch = "wasm32"))]
37pub use pocket_ic;
38
39#[cfg(not(target_arch = "wasm32"))]
40pub use {ic_host_artifacts, ic_host_fs, ic_host_process, ic_host_tools};
41
42#[cfg(not(target_arch = "wasm32"))]
43pub mod pic;
44
45pub mod performance;
46
47#[cfg(all(test, unix, not(target_arch = "wasm32")))]
48mod test_executable;
49
50use candid::Principal;
51
52/// Deterministic principal generator for tests.
53///
54/// Values are derived directly from a numeric seed, making fixtures stable
55/// without embedding textual principal literals.
56pub struct Fake;
57
58impl Fake {
59    /// Deterministically derive a [`Principal`] from `seed`.
60    #[must_use]
61    pub fn principal(seed: u32) -> Principal {
62        let mut buf = [0u8; 29];
63        buf[..4].copy_from_slice(&seed.to_be_bytes());
64
65        Principal::from_slice(&buf)
66    }
67}
68
69#[cfg(test)]
70mod tests {
71    use super::*;
72
73    #[test]
74    fn fake_principal_is_deterministic_and_unique() {
75        let p1 = Fake::principal(7);
76        let p2 = Fake::principal(7);
77        let q = Fake::principal(8);
78
79        assert_eq!(p1, p2, "Fake::principal should be deterministic");
80        assert_ne!(p1, q, "Fake::principal should differ for different seeds");
81
82        let bytes = p1.as_slice();
83        assert_eq!(bytes.len(), 29, "Principal must be 29 bytes");
84    }
85}
ic_testkit/lib.rs

ic_testkit/
lib.rs
