fsfw/unittest/README.md

FSFW Testing

This repository contains testing and unit testing components.

Catch2 has been used as a framework, and these unit tests can only be run on a linux host machine. The makefile with default settings creates the unit test binary which can be run in the terminal or in eclipse.

Instructions

Basic steps:

1. Clone this branch

   git clone https://egit.irs.uni-stuttgart.de/fsfw/fsfw_tests.git
   

2. Inititate the framework submodule (need to only be done once)

   git submodule init
   git submodule sync
   git submodule update
   

3. Run the makefile With

   make all -j<Number Of Processors>
   

   This will build the debug version of the unit tests. The release version can be built with the target release

4. Run the binary located in the _bin folder in the terminal or in eclipse.

   _bin/<binaryName>.elf [--success]
   

   The success parameter is optional. Leaving it out ommits the success messages.

5. To clear the binary, object and dependency folder, run

   make clean
   

Please note that on most UNIX environments (e.g. Ubuntu), the real time functionalities used by the UNIX pthread module are restricted, which will lead to permission errors when creating these tasks.

To solve this issues, try following steps:

1. Edit the /etc/security/limits.conf file and add following lines at the end (worked on Ubuntu 19.10):

   <username>   hard   rtprio  99
   <username>   soft   rtprio  99
   

   Then restart the computer.
   The soft limit can also be set in the console with ulimit -Sr if the hard limit has been increased, but it is recommended to add it to the file as well for convenience. If adding the second line is not desired for security reasons, the soft limit needs to be set for each session. If using an IDE like eclipse in that case, the IDE needs to be started from the console after setting the soft limit higher there.
2. Run the shell script inside the linux folder (worked on Ubuntu 18.04)

   ./unlockRealtime
   

   This script executes the setcap command on bash and on the binaries. It also increases the soft real time limit of the current shell instance to the maximum. If running the script before executing the binary does not help, try the following step.

Eclipse CDT settings

The default eclipse terminal has issues displaying the colors used when running the unit test binary by catch2. To fix this issue, install the ANSI Escape In Console package from the eclipse marketplace.

GCOV integration

GCOV has been integrated as a code coverage tool. It can be enabled by adding GCOV=1 to the build process as an additional argument. Coverage data will be provided in form of .gcno and .gcda files. These can be displayed in eclipse by looking for a .gcno or .gcda file in the _obj folder, double-clicking it and picking the right source-binary. This will generate information about which lines of a file have run, provided it is open in eclipse.

LCOV integration

The files generated by GCOV can also be processed by the tool LCOV. On ubuntu, the tool can be installed with the following command:

sudo apt-get install lcov

After that, the tool can be run by building the unit tests with GCOV=1, running them at least one time and then executing the lcov.sh script.

Adding unit tests

The catch unit tests are located in unittest/testfw. To add new unit tests, add them to the UnitTestCatch.cpp file or add a new source file which includes catch.hpp.

For writing basics tests, the assertion documentation or the existing examples are a good guideliens. For more advanced tests, refer to the catch2 documentation.

Compile without test framework

Alternatively, the unit tests can also be run internally without a framework. This can be used to perform unit tests on the real hardware. To do this, run

make -j<Number Of Processors> notestfw

This will instruct the makefile to exclude the test framework main.cpp and include our own. This will also create a binary which can be used outside the host machine (a Makefile adaptions might be neccessary if another OS than linux is required)