In this section we'll demonstrate how to run unit tests on the Virtual Lab using the Unity Test framework by Throw The Switch. Using the following instructions you'll be able write and run unit tests for your firmware. The examples here are targeted to the nRF52832 MCU but can run on the STM32F4 as well.
Run the unit test sample
As the Virtual Lab only needs your firmware binary, it can seamlessly work with Unity but let's use a simple asserts example to demostrate it.
Go to the folder where you extracted the samples_nrf52832.zip file and run the following line in the command line (from samples_nrf52832/pre_compiled/unity folder):
jumper run --fw unity.bin -u --platform nrf52832
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
After this firmware finished running, you can get the program exit code in your terminal by typing
echo $? - the expected output is
2. This unit test has FAILED in purpose, 2 out of the 5 tests were meant to fail.
Alright! Let's drill down and see what just happened.
The sample code
You can find the sample code under the samples_nrf52832/source/unity in the samples_nrf52832.zip file. The main.c file includes standard usage of the unity framework. Let's look at this code:
UnityBegin("test/TestProductionCode.c"); RUN_TEST(test_FindFunction_WhichIsBroken_ShouldReturnZeroIfItemIsNotInList_WhichWorksEvenInOurBrokenCode, 20); RUN_TEST(test_FindFunction_WhichIsBroken_ShouldReturnTheIndexForItemsInList_WhichWillFailBecauseOurFunctionUnderTestIsBroken, 30); RUN_TEST(test_FunctionWhichReturnsLocalVariable_ShouldReturnTheCurrentCounterValue, 41); RUN_TEST(test_FunctionWhichReturnsLocalVariable_ShouldReturnTheCurrentCounterValueAgain, 51); RUN_TEST(test_FunctionWhichReturnsLocalVariable_ShouldReturnCurrentCounter_ButFailsBecauseThisTestIsActuallyFlawed, 57); int unity_code = UnityEnd(); jumper_sudo_exit_with_exit_code(unity_code);
After calling some functions that use assertions in the samples_nrf52832/source/unity/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 server 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 these instructions:
- Get the Jumper Virtual Lab Addons library by cloning this git repo:
git clone https://github.com/Jumperr-labs/jumper-vlab-addon.git
#include "jumper.h"to your .c file.
- Add the
jumper.cfiles from this library to your build.