Solidity Unit Testing plugin

The Solidity Unit Testing plugin allows you to write and run automated tests for your Solidity smart contracts to verify they work correctly before deployment.

It helps you generate test files, write test functions using a built-in assertion library (like Assert.equal, Assert.notEqual), and execute those tests in a separate environment to see pass/fail results.

Activating the Solidity unit testing plugin

To activate the plugin, go to the Plugin Manager, search "Unit Testing" and enable the "Solidity Unit Testing" plugin.

When the plugin loads, you’ll see a screen like this:

Unit testing page

测试目录

When you load the plugin, you need to specify a directory where the plugin will load and store test files. By default, it's a tests folder at the root of your Workspace.

备注

The plugin will not automatically create directories. You must click "Create" to generate the specified folder structure.

After specifying the test folder, click the "Create" button. Alternatively, you can select an existing folder as the tests folder by typing "/" followed by the name of the folder.

Test Directory

Generating tests

The plugin can generate generic test files that contain information about developing tests for a contract. The name of the generic test file is determined by the currently active .sol file on the Main Panel. If there is no active file, a generic test file named, newFile_test.sol will be created.

Below is an example of a generic test file:

pragma solidity >=0.4.22 <0.8.0;
import "remix_tests.sol"; // this import is automatically injected by Remix.
import "remix_accounts.sol";
// Import here the file to test.

// File name has to end with '_test.sol', this file can contain more than one testSuite contracts
contract testSuite {

    /// 'beforeAll' runs before all other tests
    /// More special functions are: 'beforeEach', 'beforeAll', 'afterEach' & 'afterAll'
    function beforeAll() public {
        // Here should instantiate tested contract
        Assert.equal(uint(1), uint(1), "1 should be equal to 1");
    }

    function checkSuccess() public {
        // Use 'Assert' to test the contract,
        // See documentation: https://remix-ide.readthedocs.io/en/latest/assert_library.html
        Assert.equal(uint(2), uint(2), "2 should be equal to 2");
        Assert.notEqual(uint(2), uint(3), "2 should not be equal to 3");
    }

    function checkSuccess2() public pure returns (bool) {
        // Use the return value (true or false) to test the contract
        return true;
    }

    function checkFailure() public {
        Assert.equal(uint(1), uint(2), "1 is not equal to 2");
    }

    /// Custom Transaction Context
    /// See more: https://remix-ide.readthedocs.io/en/latest/unittesting.html#customization
    /// #sender: account-1
    /// #value: 100
    function checkSenderAndValue() public payable {
        // account index varies 0-9, value is in wei
        Assert.equal(msg.sender, TestsAccounts.getAccount(1), "Invalid sender");
        Assert.equal(msg.value, 100, "Invalid value");
    }
}

Writing tests

编写足够的单元测试，以确保您的合约在不同的情况下按预期工作。

Remix injects a built-in assert library for testing. You can visit the library documentation here.

Additionally, Remix allows the usage of special functions in the test file to make testing more structural. They are:

  • beforeEach() - 在每次测试之前运行

  • beforeAll() - 在所有测试之前运行

  • afterEach() - 在每次测试之后运行

  • afterAll() - 在所有测试之后运行

To get started, see this simple example.

小技巧

You can use RemixAI to generate tests for your files.

Running tests

Once you are done with writing tests, select the file(s) and click on Run to execute the tests. The execution will run in a separate environment. After completing the execution of one file, a test summary will be shown:

对于失败的测试，将有更多的断言细节来分析问题。单击失败的测试将在编辑器中高亮显示相关代码行。

Stopping tests

如果您选择运行多个文件的测试并想要停止执行，请单击停止按钮。它将在运行当前文件的测试后停止执行。

Customizing tests

Remix 帮助用户通过各种类型的自定义来正确测试合约。

1. Custom Compiler Context

Solidity Unit Testing refers to the Solidity Compiler plugin for compiler configurations. Configure Compiler, EVM Version, Enable Optimization & runs in the Solidity Compiler plugin and this will be used in the Solidity Unit Testing plugin for contract compilation before running unit tests.

2. Custom Transaction Context

For interacting with a contract's method, the main parameters of a transaction are from address, value & gas. Typically, a method's behaviour is tested with different values of these parameters.

在交易的中，您可以使用NatSpec注释输入自定义的msg.sender和msg.value值，如：

/// #sender: account-0
/// #value: 10
function checkSenderIs0AndValueis10 () public payable {
    Assert.equal(msg.sender, TestsAccounts.getAccount(0), "wrong sender in checkSenderIs0AndValueis10");
    Assert.equal(msg.value, 10, "wrong value in checkSenderIs0AndValueis10");
}

Instructions to use:

  1. 参数必须在方法的NatSpec中定义

  2. 每个参数键都应以 (#) 为前缀，并以一个空格（: ）后缀结束，如#sender:和#value:

  3. 目前，仅可为sender和value参数进行自定义

  4. Sender是交易的发送方地址，可在合约方法中使用msg.sender访问，必须以固定格式“account-<account_index>”定义

  5. <account_index>的取值范围取决于remix-ide版本号，v0.10.0之前为0-2，之后为0-9

  6. remix_accounts.sol must be imported in your test file to use custom sender

  7. Value是以wei为单位发送的value，可在合约方法中使用msg.value访问，必须是一个数字。

Regarding gas, Remix estimates the required gas for each transaction internally. Still if a contract deployment fails with Out-of-Gas error, it tries to redeploy it by doubling the gas. Deployment failing with double gas will show error: contract deployment failed after trying twice: The contract code couldn't be stored, please check your gas limit

Various test examples can be seen in examples section.

要记住的要点

  • 测试合约不能含有带参数的方法。如果有这样的方法，将显示错误信息：“在测试合约中，方法'methodname'不能带有参数”。

  • 在remix-ide v0.10.0之前，测试账户数为3，在之后为10。

  • While a test file which imports remix_accounts.sol might not compile successfully with Solidity Compiler plugin, do not worry, this will have no bearing on its success with Solidity Unit Testing plugin.