pic-ic

Pic JS

Pic JS is a library for interacting with a local instance of pocket-ic from TypeScript.

The pocket-ic is a canister testing platform for the Internet Computer. It is a standalone executable that can be used to test canisters locally, without the need to deploy them to a full replica.

Other languages available include Python and Rust.

Installation

npm i -D @hadronous/pic

Install peer dependencies if needed:

npm i -D @dfinity/{agent,candid,identity,principal}

Usage

The easist way to use PocketIC is to use setupCanister convenience method:

import { PocketIc } from '@hadronous/pic';
import { _SERVICE, idlFactory } from '../declarations';

const wasmPath = resolve('..', '..', 'canister.wasm');

const pic = await PocketIc.create();
const fixture = await pic.setupCanister<_SERVICE>(idlFactory, wasmPath);
const { actor } = fixture;

// perform tests...

await pic.tearDown();

If more control is needed, then the createCanister, installCode and createActor methods can be used directly:

import { PocketIc } from '@hadronous/pic';
import { _SERVICE, idlFactory } from '../declarations';

const wasmPath = resolve('..', '..', 'canister.wasm');

const pic = await PocketIc.create();

const canisterId = await pic.createCanister();
await pic.installCode(canisterId, wasmPath);
const actor = pic.createActor<_SERVICE>(idlFactory, canisterId);

// perform tests...

await pic.tearDown();

API Docs

More detailed documentation is available in the API docs. The best place to start is with the PocketIc class and then move onto the Actor class.

Examples

All examples are written in TypeScript with Jest as the test runner, but @hadronous/pic can be used with JavaScript and any other testing runner, such as NodeJS, bun or Mocha.

• The Counter example demonstrates how to work with a simple canister as well as canister upgrades and WASM reinstallation.
• The Clock example demonstrates how to work with the replica's system time, canister timers as well as checking for canister existence and cycle management.
• The Todo example demonstrates how to work with more complex canisters, identities, canister upgrades, and stable memory management.