.. | |||
features | 5 years ago | ||
platform/ CircularBuffer | 5 years ago | ||
stubs | 5 years ago | ||
target_h | 5 years ago | ||
template | 5 years ago | ||
unit_test | 5 years ago | ||
.mbedignore | 5 years ago | ||
CMakeLists.txt | 5 years ago | ||
CMakeSettings.json | 5 years ago | ||
README.md | 5 years ago | ||
googletest-CMakeLists.txt.in | 5 years ago | ||
mbed_unittest.py | 5 years ago |
This document describes how to write and test unit tests for Arm Mbed OS. To prevent and solve problems, please see the troubleshooting section.
Unit tests test code in small sections on a host machine. Unlike other testing tools, unit testing doesn't require embedded hardware, and it doesn't need to build the full operating system. Because of this, unit testing can result in faster tests than other testing tools. Unit testing takes place in a build environment where we test each C or C++ class or module in isolation. This means we build test suites into separate test binaries and stub all access outside to remove dependencies on any specific embedded hardware or software combination. This allows us to complete the testing using native compilers on the build machine.
Please install the following dependencies to use Mbed OS unit testing.
Detailed instructions for supported operating systems are below.
sudo apt-get -y install build-essential cmake
Install Python and Pip with:
sudo apt-get -y install python python-setuptools sudo easy_install pip
Install Gcovr and Mbed CLI with pip install "gcovr>=4.1" mbed-cli
.
xcode-select --install
.brew install cmake
.Install Python and Pip:
brew install python sudo easy_install pip
Install Gcovr and Mbed CLI with pip install "gcovr>=4.1" mbed-cli
.
brew install gcc
.pip install "gcovr>=4.1" mbed-cli
.Unit tests are located in the Mbed OS repository under the UNITTESTS
folder. We recommend unit test files use an identical directory path to the file under test. This makes it easier to find unit tests for a particular class or a module. For example, if the file under test is some/example/path/ClassName.cpp
, then all the test files are in the UNITTESTS/some/example/path/ClassName
directory. Each test suite needs to have its own unittest.cmake
file for test configuration.
Registering unit tests for running is automatic, and the test runner handles registration. However, test files are not automatically assigned to be built. We build unit tests by using a separate build system, which searches for unit tests under the UNITTESTS
directory.
For the build system to find and build any test suite automatically, you must include a unit test configuration file named unittest.cmake
for each unit test suite. This configuration file contains all the source files required for the build.
The build system automatically generates names of test suites. The name is constructed by taking a relative file path from the UNITTESTS directory to the test directory and replacing path separators with dashes. For example, the test suite name for some/example/path/ClassName.cpp
is some-example-path-ClassName
. Suite names are used when deciding which test suites to run.
Mbed CLI supports unit tests through mbed test --unittests
command. For information on using Mbed CLI, please see the CLI documentation.
Create two files in the test directory for each test suite:
test_ClassName.cpp
).unittest.cmake
).List all the files required for the build in the unittest.cmake
file. We recommend you list the file paths relative to the UNITTESTS
folder. Use the following variables to list the source files and include paths:
With the following steps, you can write a simple unit test. In this example, rtos/Semaphore.cpp
is a class under test.
UNITTESTS/rtos/Semaphore
.Create a test configuration file UNITTESTS/rtos/Semaphore/unittest.cmake
with the following content:
set(unittest-sources ../rtos/Semaphore.cpp ) set(unittest-test-sources stubs/mbed_assert.c rtos/Semaphore/test_Semaphore.cpp )
Create a test source file UNITTESTS/rtos/Semaphore/test_Semaphore.cpp
with the following content:
#include "gtest/gtest.h" #include "rtos/Semaphore.h" static osStatus_t retval = osOK; static uint32_t count = 0; // Test stubs osStatus_t osSemaphoreAcquire(osSemaphoreId_t semaphore_id, uint32_t timeout) { return retval; } osStatus_t osSemaphoreDelete(osSemaphoreId_t semaphore_id) { return retval; } osStatus_t osSemaphoreRelease(osSemaphoreId_t semaphore_id) { return retval; } uint32_t osSemaphoreGetCount(osSemaphoreId_t semaphore_id) { return count; } osSemaphoreId_t osSemaphoreNew(uint32_t max_count, uint32_t initial_count, const osSemaphoreAttr_t *attr) { return (void *)&count; // Just a dymmy reference } class TestSemaphore : public testing::Test { protected: rtos::Semaphore *sem; virtual void SetUp() { sem = new rtos::Semaphore(); } virtual void TearDown() { delete sem; } }; TEST_F(TestSemaphore, constructor) { EXPECT_TRUE(sem); }
Use Mbed CLI to build and run unit tests. For advanced use, you can run CMake and a Make program directly.
mkdir UNITTESTS/build
.cd UNITTESTS/build
.UNITTESTS
folder as the argument. So from UNITTESTS/build
use cmake ..
:
-g [generator]
if generating other than Unix Makefiles such in case of MinGW use -g "MinGW Makefiles"
.-DCMAKE_MAKE_PROGRAM=<value>
, -DCMAKE_CXX_COMPILER=<value>
and -DCMAKE_C_COMPILER=<value>
to use a specific Make program and compilers.-DCMAKE_BUILD_TYPE=Debug
to build a debug build.-DCOVERAGE=True
to add coverage compiler flags.Run a test binary in the build directory to run a unit test suite. To run multiple test suites at once, use CTest test runner. Run CTest with ctest
. Add -v
to get results for each test case. See the CTest manual for more information.
-DCMAKE_BUILD_TYPE=Debug
, and then run a Make program.Use Mbed CLI to generate code coverage reports. For advanced use, follow these steps:
-DCMAKE_BUILD_TYPE=Debug
and -DCOVERAGE=True
.Problem: Generic problems with CMake or with the build process.
Problem: Virus protection identifies files generated by CMake as malicious and quarantines the files on Windows.
Problem: CMake compiler check fails on Mac OS Mojave when using GCC-8.
brew uninstall binutils
.