Crate pocket_ic_harness 

A test harness for Internet Computer canisters using PocketIC.

This crate provides reusable utilities for integration testing IC canisters:

• Canister trait — define your canisters and their WASM paths
• CanisterSetup trait — define how canisters are installed before each test
• PocketIcTestEnv — generic test environment with canister installation and registry
• PocketIcClient — typed query/update calls with Candid encoding
• init_new_agent — create IC agents against PocketIC endpoints
• test — proc-macro attribute for automatic setup/teardown

Quick Start

Define your canisters and setup:

use std::path::Path;
use candid::Encode;
use pocket_ic_harness::{Canister, CanisterSetup, PocketIcTestEnv};

#[derive(Debug, Clone, Hash, PartialEq, Eq)]
enum MyCanister {
    Backend,
}

impl Canister for MyCanister {
    fn as_path(&self) -> &Path {
        match self {
            MyCanister::Backend => Path::new("path/to/backend.wasm.gz"),
        }
    }

    fn all_canisters() -> &'static [Self] {
        &[Self::Backend]
    }
}

struct MySetup;

impl CanisterSetup for MySetup {
    type Canister = MyCanister;

    async fn setup(env: &mut PocketIcTestEnv<Self>) {
        let init_arg = Encode!(&()).unwrap();
        env.install_canister(MyCanister::Backend, init_arg).await;
    }
}

Write tests with the proc-macro — canisters are already installed:

#[pocket_ic_harness::test]
async fn test_my_canister(ctx: PocketIcTestEnv<MySetup>) {
    let canister_id = ctx.canister_id(&MyCanister::Backend);
    // test your canister...
}

Structs

PocketIcClient

A typed client for making query and update calls to a canister via PocketIC.

PocketIcTestEnv

Test environment for PocketIC-based integration tests.

Traits

Canister

Trait for identifying a canister and locating its WASM binary.

CanisterSetup

Trait for defining canister installation and configuration.

Functions

admin

Returns the admin test principal.

alice

Returns the Alice test principal.

bob

Returns the Bob test principal.

init_new_agent

Creates a new IC agent connected to the PocketIC HTTP endpoint.

Attribute Macros

test

Attribute macro for PocketIC integration tests.