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

``shell
npm i -D @dfinity/pic
`

Install peer dependencies if they are not already installed:

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

Usage

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

`ts
import { PocketIc } from '@dfinity/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:

`ts
import { PocketIc } from '@dfinity/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 dfinity.github.io/pic-js.

Examples

All examples are written in TypeScript with Jest as the test runner,
but @dfinity/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.
- Google Search example demonstrates how to mock HTTPS Outcalls.