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, 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//! - marker parsing, aggregation, comparison, and reports in [`benchmark`];
15//! - canister-side marker emission in [`performance`];
16//! - deterministic test principals through [`Fake`].
17//!
18//! The [`pocket_ic`], [`pic`], and [`artifacts`] exports are unavailable when
19//! compiling for `wasm32`; benchmark data types and marker emission remain
20//! available to canister code.
21
22pub mod benchmark;
23
24#[cfg(not(target_arch = "wasm32"))]
25mod batch;
26
27#[cfg(not(target_arch = "wasm32"))]
28mod timing;
29
30#[cfg(not(target_arch = "wasm32"))]
31pub mod artifacts;
32
33#[cfg(not(target_arch = "wasm32"))]
34pub use pocket_ic;
35
36#[cfg(not(target_arch = "wasm32"))]
37pub mod pic;
38
39pub mod performance;
40
41#[cfg(all(test, unix, not(target_arch = "wasm32")))]
42#[path = "../tests/support/executable.rs"]
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}