Merge pull request #677 from lorjala/unittests

Add documentation for unit testing

Author: Amanda Butler

docs.json

@@ -835,7 +835,11 @@
                     },
                     {
                         "type": "markdown",
-                        "url": "https://github.com/ARMmbed/mbed-os-5-docs/blob/development/docs/tools/testing/testing_greentea.md"
+                        "url": "https://github.com/ARMmbed/mbed-os-5-docs/blob/development/docs/tools/testing/unit_testing.md"
+                    },
+                    {
+                        "type": "markdown",
+                        "url": "https://github.com/ARMmbed/mbed-os-5-docs/blob/development/docs/tools/testing/testing_greentea.md
                     },
                     {
                         "type": "markdown",

docs/tools/offline/cli-test-debug.md

@@ -1,5 +1,7 @@
 ## Test and debug
 
+### Testing
+
 Use the `mbed test` command to compile and run tests.
 
 There are two testing frameworks: Greentea and Icetea. Greentea provides tests designed for driver porting and target verification. Icetea provides and manages tests for multiple devices at the same time. For example, you can test the network setup for a server and multiple clients, simultaneously controlling them from the test environment.
@@ -210,6 +212,65 @@ As shown above, tests exist inside `TESTS\testgroup\testcase\` directories. Plea
 
 <span class="notes">**Note:** `mbed test` does not work in applications that contain a `main` function that is outside of a `TESTS` directory.</span>
 
+### Unit testing
+
+Use the `mbed unittest` command to build and run unit tests, or to generate files for new unit tests.
+
+Build and run unit tests with `mbed unittest`. The arguments are:
+
+* `--compile` to only compile unit tests.
+* `--run` to only run unit tests.
+* `-c` or `--clean` to clean build directory.
+* `-d` or `--debug` to prepare debug build.
+* `--coverage <TYPE>` to generate code coverage report where TYPE can be "html", "xml" or "both".
+* `-m <NAME>` or `--make-program <NAME>` to select which make build tool to use where NAME can be "make", "gmake", "mingw32-make" or "ninja".
+* `-g <NAME>` or `--generator <NAME>` to select which CMake generator to use where NAME can be "Unix Makefiles", "MinGW Makefiles" or "Ninja".
+* `-r <EXPRESSION>` or `--regex <EXPRESSION>` to run tests matching the regular expression.
+* `--build <PATH>` to specify build directory.
+* `-v` or `--verbose` for verbose diagnostic output.
+
+Generate files for a new unit test with `mbed unittest --new <FILE>`.
+
+### Building and running unit tests
+
+You can specify to only **build** the unit tests by using the `--compile option:
+
+```
+$ mbed unittest --compile
+```
+
+You can specify to only **run** the unit tests by using the `--run` option:
+
+```
+$ mbed unittest --run
+```
+
+If you do not specify any of these, `mbed unittest` builds all available unit tests and runs them.
+
+### Running a subset of tests
+
+You can run a **limited set** of unit tests by using the `-r` or `--regex` option. This takes a regular expression, which it compares against the test names. For example, to run all cellular unit tests, you can specify:
+
+```
+$ mbed unittest -r cellular
+```
+
+### Getting code coverage
+
+You can generate a code coverage report by using the `--coverage` option. For example, to create an html report, you can specify:
+
+```
+$ mbed unittest --coverage html
+```
+
+### Creating new unit tests
+
+All unit tests are under the `mbed-os/UNITTESTS` directory. You can **generate** the necessary files for a unit test by using the `--new` option. For example, to create the files for `rtos/Semaphore.cpp`, you can specify:
+
+```
+$ mbed unittest --new rtos/Semaphore.cpp
+```
+
 ### Troubleshooting
 
 #### Import Mercurial (mbed.org) programs or libraries

docs/tools/testing/testing_intro.md

@@ -2,6 +2,8 @@
 
 Testing is a critical step in the development process. The Arm Mbed ecosystem offers several tools to help you test your code.
 
+You can use unit testing tools to build and run Mbed OS unit tests. Each unit test is built into an isolated test executable using a separate build system and build tools native to the development machine without any hardware or software dependencies. You can use the tool with Mbed CLI using the keyword `unittest`.
+
 Greentea, Icetea, `htrun` and `mbed-ls` are testing tools written in Python. Greentea tests serve as functional unit tests in C++, as well as integration tests for complex use cases that execute on microcontrollers. The Icetea test tool adds more support for interoperability testing by making it easier to handle multiple devices and external service during testing. Arm Mbed CLI has a verb `test` that drives these tools to form a testing system. These comprise our automated testing framework for Mbed OS development. 
 
 The testing system automates the process of flashing Mbed boards, driving the tests and accumulating test results into test reports. Developers and Mbed Partners use this system for local development, as well as for automation in a Continuous Integration environment.

docs/tools/testing/unit_testing.md

@@ -0,0 +1,45 @@
+## Unit testing
+
+### Introduction
+
+Traditional software testing is defined into three main levels: unit testing, integration testing and system testing. These levels are often pictured as a pyramid to indicate the amount of testing for each level.
+
+```
+^ Testing level
+|
+|       /\
+|      /  \       System testing
+|     /----\
+|    /      \     Integration testing
+|   /--------\
+|  /          \   Unit testing
+| /------------\
+|
+*-------------------> Amount of tests
+```
+
+We perform integration and system testing in an environment where we run the tests with the full Mbed OS. Other testing tools for Mbed OS require specific embedded hardware, which means traditional unit testing is not possible.
+
+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.
+
+### Using unit tests
+
+#### Test code structure
+
+Unit tests are located in Mbed OS repository under `UNITTESTS`. Each unit test uses an identical directory tree structure to the file to be tested. This makes it easier to find unit tests for a particular class or a module. For example, if the file to be tested is `rtos/Semaphore.cpp`, then all the test files are in the `UNITTESTS/rtos/Semaphore` directory.
+
+##### Test discovery
+
+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, a unit test configuration file named `unittest.cmake` is required to be included with each unit test. This configuration file contains a name for the test and other source files the build requires.
+
+##### Test names
+
+Each test suite requires a name to be configured in the `unittest.cmake` file. This name is used for generated files and when running a subset of tests.
+
+#### Building, running and writing tests
+
+Unit testing requires external tools you need to install. See the developer [documentation](https://github.com/ARMmbed/mbed-os/blob/master/UNITTESTS/README.md) in GitHub for the full installation guide.
+
+You can build and run unit tests through Arm Mbed CLI. You can also use the tool to generate new test files. For information on using Mbed CLI, please see the [CLI documentation](/docs/development/tools/arm-mbed-cli.html).