Testing with `gclient`
gclient is intended to be used as a tool for testing Vara programs with a real blockchain network. It allows sending extrinsics and RPCs by connecting to the network. gclient is recommended for end-to-end testing to ensure the program works as expected in the real blockchain world.
It is essential to note that testing with gclient requires a running node as the second part of the test suite. gclient interacts with the node over the WebSocket protocol. Depending on the testing purpose, gclient can communicate with either a local or a remote node. Using a local node in developer mode is the best choice for initial debugging and continuous integration.
Testing with gclient is slower than gtest and produces more build artifacts, making it better suited as the final step in quality control. However, gclient provides the most accurate test results.
Import gclient Library
To use the gclient library, import it into the Cargo.toml file in the [dev-dependencies] block. Also, add some external crates that are used together with gclient:
[package]
name = "first-gear-app"
version = "0.1.0"
authors = ["Your Name"]
edition = "2021"
[dependencies]
gstd = { git = "https://github.com/gear-tech/gear.git", tag = "v1.1.1", features = ["debug"] }
[build-dependencies]
gear-wasm-builder = { git = "https://github.com/gear-tech/gear.git", tag = "v1.1.1" }
[dev-dependencies]
gclient = { git = "https://github.com/gear-tech/gear.git", tag = "v1.1.1" }
tokio = { version = "1", features = ["full"] }Running the Node
The best way is to download the latest node binary for your operating system from https://get.gear.rs. Then unpack the package and run the node. Here and below, the node is assumed to be running in developer mode.
Terminal:
curl https://get.gear.rs/gear-v1.1.1-x86_64-unknown-linux-gnu.tar.xz | tar xJor
Linux x86-64: gear-v1.1.1-x86_64-unknown-linux-gnu.tar.xz
You can try to run the node:
❯ ./gear --version
gear 1.1.1-33ee05d5aabTerminal:
curl https://get.gear.rs/gear-v1.1.1-aarch64-apple-darwin.tar.xz | tar xJor
macOS ARM: gear-v1.1.1-aarch64-apple-darwin.tar.xz
You can try to run the node:
❯ ./gear --version
gear 1.1.1-33ee05d5aabTerminal:
curl https://get.gear.rs/gear-v1.1.1-x86_64-apple-darwin.tar.xz | tar xJor
macOS x86-64: gear-v1.1.1-x86_64-apple-darwin.tar.xz
You can try to run the node:
❯ ./gear --version
gear 1.1.1-33ee05d5aabTerminal:
curl -O https://get.gear.rs/gear-v1.1.1-x86_64-pc-windows-msvc.zipor
Windows x86-64: gear-v1.1.1-x86_64-pc-windows-msvc.zip
Unzip the downloaded package then you can try to run the node:
❯ gear.exe --version
gear 1.1.1-33ee05d5aabOpen the second terminal window and run tests using cargo as described in the previous section.
Simple Example
Add an end-to-end test to the first-gear-app introduced in the Getting Started section.
Add the tests directory next to the src directory and create the end2end.rs file in it.
└── first-gear-app
├── Cargo.toml
├── src
│ └── lib.rs
└── tests
└── end2end.rsend2end.rs:
use gclient::{EventProcessor, GearApi, Result};
const WASM_PATH: &str = "./target/wasm32-unknown-unknown/release/first_gear_app.opt.wasm";
#[tokio::test]
#[ignore]
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(())
}Run the following command and wait for all tests to be green:
cargo test --release -- --include-ignoredIt is recommended to mark tests with gclient with the #[ignore] attribute to separate their slow execution from the rest. To execute ignored tests with Cargo, add the --include-ignored flag after a double dash (--) as shown above.
More Details About gclient
Please refer to the gclient docs for more information about its capabilities and use cases.