ESP-IDF Unit testing with Unity

When you are developing an application using ESP-IDF and you are considering adding unit testing for your components functions, this extension can help to discover and execute tests on your device based on Unity as described in Unit Testing in ESP32 documentation.

The extension explores tests in your current project workspace folders that follow the convension in the former documentation, this is, all tests files that follow the glob pattern specified in the idf.unitTestFilePattern configuration setting (default: **/test/test_*.c) in your current workspace folders. The tests cases are parsed with the TEST_CASE\\(\"(.*)\",\\s*\"(.*)\"\\) regular expression matching the following test file format:

TEST_CASE("test name", "[module name]")
{
        // Add test here
}

Configure the ESP-IDF Project to enable unit tests in the extension

Let’s say you have a ESP-IDF project with the following structure:

unit_test
  - components                              - Components of the application project
    - testable
      - include
      - test                                - Test directory of the component
        * component.mk / CMakeLists.txt     - Component makefile of tests
        * test_mean.c                       - Test source file
      * component.mk / CMakeLists.txt       - Component makefile
      * mean.c                              - Component source file

Inside the testable component, unit tests are added into test directory. test directory contains source files of the tests and the component makefile (component.mk / CMakeLists.txt).

If you want to add tests for a testable component, just need to define a test subdirectory and add test_name.c files with the different test cases to run.

This is the structure from the ESP-IDF unit_test example which can serve as reference.

Note

You can customize the test file discovery pattern by modifying the idf.unitTestFilePattern setting in your VS Code settings. This allows you to use different naming conventions or directory structures for your test files.

PyTest Embedded Services Configuration

The extension uses pytest-embedded to run tests on ESP-IDF devices. The idf.pyTestEmbeddedServices configuration setting allows you to specify which embedded services to use when running pytest commands.

By default, the extension uses ["esp", "idf"] as the embedded services. These services provide the following functionality:

  • esp: Enables Espressif-specific functionality including automatic target detection and port confirmation using esptool

  • idf: Provides ESP-IDF project support including automatic flashing of built binaries and parsing of binary information

You can customize the embedded services by modifying the idf.pyTestEmbeddedServices setting in your VS Code settings. For example, you might want to add additional services like:

  • serial: For basic serial port communication

  • jtag: For OpenOCD/GDB utilities

  • qemu: For running tests on QEMU instead of real hardware

  • wokwi: For running tests on Wokwi simulation platform

For a complete list of available services and their capabilities, refer to the pytest-embedded Services Documentation.

Note

The embedded services you choose will affect the pytest command that gets executed. Make sure the services you specify are compatible with your testing environment and requirements.

Running the tests

When you click on the Testing Tab in the Visual Studio Code Activity bar, the extension will try to find all test files and test cases and save the list of test components to add later in step 3.

Note

User needs to install ESP-IDF PyTest python requirements by selecting menu View > Command Palette and type ESP-IDF Unit Test: Install ESP-IDF PyTest requirements. Select the command and see the pytest package installation output.

When it press the run button on a test, it will configure the current project before the tests as follows:

  1. Check that PyTest requirements from ESP-IDF are satisfied.

Note

Unit tests in this extension requires ESP-IDF PyTest requirements to be installed in your Python virtual environment.

  1. Install ESP-IDF PyTest requirements if they are not found in the python current virtual environment specified in idf.toolsPath configuration setting in settings.json.

  2. Copy the unity-app from the extension template and add the test components to the main CMakeLists.txt TEST_COMPONENTS cmake variable. The extension unity-app is a basic ESP-IDF application with a unity menu that will be built and flashed on the current idf.port serial device with all test cases that were found during exploration step.

Note

You can also create, build and flash the unity test application using the ESP-IDF Unit Test: Install ESP-IDF PyTest requirements extension command, which will copy build and flash to your device the generated unit testing application.

  1. Runs pytest-embedded a plugin that extends PyTest to run on esp-idf devices and output the results as XML file in the unity-app directory. This is executed as an extension task and the output shown in the terminal (similar to Build and Flash tasks). The pytest command uses the embedded services specified in the idf.pyTestEmbeddedServices configuration setting (default: ["esp", "idf"]).

Note

You can customize the embedded services used by pytest by modifying the idf.pyTestEmbeddedServices setting in your VS Code settings. This allows you to specify different services or add additional ones as needed for your testing environment.

  1. The XML results file is parsed and test results are updated in the Testing tab with test duration.

  2. You can refresh the tests and build the unity-app again with the Refresh Tests button from the Testing tab.