pic-js_skill

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.