# pic-ic

> An Internet Computer Protocol canister testing library for TypeScript and JavaScript.

Latest version **0.7.0** (published 2025-01-04) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install pic-ic
pnpm add pic-ic
yarn add pic-ic
bun add pic-ic
```

## Health

**Score 30/100 (F)** — status: maintenance-mode.

Positive: has types; no vulnerabilities.

Warnings: low downloads; no esm support; pre 1.0.

Negative: stale; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.7.0 |
| Published | 2025-01-04 |
| First published | 2023-12-19 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 1 |
| Unpacked size | 182.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | Hadronous Labs |
| Maintainers | zen.voich |
| Keywords | internet-computer, internet-computer-protocol, icp, smart-contracts, smart-contract, canisters, pocket-ic, testing, integration-testing, testing-tools |

## Links

- npm: https://www.npmjs.com/package/pic-ic
- Repository: https://github.com/hadronous/pic-js
- Homepage: https://hadronous.github.io/pic-js
- Issues: https://github.com/hadronous/pic-js/issues
- npm.io page: https://npm.io/package/pic-ic

## Dependencies (1)

- [bip39](https://npm.io/package/bip39.md) ^3.1.0

## Alternatives

- [duck](https://npm.io/package/duck.md) — 4.2M weekly downloads
- [ava](https://npm.io/package/ava.md) — 560.2K weekly downloads
- [storybook-addon-module-mock](https://npm.io/package/storybook-addon-module-mock.md) — 71.7K weekly downloads
- [vest](https://npm.io/package/vest.md) — 50.1K weekly downloads
- [@ethereum-waffle/mock-contract](https://npm.io/package/@ethereum-waffle/mock-contract.md) — 40.0K weekly downloads

## Recent versions

- 0.7.0 (latest) — 2025-01-04
- 0.5.4 (patch) — 2025-08-06
- 0.6.0 — 2025-01-04
- 0.5.3 — 2024-09-12
- 0.5.2 — 2024-09-12
- 0.5.1 — 2024-08-26
- 0.5.0 — 2024-08-26
- 0.4.0 — 2024-08-05
- 0.3.3 — 2024-01-09
- 0.3.2 — 2023-12-19
- 0.3.1 — 2023-12-19
- 0.3.0 — 2023-12-19

## 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](https://internetcomputer.org/). 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](https://github.com/dfinity/pocketic-py/) and [Rust](https://github.com/dfinity/ic/tree/master/packages/pocket-ic).

## Installation

```shell
npm i -D @hadronous/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 '@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:

```ts
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](https://hadronous.github.io/pic-js/).

## Examples

All examples are written in [TypeScript](https://www.typescriptlang.org/) with [Jest](https://jestjs.io/) as the test runner,
but `@hadronous/pic` can be used with JavaScript and any other testing runner, such as [NodeJS](https://nodejs.org/dist/latest-v20.x/docs/api/test.html), [bun](https://bun.sh/docs/cli/test) or [Mocha](https://mochajs.org/).

- The [Counter](https://github.com/hadronous/pic-js/tree/main/examples/counter/README.md) example demonstrates how to work with a simple canister as well as init arguments, canister upgrades and WASM reinstallation.
- The [Clock](https://github.com/hadronous/pic-js/tree/main/examples/clock/README.md) 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](https://github.com/hadronous/pic-js/tree/main/examples/todo/README.md) example demonstrates how to work with more complex canisters, identities, canister upgrades, and stable memory management.
- The [Multicanister](https://github.com/hadronous/pic-js/tree/main/examples/multicanister/README.md) example demonstrates how to work with multiple canisters and multiple subnets.
- The [NNS Proxy](https://github.com/hadronous/pic-js/tree/main/examples/nns_proxy/README.md) example demonstrates how to work with an NNS state directory.
- [Google Search](https://github.com/hadronous/pic-js/tree/main/examples/google_search/README.md) example demonstrates how to mock HTTPS Outcalls.

---
_Source: https://npm.io/package/pic-ic · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._