FreeRTOS-Kernel/FreeRTOS/Test/CMock

FreeRTOS Kernel Unit Tests

Prerequisites as tested

GCC

gcc: gcc (GCC) 9.2.0

LCOV

lcov: LCOV version 1.14-6-g40580cd

Make

GNU Make 3.82

Ruby

ruby 2.0.0p648 (2015-12-16) [x86_64-linux]

Doxygen (optional)

1.8.5

Python (optional, required for coverage filtering)

Python 3.8 or later

Cflow (optional, required for coverage filtering)

cflow (GNU cflow) 1.6

How to run

$ make help
Usage: $ make <unit>

 where <unit> is one of: queue doc all run run_formatted run_col
 run_col_formatted coverage

Explanation

$ make queue

Would build the kernel queue unit tests and put the executable in build/bin

$ make doc

Would generate the doxygen documentation in build/doc

$ make run | run_formatted | run_col | run_col_formatted

Would build all unit tests and runs them one after the other with different options between normal and formatted and colored for easily spotting errors

$ make coverage

Would build all unit tests, runs them one after the other, then generates html code coverage and places them in build/coverage with initial file index.html

Runing tests with Address Sanitizer enabled

The GCC address sanitizer can be enabled by passing in "ENABLE_SANITIZER=1" when calling make.

Note: Enabling the address sanitizer will introduce additional branches that may not be possible to get test coverage of. For this reason, the address sanitizer is not enabled by default. It is recommended that developers enable the address sanitizer when modifying or developing new test cases.

Running individual tests

From each test directory, you can build, run the test, and generate gcov coverage with the default "all" target like so:

$ make -C list

For convenience, a "gcov" target is also provided.

$ make -C list gcov

Alternatively, you can generate filtered coverage with the "lcov" target:

$ make -C list lcov

You can also generate an html coverage report with the lcovhtml target:

$ make -C list lcovhtml

Coverage Filtering

Coverage filtering is meant to remove "unintentional" or "incidental" test coverage that is generated by other test cases which call a specific function but are not meant to test that function. In order to use coverage filtering and the associated lcov and lcovhtml targets, you must install the "optional" requirements listed above.

Additionally, you must also document which functions you are targeting inside each _utest.c file with a tag inside each file similar to the following:

@coverage vFunctionNameHere vAnotherFunctionNameHere