<commit_before># Description
This document is a simple cookbook introducing testing facilities available for mbed 3.0. From this document you will learn how to:
* Create simple test(s) for your software encapsulated in yotta package. To read full yotta documentation go [here](http://docs.yottabuild.org/reference/commands.html).
* Create more complicated test cases where additional mocking / test case supervision is required
* write mocks (we call them **host tests** in mbed) running on test host (your PC / Mac).
This document provides examples for all three methods of testing.
* Create [unit tests](http://en.wikipedia.org/wiki/Unit_testing) with [mbed compatible CppUTest library](https://github.com/ARMmbed/mbed-cpputest-private).
  * Information about CppUTest library can be found [here](https://cpputest.github.io/manual.html).

Both test tools and host test scripts are written in Python 2.7. This means minimum knowledge about Python development is required.

## Test process
Currently using test tools you can develop test cases which run on a single hardware platform and can interact with host computer via serial port (series of ```print```s and ```sscanf``` calls). Host computer communicates with mbed device using serial port connection (duplex) to drive test scenarions.

Test tools offer [host test](https://github.com/ARMmbed/mbed-host-tests) functionality. A host test is a supervising Python script executed on host computer (your Mac or PC) and used to mock certain functionality or feature like TCP servers required to test your code. Host tests are part of separate Python module (mbed-host-tests).
Each host test should be as generic as possible so many test cases running on mbed platforms can reuse it. For example simple TCP or UDP echo server can be used to test different network APIs also for mbed 2.0.

Test tools are designed in such a way s0:
* you can concentrate on test development and
* (re)use existing host tests or 
* create new host test to cover new functional / interoperability domain of your tests.

### Test suite (mbed-greentea)
Mbed 3.0 test suite called mbed-greentea is a Python 2.7 application which:
* Build your tests inside your yotta package using ```yotta build``` command.
  * List all tests in \build\<target_name>\test.
* For each built's test case in your yotta module, mbed-greentea executes in order below actions:
  * Flash hardware (target) with test binary.
  * Reset hardware (target) via serial port (send break command).
  * Listen on target's serial port and scans for prints from target.
  * Execute proper host test which will supervise your test case and
  * pass test result back to test suite (for reporting).

### Limitations
It is impossible to develop (with current test tools) test cases or test scenarios where few mbed devices cooperate with each other. For example it is impossible to write test cases for mesh networks or tests where two mbed devices communicate with each other via sockets / Bluetooth etc.

## yotta package
Place your test case under a sub-directory of ```\test``` directory located in your yotta package:
Note: For details please check ['The test Directory' section of yotta documentation](http://docs.yottabuild.org/tutorial/testing.html).
```
\your-yotta-pacjage-dir
  \source
    ...
  \test
    \test_case_1
      source.cpp
      test-case-1.cpp
    \test_case_2<commit_msg>Update QUICKSTART.md<commit_after># Description
This document is a simple cookbook introducing testing facilities available for mbed 3.0. From this document you will learn how to:
* Create simple test(s) for your software encapsulated in yotta package. To read full yotta documentation go [here](http://docs.yottabuild.org/reference/commands.html).
* Create more complicated test cases where additional mocking / test case supervision is required
* write mocks (we call them **host tests** in mbed) running on test host (your PC / Mac).
This document provides examples for all three methods of testing.
* Create [unit tests](http://en.wikipedia.org/wiki/Unit_testing) with [mbed compatible CppUTest library](https://github.com/ARMmbed/mbed-cpputest-private).
  * Information about CppUTest library can be found [here](https://cpputest.github.io/manual.html).

Both test tools and host test scripts are written in Python 2.7. This means minimum knowledge about Python development is required.

## Test process
Currently using test tools you can develop test cases which run on a single hardware platform and can interact with host computer via serial port (series of ```print```s and ```sscanf``` calls). Host computer communicates with mbed device using serial port connection (duplex) to drive test scenarions.

Test tools offer [host test](https://github.com/ARMmbed/mbed-host-tests) functionality. A host test is a supervising Python script executed on host computer (your Mac or PC) and used to mock certain functionality or feature like TCP servers required to test your code. Host tests are part of separate Python module (mbed-host-tests).
Each host test should be as generic as possible so many test cases running on mbed platforms can reuse it. For example simple TCP or UDP echo server can be used to test different network APIs also for mbed 2.0.

Test tools are designed to:
* Let you can concentrate on test development not test framework building and
* (re)use existing host tests or 
* create new host test to cover new functional / interoperability domain of your tests.

### Test suite (mbed-greentea)
Mbed 3.0 test suite called mbed-greentea is a Python 2.7 application which:
* Build your tests inside your yotta package using ```yotta build``` command.
  * List all tests in \build\<target_name>\test.
* For each built's test case in your yotta module, mbed-greentea executes in order below actions:
  * Flash hardware (target) with test binary.
  * Reset hardware (target) via serial port (send break command).
  * Listen on target's serial port and scans for prints from target.
  * Execute proper host test which will supervise your test case and
  * pass test result back to test suite (for reporting).

### Limitations
It is impossible to develop (with current test tools) test cases or test scenarios where few mbed devices cooperate with each other. For example it is impossible to write test cases for mesh networks or tests where two mbed devices communicate with each other via sockets / Bluetooth etc.

## yotta package
Place your test case under a sub-directory of ```\test``` directory located in your yotta package:
Note: For details please check ['The test Directory' section of yotta documentation](http://docs.yottabuild.org/tutorial/testing.html).
```
\your-yotta-pacjage-dir
  \source
    ...
  \test
    \test_case_1
      source.cpp
      test-case-1.cpp
    \test_case_2
{'fraction_non_alphanumeric': 0.0683924106486248, 'fraction_numerical': 0.003971172231210472, 'mean_word_length': 4.320813771517997, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 5, 'https://': 6, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3781710', 'n_tokens_mistral': 1765, 'n_tokens_neox': 1703, 'n_words': 925}