Skip to content

PocketIC Python: A Canister Testing Library for the Internet Computer

License

Notifications You must be signed in to change notification settings

dfinity/pocketic-py

Repository files navigation

PocketIC Python: A Canister Testing Library

PocketIC is a local canister testing solution for the Internet Computer.
This testing library works together with the PocketIC server, allowing you to interact with your local IC instances and the canisters thereon.

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

from pocket_ic import PocketIC

pic = PocketIC()
canister_id = pic.create_canister()
pic.add_cycles(canister_id, 2_000_000_000_000)  # 2T cycles
pic.install_code(...)

# make canister calls
response = pic.update_call(canister_id, method="greet", ...)
assert(response == 'Hello, PocketIC!')

... or even directly with a canister object:

my_canister = pic.create_and_install_canister_with_candid(...)
# call your canister methods with native Python syntax
response = my_canister.greet()
assert(response == 'Hello, PocketIC!')

Getting Started

Quickstart

  • Download the latest PocketIC server from the PocketIC repo that is compatible with the library version you're using.
  • Leave the binary in your current working directory, or specify the path to the binary by setting the POCKET_IC_BIN environment variable before running your tests.
  • Run pip3 install pocket-ic in your (virtual) environment to get the Python library.
  • Use from pocket_ic import PocketIC in your Python code and start testing!

Examples

To see some working code, see the examples/ folder, or check out the how to use this library guide. To run an example, clone this repo and run python3 examples/counter_canister/counter_canister_test.py from the repository's root directory. To see a minimalistic setup of PocketIC in a Motoko project, check out the ICP Hello World Motoko repository.

Documentation

Contributing

See CONTRIBUTING.md