# PocketIC: Testing Canisters in Python 🐍

**URL:** <https://forum.dfinity.org/t/pocketic-testing-canisters-in-python/22490>\
**Category:** Developers\
**Created:** [September 1, 2023, 2:33pm UTC](https://forum.dfinity.org/t/pocketic-testing-canisters-in-python/22490 "2023-09-01T14:33:46Z")\
**Posts on this page:** 20\
**Page:** 1

<div class="post-metadata">

**Author:** ![fxgst](https://sea1.discourse-cdn.com/flex023/user_avatar/forum.dfinity.org/fxgst/32/12439_2.png) [@fxgst](https://forum.dfinity.org/u/fxgst)\
**Post date:** [September 1, 2023, 2:33pm UTC](https://forum.dfinity.org/t/pocketic-testing-canisters-in-python/22490/1 "2023-09-01T14:33:46Z")

</div>

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:

```python
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:

```python
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 🚀

You can start testing your canisters in Python with PocketIC **today**.  
To get started, take a look at the **[README](https://github.com/dfinity/pocketic-py#readme)** of PocketIC and check out the examples.

## How it Works ⚙

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](https://github.com/rocklabs-io/ic-py)**, this library provides a convenient API to parse **Candid** files into **native Python objects** with the corresponding canister interfaces.

## What Else? 🧐

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 👥

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!

---

<div class="post-metadata">

**Author:** ![gravity\_vi](https://sea1.discourse-cdn.com/flex023/user_avatar/forum.dfinity.org/gravity_vi/32/35810_2.png) [@gravity\_vi](https://forum.dfinity.org/u/gravity_vi)\
**Post date:** [January 15, 2024, 9:14am UTC](https://forum.dfinity.org/t/pocketic-testing-canisters-in-python/22490/2 "2024-01-15T09:14:08Z")

</div>

We are facing an issue with `pocket_ic`. In our scenario a `user_index` canister manages all canister for users. And when the upgrades run for `user_index` canister it also upgrades all the individual user canisters in` post_upgrade`. Previously we used to use `state_machine` to test this scenario and one call to tick command with `advance_time` used to upgrade `user_index` and all individual canisters. With the recent move to pocket\_ic `tick` call is not upgrading all the canisters. Is there a way to determine how many tick calls would needed for the completed upgrade process.

---

<div class="post-metadata">

**Author:** ![fxgst](https://sea1.discourse-cdn.com/flex023/user_avatar/forum.dfinity.org/fxgst/32/12439_2.png) [@fxgst](https://forum.dfinity.org/u/fxgst)\
**Post date:** [January 15, 2024, 9:20am UTC](https://forum.dfinity.org/t/pocketic-testing-canisters-in-python/22490/3 "2024-01-15T09:20:49Z")

</div>

Hi @gravity_vi, thanks for your question. Are you using multiple subnets in PocketIC, or are all your canisters on the same subnet? If your canisters live on different subnets, it might be the case that more ticks are required, see [this thread](https://forum.dfinity.org/t/pocketic-multi-subnet-canister-testing/24901/4).

---

<div class="post-metadata">

**Author:** ![gravity\_vi](https://sea1.discourse-cdn.com/flex023/user_avatar/forum.dfinity.org/gravity_vi/32/35810_2.png) [@gravity\_vi](https://forum.dfinity.org/u/gravity_vi)\
**Post date:** [January 15, 2024, 9:21am UTC](https://forum.dfinity.org/t/pocketic-testing-canisters-in-python/22490/4 "2024-01-15T09:21:32Z")

</div>

It’s on the same subnet

---

<div class="post-metadata">

**Author:** ![mraszyk](https://sea1.discourse-cdn.com/flex023/user_avatar/forum.dfinity.org/mraszyk/32/7945_2.png) [@mraszyk](https://forum.dfinity.org/u/mraszyk)\
**Post date:** [January 15, 2024, 9:34am UTC](https://forum.dfinity.org/t/pocketic-testing-canisters-in-python/22490/5 "2024-01-15T09:34:10Z")

</div>

Another potential explanation is the subnet type of the subnet to which the canisters are deployed - application subnets have 10x [lower](https://github.com/dfinity/ic/blob/7b5170d04ce712c8caed1f4a86d8597948309c46/rs/config/src/subnet_config.rs#L82) round instruction limits compared to system subnets and thus you might need up to 10x more ticks if your canisters do some work in their pre- and post-upgrade hooks.

---

<div class="post-metadata">

**Author:** ![fxgst](https://sea1.discourse-cdn.com/flex023/user_avatar/forum.dfinity.org/fxgst/32/12439_2.png) [@fxgst](https://forum.dfinity.org/u/fxgst)\
**Post date:** [January 15, 2024, 9:43am UTC](https://forum.dfinity.org/t/pocketic-testing-canisters-in-python/22490/6 "2024-01-15T09:43:06Z")

</div>

Adding to @mraszyk’s comment, this comes from the fact that starting from version 2.0, PocketIC uses an application subnet by default instead of a system subnet to resemble the mainnet more closely.

---

<div class="post-metadata">

**Author:** ![gravity\_vi](https://sea1.discourse-cdn.com/flex023/user_avatar/forum.dfinity.org/gravity_vi/32/35810_2.png) [@gravity\_vi](https://forum.dfinity.org/u/gravity_vi)\
**Post date:** [January 16, 2024, 4:13pm UTC](https://forum.dfinity.org/t/pocketic-testing-canisters-in-python/22490/7 "2024-01-16T16:13:44Z")

</div>

Thanks @fxgst @mraszyk for the quick response. I will try it out

---

<div class="post-metadata">

**Author:** ![Stefs-2142](https://sea1.discourse-cdn.com/flex023/user_avatar/forum.dfinity.org/stefs-2142/32/14535_2.png) [@Stefs-2142](https://forum.dfinity.org/u/Stefs-2142)\
**Post date:** [March 7, 2024, 5:19pm UTC](https://forum.dfinity.org/t/pocketic-testing-canisters-in-python/22490/8 "2024-03-07T17:19:16Z")

</div>

Hello! I am using your framework along with Pytest for testing canisters written in Motoko. I have encountered a difficulty with defining a custom type Types.Record. I understand this question is more related to the ic-py library, but perhaps you might be able to help me.

I am confused about how exactly to describe my “frequency” field, which accepts a variable data type Frequency.

```js
    public type Position = {
        beneficiary : Principal;
        amountToSell : Nat;
        tokenToBuy : Principal;
        tokenToSell : Principal;
        frequency : Frequency;
    };

    public type Frequency = {
        #Daily;
        #Weekly;
        #Monthly;
    };

```

This is how i define Candid type and vals for it.

```Python

    position_type = Types.Record(
        {
            "beneficiary": Types.Principal,
            "amountToSell": Types.Nat,
            "tokenToBuy": Types.Principal,
            "tokenToSell": Types.Principal,
            "frequency": Types.Record(
                {
                    "Frequency": Types.Variant(
                        fields={???}
                    )
                }
            ),
        }
    )
    position_vals = {
        "beneficiary": default_principal.to_str(),
        "amountToSell": 1,
        "tokenToBuy": ckBtc_principal_id.to_str(),
        "tokenToSell": icp_principal_id.to_str(),
        "frequency": ???,
    }

```

And the next code that i used for call:

```python
    params = {"type": position_type, "value": position_vals}
    result = pic.query_call(canister_id, "openPosition", ic.encode(params=params))

```

Thank you in advance for any feedback!

---

<div class="post-metadata">

**Author:** ![michael-weigelt](https://avatars.discourse-cdn.com/v4/letter/m/b487fb/32.png) [@michael-weigelt](https://forum.dfinity.org/u/michael-weigelt)\
**Post date:** [March 8, 2024, 9:17am UTC](https://forum.dfinity.org/t/pocketic-testing-canisters-in-python/22490/9 "2024-03-08T09:17:01Z")

</div>

Hi Stefs,

If I understand correctly, you are asking how to encode a variant type for candid in json? According to [this list](https://github.com/rocklabs-io/ic-py/tree/main/examples), you need a dict with a single key-value pair. It looks like {“Daily”: 1} might do, although I have not tested this.

Does that answer your question?

---

<div class="post-metadata">

**Author:** ![fxgst](https://sea1.discourse-cdn.com/flex023/user_avatar/forum.dfinity.org/fxgst/32/12439_2.png) [@fxgst](https://forum.dfinity.org/u/fxgst)\
**Post date:** [March 8, 2024, 9:25am UTC](https://forum.dfinity.org/t/pocketic-testing-canisters-in-python/22490/10 "2024-03-08T09:25:06Z")

</div>

Hi @Stefs-2142,  
I think you want to define the variants the following way:

```python
position_type = Types.Record(
        {
            "beneficiary": Types.Principal,
            "amountToSell": Types.Nat,
            "tokenToBuy": Types.Principal,
            "tokenToSell": Types.Principal,
            "frequency": Types.Variant(
                      {
                          "Daily": Types.Null,
                          "Weekly": Types.Null,
                          "Monthly": Types.Null,
                      }
            ),
        }
    )
    position_vals = {
        "beneficiary": default_principal.to_str(),
        "amountToSell": 1,
        "tokenToBuy": ckBtc_principal_id.to_str(),
        "tokenToSell": icp_principal_id.to_str(),
        "frequency": {"Daily": None},
    }

```

And then call it like this:

```python
    payload = [{"type": position_type, "value": position_vals}]
    result = pic.query_call(canister_id, "openPosition", ic.encode(payload))

```

Please let us know if that works!

---

<div class="post-metadata">

**Author:** ![Stefs-2142](https://sea1.discourse-cdn.com/flex023/user_avatar/forum.dfinity.org/stefs-2142/32/14535_2.png) [@Stefs-2142](https://forum.dfinity.org/u/Stefs-2142)\
**Post date:** [March 8, 2024, 2:35pm UTC](https://forum.dfinity.org/t/pocketic-testing-canisters-in-python/22490/11 "2024-03-08T14:35:48Z")

</div>

Yep, my question pertains to the encoding of the Variant object. Thanks for your reply!

---

<div class="post-metadata">

**Author:** ![Stefs-2142](https://sea1.discourse-cdn.com/flex023/user_avatar/forum.dfinity.org/stefs-2142/32/14535_2.png) [@Stefs-2142](https://forum.dfinity.org/u/Stefs-2142)\
**Post date:** [March 8, 2024, 2:42pm UTC](https://forum.dfinity.org/t/pocketic-testing-canisters-in-python/22490/12 "2024-03-08T14:42:17Z")

</div>

Fantastic, thanks! Yes, that works)

I’ll pose another quick question on the topic. How should the type be correctly specified in **retTypes** for it to function properly?

Take my **openPosition** method, for instance. In my earlier message, I incorrectly referred to it as a query—my mistake, but it didn’t impact the logic. It returns the following type in Motoko:

```auto
public type PositionId = Nat;

```

To specify this type in retTypes, I used:

```python
result = pic.update_call(canister_id, "openPosition", ic.encode(params=payload)) 
assert ic.decode(result, retTypes=[Types.Nat]) == 0

```

However, the outcome was a result that wasn’t unpacked:

```auto
E AssertionError: assert [{'type': 'nat', 'value': 0}] == 0
E + where [{'type': 'nat', 'value': 0}] = <function decode at 0x7fa38401fe20>(b'DIDL\x00\x01}\x00', retTypes=[<ic.candid.NatClass object at 0x7fa384019480>])
E + where <function decode at 0x7fa38401fe20> = ic.decode

```

Am I correct in thinking that accurately defining retTypes should yield a decoded result of = `0`, rather than `{'type': 'nat', 'value': 0}`?

---

<div class="post-metadata">

**Author:** ![Stefs-2142](https://sea1.discourse-cdn.com/flex023/user_avatar/forum.dfinity.org/stefs-2142/32/14535_2.png) [@Stefs-2142](https://forum.dfinity.org/u/Stefs-2142)\
**Post date:** [March 8, 2024, 3:10pm UTC](https://forum.dfinity.org/t/pocketic-testing-canisters-in-python/22490/13 "2024-03-08T15:10:40Z")

</div>

Just opened a small issue for your framework)

> <https://github.com/dfinity/pocketic-py/issues/58>
>
> Hi!
> Looks like \*\*\_effective\_canister\_id\*\* parameter don't used in functions:
> 
> …
> \* query\_raw - https://github.com/dfinity/pocketic-py/blob/pocket\_ic/pocket\_ic.py#L540
> 
> \* update\_raw - https://github.com/dfinity/pocketic-py/blob/main/pocket\_ic/pocket\_ic.py#L547

---

<div class="post-metadata">

**Author:** ![fxgst](https://sea1.discourse-cdn.com/flex023/user_avatar/forum.dfinity.org/fxgst/32/12439_2.png) [@fxgst](https://forum.dfinity.org/u/fxgst)\
**Post date:** [March 11, 2024, 7:31am UTC](https://forum.dfinity.org/t/pocketic-testing-canisters-in-python/22490/14 "2024-03-11T07:31:18Z")

</div>

Hi @Stefs-2142, decoding candid can be a bit cumbersome. Candid always returns tuples, so first you need to take the first element from the tuple that is returned (there is only one element) with `[0]`. Then, you get the dict with `{'type': ..., 'value' ...}`, so to get the value, just add `['value']`.  
So in total, to get out the result value in your case, you type

```auto
ic.decode(result, retTypes=[Types.Nat])[0]['value']

```

then you get back

```auto
0

```

instead of

```auto
[{'type': 'nat', 'value': 0}]

```

if you just did

```auto
ic.decode(result, retTypes=[Types.Nat])

```

I hope this helps!

---

<div class="post-metadata">

**Author:** ![Stefs-2142](https://sea1.discourse-cdn.com/flex023/user_avatar/forum.dfinity.org/stefs-2142/32/14535_2.png) [@Stefs-2142](https://forum.dfinity.org/u/Stefs-2142)\
**Post date:** [March 19, 2024, 4:56pm UTC](https://forum.dfinity.org/t/pocketic-testing-canisters-in-python/22490/15 "2024-03-19T16:56:35Z")

</div>

Hey!  
Thank you.  
Indeed, this is the exact conclusion I arrived at regarding unpacking. It appears that `retType` has no impact on the outcome.

---

<div class="post-metadata">

**Author:** ![fxgst](https://sea1.discourse-cdn.com/flex023/user_avatar/forum.dfinity.org/fxgst/32/12439_2.png) [@fxgst](https://forum.dfinity.org/u/fxgst)\
**Post date:** [November 20, 2024, 9:32am UTC](https://forum.dfinity.org/t/pocketic-testing-canisters-in-python/22490/16 "2024-11-20T09:32:16Z")

</div>

**Update:** [PocketIC Python version 3.0](https://pypi.org/project/pocket-ic/3.0.0/) has been released! 🎉  
It now supports the latest and greatest PocketIC server in version [7.0](https://github.com/dfinity/pocketic/releases/tag/7.0.0), which was released last week. Note that it does not support all the latest features that the server offers (e.g., HTTP outcalls, Bitcoin or auto progress mode).  
We do not have immediate plans to add these features to PocketIC Python, but we are more than happy for external [contributions](https://github.com/dfinity/pocketic-py)!

---

<div class="post-metadata">

**Author:** ![fxgst](https://sea1.discourse-cdn.com/flex023/user_avatar/forum.dfinity.org/fxgst/32/12439_2.png) [@fxgst](https://forum.dfinity.org/u/fxgst)\
**Post date:** [April 28, 2025, 11:31am UTC](https://forum.dfinity.org/t/pocketic-testing-canisters-in-python/22490/17 "2025-04-28T11:31:22Z")

</div>

🎉 **PocketIC Python 3.1** has been [released](https://pypi.org/project/pocket-ic/3.1.0/) today! New features: support for PocketIC server version 9.0, and the ability to store and load state to/from a directory on your computer. Happy testing!

---

<div class="post-metadata">

**Author:** ![0x4d5a](https://sea1.discourse-cdn.com/flex023/user_avatar/forum.dfinity.org/0x4d5a/32/15654_2.png) [@0x4d5a](https://forum.dfinity.org/u/0x4d5a)\
**Post date:** [May 30, 2025, 4:44pm UTC](https://forum.dfinity.org/t/pocketic-testing-canisters-in-python/22490/18 "2025-05-30T16:44:38Z")

</div>

@mraszyk @fxgst  
Does the PocketIC Py support HTTPS Outcalls?

---

<div class="post-metadata">

**Author:** ![mraszyk](https://sea1.discourse-cdn.com/flex023/user_avatar/forum.dfinity.org/mraszyk/32/7945_2.png) [@mraszyk](https://forum.dfinity.org/u/mraszyk)\
**Post date:** [May 30, 2025, 6:00pm UTC](https://forum.dfinity.org/t/pocketic-testing-canisters-in-python/22490/19 "2025-05-30T18:00:38Z")

</div>

Canister http outcalls are performed via an inter-canister call from a canister. Hence, their support is transparent to the PocketIC (Python) library and they are supposed to work.

---

<div class="post-metadata">

**Author:** ![fxgst](https://sea1.discourse-cdn.com/flex023/user_avatar/forum.dfinity.org/fxgst/32/12439_2.png) [@fxgst](https://forum.dfinity.org/u/fxgst)\
**Post date:** [June 2, 2025, 8:44am UTC](https://forum.dfinity.org/t/pocketic-testing-canisters-in-python/22490/20 "2025-06-02T08:44:01Z")

</div>

Hi, HTTPS outcalls are currently not supported with PocketIC Python, as it does not have the ability to mock responses, but also does not support the “live” mode, where PocketIC produces blocks “automatically”, which would be required to perform actual calls to HTTP endpoints.

[Next page](https://forum.dfinity.org/t/pocketic-testing-canisters-in-python/22490.md?page=2)
