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:
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
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
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
#ifndef _LIBCOMPONENT_H_
#define _LIBCOMPONENT_H_
#include <Arduino.h>
class LibComponent {
public:
int addTwoNumbers(int a, int b) {
return a + b;
}
};
#endif
#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);
}
[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.