Support for unit testing

README.md

@@ -25,6 +25,7 @@ This document covers the installation and usage of Mbed CLI.
     2. [Compiling and running tests](#compiling-and-running-tests)
     3. [Limiting the test scope](#limiting-the-test-scope)
     4. [Test directory structure](#test-directory-structure)
+1. [Unit testing](#unit-testing)
 1. [Publishing your changes](#publishing-your-changes)
     1. [Checking status](#checking-status)
     2. [Pushing upstream](#pushing-upstream)
@@ -727,6 +728,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` will build all available unit tests and run 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 `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
+```
+
 ## Publishing your changes
 
 ### Checking status

mbed/mbed.py

@@ -3011,6 +3011,61 @@ def help_():
     return parser.print_help()
 
 
+@subcommand('unittest',
+    dict(name='--compile', action='store_true', dest="compile_only", help='Only compile unit tests'),
+    dict(name='--run', action='store_true', dest="run_only", help='Only run unit tests'),
+    dict(name=['-c', '--clean'], action='store_true', help='Clean the build directory'),
+    dict(name=['-d', '--debug'], action='store_true', help='Enable debug build'),
+    dict(name='--coverage', choices=['html', 'xml', 'both'], help='Generate code coverage report'),
+    dict(name=['-m', '--make-program'], choices=['gmake', 'make', 'mingw32-make', 'ninja'], help='Which make program to use'),
+    dict(name=['-g', '--generator'], choices=['Unix Makefiles', 'MinGW Makefiles', 'Ninja'], help='Which CMake generator to use'),
+    dict(name=['-r', '--regex'], help='Run tests matching regular expression'),
+    dict(name='--build', help='Build directory. Default: BUILD/unittests/'),
+    dict(name='--new', help='generate files for a new unit test', metavar="FILEPATH"),
+    help='Create, build and run unit tests')
+def unittest_(compile_only=False, run_only=False, clean=False, debug=False, coverage=None, make_program=None, generator=None, regex=None, build=None, new=None):
+    # Find the root of the program
+    program = Program(getcwd(), False)
+    program.check_requirements(True)
+    # Save original working directory
+    orig_path = getcwd()
+
+    mbed_os_dir = program.get_os_dir()
+    if mbed_os_dir is None:
+        error("No Mbed OS directory found.")
+    unittests_dir = os.path.join(mbed_os_dir, "UNITTESTS")
+
+    tool = os.path.join(unittests_dir, "mbed_unittest.py")
+
+    # Prepare environment variables
+    env = program.get_env()
+
+    if os.path.exists(tool):
+        with cd(program.path):
+            # Setup the build path if not specified
+            build_path = build
+            if not build_path:
+                build_path = os.path.join(os.path.relpath(program.path, orig_path), program.build_dir, 'unittests')
+
+            # Run unit testing tools
+            popen([python_cmd, tool]
+                    + (["--compile"] if compile_only else [])
+                    + (["--run"] if run_only else [])
+                    + (["--clean"] if clean else [])
+                    + (["--debug"] if debug else [])
+                    + (["--coverage", coverage] if coverage else [])
+                    + (["--make-program", make_program] if make_program else [])
+                    + (["--generator", generator] if generator else [])
+                    + (["--regex", regex] if regex else [])
+                    + ["--build", build_path]
+                    + (["--new", new] if new else [])
+                    + (["--verbose"] if verbose else [])
+                    + remainder,
+                    env=env)
+    else:
+        warning("Unit testing is not supported with this Mbed OS version.")
+
+
 def main():
     global verbose, very_verbose, remainder, cwd_root