jorgenbuilder/icp-skills
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
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.
3 skills
This skill guides writing canister integration tests with PicJS and PocketIC in JavaScript/TypeScript projects consistently and efficiently.
This skill enables secure, read-only research of forum.dfinity.org by browsing topics and users using authenticated GET requests.
This skill guides you through using the ICP CLI icp for local networks, builds, deploys, canister operations, and environments.
