Getting Started with Unit Tests

Install Prerequisites

• .NET Core SDK (>2.1.4)

Setup Project

Open command line / terminal and create a new C# project with the command dotnet new console --name YOUR_PROJECT_NAME

Example:

dotnet new console --name MyProject

Add the Meadow package

Add the Meadow unit testing framework package with the command dotnet add package Meadow.UnitTestTemplate

cd MyProject
dotnet add package Meadow.UnitTestTemplate

Create a Solidity contract source directory

Create a directory named contracts to place your Solidity source files (the directory must be named contracts).

mkdir contracts

Add .sol sources

Add your Solidity source files to the contracts directory.

Here's an example hello world Solidity contract that we'll save to our contracts directory as HelloWorld.sol. Solidity source files must have the .sol file extension.

pragma solidity ^0.4.24;

contract HelloWorld {

    event HelloEvent(string _message, address _sender);

    function renderHelloWorld () public returns (string) {
        emit HelloEvent("Hello world", msg.sender);
        return 'Hello world';
    }

}

Build project

Run dotnet build and you should see a GeneratedContracts directory with generated source files matching your Solidity contracts. In our example we'll have a GeneratedContracts/HelloWorld.sol.cs.

Create a C# test for contract interaction

Create a .cs file in your project directory to add our contract test code. For example HelloWorldTests.cs.

Create a test class. The following example will deploy our contract, test a function call result, and test a transaction execution and validate its event log.

using Meadow.Contract;
using Meadow.JsonRpc.Types;
using Meadow.UnitTestTemplate;
using Microsoft.VisualStudio.TestTools.UnitTesting;
using System.Threading.Tasks;

namespace MyProject
{
    [TestClass]
    public class HelloWorldTests : ContractTest
    {
        HelloWorld _contract;

        // This triggers the coverage report generation (only needed once in the project).
        [AssemblyCleanup]
        public static async Task Cleanup()
        {
            await Global.Cleanup();
        }

        protected override async Task BeforeEach()
        {
            // Deploy our test contract
            _contract = await HelloWorld.New(RpcClient);
        }

        [TestMethod]
        public async Task ValidateCallResult()
        {
            // Call the renderHelloWorld function and get the return value.
            var callResult = await _contract.renderHelloWorld().Call();

            // Validate the return value is what we expect.
            Assert.AreEqual("Hello world", callResult);
        }

        [TestMethod]
        public async Task ValidateTransactionEventResult()
        {
            // Execute the renderHelloWorld function as a transaction.
            var txHash = await _contract.renderHelloWorld().SendTransaction();

            // Get the transaction receipt.
            var receipt = await RpcClient.GetTransactionReceipt(txHash);

            // Get the event log from receipt that we are expecting.
            var eventLog = receipt.FirstEventLog<HelloWorld.HelloEvent>();

            // Optionally, the above steps can be shorted to..
            eventLog = await _contract
                .renderHelloWorld()
                .FirstEventLog<HelloWorld.HelloEvent>();

            // Validate the event log arg is what we expect.
            Assert.AreEqual("Hello world", eventLog._message);
        }
        
        [TestMethod]
        public async Task ValidateTransactionSender()
        {
            // An array of accounts is available as:
            var fromAccount = Accounts[5];

            // An RPC client instance is available, example:
            var balance = await RpcClient.GetBalance(
                fromAccount, 
                BlockParameterType.Latest);

            // By default the first RPC account is used for calls and transactions.
            // We can specify which account to use with TransactionParams..
            var txParams = new TransactionParams { From = Accounts[5] };
            var receipt = await _contract
                .renderHelloWorld()
                .TransactionReceipt(txParams);

            // Validate the msg.sender as set in our example event log.
            var eventLog = receipt.FirstEventLog<HelloWorld.HelloEvent>();
            Assert.AreEqual(eventLog._sender, fromAccount);
        }
    }
}

Run tests

Run the command dotnet test in your project directory. If successful you should see:

Starting test execution, please wait...
Total tests: 3. Passed: 3. Failed: 0. Skipped: 0.
Test Run Successful.

View coverage report

A Report directory will be created in your project directory after the unit tests have ran.

Open the Report/index.html file in a web browser to see the Solidity code coverage report.