PIO Unit Testing¶

Demo¶

This is a demo of Local & Embedded: Calculator, which demonstrates running embedded tests on physical hardware (Arduino Uno) and native tests on host machine (desktop).

Learn more about platformio test command.

Tutorials and Examples¶

Configuration¶

PIO Unit Testing Engine can be configured from “platformio.ini” (Project Configuration File)

Test Types¶

Test Runner¶

Test Runner allows you to process specific environments or ignore a test using “Glob patterns”. You can also ignore a test for specific environments using a test_ignore option from “platformio.ini” (Project Configuration File).

Test Transport¶

PIO Unit Testing Engine engine uses different transports to communicate with a target device. By default, it uses Serial/UART transport provided by a framework. For example, when “framework = arduino”, the first available Serial will be used. When Native dev-platform is used a native transport will be activated automatically. See example below.

Default baudrate/speed is set to test_speed.

You can also define custom transport and implement its interface:

• unittest_uart_begin();

• unittest_uart_putchar(char c);

• unittest_uart_flush();

• unittest_uart_end();

Examples

1. Custom transport for Native platform

• Set test_transport = custom in “platformio.ini” (Project Configuration File)

[env:mycustomtransport]
platform = native
test_transport = custom

• Create unittest_transport.h file in project/test directory and implement prototypes above

#ifndef UNITTEST_TRANSPORT_H
#define UNITTEST_TRANSPORT_H

#include <stdio.h>

void unittest_uart_begin() {

}

void unittest_uart_putchar(char c) {
  putchar(c);
}

void unittest_uart_flush() {
  fflush(stdout);
}

void unittest_uart_end() {

}

#endif

2. STM32Cube HAL and Nucleo-F401RE: debugging and unit testing

Workflow¶

1. Create PlatformIO project using the platformio project init command. For Desktop Unit Testing (on a host machine), you need to use Native.

   ; PlatformIO Project Configuration File
   ;
   ;   Build options: build flags, source filter, extra scripting
   ;   Upload options: custom port, speed and extra flags
   ;   Library options: dependencies, extra library storages
   ;
   ; Please visit documentation for the other options and examples
   ; https://docs.platformio.org/page/projectconf.html
   
   ;
   ; Embedded platforms
   ;
   
   [env:uno]
   platform = atmelavr
   framework = arduino
   board = uno
   
   [env:nodemcu]
   platform = espressif8266
   framework = arduino
   board = nodemcuv2
   
   ;
   ; Desktop platforms (Win, Mac, Linux, Raspberry Pi, etc)
   ; See https://platformio.org/platforms/native
   ;
   
   [env:native]
   platform = native
   

2. Create a test folder in a root of your project. See test_dir.

3. Write a test using API. Each test is a small independent program/firmware with its own main() or setup()/loop() functions. Test should start with UNITY_BEGIN() and finish with UNITY_END() calls.

   Warning

   If your board does not support software resetting via Serial.DTR/RTS, you should add at least 2 seconds delay before UNITY_BEGIN(). That time is needed to establish a Serial connection between a host machine and a target device.

   delay(2000); // for Arduino framework
   wait(2);     // for ARM mbed framework
   UNITY_BEGIN();
   

4. Place a test in the test directory. If you have more than one test, split them into sub-folders. For example, test/test_1/*.[c,cpp,h], test_N/*.[c,cpp,h], etc. If there is no such directory in the test folder, then PIO Unit Testing Engine will treat the source code of test folder as SINGLE test.

5. Run tests using the platformio test command.

API¶

Summary of the Unity Test API:

• Running Tests

  • RUN_TEST(func)

• Ignoring Tests

  • TEST_IGNORE()

  • TEST_IGNORE_MESSAGE (message)

• Aborting Tests

  • TEST_PROTECT()

  • TEST_ABORT()

• Basic Validity Tests

  • TEST_ASSERT_TRUE(condition)

  • TEST_ASSERT_FALSE(condition)

  • TEST_ASSERT(condition)

  • TEST_ASSERT_UNLESS(condition)

  • TEST_FAIL()

  • TEST_FAIL_MESSAGE(message)

• Numerical Assertions: Integers

  • TEST_ASSERT_EQUAL_INT(expected, actual)

  • TEST_ASSERT_EQUAL_INT8(expected, actual)

  • TEST_ASSERT_EQUAL_INT16(expected, actual)

  • TEST_ASSERT_EQUAL_INT32(expected, actual)

  • TEST_ASSERT_EQUAL_INT64(expected, actual)

  • TEST_ASSERT_EQUAL_UINT(expected, actual)

  • TEST_ASSERT_EQUAL_UINT8(expected, actual)

  • TEST_ASSERT_EQUAL_UINT16(expected, actual)

  • TEST_ASSERT_EQUAL_UINT32(expected, actual)

  • TEST_ASSERT_EQUAL_UINT64(expected, actual)

  • TEST_ASSERT_EQUAL_HEX(expected, actual)

  • TEST_ASSERT_EQUAL_HEX8(expected, actual)

  • TEST_ASSERT_EQUAL_HEX16(expected, actual)

  • TEST_ASSERT_EQUAL_HEX32(expected, actual)

  • TEST_ASSERT_EQUAL_HEX64(expected, actual)

  • TEST_ASSERT_EQUAL_HEX8_ARRAY(expected, actual, elements)

  • TEST_ASSERT_EQUAL(expected, actual)

  • TEST_ASSERT_INT_WITHIN(delta, expected, actual)

• Numerical Assertions: Bitwise

  • TEST_ASSERT_BITS(mask, expected, actual)

  • TEST_ASSERT_BITS_HIGH(mask, actual)

  • TEST_ASSERT_BITS_LOW(mask, actual)

  • TEST_ASSERT_BIT_HIGH(mask, actual)

  • TEST_ASSERT_BIT_LOW(mask, actual)

• Numerical Assertions: Floats

  • TEST_ASSERT_FLOAT_WITHIN(delta, expected, actual)

  • TEST_ASSERT_EQUAL_FLOAT(expected, actual)

  • TEST_ASSERT_EQUAL_DOUBLE(expected, actual)

• String Assertions

  • TEST_ASSERT_EQUAL_STRING(expected, actual)

  • TEST_ASSERT_EQUAL_STRING_LEN(expected, actual, len)

  • TEST_ASSERT_EQUAL_STRING_MESSAGE(expected, actual, message)

  • TEST_ASSERT_EQUAL_STRING_LEN_MESSAGE(expected, actual, len, message)

• Pointer Assertions

  • TEST_ASSERT_NULL(pointer)

  • TEST_ASSERT_NOT_NULL(pointer)

• Memory Assertions

  • TEST_ASSERT_EQUAL_MEMORY(expected, actual, len)

CLI Guide¶