Crate gclient

source ·
Expand description

Utility library for writing end-to-end tests for Gear programs.

This crate can be considered a companion of the gtest when covering the program code with tests. When gtest is most appropriate for unit and integration tests, gclient fits better for higher-level debugging.

gclient is intended to test Gear programs with a real blockchain network. It allows you to send extrinsics and RPCs by connecting to the network.

It is essential to underline that testing with gclient requires the running node as the second part of the test suite. The gclient interacts with the node over the WebSocket protocol. Depending on the purpose of testing, gclient can communicate with either a local or a remote node. The best choice is to use the local node in developer mode for initial debugging and continuous integration.

Testing with gclient is slower than gtest and produces more build artifacts, so it is better suited as the last mile in quality control. However, gclient gives the most accurate test results.


To use the gclient library, you must import it into your Cargo.toml file in the [dev-dependencies] block. Also, you need to add some external crates that are used together with gclient:

# ...

gclient = { git = "" }
tokio = { version = "1.23.0", features = ["full"] }

sp-core = { git = "", branch = "gear-stable" }
sp-runtime = { git = "", branch = "gear-stable" }

Download the latest node binary for your operating system from Then unpack the package and run the node. Here we assume the node is running in developer mode:

./gear --dev

The final step is to write tests in a separate tests directory and make cargo to execute them:

cargo test


Simple test example that uploads the program and sends the PING message.

use gclient::{EventProcessor, GearApi, Result};

const WASM_PATH: &str = "./target/wasm32-unknown-unknown/release/first_gear_app.opt.wasm";

async fn test_example() -> Result<()> {
    // Create API instance
    let api = GearApi::dev().await?;

    // Subscribe to events
    let mut listener = api.subscribe().await?;

    // Check that blocks are still running

    // Calculate gas amount needed for initialization
    let gas_info = api
        .calculate_upload_gas(None, gclient::code_from_os(WASM_PATH)?, vec![], 0, true)

    // Upload and init the program
    let (message_id, program_id, _hash) = api


    let payload = b"PING".to_vec();

    // Calculate gas amount needed for handling the message
    let gas_info = api
        .calculate_handle_gas(None, program_id, payload.clone(), 0, true)

    // Send the PING message
    let (message_id, _hash) = api
        .send_message_bytes(program_id, payload, gas_info.min_limit, 0)





  • Event listener that allows catching and processing events propagated through the network.
  • The API instance contains methods to access the node.
  • Full WebSocket address required to specify the node.




  • Read and return contents of a Wasm file specified by the path.
  • Convert hex string to byte array.
  • Returns time elapsed since UNIX_EPOCH in microseconds.
  • Return the full path to the optimized Wasm binary file with the demo_name name located in the root_path directory.
  • Compile a source WebAssembly Text (WAT) to Wasm binary code.

Type Definitions

  • Result type with a predefined error type (Error).