Unit Testing on Linux

备注

Host testing with IDF is experimental for now. We try our best to keep interfaces stable but can’t guarantee it for now. Feedback via github or the forum on esp32.com is highly welcome, though and may influence the future design of the host-based tests.

This article provides an overview of unit tests with IDF on Linux. For using unit tests on the target, please refer to target based unit testing.

Embedded Software Tests

Embedded software tests are challenging due to the following factors:

  • Difficulties running tests efficiently.

  • Lack of many operating system abstractions when interfacing with hardware, making it difficult to isolate code under test.

To solve these two problems, Linux host-based tests with CMock are introduced. Linux host-based tests are more efficient than unit tests on the target since they:

  • Compile the necessary code only

  • Don’t need time to upload to a target

  • Run much faster on a host-computer, compared to an ESP

Using the CMock framework also solves the problem of hardware dependencies. Through mocking, hardware details are emulated and specified at run time, but only if necessary.

Of course, using code on the host and using mocks does not fully represent the target device. Thus, two kinds of tests are recommended:

  1. Unit tests which test program logic on a Linux machine, isolated through mocks.

  2. System/Integration tests which test the interaction of components and the whole system. They run on the target, where irrelevant components and code may as well be emulated via mocks.

This documentation is about the first kind of tests. Refer to target based unit testing for more information on target tests (the second kind of tests).

IDF Unit Tests on Linux Host

The current focus of the Linux host tests is on creating isolated unit tests of components, while mocking the component’s dependencies with CMock.

A complete implementation of IDF to run on Linux does not exist currently.

There are currently two examples for running IDF-built code on Linux host:

Inside the component which should be tested, there is a separate directory host_test, besides the “traditional” test directory or the test_apps directory. It has one or more subdirectories:

- host_test/

             - fixtures/
                 contains test fixtures (structs/functions to do test case set-up and tear-down).
                 If there are no fixtures, this can be ommitted.
             - <test_name>/
                 IDF applications which run the tests
             - <test_name2>/
                 Further tests are possible.

The IDF applications inside host_test set the mocking configuration as described in the IDF unit test documentation.

The NVS page unit test provides some illustration of how to control the mocks.

Requirements

  • 已安装 ESP-IDF 及使用 ESP-IDF 的所有依赖项

  • 满足系统软件包需求 (libbsdlibbsd-dev)

  • Linux 或 macOS 和 GCC 编译器已更新至足够新的版本

  • 应用程序所依赖的所有组件必须受 Linux 目标(Linux/POSIX 模拟器)支持,或可进行模拟

对于在 Linux 目标上运行的应用程序,需要在应用程序根目录的 CMakeLists.txt 文件中,设置 COMPONENTS 变量为 main,具体操作如下:

set(COMPONENTS main)

为方便起见,应用程序会在构建过程中,自动包含 ESP-IDF 的所有组件,执行上述代码则可以防止此类情况。

The host tests have been tested on Ubuntu 20.04 with GCC version 9 and 10.