ic-testkit

Reusable PocketIC-oriented test utilities for IC canister tests.

Use this crate when you want generic host-side test infrastructure that can be shared across IC canister projects.

Toolchains:

• MSRV: Rust 1.88
• internal build/test lane: Rust 1.95

What it adds over raw pocket-ic:

• a narrower Pic wrapper that exposes the PocketIC operations this crate supports as a stable test surface
• typed startup errors for common PocketIC launch failures, including missing binaries, invalid binaries, failed downloads, server startup failures, and startup timeouts
• a cross-process PicSerialGuard for test suites that need to serialize PocketIC usage and avoid shared server/resource exhaustion
• Candid update_call and query_call helpers that encode arguments, decode results, and preserve useful canister/method context on failures
• generic create/install helpers for caller-provided wasm modules and init bytes
• install-code rate-limit retry helpers that advance PocketIC time between attempts
• canister diagnostics that dump status and logs for failed test paths
• standalone prebuilt-wasm fixtures that own their Pic, canister id, and serialization guard together
• cached baseline primitives that snapshot canisters once and restore them between tests, rebuilding automatically when a cached PocketIC instance dies
• controller snapshot helpers for capture/restore flows that need sender fallbacks
• deterministic fake principals and ledger-style accounts for reproducible tests
• wasm artifact path, readiness, build, and read helpers for host-side test harnesses
• watched-input freshness checks for generated .icp artifacts
• workspace target-directory helpers for crates living at a workspace root or under crates/

Current API shape:

• Pic is the intentional host-side wrapper surface for PocketIC calls used by this crate
• cached baseline guards expose explicit accessors instead of transparently derefing into raw PocketIc
• tests should prefer the wrapper methods and fixture helpers here instead of reaching through to the underlying PocketIC client directly

What it intentionally does not own:

• application init payloads, role names, or endpoint method constants
• application-specific readiness polling
• product-specific canister fixture graphs
• attestation-specific fixture policy
• repo-only audit probes
• broad self-test orchestration

If you are writing downstream PocketIC tests, start here. If you are editing application-specific integration harnesses, keep that code in the owning application repo instead of widening this generic surface.