.. | |||
empty_baseline | 3 years ago | ||
features/ lorawan | 3 years ago | ||
stubs | 3 years ago | ||
target_h | 3 years ago | ||
template | 4 years ago | ||
unit_test | 4 years ago | ||
.mbedignore | 7 years ago | ||
CMakeLists.txt | 3 years ago | ||
CMakeSettings.json | 5 years ago | ||
README.md | 4 years ago | ||
googletest-CMakeLists.txt.in | 4 years ago | ||
mbed_unittest.py | 4 years ago |
This document describes how to write and use unit tests for Arm Mbed OS.
Unit tests test code in small sections on a host machine. Unlike other testing tools, unit testing doesn't require embedded hardware or need to build a full operating system. Because of this, unit testing can result in faster tests than other tools. Unit testing happens in a build environment where you test each C or C++ class or module in isolation. 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 you to complete tests 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.
In a terminal window:
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
.
In a terminal window:
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
.In a terminal window:
pip install "gcovr>=4.1" mbed-cli
.Find unit tests in the Mbed OS repository under the UNITTESTS
folder. We recommend unit test files use an identical directory path as the file under test. This makes it easier to find unit tests for a particular class or a module. For example, if the file you're testing 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.
All the class stubs should be located in the UNITTESTS/stubs
directory. A single stub class can be used by multiple test suites and should follow the naming convention ClassName_stub.cpp
for the source file, and ClassName_stub.h
for the header file. Use the actual header files for the unit tests, and don't stub headers if possible. The stubbed headers reside in the UNITTESTS/target_h
directory.
Registering unit tests to run happens automatically, and the test runner handles registration. However, test files do not automatically build. Build unit tests with a separate system that searches for unit tests under the UNITTESTS
directory.
For the build system to find and build any test suite automatically, include a unit test configuration file named unittest.cmake
for each unit test suite. This configuration file lists all the source files required for the test 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 the mbed test --unittests
command. For information on using Mbed CLI, please see the CLI documentation.
A unit tests suite consists of one or more test cases. The test cases should cover all the functions in a class under test. All the external dependencies are stubbed including the other classes in the same module. Avoid stubbing header files. Finally, analyze code coverage to ensure all code is tested, and no dead code is found.
Unit tests are written using Google Test v1.8.1.
Please see the documentation for Google Test to learn how to write unit tests using its framework. See the documentation for Google Mock if you want to write and use C++ mock classes instead of stubs.
Create two files in the test directory for each test suite:
test_ClassName.cpp
).unittest.cmake
).List all the required files for the build in the unittest.cmake
file with paths relative to the UNITTESTS
folder. Use the following variables to list the source files and include paths:
UNITTESTS/CMakeLists.txt
.You can also set custom compiler flags and other configurations supported by CMake in unittest.cmake
.
With the following steps, you can write a simple unit test. This example creates dummy classes to be tested, creates and configures unit tests for a class and stubs all external dependencies.
Create the following dummy classes in mbed-os/example
:
MyClass.h
#ifndef MYCLASS_H_ #define MYCLASS_H_ namespace example { class MyClass { public: int myFunction(); }; } #endif
MyClass.cpp
#include "MyClass.h" #include "OtherClass.h" namespace example { int MyClass::myFunction() { OtherClass o = OtherClass(); return o.otherFunction(); } }
OtherClass.h
#ifndef OTHERCLASS_H_ #define OTHERCLASS_H_ namespace example { class OtherClass { public: int otherFunction(); }; } #endif
OtherClass.cpp
#include "OtherClass.h" namespace example { int OtherClass::otherFunction() { return 1; } }
Create a directory for MyClass unit tests in UNITTESTS/example/MyClass
.
Create a configuration file and a source file for MyClass unit tests in UNITTESTS/example/MyClass
:
unittest.cmake
# Add here additional test specific include paths set(unittest-includes ${unittest-includes} ../example ) # Add here classes under test set(unittest-sources ../example/MyClass.cpp ) # Add here test classes and stubs set(unittest-test-sources example/MyClass/test_MyClass.cpp stubs/OtherClass_stub.cpp )
test_MyClass.cpp
#include "gtest/gtest.h" #include "example/MyClass.h" class TestMyClass : public testing::Test { protected: example::MyClass *obj; virtual void SetUp() { obj = new example::MyClass(); } virtual void TearDown() { delete obj; } }; TEST_F(TestMyClass, constructor) { EXPECT_TRUE(obj); } TEST_F(TestMyClass, myfunction) { EXPECT_EQ(obj->myFunction(), 0); }
Stub all external dependencies. Create the following stub in UNITTESTS/stubs
:
OtherClass_stub.cpp
#include "example/OtherClass.h" namespace example { int OtherClass::otherFunction() { return 0; } }
This example does not use any Mbed OS code, but if your unit tests do, then remember to update header stubs in UNITTESTS/target_h
and source stubs in UNITTESTS/stubs
with any missing type or function declarations.
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
for a debug build.-DCOVERAGE=True
to add coverage compiler flags.-Dgtest_disable_pthreads=ON
to run in a single thread.Run a test binary in the build directory to run a unit test suite. To run multiple test suites at once, use the CTest test runner. Run CTest with ctest
. Add -v
to get results for each test case. See the CTest manual for more information.
gtest-runner
according to the documentation.gtest-runner
.-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: (Windows) Virus protection identifies files generated by CMake as malicious and quarantines the files.
Problem: (Windows) Git with shell installation adds sh.exe to the path and then CMake throws an error: sh.exe was found in your PATH. For MinGW make to work correctly, sh.exe must NOT be in your path.
Problem: (Mac OS) CMake compiler check fails on Mac OS Mojave when using GCC-8.
brew uninstall binutils
.