@hadronous/pic

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 they are not already installed:

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

Usage

The easiest 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();

Documentation

More detailed documentation is available over at hadronous.github.io/pic-js.

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 init arguments, 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.
• The Multicanister example demonstrates how to work with multiple canisters and multiple subnets.
• The NNS Proxy example demonstrates how to work with an NNS state directory.