ic_testkit/lib.rs
1//! Focused `PocketIC` test-harness utilities for Internet Computer canisters.
2//!
3//! Import native `PocketIC` clients and DTOs from `ic_testkit::pocket_ic`.
4//! `pic` adds optional typed Wire calls, extension traits for
5//! installation, diagnostics and snapshots, startup errors, caller-owned
6//! managed-server startup and bounded readiness polling. It does not provide a
7//! simulator wrapper or a host-wide runtime lock.
8//!
9//! The crate also provides:
10//!
11//! - marker parsing, aggregation, comparison, and reports in [`benchmark`];
12//! - canister-side marker emission in `performance` (Wasm only);
13//! - deterministic test principals through [`fake_principal`].
14//!
15//! The `pic` helpers are unavailable
16//! when compiling for `wasm32`; parsing and analysis are native-only. Benchmark
17//! data types, checked marker formatting and marker emission remain
18//! available to canister code.
19
20pub mod benchmark;
21
22#[cfg(not(target_arch = "wasm32"))]
23pub mod pocket_ic;
24
25#[cfg(not(target_arch = "wasm32"))]
26pub mod pic;
27
28#[cfg(target_arch = "wasm32")]
29pub mod performance;
30
31use ic_platform_types::principal::ExternalPrincipal as Principal;
32
33/// Deterministically derive a test [`Principal`] from `seed`.
34///
35/// Values are derived directly from a numeric seed, making fixtures stable
36/// without embedding textual principal literals.
37#[must_use]
38pub fn fake_principal(seed: u32) -> Principal {
39 let mut buf = [0u8; 29];
40 buf[..4].copy_from_slice(&seed.to_be_bytes());
41
42 Principal::from_slice(&buf)
43}
44
45#[cfg(test)]
46mod tests {
47 use super::*;
48
49 #[test]
50 fn fake_principal_is_deterministic_and_unique() {
51 let p1: Principal = fake_principal(7);
52 let p2 = fake_principal(7);
53 let q = fake_principal(8);
54
55 assert_eq!(p1, p2, "fake_principal should be deterministic");
56 assert_ne!(p1, q, "fake_principal should differ for different seeds");
57
58 let bytes = p1.as_slice();
59 assert_eq!(bytes.len(), 29, "Principal must be 29 bytes");
60 }
61}