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