Component Tests on ESP32 with VSCode and the Unity Testing Framework

When working on embedded systems like the ESP32, testing your code on real hardware is invaluable. While simulations and mocks have their place, running tests directly on the target device ensures that your components behave exactly as expected in the environment where they will ultimately run.

The ESP-IDF provides a way to perform these tests using the Unity testing framework. However, the official documentation is somewhat sparse and can be confusing if you’re setting this up for the first time. In this article, we’ll walk through the process step-by-step, so you can quickly get your own component tests running in VSCode.

A working sample project can be found here.

Setup

Create a Component to test

Your component should be located at:

<project_root>/components/<component_to_test>

For this example, I’ve created a simple hashing component which provides a SHA256 function at:

/components/hash

Inside the component directory, create a sub-directory named test and add a test file:

<project_root>/components/<component_to_test>/test/test_<component_name>.c

In my example this file would be:

/components/hash/test/test_hash.c

Any file placed in this folder with the test_*.c naming convention will be automatically picked up as a component test.

In your component’s CMakeLists.txt, ensure you include Unity:

The complete layout of the component directory should look something like this:

Create a Test App

To run the tests, you need a dedicated test application. For ESP-IDF v5.4.1, the VSCode test runner expects this app to be located at <project_root>/unity-app.

This app is minimal and only needs to execute Unity’s test runner:

In the test app’s CMakeLists.txt, you must specify the components you want to test. In my example I want to test the hash component:

Writing Tests

Tests are written using the Unity testing framework.

Each test case is defined with the TEST_CASE macro:

TEST_CASE("Hashing produces correct result", "[hash]") {
    [...]
    TEST_ASSERT_EQUAL(32, result);
}

 

• • The first argument is the test’s name.

• • The second argument in square brackets is a category.

• • Use TEST_ASSERT_* macros to verify results.

This approach allows you to group and organize tests efficiently.

A complete Test Suite could look like this:

Executing Tests

Once your tests are in place, there are two ways to run them:

Manual Execution

ESP-IDF provides a built-in launch target for testing: ESP-IDF: Unit Test: Build and Flash Unit Test App for Testing

This option builds and flashes the test app using the build and flash settings from the ESP-IDF VSCode extension.

After flashing, start the ESP-IDF monitor. If everything is working correctly, you’ll see:

When you press ENTER, a list of tests will appear. Select one by entering its number and pressing ENTER. The results will then be displayed directly in the monitor.

Using the VSCode Test Runner

VSCode also offers an integrated test runner UI:

 

• • Once the ESP-IDF plugin for VSCode is installed, tests are automatically discovered.

• • You can run individual tests or all tests for a component.

• • The first time you run a test, the test runner will build and flash the test app.

• • Results are displayed in the UI with a convenient green/red indicator for success or failure.

This method is extremely convenient for quickly iterating on tests without manually flashing and monitoring output.

The test output is shown in the terminal. You may see some pytest warnings, but these are harmless and can be ignored. The important thing is that the test run reports “passed” which is also reflected by the green checkmark in the test runner UI.

Conclusion

Running component tests directly on an ESP32 using VSCode and Unity is a powerful way to ensure code quality. Although ESP-IDF’s documentation can be lacking, once the initial setup is complete, testing becomes seamless and efficient.

In future articles, we’ll explore more advanced test setups, including mocking and hardware abstraction, but with this foundation, you should already be able to build confidence in your code on real hardware.