Getting started Unit testing with Arduino platform

This article discusses how to unit test a simple project with Arduino, if you’re not used to writing unit tests, or need more background, then first read this guide on unit testing embedded projects.

My favoured library for writing unit tests on Arduino platform is AUnit. It is open source, under a commercial friendly MIT license and provides a nice API.

It is available from here:

• AUnit is available through library manager, just install it direct from the IDE.
• [https://github.com/bxparks/AUnit] the library source code itself.
• [https://github.com/bxparks/AUniter] if you want to automate the running of the tests.

For a project that has a sketch and source files

In this scenario we have application, with a .INO file that starts the application, and calls upon the services of a component SomeComponent; which is in the src directory. In this case, we’d want to test at least the component, so we’d create a tests directory at the top level and create TestSomeComponent under this directory, just like a normal Arduino sketch (IE: file name matches directory name).

Application
    src
        SomeComponent.cpp
        SomeComponent.h
    tests
        TestSomeComponent
            TestSomeComponent.ino
    Application.ino

For a library that has examples and tests

Before I discovered how easy it was to have proper unit tests run on the Arduino platform, I used to mix examples with unit tests, I’d actually have very complex examples that were really unit or integration tests. Now I separate them out, as they are very different use cases. Tests should conclusively test a component of the system; whereas examples should demonstrate how to use the components of the library, in the simplest way possible.

Let’s now look at an example layout for a library; where there examples are both examples and tests. We create a tests folder as above, and create any tests we wish to run under this folder, in exactly the same way as an Arduino sketch.

LibComponent
    src
        LibComponent.h
    examples
        CompExample1
            CompExample1.ino
    tests
        CompTest1
            CompTest1.ino
    library.properties

Getting started in the code

Much of how to get started with AUnit is available in the documentation on the AUnit github page, and I certainly don’t want to duplicate it here. What I will do here is give a simple example, to show how easy it is to get started.

Step 1 - install the AUnit library through library manager.

Step 2 - create a tests directory in the top level of your project.

Step 3 - create a CompTest1 directory under that and an INO file with the same name (replace test name as desired)

Step 4 - write the test..

After the above, we have an empty test that does nothing, we need something to test. Let’s create our LibComponent.h from above that just adds up two numbers and returns the result. Then write a test

LibComponent.h

#ifndef _LIBCOMPONENT_H_
#define _LIBCOMPONENT_H_

#include <Arduino.h>

class LibComponent {
public:
    int addTwoNumbers(int a, int b) {
        return a + b;
    }        
};

#endif

CompTest1.ino

#line 2 "CompTest1.ino"

#include <AUnit.h>
#include "LibComponent.h"

using namespace aunit;

// here's what we are actually testing
LibComponent compUnderTest;

// in setup, we prepare the serial port.
void setup() {
    Serial.begin(115200);
    while(!Serial);
}

// we just call the test runner in loop
void loop() {
    TestRunner::run();
}
    
test(addingTwoNumbersTogether) {
    assertEqual(compUnderTest.addTwoNumbers(10, 10), 20);
}

Results of running the test

[Starting] Opening the serial port - /dev/cu.usbmodemFD1321
[Info] Opened the serial port - /dev/cu.usbmodemFD1321
TestRunner started on 1 test(s).
Test addingTwoNumbersTogether passed.

That is about the simplest unit test that can be written. It should give you a starting point for writing tests on Arduino. To run the test from an IDE just open the sketch and run it. It can be automated using AUniter as discussed above.

Please also see my page linked below on testing with IoAbstraction; which makes testing even easier.