Marco Zecchini / Mbed OS Example_RTOS

Rtos API example

mbed-os/features/frameworks/greentea-client/README.md@0:9fca2b23d0ba, 2019-02-23 (annotated)

Committer:
marcozecchini
Date:
Sat Feb 23 12:13:36 2019 +0000
Revision:
0:9fca2b23d0ba
final commit

Who changed what in which revision?

UserRevisionLine numberNew contents of line
marcozecchini 0:9fca2b23d0ba 1 # Table of Contents
marcozecchini 0:9fca2b23d0ba 2
marcozecchini 0:9fca2b23d0ba 3 * [greentea-client](#greentea-client)
marcozecchini 0:9fca2b23d0ba 4 * [mbed-drivers dependencies](#mbed-drivers-dependencies)
marcozecchini 0:9fca2b23d0ba 5 * [Greentea test tools](#greentea-test-tools)
marcozecchini 0:9fca2b23d0ba 6 * [Compatibility](#compatibility)
marcozecchini 0:9fca2b23d0ba 7 * [Greentea support](#greentea-support)
marcozecchini 0:9fca2b23d0ba 8 * [utest support](#utest-support)
marcozecchini 0:9fca2b23d0ba 9 * [greentea-client support in your module](#greentea-client-support-in-your-module)
marcozecchini 0:9fca2b23d0ba 10 * [Terms](#terms)
marcozecchini 0:9fca2b23d0ba 11 * [Test suite](#test-suite)
marcozecchini 0:9fca2b23d0ba 12 * [Test case](#test-case)
marcozecchini 0:9fca2b23d0ba 13 * [key-value protocol](#key-value-protocol)
marcozecchini 0:9fca2b23d0ba 14 * [Where can I use it?](#where-can-i-use-it)
marcozecchini 0:9fca2b23d0ba 15 * [Test suite model](#test-suite-model)
marcozecchini 0:9fca2b23d0ba 16 * [utest support template](#utest-support-template)
marcozecchini 0:9fca2b23d0ba 17 * [No utest support template](#no-utest-support-template)
marcozecchini 0:9fca2b23d0ba 18
marcozecchini 0:9fca2b23d0ba 19 # greentea-client
marcozecchini 0:9fca2b23d0ba 20
marcozecchini 0:9fca2b23d0ba 21 **Tip:** If you are unsure about the terms used in this document, please see the [Terms](#Terms) section.
marcozecchini 0:9fca2b23d0ba 22
marcozecchini 0:9fca2b23d0ba 23 ```greentea-client``` is a C++ client library for [the Greentea test tool](https://github.com/ARMmbed/greentea) when used in an [mbed](www.mbed.com) project.
marcozecchini 0:9fca2b23d0ba 24 This package implements the slave side of the simple key-value protocol used for communication between the device under test (DUT) and the host. ```Greentea``` on the host side implements the protocol's master behavior. ```greentea-client``` is released through the [yotta registry](https://yotta.mbed.com/#/module/greentea-client/0.1.8).
marcozecchini 0:9fca2b23d0ba 25
marcozecchini 0:9fca2b23d0ba 26
marcozecchini 0:9fca2b23d0ba 27 ```
marcozecchini 0:9fca2b23d0ba 28 DUT <--- serial port connection ---> host
marcozecchini 0:9fca2b23d0ba 29 (slave) . (master)
marcozecchini 0:9fca2b23d0ba 30 .
marcozecchini 0:9fca2b23d0ba 31 [greentea-client] . [conn_process] [htrun]
marcozecchini 0:9fca2b23d0ba 32 ===== . ================ =========
marcozecchini 0:9fca2b23d0ba 33 | . | |
marcozecchini 0:9fca2b23d0ba 34 | . | |
marcozecchini 0:9fca2b23d0ba 35 | {{ key ; value }} | |
marcozecchini 0:9fca2b23d0ba 36 |------------------------->| (key, value, timestamp) |
marcozecchini 0:9fca2b23d0ba 37 | . |------------------------>|
marcozecchini 0:9fca2b23d0ba 38 | . | |
marcozecchini 0:9fca2b23d0ba 39 | . | |
marcozecchini 0:9fca2b23d0ba 40 | . | |
marcozecchini 0:9fca2b23d0ba 41 | . | |
marcozecchini 0:9fca2b23d0ba 42 | . | |
marcozecchini 0:9fca2b23d0ba 43 | . | (key, value, timestamp) |
marcozecchini 0:9fca2b23d0ba 44 | {{ key ; value }} |<------------------------|
marcozecchini 0:9fca2b23d0ba 45 |<-------------------------| |
marcozecchini 0:9fca2b23d0ba 46 | . | |
marcozecchini 0:9fca2b23d0ba 47 .
marcozecchini 0:9fca2b23d0ba 48 ```
marcozecchini 0:9fca2b23d0ba 49
marcozecchini 0:9fca2b23d0ba 50 ```greentea-client``` is a [yotta module](http://yottadocs.mbed.com/reference/module.html). You can easily include it in your yotta project as ```dependency```/```testDependency```.
marcozecchini 0:9fca2b23d0ba 51
marcozecchini 0:9fca2b23d0ba 52 ## mbed-drivers dependencies
marcozecchini 0:9fca2b23d0ba 53
marcozecchini 0:9fca2b23d0ba 54 This package was introduced as a future replacement for the [mbed-drivers/test_env.h](https://github.com/ARMmbed/mbed-drivers/blob/master/mbed-drivers/test_env.h) test framework. ```mbed-drivers/test_env.h``` is no longer considered the correct way to write tests for mbed modules.
marcozecchini 0:9fca2b23d0ba 55
marcozecchini 0:9fca2b23d0ba 56 Examples of test cases ported from the old ```mbed-drivers/test_env``` to the ```greentea-client``` model can be found here:
marcozecchini 0:9fca2b23d0ba 57 * [core-util](https://github.com/ARMmbed/core-util/pull/95)
marcozecchini 0:9fca2b23d0ba 58 * [ualloc](https://github.com/ARMmbed/ualloc/pull/24)
marcozecchini 0:9fca2b23d0ba 59 * [minar](https://github.com/ARMmbed/minar/pull/36)
marcozecchini 0:9fca2b23d0ba 60 * [mbed-drivers](https://github.com/ARMmbed/mbed-drivers/pull/165)
marcozecchini 0:9fca2b23d0ba 61 * [sal](https://github.com/ARMmbed/sal/pull/46)
marcozecchini 0:9fca2b23d0ba 62 * [sockets](https://github.com/ARMmbed/sockets/pull/64)
marcozecchini 0:9fca2b23d0ba 63 * [utest](https://github.com/ARMmbed/utest/pull/6)
marcozecchini 0:9fca2b23d0ba 64
marcozecchini 0:9fca2b23d0ba 65 ## Greentea test tools
marcozecchini 0:9fca2b23d0ba 66
marcozecchini 0:9fca2b23d0ba 67 ```Greentea``` is a test automation tool written in Python and designed to automate test execution for [mbed](www.mbed.com) projects encapsulated as [yotta](http://yottadocs.mbed.com) modules. Its key features include: integration with yotta module, test automation for yotta module's tests and reporting.
marcozecchini 0:9fca2b23d0ba 68
marcozecchini 0:9fca2b23d0ba 69 ## Compatibility
marcozecchini 0:9fca2b23d0ba 70
marcozecchini 0:9fca2b23d0ba 71 ```greentea-client``` is compatible with:
marcozecchini 0:9fca2b23d0ba 72 * [Greentea](https://github.com/ARMmbed/greentea) v0.2.x onwards
marcozecchini 0:9fca2b23d0ba 73 * [htrun](https://github.com/ARMmbed/htrun) v0.2.x onwards
marcozecchini 0:9fca2b23d0ba 74 * [utest](https://github.com/ARMmbed/utest) v1.10.0 onwards
marcozecchini 0:9fca2b23d0ba 75 * [unity](https://github.com/ARMmbed/utest) v2.0.1 onwards
marcozecchini 0:9fca2b23d0ba 76
marcozecchini 0:9fca2b23d0ba 77 ### Greentea support
marcozecchini 0:9fca2b23d0ba 78
marcozecchini 0:9fca2b23d0ba 79 If you wish to use ```greentea-client``` please make sure you are using latest ```Greentea``` tools from [PyPI](https://pypi.python.org/pypi/mbed-greentea) (you will need Python 2.7):
marcozecchini 0:9fca2b23d0ba 80 ```
marcozecchini 0:9fca2b23d0ba 81 $ pip install mbed-greentea --upgrade
marcozecchini 0:9fca2b23d0ba 82 ```
marcozecchini 0:9fca2b23d0ba 83
marcozecchini 0:9fca2b23d0ba 84 *Note*: If you previously used ```mbed-drivers/test_env.h``` features to write your test cases please downgrade ```Greentea``` to a version lower than ```v0.2.0``` to stay compatible:
marcozecchini 0:9fca2b23d0ba 85 ```
marcozecchini 0:9fca2b23d0ba 86 $ pip install "mbed-greentea<0.2.0" --upgrade
marcozecchini 0:9fca2b23d0ba 87 ```
marcozecchini 0:9fca2b23d0ba 88
marcozecchini 0:9fca2b23d0ba 89 *Note*: [Greentea v0.1.x](https://github.com/ARMmbed/greentea/tree/master_v0_1_x) is still developed on a ```master_v0_1_x``` branch. We will only apply critical patches to version 0.1.x, no feature development is planned.
marcozecchini 0:9fca2b23d0ba 90
marcozecchini 0:9fca2b23d0ba 91 ### utest support
marcozecchini 0:9fca2b23d0ba 92
marcozecchini 0:9fca2b23d0ba 93 ```utest``` is our preferred test harness which allows you to execute a series of (asynchronous) C++ test cases. ```greentea-client``` includes as test dependency ```utest``` yotta module. See the ```greentea-client``` [module.json](https://github.com/ARMmbed/greentea-client/blob/master/module.json) ```testDependency``` section:
marcozecchini 0:9fca2b23d0ba 94 ```json
marcozecchini 0:9fca2b23d0ba 95 {
marcozecchini 0:9fca2b23d0ba 96 "testDependencies": {
marcozecchini 0:9fca2b23d0ba 97 "utest": "^1.10.0"
marcozecchini 0:9fca2b23d0ba 98 }
marcozecchini 0:9fca2b23d0ba 99 }
marcozecchini 0:9fca2b23d0ba 100 ```
marcozecchini 0:9fca2b23d0ba 101
marcozecchini 0:9fca2b23d0ba 102 ### greentea-client support in your module
marcozecchini 0:9fca2b23d0ba 103
marcozecchini 0:9fca2b23d0ba 104 Currently ```greentea-client``` is in on version ```1.0.x```. Please use a ```^1.0.0``` dependency version in your ```module.json``` file.
marcozecchini 0:9fca2b23d0ba 105
marcozecchini 0:9fca2b23d0ba 106 Example of ```module.json``` file with ```greentea-client``` as a test dependency:
marcozecchini 0:9fca2b23d0ba 107 ```json
marcozecchini 0:9fca2b23d0ba 108 {
marcozecchini 0:9fca2b23d0ba 109 "testDependencies": {
marcozecchini 0:9fca2b23d0ba 110 "greentea-client": "^1.0.0",
marcozecchini 0:9fca2b23d0ba 111 "utest" : "^1.10.0",
marcozecchini 0:9fca2b23d0ba 112 "unity" : "^2.1.0"
marcozecchini 0:9fca2b23d0ba 113 }
marcozecchini 0:9fca2b23d0ba 114 }
marcozecchini 0:9fca2b23d0ba 115 ```
marcozecchini 0:9fca2b23d0ba 116
marcozecchini 0:9fca2b23d0ba 117 ## Terms
marcozecchini 0:9fca2b23d0ba 118
marcozecchini 0:9fca2b23d0ba 119 ### Test suite
marcozecchini 0:9fca2b23d0ba 120 A test suite is a binary containing test cases we execute on hardware. The test suite has a beginning and an end (like your ```main()``` function would. The test suite may pass, fail or be in an error state (for example if test suite times out or there was a serial port connection problem).
marcozecchini 0:9fca2b23d0ba 121
marcozecchini 0:9fca2b23d0ba 122 ### Test case
marcozecchini 0:9fca2b23d0ba 123
marcozecchini 0:9fca2b23d0ba 124 Preferably you will use ```utest``` to define test cases . test case has the beginning and the end. During test case execution you will use ``ùnity``` assert macros, schedule MINAR callbacks, check for timeouts in your code. Your test cases may pass, fail or be in an error state which means something went wrong and we were unable to determine exactly what that was (you may have to check the logs).
marcozecchini 0:9fca2b23d0ba 125
marcozecchini 0:9fca2b23d0ba 126 ### key-value protocol
marcozecchini 0:9fca2b23d0ba 127
marcozecchini 0:9fca2b23d0ba 128 The key-value protocol (also called ```KiVi```) is a simple protocol introduced to the ```Greentea``` test tools. It is used to send simple text messages (events) between the DUT and the host. Each message consists of a _key_ and corresponding _value_ pair.
marcozecchini 0:9fca2b23d0ba 129 A ```KiVi``` message is defined as a string encapsulated between double curly braces. The key and value are separated by a semicolon (```;```).
marcozecchini 0:9fca2b23d0ba 130 For example: the ```{{timeout;120}}}``` string is a simple key-value message where the key "_timeout_" is associated with the value "_120_". Both ```greentea-client``` and ```Greentea``` understand this format and can detect key-value messages in a data stream. Both _key_ and _value_ are ASCII strings.
marcozecchini 0:9fca2b23d0ba 131 This protocol is a master-slave protocol. The host has the role of _master_ and the DUT is the _slave_.
marcozecchini 0:9fca2b23d0ba 132
marcozecchini 0:9fca2b23d0ba 133 ```greentea-client``` implements the key-value protocol tokenizer and parser.
marcozecchini 0:9fca2b23d0ba 134
marcozecchini 0:9fca2b23d0ba 135 ## Where can I use it?
marcozecchini 0:9fca2b23d0ba 136 It is possible to write test cases that use ```greentea-client``` and at the same time support ```mbed``` features such as [MINAR scheduler](https://github.com/ARMmbed/minar). It is also possible to mix ```greentea-client``` with other test tools we use at ```mbed``` such as [utest](https://github.com/ARMmbed/utest) and [unity](https://github.com/ARMmbed/unity).
marcozecchini 0:9fca2b23d0ba 137
marcozecchini 0:9fca2b23d0ba 138 You can also find references to ```greentea-client``` in many ```mbed``` packages. For example:
marcozecchini 0:9fca2b23d0ba 139 * [mbed-drivers](https://github.com/ARMmbed/mbed-drivers) - check its [module.json](https://github.com/ARMmbed/mbed-drivers/blob/master/module.json)
marcozecchini 0:9fca2b23d0ba 140 * [core-util](https://github.com/ARMmbed/core-util) - check its [module.json](https://github.com/ARMmbed/core-util/blob/master/module.json)
marcozecchini 0:9fca2b23d0ba 141
marcozecchini 0:9fca2b23d0ba 142 # Test suite model
marcozecchini 0:9fca2b23d0ba 143 ## utest support template
marcozecchini 0:9fca2b23d0ba 144 ```c++
marcozecchini 0:9fca2b23d0ba 145 #include "greentea-client/test_env.h"
marcozecchini 0:9fca2b23d0ba 146 #include "utest/utest.h"
marcozecchini 0:9fca2b23d0ba 147 #include "unity/unity.h"
marcozecchini 0:9fca2b23d0ba 148
marcozecchini 0:9fca2b23d0ba 149 void test_case_1_func() {
marcozecchini 0:9fca2b23d0ba 150 // Test case #1 body
marcozecchini 0:9fca2b23d0ba 151 // Here you can run your test cases and assertions
marcozecchini 0:9fca2b23d0ba 152 TEST_ASSERT_TRUE(true);
marcozecchini 0:9fca2b23d0ba 153 TEST_ASSERT_FALSE(false);
marcozecchini 0:9fca2b23d0ba 154 }
marcozecchini 0:9fca2b23d0ba 155
marcozecchini 0:9fca2b23d0ba 156 void test_case_2_func() {
marcozecchini 0:9fca2b23d0ba 157 // Test case #2 body
marcozecchini 0:9fca2b23d0ba 158 // Here you can run your test cases and assertions
marcozecchini 0:9fca2b23d0ba 159 TEST_ASSERT_TRUE(true);
marcozecchini 0:9fca2b23d0ba 160 TEST_ASSERT_FALSE(false);
marcozecchini 0:9fca2b23d0ba 161 }
marcozecchini 0:9fca2b23d0ba 162
marcozecchini 0:9fca2b23d0ba 163 const Case cases[] = {
marcozecchini 0:9fca2b23d0ba 164 Case("Test case #1 name", test_case_1_func),
marcozecchini 0:9fca2b23d0ba 165 Case("Test case #1 name", test_case_2_func)
marcozecchini 0:9fca2b23d0ba 166 };
marcozecchini 0:9fca2b23d0ba 167
marcozecchini 0:9fca2b23d0ba 168 status_t greentea_setup(const size_t number_of_cases) {
marcozecchini 0:9fca2b23d0ba 169 GREENTEA_SETUP(5, "default_auto");
marcozecchini 0:9fca2b23d0ba 170 return greentea_test_setup_handler(number_of_cases);
marcozecchini 0:9fca2b23d0ba 171 }
marcozecchini 0:9fca2b23d0ba 172
marcozecchini 0:9fca2b23d0ba 173 void app_start(int, char*[]) {
marcozecchini 0:9fca2b23d0ba 174 Harness::run(specification);
marcozecchini 0:9fca2b23d0ba 175 }
marcozecchini 0:9fca2b23d0ba 176 ```
marcozecchini 0:9fca2b23d0ba 177 ## No utest support template
marcozecchini 0:9fca2b23d0ba 178 ```c++
marcozecchini 0:9fca2b23d0ba 179 #include "greentea-client/test_env.h"
marcozecchini 0:9fca2b23d0ba 180 #include "unity/unity.h"
marcozecchini 0:9fca2b23d0ba 181
marcozecchini 0:9fca2b23d0ba 182 void app_start(int, char*[]) {
marcozecchini 0:9fca2b23d0ba 183 bool result = true;
marcozecchini 0:9fca2b23d0ba 184 GREENTEA_SETUP(15, "default_auto");
marcozecchini 0:9fca2b23d0ba 185
marcozecchini 0:9fca2b23d0ba 186 // Test suite body
marcozecchini 0:9fca2b23d0ba 187 // Here you can run your test cases and or assertions
marcozecchini 0:9fca2b23d0ba 188 TEST_ASSERT_TRUE(true);
marcozecchini 0:9fca2b23d0ba 189 TEST_ASSERT_FALSE(false);
marcozecchini 0:9fca2b23d0ba 190
marcozecchini 0:9fca2b23d0ba 191 GREENTEA_TESTSUITE_RESULT(result);
marcozecchini 0:9fca2b23d0ba 192 }
marcozecchini 0:9fca2b23d0ba 193 ```