Crate gclient 

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.

Usage

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:

# ...

[dev-dependencies]
gclient = { git = "https://github.com/gear-tech/gear.git" }
tokio = { version = "1.23.0", features = ["full"] }

[patch.crates-io]
sp-core = { git = "https://github.com/gear-tech/substrate.git", branch = "gear-stable" }
sp-runtime = { git = "https://github.com/gear-tech/substrate.git", branch = "gear-stable" }

Download the latest node binary for your operating system from https://get.gear.rs. 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

Examples

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

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

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

#[tokio::test]
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
    assert!(listener.blocks_running().await?);

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

    // Upload and init the program
    let (message_id, program_id, _hash) = api
        .upload_program_bytes_by_path(
            WASM_PATH,
            gclient::now_micros().to_le_bytes(),
            vec![],
            gas_info.min_limit,
            0,
        )
        .await?;

    assert!(listener.message_processed(message_id).await?.succeed());

    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)
        .await?;

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

    assert!(listener.message_processed(message_id).await?.succeed());

    Ok(())
}

Modules

ext

gear

Generated runtime API types.

Structs

EventListener

Event listener that allows catching and processing events propagated through the network.

GearApi

The API instance contains methods to access the node.

ProgramStateChange

Program state change item.

ProgramStateChanges

Subscription of program state changes.

UserMessageReply

Reply-specific details for a user message.

UserMessageSent

Structured representation of pallet_gear::Event::UserMessageSent notifications.

UserMessageSentFilter

Filter options for gear_subscribeUserMessageSent.

UserMessageSentSubscription

Subscription of user message notifications.

WSAddress

Full WebSocket address required to specify the node.

Enums

DispatchStatus

Dispatch status returned after processing a message.

Error

Common error type.

Traits

EventProcessor

Events processing trait.

Functions

code_from_os

Read and return contents of a Wasm file specified by the path.

hex_to_vec

Convert hex string to byte array.

now_micros

Returns time elapsed since UNIX_EPOCH in microseconds.

wasm_target

Return the full path to the optimized Wasm binary file with the demo_name name located in the root_path directory.

Type Aliases

Event

The outer event enum.

GearEvent

The Event enum of this pallet

Result

Result type with a predefined error type (Error).