update unittesting documentation

Author: lorjala

UNITTESTS/README.md

@@ -49,7 +49,7 @@ Detailed instructions for supported operating systems are below.
 
 #### Installing dependencies on Windows
 
-1. Download and install [MinGW-W64](http://mingw-w64.org/).
+1. Download and install MinGW-W64 from [SourceForge](https://sourceforge.net/projects/mingw-w64/files/Toolchains%20targetting%20Win64/Personal%20Builds/mingw-builds/).
 1. Download CMake binaries from https://cmake.org/download/, and run the installer.
 1. Download Python 2.7 or Python 3 from https://www.python.org/getit/, and run the installer.
 1. Add MinGW, CMake and Python into system PATH.
@@ -59,11 +59,13 @@ Detailed instructions for supported operating systems are below.
 
 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.
 
+All the class stubs should be located in the `UNITTESTS/stubs` directory. A single stub class can be used by multiple test suites and therefore should follow the naming convention of `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 try not to stub headers if possible. The stubbed headers reside in the `UNITTESTS/target_h` 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, 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.
+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 lists all the source files required for the test build.
 
 #### Test names
 
@@ -75,17 +77,27 @@ Mbed CLI supports unit tests through `mbed test --unittests` command. For inform
 
 ### Writing unit tests
 
+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 the code coverage to ensure all the code is tested and no dead code is found.
+
+Please see the [documentation for Google Test](https://github.com/google/googletest/blob/master/googletest/docs/primer.md) to learn how to write unit tests using the framework. See the [documentation for Google Mock](https://github.com/google/googletest/blob/master/googlemock/docs/Documentation.md) if you want to write and use C++ mock classes instead of stubs.
+
+#### Test suite configuration
+
 Create two files in the test directory for each test suite:
 
 - Unit test source file (`test_ClassName.cpp`).
 - Unit test configuration file (`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:
+List all the files required for the build in the `unittest.cmake` file. You will need to list the file paths relative to the `UNITTESTS` folder. Use the following variables to list the source files and include paths:
 
-- **unittest-includes** - List of header include paths. You can use this to extend or overwrite default paths listed in CMakeLists.txt.
+- **unittest-includes** - List of header include paths. You can use this to extend or overwrite default paths listed in `UNITTESTS/CMakeLists.txt`.
 - **unittest-sources** - List of files under test.
 - **unittest-test-sources** - List of test sources and stubs.
 
+You can also set custom compiler flags and other configurations supported by CMake in `unittest.cmake`.
+
+#### Example
+
 With the following steps, you can write a simple unit test. In this example, `rtos/Semaphore.cpp` is a class under test.
 
 1. Create a directory for unit test files in `UNITTESTS/rtos/Semaphore`.
@@ -97,11 +109,13 @@ With the following steps, you can write a simple unit test. In this example, `rt
    )
    
    set(unittest-test-sources
-       stubs/mbed_assert.c
+       stubs/mbed_assert_stub.c
+       stubs/Kernel_stub.cpp
        rtos/Semaphore/test_Semaphore.cpp
    )
    ```
-
+1. Stub all external dependencies. Create stubs `UNITTESTS/stubs/mbed_assert_stub.c` and `UNITTESTS/stubs/Kernel_stub.cpp` if they do not exist.
+1. Update header stubs with any missing type or function declarations.
 1. Create a test source file `UNITTESTS/rtos/Semaphore/test_Semaphore.cpp` with the following content:
 
 ```
@@ -185,6 +199,7 @@ Run a test binary in the build directory to run a unit test suite. To run multip
 
 1. Use Mbed CLI to build a debug build. For advanced use, run CMake directly with `-DCMAKE_BUILD_TYPE=Debug`, and then run a Make program.
 1. Run GDB with a test executable as an argument to debug unit tests.
+1. Run tests with Valgrind to analyze test memory profile.
 
 ### Get code coverage
 
@@ -200,8 +215,11 @@ Use Mbed CLI to generate code coverage reports. For advanced use, follow these s
 **Problem:** Generic problems with CMake or with the build process.
 * **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.
 
-**Problem:** Virus protection identifies files generated by CMake as malicious and quarantines the files on Windows.
+**Problem:** (Windows) Virus protection identifies files generated by CMake as malicious and quarantines the files.
 * **Solution**: Restore the false positive files from the quarantine.
 
-**Problem:** CMake compiler check fails on Mac OS Mojave when using GCC-8.
+**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.
+* **Solution**:  Remove sh.exe from the system path.
+
+**Problem:** (Mac OS) CMake compiler check fails on Mac OS Mojave when using GCC-8.
 * **Solution**: Make sure gnm (binutils) is not installed. Uninstall binutils with `brew uninstall binutils`.