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-unknown-unknown/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

• errors
• ext
• metadata

Structs

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

Enums

• DispatchStatus
  Dispatch status returned after processing a message.
• Error
  Common error type.
• Event
• GearEvent
  The Event enum of this pallet

Traits

• EventProcessor
  Events processing trait.

Functions

• bank_address
  Returns default bank address.
• 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.
• wat2wasm
  Compile a source WebAssembly Text (WAT) to Wasm binary code.

Type Aliases

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