BA / SerialCom

Important changes to repositories hosted on mbed.com

Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.

To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.

It is also possible to export all your personal repositories from the account settings page.

Fork of OmniWheels by Gustav Atmel

mbed-os/features/frameworks/greentea-client/README.md@1:9c5af431a1f1, 2018-05-01 (annotated)

Committer:
gustavatmel
Date:
Tue May 01 15:47:08 2018 +0000
Revision:
1:9c5af431a1f1
sdf

Who changed what in which revision?

UserRevisionLine numberNew contents of line
gustavatmel 1:9c5af431a1f1 1 # Table of Contents
gustavatmel 1:9c5af431a1f1 2
gustavatmel 1:9c5af431a1f1 3 * [greentea-client](#greentea-client)
gustavatmel 1:9c5af431a1f1 4 * [mbed-drivers dependencies](#mbed-drivers-dependencies)
gustavatmel 1:9c5af431a1f1 5 * [Greentea test tools](#greentea-test-tools)
gustavatmel 1:9c5af431a1f1 6 * [Compatibility](#compatibility)
gustavatmel 1:9c5af431a1f1 7 * [Greentea support](#greentea-support)
gustavatmel 1:9c5af431a1f1 8 * [utest support](#utest-support)
gustavatmel 1:9c5af431a1f1 9 * [greentea-client support in your module](#greentea-client-support-in-your-module)
gustavatmel 1:9c5af431a1f1 10 * [Terms](#terms)
gustavatmel 1:9c5af431a1f1 11 * [Test suite](#test-suite)
gustavatmel 1:9c5af431a1f1 12 * [Test case](#test-case)
gustavatmel 1:9c5af431a1f1 13 * [key-value protocol](#key-value-protocol)
gustavatmel 1:9c5af431a1f1 14 * [Where can I use it?](#where-can-i-use-it)
gustavatmel 1:9c5af431a1f1 15 * [Test suite model](#test-suite-model)
gustavatmel 1:9c5af431a1f1 16 * [utest support template](#utest-support-template)
gustavatmel 1:9c5af431a1f1 17 * [No utest support template](#no-utest-support-template)
gustavatmel 1:9c5af431a1f1 18
gustavatmel 1:9c5af431a1f1 19 # greentea-client
gustavatmel 1:9c5af431a1f1 20
gustavatmel 1:9c5af431a1f1 21 **Tip:** If you are unsure about the terms used in this document, please see the [Terms](#Terms) section.
gustavatmel 1:9c5af431a1f1 22
gustavatmel 1:9c5af431a1f1 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.
gustavatmel 1:9c5af431a1f1 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).
gustavatmel 1:9c5af431a1f1 25
gustavatmel 1:9c5af431a1f1 26
gustavatmel 1:9c5af431a1f1 27 ```
gustavatmel 1:9c5af431a1f1 28 DUT <--- serial port connection ---> host
gustavatmel 1:9c5af431a1f1 29 (slave) . (master)
gustavatmel 1:9c5af431a1f1 30 .
gustavatmel 1:9c5af431a1f1 31 [greentea-client] . [conn_process] [htrun]
gustavatmel 1:9c5af431a1f1 32 ===== . ================ =========
gustavatmel 1:9c5af431a1f1 33 | . | |
gustavatmel 1:9c5af431a1f1 34 | . | |
gustavatmel 1:9c5af431a1f1 35 | {{ key ; value }} | |
gustavatmel 1:9c5af431a1f1 36 |------------------------->| (key, value, timestamp) |
gustavatmel 1:9c5af431a1f1 37 | . |------------------------>|
gustavatmel 1:9c5af431a1f1 38 | . | |
gustavatmel 1:9c5af431a1f1 39 | . | |
gustavatmel 1:9c5af431a1f1 40 | . | |
gustavatmel 1:9c5af431a1f1 41 | . | |
gustavatmel 1:9c5af431a1f1 42 | . | |
gustavatmel 1:9c5af431a1f1 43 | . | (key, value, timestamp) |
gustavatmel 1:9c5af431a1f1 44 | {{ key ; value }} |<------------------------|
gustavatmel 1:9c5af431a1f1 45 |<-------------------------| |
gustavatmel 1:9c5af431a1f1 46 | . | |
gustavatmel 1:9c5af431a1f1 47 .
gustavatmel 1:9c5af431a1f1 48 ```
gustavatmel 1:9c5af431a1f1 49
gustavatmel 1:9c5af431a1f1 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```.
gustavatmel 1:9c5af431a1f1 51
gustavatmel 1:9c5af431a1f1 52 ## mbed-drivers dependencies
gustavatmel 1:9c5af431a1f1 53
gustavatmel 1:9c5af431a1f1 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.
gustavatmel 1:9c5af431a1f1 55
gustavatmel 1:9c5af431a1f1 56 Examples of test cases ported from the old ```mbed-drivers/test_env``` to the ```greentea-client``` model can be found here:
gustavatmel 1:9c5af431a1f1 57 * [core-util](https://github.com/ARMmbed/core-util/pull/95)
gustavatmel 1:9c5af431a1f1 58 * [ualloc](https://github.com/ARMmbed/ualloc/pull/24)
gustavatmel 1:9c5af431a1f1 59 * [minar](https://github.com/ARMmbed/minar/pull/36)
gustavatmel 1:9c5af431a1f1 60 * [mbed-drivers](https://github.com/ARMmbed/mbed-drivers/pull/165)
gustavatmel 1:9c5af431a1f1 61 * [sal](https://github.com/ARMmbed/sal/pull/46)
gustavatmel 1:9c5af431a1f1 62 * [sockets](https://github.com/ARMmbed/sockets/pull/64)
gustavatmel 1:9c5af431a1f1 63 * [utest](https://github.com/ARMmbed/utest/pull/6)
gustavatmel 1:9c5af431a1f1 64
gustavatmel 1:9c5af431a1f1 65 ## Greentea test tools
gustavatmel 1:9c5af431a1f1 66
gustavatmel 1:9c5af431a1f1 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.
gustavatmel 1:9c5af431a1f1 68
gustavatmel 1:9c5af431a1f1 69 ## Compatibility
gustavatmel 1:9c5af431a1f1 70
gustavatmel 1:9c5af431a1f1 71 ```greentea-client``` is compatible with:
gustavatmel 1:9c5af431a1f1 72 * [Greentea](https://github.com/ARMmbed/greentea) v0.2.x onwards
gustavatmel 1:9c5af431a1f1 73 * [htrun](https://github.com/ARMmbed/htrun) v0.2.x onwards
gustavatmel 1:9c5af431a1f1 74 * [utest](https://github.com/ARMmbed/utest) v1.10.0 onwards
gustavatmel 1:9c5af431a1f1 75 * [unity](https://github.com/ARMmbed/utest) v2.0.1 onwards
gustavatmel 1:9c5af431a1f1 76
gustavatmel 1:9c5af431a1f1 77 ### Greentea support
gustavatmel 1:9c5af431a1f1 78
gustavatmel 1:9c5af431a1f1 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):
gustavatmel 1:9c5af431a1f1 80 ```
gustavatmel 1:9c5af431a1f1 81 $ pip install mbed-greentea --upgrade
gustavatmel 1:9c5af431a1f1 82 ```
gustavatmel 1:9c5af431a1f1 83
gustavatmel 1:9c5af431a1f1 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:
gustavatmel 1:9c5af431a1f1 85 ```
gustavatmel 1:9c5af431a1f1 86 $ pip install "mbed-greentea<0.2.0" --upgrade
gustavatmel 1:9c5af431a1f1 87 ```
gustavatmel 1:9c5af431a1f1 88
gustavatmel 1:9c5af431a1f1 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.
gustavatmel 1:9c5af431a1f1 90
gustavatmel 1:9c5af431a1f1 91 ### utest support
gustavatmel 1:9c5af431a1f1 92
gustavatmel 1:9c5af431a1f1 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:
gustavatmel 1:9c5af431a1f1 94 ```json
gustavatmel 1:9c5af431a1f1 95 {
gustavatmel 1:9c5af431a1f1 96 "testDependencies": {
gustavatmel 1:9c5af431a1f1 97 "utest": "^1.10.0"
gustavatmel 1:9c5af431a1f1 98 }
gustavatmel 1:9c5af431a1f1 99 }
gustavatmel 1:9c5af431a1f1 100 ```
gustavatmel 1:9c5af431a1f1 101
gustavatmel 1:9c5af431a1f1 102 ### greentea-client support in your module
gustavatmel 1:9c5af431a1f1 103
gustavatmel 1:9c5af431a1f1 104 Currently ```greentea-client``` is in on version ```1.0.x```. Please use a ```^1.0.0``` dependency version in your ```module.json``` file.
gustavatmel 1:9c5af431a1f1 105
gustavatmel 1:9c5af431a1f1 106 Example of ```module.json``` file with ```greentea-client``` as a test dependency:
gustavatmel 1:9c5af431a1f1 107 ```json
gustavatmel 1:9c5af431a1f1 108 {
gustavatmel 1:9c5af431a1f1 109 "testDependencies": {
gustavatmel 1:9c5af431a1f1 110 "greentea-client": "^1.0.0",
gustavatmel 1:9c5af431a1f1 111 "utest" : "^1.10.0",
gustavatmel 1:9c5af431a1f1 112 "unity" : "^2.1.0"
gustavatmel 1:9c5af431a1f1 113 }
gustavatmel 1:9c5af431a1f1 114 }
gustavatmel 1:9c5af431a1f1 115 ```
gustavatmel 1:9c5af431a1f1 116
gustavatmel 1:9c5af431a1f1 117 ## Terms
gustavatmel 1:9c5af431a1f1 118
gustavatmel 1:9c5af431a1f1 119 ### Test suite
gustavatmel 1:9c5af431a1f1 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).
gustavatmel 1:9c5af431a1f1 121
gustavatmel 1:9c5af431a1f1 122 ### Test case
gustavatmel 1:9c5af431a1f1 123
gustavatmel 1:9c5af431a1f1 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).
gustavatmel 1:9c5af431a1f1 125
gustavatmel 1:9c5af431a1f1 126 ### key-value protocol
gustavatmel 1:9c5af431a1f1 127
gustavatmel 1:9c5af431a1f1 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.
gustavatmel 1:9c5af431a1f1 129 A ```KiVi``` message is defined as a string encapsulated between double curly braces. The key and value are separated by a semicolon (```;```).
gustavatmel 1:9c5af431a1f1 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.
gustavatmel 1:9c5af431a1f1 131 This protocol is a master-slave protocol. The host has the role of _master_ and the DUT is the _slave_.
gustavatmel 1:9c5af431a1f1 132
gustavatmel 1:9c5af431a1f1 133 ```greentea-client``` implements the key-value protocol tokenizer and parser.
gustavatmel 1:9c5af431a1f1 134
gustavatmel 1:9c5af431a1f1 135 ## Where can I use it?
gustavatmel 1:9c5af431a1f1 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).
gustavatmel 1:9c5af431a1f1 137
gustavatmel 1:9c5af431a1f1 138 You can also find references to ```greentea-client``` in many ```mbed``` packages. For example:
gustavatmel 1:9c5af431a1f1 139 * [mbed-drivers](https://github.com/ARMmbed/mbed-drivers) - check its [module.json](https://github.com/ARMmbed/mbed-drivers/blob/master/module.json)
gustavatmel 1:9c5af431a1f1 140 * [core-util](https://github.com/ARMmbed/core-util) - check its [module.json](https://github.com/ARMmbed/core-util/blob/master/module.json)
gustavatmel 1:9c5af431a1f1 141
gustavatmel 1:9c5af431a1f1 142 # Test suite model
gustavatmel 1:9c5af431a1f1 143 ## utest support template
gustavatmel 1:9c5af431a1f1 144 ```c++
gustavatmel 1:9c5af431a1f1 145 #include "greentea-client/test_env.h"
gustavatmel 1:9c5af431a1f1 146 #include "utest/utest.h"
gustavatmel 1:9c5af431a1f1 147 #include "unity/unity.h"
gustavatmel 1:9c5af431a1f1 148
gustavatmel 1:9c5af431a1f1 149 void test_case_1_func() {
gustavatmel 1:9c5af431a1f1 150 // Test case #1 body
gustavatmel 1:9c5af431a1f1 151 // Here you can run your test cases and assertions
gustavatmel 1:9c5af431a1f1 152 TEST_ASSERT_TRUE(true);
gustavatmel 1:9c5af431a1f1 153 TEST_ASSERT_FALSE(false);
gustavatmel 1:9c5af431a1f1 154 }
gustavatmel 1:9c5af431a1f1 155
gustavatmel 1:9c5af431a1f1 156 void test_case_2_func() {
gustavatmel 1:9c5af431a1f1 157 // Test case #2 body
gustavatmel 1:9c5af431a1f1 158 // Here you can run your test cases and assertions
gustavatmel 1:9c5af431a1f1 159 TEST_ASSERT_TRUE(true);
gustavatmel 1:9c5af431a1f1 160 TEST_ASSERT_FALSE(false);
gustavatmel 1:9c5af431a1f1 161 }
gustavatmel 1:9c5af431a1f1 162
gustavatmel 1:9c5af431a1f1 163 const Case cases[] = {
gustavatmel 1:9c5af431a1f1 164 Case("Test case #1 name", test_case_1_func),
gustavatmel 1:9c5af431a1f1 165 Case("Test case #1 name", test_case_2_func)
gustavatmel 1:9c5af431a1f1 166 };
gustavatmel 1:9c5af431a1f1 167
gustavatmel 1:9c5af431a1f1 168 status_t greentea_setup(const size_t number_of_cases) {
gustavatmel 1:9c5af431a1f1 169 GREENTEA_SETUP(5, "default_auto");
gustavatmel 1:9c5af431a1f1 170 return greentea_test_setup_handler(number_of_cases);
gustavatmel 1:9c5af431a1f1 171 }
gustavatmel 1:9c5af431a1f1 172
gustavatmel 1:9c5af431a1f1 173 void app_start(int, char*[]) {
gustavatmel 1:9c5af431a1f1 174 Harness::run(specification);
gustavatmel 1:9c5af431a1f1 175 }
gustavatmel 1:9c5af431a1f1 176 ```
gustavatmel 1:9c5af431a1f1 177 ## No utest support template
gustavatmel 1:9c5af431a1f1 178 ```c++
gustavatmel 1:9c5af431a1f1 179 #include "greentea-client/test_env.h"
gustavatmel 1:9c5af431a1f1 180 #include "unity/unity.h"
gustavatmel 1:9c5af431a1f1 181
gustavatmel 1:9c5af431a1f1 182 void app_start(int, char*[]) {
gustavatmel 1:9c5af431a1f1 183 bool result = true;
gustavatmel 1:9c5af431a1f1 184 GREENTEA_SETUP(15, "default_auto");
gustavatmel 1:9c5af431a1f1 185
gustavatmel 1:9c5af431a1f1 186 // Test suite body
gustavatmel 1:9c5af431a1f1 187 // Here you can run your test cases and or assertions
gustavatmel 1:9c5af431a1f1 188 TEST_ASSERT_TRUE(true);
gustavatmel 1:9c5af431a1f1 189 TEST_ASSERT_FALSE(false);
gustavatmel 1:9c5af431a1f1 190
gustavatmel 1:9c5af431a1f1 191 GREENTEA_TESTSUITE_RESULT(result);
gustavatmel 1:9c5af431a1f1 192 }
gustavatmel 1:9c5af431a1f1 193 ```