Guide to testing Move transactions

Testing of the Move transaction described in this document is under development. Support for this feature will depend on its use and acceptance by the Aptos community.

If you are a Move smart contract developer, you can use Move transaction testing to create and run end-to-end tests.

This guide describes the steps for creating and running end-to-end Move transaction tests using the Aptos CLI.

  • Aptos CLI installation guide
  • Aptos CLI installation guide

Compared to Move unit tests, which are useful for verifying the correctness of in-module code, Move transaction testing allows you to test a wider range of use cases, such as Move unit publishing and inter-module communication.

  1. Overview
  2. Quick Start
  3. Examples


For an overview of what Move transaction testing looks like, see the aptos_test_harness GitHub folder.

The Move transaction test suite consists of two types of files:

  • Move files with the *.move extension. These Move files contain transaction testing. Transaction tests are Rust clap (Command Line Argument Parser) commands. They are written as symbols in the Move files. To distinguish them from normal Move characters, transaction test commands are provided with a special character string indicator //# .
  • Baseline files with the *.exp extension. These baseline files will be created empty the first time you run the aptos CLI. If you run the test with the UB=1 option the first time, the baseline files will be populated with the test results.

Quick Start

Before getting into the details, you can follow these steps to run a sample to test the Move transaction and see the results.

Step 1: Install the Aptos CLI

Make sure you have installed the aptos Aptos CLI tool. For how to install and use the aptos CLI tool, see 👇 .

  • Aptos CLI installation guide
  • Aptos CLI installation guide

Step 2: Run the Move transactional test suite

  • Clone or download the aptos-core repository on GitHub.
  • The Move transactional test suite is located in aptos-core/aptos-move/aptos-transactional-test-harness/test .
  • Run the aptos CLI command with the move transactional-test option.

When running the aptos CLI command, make sure that you enable UB=1 only the first time or if you have updated the tests as shown below.

UB=1 aptos move transactional-test --root-path aptos-core/aptos-move/aptos-transactional-test-harness/test
Enter fullscreen mode Exit fullscreen mode
  • The --root-path parameter indicates where all the tests are located.
  • The test runs through a directory hierarchy and finds tests specified as characters with a special prefix //####code>, in files whose names end with .move or .mvir.
  • The Move transaction testing program runs tests and compares the test results with the base files. The base files store the contents of the results that were obtained during the first run.


This section provides examples showing how to create and run various commands to test a Move transaction.

Creating an account

//# create_account —name Alice [--initial-coins 10000]
Enter fullscreen mode Exit fullscreen mode

The create_account command generates a deterministic private key/public key pair and creates the named account address (Alice in the above example).

Initial coins can be specified, otherwise the default value of 10000 is used.

Publish modules

//# publish [--gas-budget 100]
module Alice::first_module {
    public entry fun foo() {
Enter fullscreen mode Exit fullscreen mode

The command publish publishes a Move module to the specified account (Alice in the above example). Optionally, the number of gas units allowed to publish a transaction can be specified via --gas-budget.

The default value is the maximum number of coins available on the sender account.

Running the module script functions

//# run --signers Alice [--args x"68656C6C6F20776F726C64"] [--type-args "0x1::aptos_coin::AptosCoin"] [--expiration 1658432810] [--sequence-number 1] [--gas-price 1] [--show-events] -- Alice::first_module::function_name
Enter fullscreen mode Exit fullscreen mode

The run command launches a module script function by sending a transaction.

In the above example:

Executing scripts.

//# run --script --signers Alice [--args x"68656C6C6F20776F726C64"] [--type-args "0x1::aptos_coin::AptosCoin"] [--expiration 1658432810] [--sequence-number 1] [--gas-price 1]
script {
    use aptos_framework::coin;
    use aptos_framework::aptos_coin::AptosCoin;

    fun main(sender: &signer, receiver: address, amount: u64) {
        coin::transfer<AptosCoin>(sender, receiver, amount);
Enter fullscreen mode Exit fullscreen mode

The run command can also be used with the -script option to execute a script.

Resource Viewing

//# view_resource --address Alice --type 0x1::coin::CoinStore<0x1::test_coin::TestCoin> [--field coin.value]
Enter fullscreen mode Exit fullscreen mode

View_resource displays the resources contained in the address.

View tables

//# view_table --table_handle 5713946181763753045826830927579154558 --key_type 0x1::string::String --key_value x"68656C6C6F20776F726C64" --value_type 0x1::token::Collection 
Enter fullscreen mode Exit fullscreen mode

View_table displays the element in the table by the element key. For example, in the code below Move:

struct Collections has key {
    collections: Table<string::String, Collection>,
Enter fullscreen mode Exit fullscreen mode
  • In the repository, the table collections has a handle stored in the resource Collections.
  • To query a table item by key, we need to know the handle information of the table --table_handle 5713946181763753045826830927579154558.
  • The --key_type parameter is information about the key type. To get the key value, use the view_table option with the --key_type and --key_value parameters.
  • The --key_value is the key that is used to get the value.
  • The --value_type parameter is the type information to deserialize the table value. The returned store value must also be deserialized to be useful. Therefore, --value_type is also required.

Оцените статью
Добавить комментарий