pic-ic
v0.5.3
Published
An Internet Computer Protocol canister testing library for TypeScript and JavaScript.
Downloads
1,750
Maintainers
Readme
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.