[ This article is reposted with permission of Jonathan Seroussi from Jumper. While Jumper isn't a project of ThrowTheSwitch, it has been designed to work well with Unity and is of interest to our readers. You can find the original article here. ]
Proper unit testing is a must for any software project. To allow unit testing for a software project the R&D team must write a testable, modular code — code that can be divided into self-contained units that can be tested. On top of making the code testable, embedded software developers must make sure their code is portable. On this blog post, we are going to demonstrate an easy way to have unit testing for embedded software. We’ve combined the Jumper Virtual Lab and the popular Unity Testing Framework by Throw The Switch.
The folks at ThrowTheSwitch are on a mission to unleash the powers of C for Embedded Systems without fearing the pitfalls of C. A flexible unit testing framework is a key component in responsible, test driver development.
Unity by ThrowTheSwitch is a superb unit testing framework for C. It’s lightweight, compiles on everything, has a ton of assertion options and connects nicely with CMock for easy full mocking support.
Once you’ve written your embedded code unit tests, there are 3 ways of running them.
- On target — run on the designated board or MCU. This works to a certain extent but setting up automation is a bit of a pain. Plus if you do end up automating it, make sure you don’t over-flash your ROM as it’ll get messed up sooner rather than later.
- On a PC — maintaining a proper Hardware Abstraction Layer and separating out the application code will make your application testable on an x86 or x86_64 machine. It’s awesome for app code, but you’ll need to mock pretty much everything outside of your application code.
- On an emulator — running on something like QEMU or the Jumper Virtual Lab allows full flexibility on what you mock or not, along with the benefit of easily plugging to a test automation framework.
We’re going to demonstrate how to run Unity-based unit tests on the Jumper Virtual Lab. We’re currently supporting the nRF52 by Nordic Semiconductor (STM32 support coming soon). The Virtual Lab is able to execute binaries that were compiled for the nRF52 without having to change anything about your code or how it compiles.
Install
To install Jumper Virtual Lab, go to this link and follow the installation instructions. You’ll need to create an account and download a token file, and then install a python module using pip. And that’s it! At this stage Jumper only works on Ubuntu 16, but Windows and Mac support is coming soon.
Running the sample
Download this sample and unzip it. Inside, you’ll find a pre_compiled folder and a source folder. For convenience, we’ll use the pre compiled option.
In your terminal, go to the pre_compiled folder and enter
jumper run -u -b unity.bin
After a few seconds, the following output will start printing onto your terminal:
Loading virtual device ………… Done Virtual device is running test/TestProductionCode.c:20:test_FindFunction_WhichIsBroken_ShouldReturnZeroIfItemIsNotInList_WhichWorksEvenInOurBrokenCode:PASS test/TestProductionCode.c:32:test_FindFunction_WhichIsBroken_ShouldReturnTheIndexForItemsInList_WhichWillFailBecauseOurFunctionUnderTestIsBroken:FAIL: Expected 1 Was 0 test/TestProductionCode.c:41:test_FunctionWhichReturnsLocalVariable_ShouldReturnTheCurrentCounterValue:PASS test/TestProductionCode.c:51:test_FunctionWhichReturnsLocalVariable_ShouldReturnTheCurrentCounterValueAgain:PASS test/TestProductionCode.c:60:test_FunctionWhichReturnsLocalVariable_ShouldReturnCurrentCounter_ButFailsBecauseThisTestIsActuallyFlawed:FAIL: Expected 0x00001234 Was 0x00005A5A — — — — — — — — — — — — 5 Tests 2 Failures 0 Ignored FAIL
This test fails on purpose.
Pretty cool, right?
The Code
Let’s drill down to the code. In the sample zip, go to source/main.c. The main.c file includes standard usage of the unity framework. Let’s look at this code:
After calling some functions that use assertions in the sample/source/test/TestProductionCode.c, it’ll call int unity_code = UnityEnd(); to get the number of failed tests.
Here’s a cool feature of the Virtual Lab we designed for these case. The last line: jumper_sudo_exit_with_exit_code(unity_code); is used to stop the program execution and return an exit code to the process that executed the test. This is very useful when running the test through a CI tools like Jenkins and CircleCI.
Using jumper_sudo to terminate the test execution
To do that you’ll need to use Jumper’s exit function:
void jumper_sudo_exit_with_exit_code(uint32_t exit_code)
To add the jumper_sudo code, follow the these instructions:
- Get the Jumper Virtual Lab Addons library by cloning this git repo:
- Add #include "jumper.h" to your .c file.
- Add the jumper.h and jumper.c files from this library to your build.
And you’re set!
This post was based on the following link from the Jumper Virtual Lab documentation.
