Best Practices for Writing Unit Tests in Solidity

By Robert F3 min readFebruary 21, 2026

Structuring Your Tests

A well-structured test suite enhances readability and maintainability. Here’s a recommended structure for your Solidity test files:

Setup: Initialize your contracts and any required variables.
Test Cases: Group related tests together, often by functionality.
Teardown: Clean up or reset the environment if needed.

Example Structure

const MyContract = artifacts.require("MyContract");

contract("MyContract", (accounts) => {
    let myContract;

    beforeEach(async () => {
        myContract = await MyContract.new();
    });

    describe("Functionality Tests", () => {
        it("should perform action X correctly", async () => {
            // Test logic here
        });

        it("should revert when action Y is performed incorrectly", async () => {
            // Test logic here
        });
    });

    afterEach(async () => {
        // Clean up logic if necessary
    });
});

Utilizing Assertions

Assertions are the backbone of unit testing. They allow you to verify that your contract behaves as expected. In Solidity, you can use the Chai assertion library alongside Mocha for your tests.

Common Assertions

Assertion Type	Description	Example Code
`equal`	Checks if two values are equal	`assert.equal(result, expected);`
`notEqual`	Checks if two values are not equal	`assert.notEqual(result, unexpected);`
`isTrue`	Checks if a condition is true	`assert.isTrue(condition);`
`isFalse`	Checks if a condition is false	`assert.isFalse(condition);`
`throws`	Checks if a function throws an error	`await assert.isRejected(myContract.functionCall());`

Example Assertion Usage

const { assert } = require("chai");

describe("Token Transfer", () => {
    it("should transfer tokens correctly", async () => {
        await myContract.transfer(accounts[1], 100);
        const balance = await myContract.balanceOf(accounts[1]);
        assert.equal(balance.toString(), '100', "Balance should be 100 after transfer");
    });

    it("should revert on insufficient balance", async () => {
        await assert.isRejected(myContract.transfer(accounts[2], 1000), "Insufficient balance");
    });
});

Testing Events

Events are a crucial part of smart contracts, providing an interface for off-chain applications to listen to state changes. Testing events ensures that your contract emits the correct notifications.

Example Event Testing

First, define an event in your contract:

event Transfer(address indexed from, address indexed to, uint256 value);

Then, test that the event is emitted correctly:

it("should emit Transfer event on successful transfer", async () => {
    const result = await myContract.transfer(accounts[1], 100);
    const event = result.logs[0];

    assert.equal(event.event, "Transfer", "Event type should be Transfer");
    assert.equal(event.args.from, accounts[0], "From address should be correct");
    assert.equal(event.args.to, accounts[1], "To address should be correct");
    assert.equal(event.args.value.toString(), '100', "Value should be 100");
});

Gas Usage Testing

Gas efficiency is an important consideration in Solidity development. Testing the gas usage of functions can help you identify areas for optimization.

Example Gas Testing

it("should not exceed gas limit for transfer", async () => {
    const gasEstimate = await myContract.transfer.estimateGas(accounts[1], 100);
    assert.isBelow(gasEstimate, 30000, "Transfer should not exceed 30,000 gas");
});

Best Practices Summary

Best Practice	Description
Write Clear and Concise Tests	Each test should focus on one specific behavior.
Use Descriptive Names	Test and function names should clearly describe their purpose.
Group Related Tests	Use `describe` blocks to group similar tests.
Test Edge Cases	Ensure to cover boundary conditions and potential failure points.
Keep Tests Independent	Tests should not depend on the state of previous tests.

Conclusion

Writing unit tests for your Solidity smart contracts is essential for ensuring their reliability and security. By following best practices in structuring tests, utilizing assertions, and testing events and gas usage, you can create a robust test suite that enhances the quality of your smart contracts.

Learn more with useful resources: