PocketIC: Testing Canisters in Python 🐍

Today we’re announcing a new canister testing platform called PocketIC.

It consists of the PocketIC binary, which can run many concurrent IC instances, and a Python library which allows you to interact with those.

With PocketIC, you can test your canisters with just a few lines of Python code, either by interacting with an IC instance:

from pocket_ic import PocketIC

pic = PocketIC()
canister_id = pic.create_canister()

# use PocketIC to interact with your canisters
pic.add_cycles(canister_id, 1_000_000)
response = pic.update_call(canister_id, method="greeting", ...)
assert(response == 'Hello, PocketIC!')

… or even directly with a canister object:

my_canister = pic.create_and_install_canister_with_candid(...)

# call your canister functions with native Python syntax
respone = my_canister.greeting()
assert(response == 'Hello, PocketIC!')

Getting Started :rocket:

You can start testing your canisters in Python with PocketIC today.
To get started, take a look at the README of PocketIC and check out the examples.

How it Works :gear:

The PocketIC server is built upon the existing StateMachine infrastructure which is already being used by developers from DFINITY, OpenChat, HotOrNot, and others.

We created an HTTP layer on top of the StateMachine, so that its interface is language-agnostic. Now, anyone can create an integration library for PocketIC in any language. We took the first step by providing a Python testing library, which showcases both how to use PocketIC in tests and how to develop against the PocketIC server API.

Furthermore, using the community built IC Python agent ic-py, this library provides a convenient API to parse Candid files into native Python objects with the corresponding canister interfaces.

What Else? :face_with_monocle:

Going forward, we are planning to offer even more capabilities for canister developers, reaching beyond what the StateMachine tests offer today. In the future, you’ll be able to:

  • Use a Rust testing library with PocketIC
  • Save and load checkpoints for fast IC state reuse
  • Use VSCode’s Testing tab to run your canister tests

Feedback & Contributions :busts_in_silhouette:

We would be happy to get your feedback or feature requests on PocketIC.
Feel free to reach out to us through the GitHub repo, or here in the Comments section!