dfinity / pocketic Goto Github PK

View Code? Open in Web Editor NEW

19.0 7.0 0.0 22 KB

A canister smart contract testing solution for the Internet Computer.

License: Other

blockchain icp internetcomputer smart-contracts testing-framework

pocketic's Introduction

PocketIC

PocketIC is a canister smart contract testing solution for the Internet Computer.

Download the PocketIC Server

You can find the versions of the PocketIC server under the Releases tab on the right. For macOS, choose pocket-ic-x86_64-darwin.gz, for Linux, choose pocket-ic-x86_64-linux.gz.

Save the downloaded file as pocket-ic.gz, decompress it, and make it executable:

gzip -d pocket-ic.gz
chmod +x pocket-ic

On macOS, you might have to additionally run:

xattr -dr com.apple.quarantine pocket-ic

to bypass the developer verification from Apple. Alternatively, you can open the pocket-ic binary by right clicking on it in the Finder and selecting "Open" from the drop-down menu. Then, confirm opening this application by clicking "Open" in the dialog that pops up.

Using PocketIC

After completion of above steps, you can verify that everything works by running:

./pocket-ic --help

which prints information on how to use the PocketIC server from the command line.

Client Libraries

To write canister tests in your projects with PocketIC, it is recommended to use one of the client libraries. The following libraries are available:

If you want your client library to be listed here, please post to the Forum!

Why PocketIC?

Canister developers have several options to test their software, but there are tradeoffs:

Install and test on the mainnet: The 'real' experience, but you pay with real cycles.
The replica provided by DFX: You get the complete stack of a single IC node. But therefore, you get no cross- or multisubnet functionality, and likely never will. Replica is quite heavyweight too, because the nonessential components are not abstracted away. Furthermore, testing with replica is not deterministic.

Enter PocketIC:

Deterministic: Synchronous control over the IC's execution environment
Lightweight: Mocks the consensus and networking layers
Versatile: Runs as a service on your test system, and accepts HTTP/JSON. This enables:
- Concurrent and independent IC instances by default - sharing is possible
- Multi-language support: Anyone can write an integration library against the PocketIC REST-API in any language
Support for multiple subnets and Xnet calls

Source Code

The source code of the PocketIC server is available on GitHub.

Contributing

Would you like to write canister tests in a different language? The PocketIC server has a JSON/REST interface, against which you may implement a user-facing library in any language.

To see a documentation of the server's endpoints, PocketIC offers an endpoint /api.json, which will return an OpenAPI specification. You can then use tools like the Swagger Editor to display the returned JSON in a more human readable way.

If you decide to contribute, we encourage you to announce it on the Forum!

pocketic's People

Contributors

Stargazers

Watchers

pocketic's Issues

Cannot deploy via `dfx deploy ...` to pocket-ic replica that runs from CLI

pocket-ic binary 2.0.1
dfx 0.15.2

I run pocket-ic by

$ pocket-ic -p 4943
2023-12-08T11:16:51.855200Z  INFO pocket_ic_server: The PocketIC server is listening on port 4943

Then I deploy by

$ dfx deploy main
Error: The replica returned an HTTP Error: Http Error: status 404 Not Found, content type "", content:

Same error for dfx canister create main.

Does replica REST API work on pocket-ic?

Also would be helpful to have documentation on how to use pocket-ic from CLI

Timer Support

Is there currently timer support for pocketic?
I am using advanceTime() and tick() but nothing seems to be triggering it in my motoko canister

Using pocket-ic-rs goes err

I have downlaod pocket-ic v2.0.1
I have config POCKET_IC_BIN in linux env
and

// this code goes err
  let mut replica = PocketIcBuilder::new()
    .with_nns_subnet()
    .with_application_subnet()
    .build();

// Err here:
running 1 test
test backend_test::nns_wallet_test::create_a_nns_wallet has been running for over 60 seconds
2023-11-28T11:26:54.383046Z  INFO pocket_ic_server: The PocketIC server is listening on port 36587
thread 'backend_test::nns_wallet_test::create_a_nns_wallet' panicked at /home/btwl/.cargo/registry/src/index.crates.io-6f17d22bba15001f/pocket-ic-2.0.1/src/lib.rs:183:14:
Could not parse response for create instance request: reqwest::Error { kind: Decode, source: Error("EOF while parsing a value", line: 1, column: 0) }
stack backtrace:
   0: rust_begin_unwind
             at /rustc/cc66ad468955717ab92600c770da8c1601a4ff33/library/std/src/panicking.rs:595:5
   1: core::panicking::panic_fmt
             at /rustc/cc66ad468955717ab92600c770da8c1601a4ff33/library/core/src/panicking.rs:67:14
   2: core::result::unwrap_failed
             at /rustc/cc66ad468955717ab92600c770da8c1601a4ff33/library/core/src/result.rs:1652:5
   3: core::result::Result<T,E>::expect
             at /rustc/cc66ad468955717ab92600c770da8c1601a4ff33/library/core/src/result.rs:1034:23
   4: pocket_ic::PocketIc::from_config
             at /home/btwl/.cargo/registry/src/index.crates.io-6f17d22bba15001f/pocket-ic-2.0.1/src/lib.rs:177:45

running 1 test
2023-11-28T11:28:05.774075Z  INFO pocket_ic_server: The PocketIC server is listening on port 44779
thread 'backend_test::nns_wallet_test::create_a_nns_wallet' panicked at /home/btwl/.cargo/registry/src/index.crates.io-6f17d22bba15001f/pocket-ic-2.0.1/src/lib.rs:183:14:
Could not parse response for create instance request: reqwest::Error { kind: Decode, source: Error("EOF while parsing a value", line: 1, column: 0) }
stack backtrace:

running 1 test
2023-11-28T11:36:23.677311Z  INFO pocket_ic_server: The PocketIC server is listening on port 33855
thread 'backend_test::nns_wallet_test::create_a_nns_wallet' panicked at /home/btwl/.cargo/registry/src/index.crates.io-6f17d22bba15001f/pocket-ic-2.0.1/src/lib.rs:183:14:
Could not parse response for create instance request: reqwest::Error { kind: Decode, source: Error("EOF while parsing a value", line: 1, column: 0) }
stack backtrace:
   0: rust_begin_unwind
             at /rustc/cc66ad468955717ab92600c770da8c1601a4ff33/library/std/src/panicking.rs:595:5
   1: core::panicking::panic_fmt
             at /rustc/cc66ad468955717ab92600c770da8c1601a4ff33/library/core/src/panicking.rs:67:14
   2: core::result::unwrap_failed
             at /rustc/cc66ad468955717ab92600c770da8c1601a4ff33/library/core/src/result.rs:1652:5
   3: core::result::Result<T,E>::expect
             at /rustc/cc66ad468955717ab92600c770da8c1601a4ff33/library/core/src/result.rs:1034:23
   4: pocket_ic::PocketIc::from_config
             at /home/btwl/.cargo/registry/src/index.crates.io-6f17d22bba15001f/pocket-ic-2.0.1/src/lib.rs:177:45
   5: pocket_ic::PocketIcBuilder::build
             at /home/btwl/.cargo/registry/src/index.crates.io-6f17d22bba15001f/pocket-ic-2.0.1/src/lib.rs:84:9
   6: integration_tests::client::setup::setup_new_env
             at ./backend/integration_tests/src/client/setup.rs:29:21
   7: integration_tests::backend_test::nns_wallet_test::create_a_nns_wallet
             at ./backend/integration_tests/src/backend_test/nns_wallet_test.rs:6:3
   8: integration_tests::backend_test::nns_wallet_test::create_a_nns_wallet::{{closure}}
             at ./backend/integration_tests/src/backend_test/nns_wallet_test.rs:4:30
   9: core::ops::function::FnOnce::call_once
             at /rustc/cc66ad468955717ab92600c770da8c1601a4ff33/library/core/src/ops/function.rs:250:5
  10: core::ops::function::FnOnce::call_once
             at /rustc/cc66ad468955717ab92600c770da8c1601a4ff33/library/core/src/ops/function.rs:250:5
note: Some details are omitted, run with `RUST_BACKTRACE=full` for a verbose backtrace.
test backend_test::nns_wallet_test::create_a_nns_wallet ... FAILED

failures:

failures:
    backend_test::nns_wallet_test::create_a_nns_wallet

test result: FAILED. 0 passed; 1 failed; 0 ignored; 0 measured; 0 filtered out; finished in 39.98s

Release binaries on GitHub?

Hi. I'm currently adding toolchain version management to mops (moc, wasmtime, pocket-ic).

And it would be easier if there are will be binaries available on GitHub releases, so I can reuse logic which I use to download moc and wasmtime binaries.

Also no need to hardcode version => hash mapping for each version(and keep it up to date), but just rely on github release tag (latest or specific version tag)

Some hyperlink is inaccessible

in here : https://crates.io/crates/pocket-ic
red marked is missing link

CanisterInstallCodeRateLimited errors after upgrading from 1.0

After upgrading from 1.0 to 2.0 we are experiencing this error in our CI:

UserError(UserError { code: CanisterInstallCodeRateLimited, description: "Canister lxzze-o7777-77777-aaaaa-cai is rate limited because it executed too many instructions in the previous install_code messages. Please retry installation after several minutes." })

Is there a fix for it?

{
  ...
  "/instances/": {
    "get": {
      "responses": {
        "200": {
          "description": "",
          "content": {
            "application/json": {
              "schema": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "post": {
      "requestBody": {
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ExtendedSubnetConfigSet"
            }
          }
        },
        "required": true
      }
    }
  },
  ...
}

Will ` let pic = PocketIc::new();` create a new empty env every time?

Or i need to mannually exec uninstall canister to empty stable memory everytime ?