Getting Started

PocketIC is a deterministic, lightweight and versatile testing solution for Internet Computer canisters.

PicJS provides bindings to interact with PocketIC from Typescript and JavaScript.

JavaScript runtime environment

Tests written with PicJS are executed in a JavaScript runtime environment, such as NodeJS.

To get started with PicJS, you will need to have a JavaScript runtime environment installed on your system. If you’re new to JavaScript, then NodeJS is the recommended choice.

PicJS requires NodeJS 22.12 or newer. On older versions, loading PicJS fails with require() of ES Module ... not supported.

Bun is an alternative JavaScript runtime environment that is compatible with PicJS. Bun has several features that make it a great choice for running PicJS tests, such as a built-in test runner and assertion library in addition to being much more performant than NodeJS. Bun is not very widely used yet, so it is not recommended for beginners.

Deno in theory should also work, but it is not officially supported and compatibility is not actively tested. If you choose Deno and run into issues, please open an issue on the GitHub repository. Deno is also not widely used, so it is not recommended for developers that are unfamiliar with it.

Package manager

PicJS is a JavaScript/TypeScript package distributed on NPM. To install and manage NPM packages, you will need to have an NPM-compatible package manager.

• npm
  • This is the official package manager for NodeJS and comes pre-installed.
  • Beginners should stick with this option.
• pnpm
  • A fast, disk space-efficient package manager.
  • A great alternative to npm for more experienced developers.
• Yarn
  • A package manager that doubles down as a project manager.
  • Another great alternative to npm for more experienced developers.
• Bun
  • Bun also includes a built-in package manager.
  • This is convenient if you are already using Bun as your runtime environment or test runner.

Installing PicJS

Install @dfinity/pic as a development dependency:

npm

npm i -D @dfinity/pic

pnpm

pnpm i -D @dfinity/pic

bun

bun add -d @dfinity/pic

yarn

yarn add -D @dfinity/pic

Installing @icp-sdk/core

@dfinity/pic has @icp-sdk/core v6 as a peer dependency. Principal, Identity and your canister’s idlFactory all cross the PicJS API, so PicJS uses your project’s copy of core rather than bringing its own. Your generated canister declarations import it already; if your project does not depend on it yet, or depends on an older major, install v6:

npm

npm i @icp-sdk/core@^6

pnpm

pnpm i @icp-sdk/core@^6

bun

bun add @icp-sdk/core@^6

yarn

yarn add @icp-sdk/core@^6

npm, pnpm and Bun install a missing peer dependency automatically; Yarn does not. If your project is on an older major, npm fails the install with ERESOLVE, while pnpm, Bun and Yarn warn about the unmet peer dependency.

Allowing the install script

PicJS downloads the pocket-ic binary from a postinstall script rather than bundling it with the library. npm, pnpm and Bun all block install scripts by default, so this one has to be permitted or the binary will be missing and tests will fail to start a server.

Add the entry for your package manager to package.json, then install:

Package manager	Entry in package.json
npm	"allowScripts": { "@dfinity/pic": true }
pnpm	"pnpm": { "onlyBuiltDependencies": ["@dfinity/pic"] }
Bun	"trustedDependencies": ["@dfinity/pic"]
Yarn	Not needed — Yarn runs postinstall by default

If you installed before adding this, run the install command again to fetch the binary.

If you provide the PocketIC binary yourself, with the binPath option or the POCKET_IC_BIN environment variable, the install script is not needed and can stay blocked.

icp-cli

PicJS tests run against your canister’s compiled WASM module, so any build tool works. The examples in this repository build their canisters with icp-cli, the command-line tool for building and deploying Internet Computer projects. See its documentation for installation.

PicJS also needs your canister’s Candid declarations; see the Canister declarations guide for how to generate them.

Test runner

PicJS tests can be run with any test runner that runs on NodeJS or Bun (in theory the same should be true for Deno, but that is not actively tested).

The following test runners are actively tested and officially supported:

• Jest
  • Recommended if you’re new to JavaScript testing because it has the largest community and is the most widely used.
  • See the Jest guide for details on getting started with Jest and PicJS.
• Vitest
  • If you’re already using Vite and Vitest for your frontend, then this is a good choice to reduce your dev dependencies.
  • See the Vitest guide for details on getting started with Vitest and PicJS.
• Bun
  • If you’re already using Bun, or want to try it out, then this is a good choice.
  • This is not recommended for beginners because it is less widely used and still immature compared to the other options.
  • See the Bun guide for details on getting started with Bun and PicJS.