Skip to content
Documentation

AO Process Testing

This section provides an overview of how to test AO processes.

In order to test AO processes, you need to have a basic understanding of the following:

  • busted - Busted is a unit testing framework for Lua. You can learn more about Busted from the official documentation
  • Ao Process Testing Suite - AO processes are tested using the AO Testing Suite. You can learn more about the AO Testing Suite from the official documentation

Process Testing Directory Structure

If you generate a new process using the Create Ao dApp, the directory structure of the process will look somewhat like this:

process-name/             # Your process's root directory.
├── scripts/              # Utility scripts for the process.
│   ├── build.sh          # Build script for the process.
│   ├── deploy.sh         # Deploy script for the process.
│   └── test.sh           # Test script for the process.
└── src/                  # Source code for the process.
    ├── test/             # Test directory for the process.
    │   ├── mocked-env    # Mocked env files to test the process.
    │   ├── setup.lua     # AO Testing Suite setup file.
    │   └── process_test.lua # Test script for the process.
    ├── process_lib.lua   # Library for the process.
    ├── process.lua       # Entry point for the process.
    └── reset_modules.lua # Reset preloaded modules.

We will now discuss the contents of the test directory in detail.

Test Directory

The test directory contains the following files:

  • mocked-env - This directory contains the mocked environment files that are used to test the process. The mocked environment files are used to mock the environment variables that are used in the process. The mocked environment files are used to test the process in different environments.
  • setup.lua - This file is used to set up the AO Testing Suite. The setup file is used to set up the AO Testing Suite before running the tests. The setup file is used to set up the environment variables that are used in the process.
  • process_test.lua - This file contains the actual test script and cases for the process.

Writing tests

Now that you have a basic understanding of the directory structure of the process, let's write some tests for the process.

Writing a test case

To write a test case for the process, you need to create a new test case in the process_test.lua file. The test case should be written using the Busted syntax.

process-name/src/test/process_test.lua
---@diagnostic disable: duplicate-set-field
require("test.setup")()
 
_G.IsInUnitTest    = true -- set this per test file to keep ao.send() from doing anything
_G.VerboseTests    = 2    -- how much logging to see (0 - none at all, 1 - important ones, 2 - everything)
-- optional logging function that allows for different verbosity levels
_G.printVerb       = function(level)
    level = level or 2
    return function(...) -- define here as global so we can use it in application code too
        if _G.VerboseTests >= level then print(table.unpack({ ... })) end
    end
end
 
 
-- Require the process library and the process file
local process      = require "process_lib" 
 
-- Define initial state
_G.Version = "1.0.0" 
_G.Balances = _G.Balances or { ["0x123"] = 1000 } 
_G.TotalSupply = _G.TotalSupply or 1000
_G.Name = "test token" 
 
-- This function resets the global variables to their initial state
local resetGlobals = function() 
  _G.Version = "1.0.0" 
  _G.Balances = _G.Balances or { ["0x123"] = 1000 } 
  _G.TotalSupply = _G.TotalSupply or 1000
  _G.Name = "test token" 
end
 
describe("token process", function() 
    setup(function() 
        -- Mock the sendReply function
        process.sendReply = function(message) 
            return message 
        end
    end) 
 
    describe("getBalance", function() 
        it("should return correct Balance", function() 
            local message = { 
                From = "0x123", 
                Action = "Balance", 
                Tags = {} 
            } 
 
            local response = process.getBalance(message) 
            assert.are.same(1000, response.Balance) 
 
            -- reset globals
            resetGlobals() 
        end) 
    end) 
end)

Running the tests

Create Ao dApp provides a test script that can be used to run the tests for the process. The test script is located in the ./ao/process-name/scripts directory of the process.

To run the tests for the process, you need to run the test script using the following command from the project root:

Terminal
cd ao/process-name && ./scripts/test.sh