Unit Testing

Welcome to the Olympix Unit Test Generator documentation! This guide will walk you through how to automatically generate unit tests (and even mutation tests) for your Solidity smart contracts using the Olympix CLI. Follow these steps to set up your environment and get started.

Overview

The Olympix Unit Test Generator works in tandem with the Foundry toolchain to create:

Unit tests for your contracts
Mutation tests to assess the quality of your existing tests

Prerequisites

Before running the generator, ensure you have completed the following:

Step-by-Step Guide

1. Ensure Your Forge Remappings Are Accurate

Your project must compile successfully with Forge. Double-check your remappings in the project configuration to avoid any compilation issues.

2. Create `OlympixUnitTest.sol`

A special file named OlympixUnitTest.sol is required in your Foundry test directory. This file contains the base contract for your unit tests.

Copy and paste the following content into OlympixUnitTest.sol to set up the foundation for your tests.

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;
abstract contract OlympixUnitTest {
    constructor(string memory _name) {}
}

3. Create Your Unit Test Skeleton

For each contract you wish to test, create a unit test file that adheres to the Forge naming convention:
<contractName>.t.sol

Your test skeleton should:

Import the contract you intend to test
Import the OlympixUnitTest contract from OlympixUnitTest.sol
Define any required state variables
Include a setUp() function to initialize the testing environment.
Any helper functions/example tests that you want the test generator to build off of.

Example unit test skeleton

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;

import "../contracts/MyContract.sol";       // Adjust the path as needed
import "./OlympixUnitTest.sol";

contract MyContractTest is OlympixUnitTest("MyContract") {
    MyContract public myContract;

    // setUp() is run before each test
    function setUp() public {
        myContract = new MyContract();
    }

    // Example test function
    function testExample() public {
        // Example assertion using a helper from OlympixUnitTest
        uint expected = 42;
        uint actual = myContract.someFunction();
        assertEqual(expected, actual);
    }
}

For a detailed example, check out this YouTube tutorial.

4. Run the Unit Test Generator

Navigate to the root folder of your Solidity project and execute the following command in your terminal:

olympix generate-unit-tests -w .

This command launches an interactive mode where you can select the contracts for which unit tests should be generated. After a brief processing period, the results will be emailed to your registered address.

5. Review and Utilize the Results

Once you receive the email:

Examine the generated unit tests.
Integrate them into your project.
Iterate on the tests as needed to improve coverage.

Need Help?

If you encounter any issues or have questions, feel free to reach out:

Email: contact@olympix.ai

Happy testing!