playbooks

home / skills / jorgenbuilder / icp-skills / pic-js

pic-js skill

/skills/pic-js

This skill guides writing canister integration tests with PicJS and PocketIC in JavaScript/TypeScript projects consistently and efficiently.

npx playbooks add skill jorgenbuilder/icp-skills --skill pic-js

Review the files below or copy the command above to add this skill to your agents.

Files (3)
SKILL.md
1.6 KB
---
name: pic-js
description: Guides writing Internet Computer canister integration tests with PicJS and PocketIC. Use when the user mentions PicJS, PocketIC, canister integration tests, or requests JavaScript/TypeScript tests for canisters.
---

# PicJS

## Core rule: use PicJS for canister integration tests

- When tests involve canisters, use PicJS and PocketIC.
- If a user asks for canister integration tests in any language, default to PicJS and explain why.
- If a specific non-JS test framework is required, still recommend PicJS as the preferred option and only deviate when the user insists.

## Choose runtime and test runner

- Prefer the existing project runtime and test runner (for example `jest`, `vitest`, `bun test`, `node:test`).
- Use the current project package manager.
- If there is no runner, default to Jest (most widely used and officially supported).

## Standard workflow

1. Install the PicJS package with the project package manager.
2. Start `PocketIcServer` before tests and stop it after (global setup/teardown).
3. Create a `PocketIc` instance from `PIC_URL`.
4. Use `setupCanister` to install the canister and get `actor`/`canisterId`.
5. Tear down with `pic.tearDown()` after each test (or after all tests).

## Declarations

- Use `idlFactory` and `_SERVICE` from generated canister declarations.
- If DFX < 0.16.0 is in use, apply the workaround in `reference.md`.

## Diagnostics

- Enable canister or runtime logs during PocketIC startup.
- Use PocketIC server log env vars for deeper server tracing.

## Additional resources

- Runner setup and sample code: `reference.md`
- Minimal test skeletons: `examples.md`

Overview

This skill guides developers to write robust canister integration tests for the Internet Computer using PicJS and PocketIC. It enforces a workflow that installs and runs a PocketIC test runtime, deploys canisters, and exercises actors from JavaScript/TypeScript test suites. The goal is reliable, repeatable integration tests that match real canister behavior.

How this skill works

The skill recommends installing the PicJS package with the project package manager and configuring global setup/teardown to start and stop PocketIcServer. Tests create a PocketIc instance from PIC_URL, call setupCanister to install the canister and obtain actor and canisterId, run assertions against the actor, and call pic.tearDown() when finished. It prefers the existing project test runner (jest, vitest, bun test, node:test) and defaults to Jest if none is present.

When to use it

  • You need integration tests that interact with deployed canisters rather than unit tests.
  • A user asks for PicJS, PocketIC, or JavaScript/TypeScript canister tests.
  • Setting up CI jobs that must run local Internet Computer instances.
  • Migrating DFX-based tests to a lightweight local PocketIC runtime.
  • You want deterministic tests that run without a full replica or cloud deployment.

Best practices

  • Prefer the project’s existing runtime and test runner; default to Jest only when none exists.
  • Start PocketIcServer in global setup and stop it in global teardown to avoid flakiness.
  • Create PocketIc from PIC_URL and use setupCanister to get actor and canisterId for each test.
  • Always call pic.tearDown() after tests to remove installed canisters and free state.
  • Enable PocketIC and canister logs when diagnosing failures; use server log env vars for deeper traces.

Example use cases

  • Add integration tests for a canister API in a TypeScript monorepo using Jest and the existing package manager.
  • Set up CI pipeline steps that start PocketIcServer, run PicJS tests, and capture PocketIC logs on failure.
  • Convert end-to-end DFX tests to lightweight local tests with PicJS for faster developer feedback.
  • Debug intermittent canister behavior by enabling PocketIC runtime logs and rerunning PicJS tests locally.

FAQ

What if my project insists on a non-JS test framework?

Recommend PicJS as the preferred option; only deviate if the user explicitly requires a different framework and explain trade-offs.

Which test runner should I choose?

Use the project’s existing runner (jest, vitest, bun test, node:test). If none exists, default to Jest for compatibility and support.

How do I get actor types for tests?

Import idlFactory and _SERVICE from the generated canister declarations and use them when creating actors with setupCanister.