September 18, 2019 by Xose Pérez
Learn different ways to unit test your Arduino code with these methods and frameworks.
Unit Testing is a common practice in software development where you basically test units of code to check that they work as expected. Those units are usually methods of your code, ideally specialized in a certain task, like performing a certain calculation or parsing an input. Your test code will then stress that method with different inputs and check if the output matches the expected value.
Even though unit testing is often a software industry thing, there is no reason why you shouldn’t unit test your Arduino sketches. It becomes a must if you are planning to release your code as open-source. In this tutorial, I will show you some examples on how to unit test your Arduino code.
In this post I will use different code examples you can find on Github. The examples are all based on the same sketch which calculates and outputs the Fibonacci number for different values. Here is the key code for this sketch (check the fibonacci_00 example in the repository):
// The 32 bits integer in the Atmel AVR overflows after F[47],
// so we will calculate up to this number
#define MAX_NUMBER 47
// Cache array
unsigned long f[MAX_NUMBER+1] = { 0 };
/*
* Calculates and returns the n-th Fibonacci Number
*/
unsigned long fibonacci(unsigned long n) {
if (0 == n) return 0;
if (1 == n) return 1;
if (0 == f[n]) {
f[n] = fibonacci(n-2) + fibonacci(n-1);
}
return f[n];
}As you can see the Fibonacci method receives a number and calculates and returns the Fibonacci number for it. The Fibonacci series is a recursive series by nature (it uses previous results for new calculations), and the Fibonacci method does the same: it calls itself. Also note that I’m using a cache array to store previous values and speed things up. Thanks to this trick the total calculation time goes down from several hours (!!) to 12 milliseconds.
But how can I be sure the calculations are correct? Well, let’s test the Fibonacci method!
We want to call a method in our code with some input value and check the output to see if it matches an expected value. We can create our own testing code, something like (this is the fibonacci_01 example in the repository):
void testFibonacci(unsigned long input, unsigned long output) {
Serial.print("Testing F[");
Serial.print(input);
Serial.print("]: ");
Serial.println((fibonacci(input) == output) ? "OK" : "ERROR");
}Now we can call our testFibonacci method like this:
void setup() {
// … Serial init code here …
// Expected values taken from https://www.tools4noobs.com/online_tools/fibonacci/
testFibonacci(0, 0);
testFibonacci(1, 1);
testFibonacci(2, 1);
testFibonacci(3, 2);
testFibonacci(5, 5);
testFibonacci(10, 55);
testFibonacci(20, 6765);
testFibonacci(30, 832040);
}The output will be:
Testing F[0]: OK
Testing F[1]: OK
Testing F[2]: OK
Testing F[3]: OK
Testing F[5]: OK
Testing F[10]: OK
Testing F[20]: OK
Testing F[30]: OKThat’s OK but it has some drawbacks: you will have to write a test method for every method you want to test, including the checking and the serial monitor output. If your code base is small (like the one we have here) it might be OK to do it like this. But once it starts growing and you start having tens or maybe hundreds of testing methods it will quickly become a nightmare.
That’s why special libraries exist that are specifically meant to deal with unit testing. These are called Unit Testing Frameworks.
There are several testing frameworks for Arduino. Let me just mention here the three I find more interesting: ArduinoUnit, AUnit, and PlatformIO Unit Testing. The last one is part of the PlatformIO ecosystem which runs outside the Arduino IDE so we will skip it for now. The other two are very similar. I will show you an example with AUnit but for no special reason, so if you want to try ArduinoUnit go ahead!
We will have to add the AUnit library to our IDE. Look for it in the Library Manager. Now let’s code the tests (this is the fibonacci_02 example in the repository).
First we include the library in our code:
#include <AUnit.h>
Now code a testing method, using special assert functions to compare the actual to the expected values:
test(fibonacci) {
// Expected values taken from https://www.tools4noobs.com/online_tools/fibonacci/
assertEqual(fibonacci(0 ), (unsigned long) 0);
assertEqual(fibonacci(1 ), (unsigned long) 1);
assertEqual(fibonacci(2 ), (unsigned long) 1);
assertEqual(fibonacci(3 ), (unsigned long) 2);
assertEqual(fibonacci(5 ), (unsigned long) 5);
assertEqual(fibonacci(10), (unsigned long) 55);
assertEqual(fibonacci(20), (unsigned long) 6765);
assertEqual(fibonacci(30), (unsigned long) 832040);
}And finally run the tests from our loop:
void loop() {
aunit::TestRunner::run();
}The output will be:
Fibonacci number generator - test 02
TestRunner started on 1 test(s).
Test fibonacci passed.
TestRunner duration: 0.002 seconds.
TestRunner summary: 1 passed, 0 failed, 0 skipped, 0 timed out, out of 1 test(s).Check the summary. Our only test method passed without issues. Good!
The AUnit library has a lot of options so I recommend you to read the documentation to know all the goodies it has.
There is a lot more around unit testing. If you are curious about what can you do and how you can do it, I recommend reading about these subjects:
IoT developer and maker. I jumped into the embedded world 10 years ago and it's a lot more fun! Creator of espurna.io, also writing at tinkerman.cat
