takashi kadono / Mbed OS Nucleo_446

Color Oled(SSD1331) connect to STMicroelectronics Nucleo-F466

Dependencies:   ssd1331

mbed-os/UNITTESTS/README.md@0:8fdf9a60065b, 2018-10-10 (annotated)

Committer:
kadonotakashi
Date:
Wed Oct 10 00:33:53 2018 +0000
Revision:
0:8fdf9a60065b
how to make mbed librry

Who changed what in which revision?

UserRevisionLine numberNew contents of line
kadonotakashi 0:8fdf9a60065b 1 ## Unit testing
kadonotakashi 0:8fdf9a60065b 2
kadonotakashi 0:8fdf9a60065b 3 This document describes how to write and test unit tests for Mbed OS. To prevent and solve problems, please see the [troubleshooting](#troubleshooting) section.
kadonotakashi 0:8fdf9a60065b 4
kadonotakashi 0:8fdf9a60065b 5 ### Introduction
kadonotakashi 0:8fdf9a60065b 6
kadonotakashi 0:8fdf9a60065b 7 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.
kadonotakashi 0:8fdf9a60065b 8
kadonotakashi 0:8fdf9a60065b 9 ### Prerequisites
kadonotakashi 0:8fdf9a60065b 10
kadonotakashi 0:8fdf9a60065b 11 Please install the following dependencies to use Mbed OS unit testing.
kadonotakashi 0:8fdf9a60065b 12
kadonotakashi 0:8fdf9a60065b 13 - GNU toolchains.
kadonotakashi 0:8fdf9a60065b 14 - GCC 6 or later. We recommend you use MinGW-W64 on Windows, but any Windows port of the above GCC versions works.
kadonotakashi 0:8fdf9a60065b 15 - CMake 3.0 or newer.
kadonotakashi 0:8fdf9a60065b 16 - Python 2.7.x, 3.5 or newer.
kadonotakashi 0:8fdf9a60065b 17 - Pip 10.0 or newer.
kadonotakashi 0:8fdf9a60065b 18 - Gcovr 4.1 or newer.
kadonotakashi 0:8fdf9a60065b 19 - Mbed CLI 1.8.0 or newer.
kadonotakashi 0:8fdf9a60065b 20
kadonotakashi 0:8fdf9a60065b 21 Detailed instructions for supported operating systems are below.
kadonotakashi 0:8fdf9a60065b 22
kadonotakashi 0:8fdf9a60065b 23 #### Installing dependencies on Debian or Ubuntu
kadonotakashi 0:8fdf9a60065b 24
kadonotakashi 0:8fdf9a60065b 25 1. `sudo apt-get -y install build-essential cmake`
kadonotakashi 0:8fdf9a60065b 26 1. Install Python and Pip with:
kadonotakashi 0:8fdf9a60065b 27
kadonotakashi 0:8fdf9a60065b 28 ```
kadonotakashi 0:8fdf9a60065b 29 sudo apt-get -y install python python-setuptools
kadonotakashi 0:8fdf9a60065b 30 sudo easy_install pip
kadonotakashi 0:8fdf9a60065b 31 ```
kadonotakashi 0:8fdf9a60065b 32
kadonotakashi 0:8fdf9a60065b 33 1. Install Gcovr and [Mbed CLI](https://os.mbed.com/docs/latest/tools/arm-mbed-cli.html) with `pip install "gcovr>=4.1" mbed-cli`.
kadonotakashi 0:8fdf9a60065b 34
kadonotakashi 0:8fdf9a60065b 35 #### Installing dependencies on macOS
kadonotakashi 0:8fdf9a60065b 36
kadonotakashi 0:8fdf9a60065b 37 1. Install [Homebrew](https://brew.sh/).
kadonotakashi 0:8fdf9a60065b 38 1. Install GCC compilers and CMake with: `brew install gcc cmake`.
kadonotakashi 0:8fdf9a60065b 39 1. Install Python and Pip:
kadonotakashi 0:8fdf9a60065b 40
kadonotakashi 0:8fdf9a60065b 41 ```
kadonotakashi 0:8fdf9a60065b 42 brew install python
kadonotakashi 0:8fdf9a60065b 43 sudo easy_install pip
kadonotakashi 0:8fdf9a60065b 44 ```
kadonotakashi 0:8fdf9a60065b 45
kadonotakashi 0:8fdf9a60065b 46 1. Install Gcovr and [Mbed CLI](https://os.mbed.com/docs/latest/tools/arm-mbed-cli.html) with `pip install "gcovr>=4.1" mbed-cli`.
kadonotakashi 0:8fdf9a60065b 47
kadonotakashi 0:8fdf9a60065b 48 #### Installing dependencies on Windows
kadonotakashi 0:8fdf9a60065b 49
kadonotakashi 0:8fdf9a60065b 50 1. Download and install [MinGW-W64](http://mingw-w64.org/).
kadonotakashi 0:8fdf9a60065b 51 1. Download CMake binaries from https://cmake.org/download/, and run the installer.
kadonotakashi 0:8fdf9a60065b 52 1. Download Python 2.7 or Python 3 from https://www.python.org/getit/, and run the installer.
kadonotakashi 0:8fdf9a60065b 53 1. Add MinGW, CMake and Python into system PATH.
kadonotakashi 0:8fdf9a60065b 54 1. Install Gcovr and [Mbed CLI](https://os.mbed.com/docs/latest/tools/arm-mbed-cli.html) with `pip install "gcovr>=4.1" mbed-cli`.
kadonotakashi 0:8fdf9a60065b 55
kadonotakashi 0:8fdf9a60065b 56 ### Test code structure
kadonotakashi 0:8fdf9a60065b 57
kadonotakashi 0:8fdf9a60065b 58 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.
kadonotakashi 0:8fdf9a60065b 59
kadonotakashi 0:8fdf9a60065b 60 #### Test discovery
kadonotakashi 0:8fdf9a60065b 61
kadonotakashi 0:8fdf9a60065b 62 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.
kadonotakashi 0:8fdf9a60065b 63
kadonotakashi 0:8fdf9a60065b 64 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.
kadonotakashi 0:8fdf9a60065b 65
kadonotakashi 0:8fdf9a60065b 66 #### Test names
kadonotakashi 0:8fdf9a60065b 67
kadonotakashi 0:8fdf9a60065b 68 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.
kadonotakashi 0:8fdf9a60065b 69
kadonotakashi 0:8fdf9a60065b 70 ### Unit testing with Mbed CLI
kadonotakashi 0:8fdf9a60065b 71
kadonotakashi 0:8fdf9a60065b 72 Mbed CLI supports unit tests through `mbed test --unittests` command. For information on using Mbed CLI, please see the [CLI documentation in handbook](https://os.mbed.com/docs/latest/tools/arm-mbed-cli.html).
kadonotakashi 0:8fdf9a60065b 73
kadonotakashi 0:8fdf9a60065b 74 ### Writing unit tests
kadonotakashi 0:8fdf9a60065b 75
kadonotakashi 0:8fdf9a60065b 76 Create two files in the test directory for each test suite:
kadonotakashi 0:8fdf9a60065b 77
kadonotakashi 0:8fdf9a60065b 78 - Unit test source file (`test_ClassName.cpp`).
kadonotakashi 0:8fdf9a60065b 79 - Unit test configuration file (`unittest.cmake`).
kadonotakashi 0:8fdf9a60065b 80
kadonotakashi 0:8fdf9a60065b 81 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:
kadonotakashi 0:8fdf9a60065b 82
kadonotakashi 0:8fdf9a60065b 83 - **unittest-includes** - List of header include paths. You can use this to extend or overwrite default paths listed in CMakeLists.txt.
kadonotakashi 0:8fdf9a60065b 84 - **unittest-sources** - List of files under test.
kadonotakashi 0:8fdf9a60065b 85 - **unittest-test-sources** - List of test sources and stubs.
kadonotakashi 0:8fdf9a60065b 86
kadonotakashi 0:8fdf9a60065b 87 With the following steps, you can write a simple unit test. In this example, `rtos/Semaphore.cpp` is a class under test.
kadonotakashi 0:8fdf9a60065b 88
kadonotakashi 0:8fdf9a60065b 89 1. Create a directory for unit test files in `UNITTESTS/rtos/Semaphore`.
kadonotakashi 0:8fdf9a60065b 90 1. Create a test configuration file `UNITTESTS/rtos/Semaphore/unittest.cmake` with the following content:
kadonotakashi 0:8fdf9a60065b 91
kadonotakashi 0:8fdf9a60065b 92 ```
kadonotakashi 0:8fdf9a60065b 93 set(unittest-sources
kadonotakashi 0:8fdf9a60065b 94 ../rtos/Semaphore.cpp
kadonotakashi 0:8fdf9a60065b 95 )
kadonotakashi 0:8fdf9a60065b 96
kadonotakashi 0:8fdf9a60065b 97 set(unittest-test-sources
kadonotakashi 0:8fdf9a60065b 98 stubs/mbed_assert.c
kadonotakashi 0:8fdf9a60065b 99 rtos/Semaphore/test_Semaphore.cpp
kadonotakashi 0:8fdf9a60065b 100 )
kadonotakashi 0:8fdf9a60065b 101 ```
kadonotakashi 0:8fdf9a60065b 102
kadonotakashi 0:8fdf9a60065b 103 1. Create a test source file `UNITTESTS/rtos/Semaphore/test_Semaphore.cpp` with the following content:
kadonotakashi 0:8fdf9a60065b 104
kadonotakashi 0:8fdf9a60065b 105 ```
kadonotakashi 0:8fdf9a60065b 106 #include "gtest/gtest.h"
kadonotakashi 0:8fdf9a60065b 107 #include "rtos/Semaphore.h"
kadonotakashi 0:8fdf9a60065b 108
kadonotakashi 0:8fdf9a60065b 109 static osStatus_t retval = osOK;
kadonotakashi 0:8fdf9a60065b 110 static uint32_t count = 0;
kadonotakashi 0:8fdf9a60065b 111
kadonotakashi 0:8fdf9a60065b 112 // Test stubs
kadonotakashi 0:8fdf9a60065b 113 osStatus_t osSemaphoreAcquire(osSemaphoreId_t semaphore_id, uint32_t timeout)
kadonotakashi 0:8fdf9a60065b 114 {
kadonotakashi 0:8fdf9a60065b 115 return retval;
kadonotakashi 0:8fdf9a60065b 116 }
kadonotakashi 0:8fdf9a60065b 117 osStatus_t osSemaphoreDelete(osSemaphoreId_t semaphore_id)
kadonotakashi 0:8fdf9a60065b 118 {
kadonotakashi 0:8fdf9a60065b 119 return retval;
kadonotakashi 0:8fdf9a60065b 120 }
kadonotakashi 0:8fdf9a60065b 121 osStatus_t osSemaphoreRelease(osSemaphoreId_t semaphore_id)
kadonotakashi 0:8fdf9a60065b 122 {
kadonotakashi 0:8fdf9a60065b 123 return retval;
kadonotakashi 0:8fdf9a60065b 124 }
kadonotakashi 0:8fdf9a60065b 125 uint32_t osSemaphoreGetCount(osSemaphoreId_t semaphore_id)
kadonotakashi 0:8fdf9a60065b 126 {
kadonotakashi 0:8fdf9a60065b 127 return count;
kadonotakashi 0:8fdf9a60065b 128 }
kadonotakashi 0:8fdf9a60065b 129 osSemaphoreId_t osSemaphoreNew(uint32_t max_count, uint32_t initial_count, const osSemaphoreAttr_t *attr)
kadonotakashi 0:8fdf9a60065b 130 {
kadonotakashi 0:8fdf9a60065b 131 return (void *)&count; // Just a dymmy reference
kadonotakashi 0:8fdf9a60065b 132 }
kadonotakashi 0:8fdf9a60065b 133
kadonotakashi 0:8fdf9a60065b 134 class TestSemaphore : public testing::Test {
kadonotakashi 0:8fdf9a60065b 135 protected:
kadonotakashi 0:8fdf9a60065b 136 rtos::Semaphore *sem;
kadonotakashi 0:8fdf9a60065b 137
kadonotakashi 0:8fdf9a60065b 138 virtual void SetUp()
kadonotakashi 0:8fdf9a60065b 139 {
kadonotakashi 0:8fdf9a60065b 140 sem = new rtos::Semaphore();
kadonotakashi 0:8fdf9a60065b 141 }
kadonotakashi 0:8fdf9a60065b 142
kadonotakashi 0:8fdf9a60065b 143 virtual void TearDown()
kadonotakashi 0:8fdf9a60065b 144 {
kadonotakashi 0:8fdf9a60065b 145 delete sem;
kadonotakashi 0:8fdf9a60065b 146 }
kadonotakashi 0:8fdf9a60065b 147 };
kadonotakashi 0:8fdf9a60065b 148
kadonotakashi 0:8fdf9a60065b 149 TEST_F(TestSemaphore, constructor)
kadonotakashi 0:8fdf9a60065b 150 {
kadonotakashi 0:8fdf9a60065b 151 EXPECT_TRUE(sem);
kadonotakashi 0:8fdf9a60065b 152 }
kadonotakashi 0:8fdf9a60065b 153 ```
kadonotakashi 0:8fdf9a60065b 154
kadonotakashi 0:8fdf9a60065b 155 ### Building and running unit tests
kadonotakashi 0:8fdf9a60065b 156
kadonotakashi 0:8fdf9a60065b 157 Use Mbed CLI to build and run unit tests. For advanced use, you can run CMake and a make program directly.
kadonotakashi 0:8fdf9a60065b 158
kadonotakashi 0:8fdf9a60065b 159 #### Build tests directly with CMake
kadonotakashi 0:8fdf9a60065b 160
kadonotakashi 0:8fdf9a60065b 161 1. Create a build directory `mkdir UNITTESTS/build`.
kadonotakashi 0:8fdf9a60065b 162 1. Move to the build directory `cd UNITTESTS/build`.
kadonotakashi 0:8fdf9a60065b 163 1. Run CMake using a relative path to `UNITTESTS` folder as the argument. So from `UNITTESTS/build` use `cmake ..`:
kadonotakashi 0:8fdf9a60065b 164 - Add `-g [generator]` if generating other than Unix Makefiles such in case of MinGW use `-g "MinGW Makefiles"`.
kadonotakashi 0:8fdf9a60065b 165 - Add `-DCOVERAGE:True` to add coverage compiler flags.
kadonotakashi 0:8fdf9a60065b 166 - See the [CMake manual](https://cmake.org/cmake/help/v3.0/manual/cmake.1.html) for more information.
kadonotakashi 0:8fdf9a60065b 167 1. Run a make program (Make, Gmake, Mingw32-make and so on) to build the tests.
kadonotakashi 0:8fdf9a60065b 168
kadonotakashi 0:8fdf9a60065b 169 #### Run tests directly with CTest
kadonotakashi 0:8fdf9a60065b 170
kadonotakashi 0:8fdf9a60065b 171 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](https://cmake.org/cmake/help/v3.0/manual/ctest.1.html) for more information.
kadonotakashi 0:8fdf9a60065b 172
kadonotakashi 0:8fdf9a60065b 173 #### Run tests with GUI test runner
kadonotakashi 0:8fdf9a60065b 174
kadonotakashi 0:8fdf9a60065b 175 1. Install *gtest-runner* using the [documentation](https://github.com/nholthaus/gtest-runner).
kadonotakashi 0:8fdf9a60065b 176 1. Run *gtest-runner*
kadonotakashi 0:8fdf9a60065b 177 1. Add test executables into the list.
kadonotakashi 0:8fdf9a60065b 178 1. Run them.
kadonotakashi 0:8fdf9a60065b 179
kadonotakashi 0:8fdf9a60065b 180 ### Get code coverage
kadonotakashi 0:8fdf9a60065b 181
kadonotakashi 0:8fdf9a60065b 182 Use Mbed CLI to generate code coverage reports. For advanced use, you can run Gcovr or any other code coverage tool directly in the build directory.
kadonotakashi 0:8fdf9a60065b 183
kadonotakashi 0:8fdf9a60065b 184 ### Troubleshooting
kadonotakashi 0:8fdf9a60065b 185
kadonotakashi 0:8fdf9a60065b 186 **Problem:** Generic problems with CMake or with the build process.
kadonotakashi 0:8fdf9a60065b 187 * **Solution**: Delete the build directory. Make sure that CMake, g++, gcc and a make program can be found in the path and are correct versions.
kadonotakashi 0:8fdf9a60065b 188
kadonotakashi 0:8fdf9a60065b 189 **Problem:** Virus protection identifies files generated by CMake as malicious and quarantines the files on Windows.
kadonotakashi 0:8fdf9a60065b 190 * **Solution**: Restore the false positive files from the quarantine.