Skip to main content

How to test a Gear program

Basics​

Gear uses the standard testing mechanism for Rust programs: build and run testing executables using cargo.

Following basic concepts and testing methods described in Rustbook, you can organize tests in two main categories: unit tests and integration tests.

The unit tests enable testing of each unit of code in isolation from the rest of the code. It helps to quickly find where the code works as expected and where it does not. One should place unit tests in the src directory in each file with the code they test.

Even when code units work correctly, it is crucial to test if several library parts work together correctly. For integration tests, a separate tests directory is required at the top level of your project directory, next to src. You can make as many test files in this directory as you need. cargo will compile each file as an individual crate.

How to test a program

There are at least two ways how to test and debug Gear programs.

The first is the off-chain testing using a low-level gtest crate. This approach is recommended for unit and integration tests.

The second is the on-chain testing with a higher level gclient crate. It perfectly fits the needs of end-to-end testing.

Although gclient is aimed at end-to-end testing, tests can be written as unit or integration tests in terms of Rust. We recommend using the integration-like approach with separate test files in the tests directory when using the gclient crate.

Building a program in test mode​

First, be sure you have a compiled Wasm file of the program you want to test. You can refer to Getting Started for additional details.

  1. Usually, the following command is used for the regular compilation of Gear smart contracts:

    cd ~/gear/contracts/first-gear-app/
    cargo build --release

    The nightly compiler is required if some unstable features have been used:

    cargo +nightly build --release

  2. The minimal command for running tests is:

    cargo test

    The nightly compiler is required if your contract uses unstable Rust features, and the compiler will ask you to enable nightly if necessary.

    cargo +nightly test

    Build tests in release mode, so they run faster:

    cargo test --release

Dig deeper​

In the following two sections, we will describe how to test the Gear program using both gtest and gclient crates.