bf2da4859c
ifndef some macros to allow overriding during compilation |
||
|---|---|---|
| .. | ||
| greentea-client | ||
| source | ||
| README.md | ||
README.md
Table of Contents
greentea-client
Tip: If you are unsure about the terms used in this document, please see the Terms section.
greentea-client is a C++ client library for the Greentea test tool when used in an mbed project.
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.
DUT <--- serial port connection ---> host
(slave) . (master)
.
[greentea-client] . [conn_process] [htrun]
===== . ================ =========
| . | |
| . | |
| {{ key ; value }} | |
|------------------------->| (key, value, timestamp) |
| . |------------------------>|
| . | |
| . | |
| . | |
| . | |
| . | |
| . | (key, value, timestamp) |
| {{ key ; value }} |<------------------------|
|<-------------------------| |
| . | |
.
greentea-client is a yotta module. You can easily include it in your yotta project as dependency/testDependency.
mbed-drivers dependencies
This package was introduced as a future replacement for the 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.
Examples of test cases ported from the old mbed-drivers/test_env to the greentea-client model can be found here:
Greentea test tools
Greentea is a test automation tool written in Python and designed to automate test execution for mbed projects encapsulated as yotta modules. Its key features include: integration with yotta module, test automation for yotta module's tests and reporting.
Compatibility
greentea-client is compatible with:
Greentea support
If you wish to use greentea-client please make sure you are using latest Greentea tools from PyPI (you will need Python 2.7):
$ pip install mbed-greentea --upgrade
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:
$ pip install "mbed-greentea<0.2.0" --upgrade
Note: Greentea 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.
utest support
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 testDependency section:
{
"testDependencies": {
"utest": "^1.10.0"
}
}
greentea-client support in your module
Currently greentea-client is in on version 1.0.x. Please use a ^1.0.0 dependency version in your module.json file.
Example of module.json file with greentea-client as a test dependency:
{
"testDependencies": {
"greentea-client": "^1.0.0",
"utest" : "^1.10.0",
"unity" : "^2.1.0"
}
}
Terms
Test suite
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).
Test case
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).
key-value protocol
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.
A KiVi message is defined as a string encapsulated between double curly braces. The key and value are separated by a semicolon (;).
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.
This protocol is a master-slave protocol. The host has the role of master and the DUT is the slave.
greentea-client implements the key-value protocol tokenizer and parser.
Where can I use it?
It is possible to write test cases that use greentea-client and at the same time support mbed features such as MINAR scheduler. It is also possible to mix greentea-client with other test tools we use at mbed such as utest and unity.
You can also find references to greentea-client in many mbed packages. For example:
- mbed-drivers - check its module.json
- core-util - check its module.json
Test suite model
utest support template
#include "greentea-client/test_env.h"
#include "utest/utest.h"
#include "unity/unity.h"
void test_case_1_func() {
// Test case #1 body
// Here you can run your test cases and assertions
TEST_ASSERT_TRUE(true);
TEST_ASSERT_FALSE(false);
}
void test_case_2_func() {
// Test case #2 body
// Here you can run your test cases and assertions
TEST_ASSERT_TRUE(true);
TEST_ASSERT_FALSE(false);
}
const Case cases[] = {
Case("Test case #1 name", test_case_1_func),
Case("Test case #1 name", test_case_2_func)
};
status_t greentea_setup(const size_t number_of_cases) {
GREENTEA_SETUP(5, "default_auto");
return greentea_test_setup_handler(number_of_cases);
}
void app_start(int, char*[]) {
Harness::run(specification);
}
No utest support template
#include "greentea-client/test_env.h"
#include "unity/unity.h"
void app_start(int, char*[]) {
bool result = true;
GREENTEA_SETUP(15, "default_auto");
// Test suite body
// Here you can run your test cases and or assertions
TEST_ASSERT_TRUE(true);
TEST_ASSERT_FALSE(false);
GREENTEA_TESTSUITE_RESULT(result);
}