Forem: Aluizio Tomazelli Junior

Unit testing ESP-IDF components with GoogleTest (host-based)

Aluizio Tomazelli Junior — Sun, 22 Feb 2026 06:05:27 +0000

I had been looking for a way to test ESP-IDF component logic without flashing to the board every time. The cycle of edit, flash, read serial gets old fast, especially when the bug is just in a calculation or a state machine — nothing hardware-specific.

ESP-IDF supports building for a Linux target, which means you can run tests straight on your machine. I put together a repo to document how I set this up, using GoogleTest as the test framework. This post covers the first example: aluiziotomazelli/gtest-esp-idf.

Prerequisites

To run these tests you need ESP-IDF 5.x installed and sourced, a Linux machine or WSL2, and two system packages that the IDF linux target depends on:

sudo apt install libbsd0 libbsd-dev

If you use the official ESP-IDF Docker container (idf-env latest), these are already included and you can skip this step — the CI badges on the repo run exactly that way, with no extra setup.

Ruby is not needed for this example. It only comes in when using CMock-based IDF mocks, which is a different approach covered in a future chapter.

Why GoogleTest instead of Unity?

Unity is a native ESP-IDF component — it's already there, no setup needed. For simple assertions it works fine. The issue shows up when your component has multiple C++ classes with distinct responsibilities and you need to test them in isolation.

Unity works alongside CMock, which ESP-IDF uses internally to mock its own components. The problem is that CMock doesn't handle C++ classes, so you end up writing mocks by hand. GMock handles this directly in the test file, in a few lines.

Project layout

The repo is organized as numbered chapters. The first one, 01_basic_test, has this structure:

01_basic_test/
├── CMakeLists.txt
├── include/
│   ├── i_sum.hpp     # Interface (abstract base class)
│   └── sum.hpp       # Concrete class header
├── src/
│   └── sum.cpp       # Production code
├── host_test/
│   ├── gtest/        # GTest wrapper component
│   └── test_sum/     # Test project for the Sum class
└── test_apps/        # Hardware verification

Production code stays in src/ and include/. Tests stay in host_test/. They don't mix.

Why the interface?

i_sum.hpp defines an abstract base class for Sum. For this example it's not strictly needed — the class is simple enough to test directly. But it's worth doing from the start: in future chapters, we'll derive mocks from interfaces using GMock, which lets you test components that depend on a class without using the real implementation. Without an interface, GMock can't create a mock.

The GTest wrapper

GoogleTest isn't part of ESP-IDF, so it needs to be introduced as a component. The wrapper lives at host_test/gtest/ and is just a CMakeLists.txt — no source files. A few things worth explaining:

Linux-only guard. GTest only gets processed when the build target is linux. It never ends up in the ESP32 binary.

if(IDF_TARGET STREQUAL "linux")

FetchContent. GTest is downloaded from GitHub at build time. The repo stays small, and updating the version is just changing the tag.

FetchContent_Declare(
  googletest
  GIT_REPOSITORY https://github.com/google/googletest.git
  GIT_TAG        v1.14.0
)

Build phase guard. ESP-IDF runs in two phases: first it scans components to resolve dependencies, then it builds. FetchContent can't run during the scan — it would fail trying to download something while the build system is still mapping dependencies. The guard keeps it to the real build phase.

if(NOT CMAKE_BUILD_EARLY_EXPANSION)
  FetchContent_MakeAvailable(googletest)
endif()

INTERFACE linking. Since the wrapper has no source files, it registers as an INTERFACE component — it doesn't compile anything itself, just exposes GTest and GMock to whoever lists gtest in their REQUIRES. This pattern keeps the wrapper reusable as more test projects are added.

Test project configuration

host_test/test_sum/ is a standalone ESP-IDF project. Two CMake details matter here:

EXTRA_COMPONENT_DIRS — the component under test and the GTest wrapper are outside this project's folder. This tells the build system where to find them.

COMPONENTS — without this, the build would process the entire ESP-IDF component tree. Listing only what's needed cuts compilation time significantly.

WHOLE_ARCHIVE — GoogleTest registers tests through static constructors. Since the test functions are never called directly by main.cpp, the linker may discard them as unused. WHOLE_ARCHIVE forces every object file to be included, so all tests are actually discovered and run. Without this, you can have a successful build with zero tests executing.

Test structure

The test project is at host_test/test_sum/. The Sum class has two methods: add(a, b) for plain addition, and add_constrained(a, b) which returns -1 if the result exceeds the allowed range. Three test groups:

Smoke test — checks that GoogleTest itself is running. If this fails, the problem is the setup, not the code.

Standard addition — tests add(a, b) with positives, negatives, and zero.

Constrained addition — three scenarios: inputs within range, at the exact limit, and over it.

TEST(TestSum, AddConstrained_OutOfRange) {
    Sum s;
    EXPECT_EQ(s.add_constrained(6, 5), -1);  // 11 > 10, should return -1
}

Running the tests

cd 01_basic_test/host_test/test_sum
idf.py --preview set-target linux
idf.py build
./build/test_sum.elf

The --preview flag is needed because the Linux target is still marked as experimental in ESP-IDF. It switches the compiler from Xtensa/RISC-V to your local GCC.

Expected output:

[==========] Running 6 tests from 1 test suite.
[----------] 6 tests from TestSum
[ RUN      ] TestSum.GTestSmokeTest
[       OK ] TestSum.GTestSmokeTest (0 ms)
...
[  PASSED  ] 6 tests.

CI

The repo has GitHub Actions workflows that run the host tests on every push using the official ESP-IDF container. Since no hardware is needed, this works out of the box with no self-hosted runners.

What's next

The next chapters will cover mocks — both GMock for testing components in isolation, and IDF's CMock-based approach for mocking hardware dependencies. Full source at github.com/aluiziotomazelli/gtest-esp-idf

wifi_manager: a Wi-Fi state manager for ESP-IDF

Aluizio Tomazelli Junior — Tue, 03 Feb 2026 03:38:48 +0000

I’m sharing a Wi-Fi manager component I built for ESP-IDF, designed to handle connection state, reconnection, and persistence in a predictable way.
GitHub

Note: English is not my native language. If it sounds AI-generated, it’s because I translate my drafts.

Why I built it

In my embedded projects I often need reliable Wi-Fi management without relying on Arduino-style libraries. Most existing solutions either are tied to the Arduino ecosystem, use blocking APIs, or lack good state control and reconnection logic. I wanted something that:

works natively with ESP-IDF (not Arduino),
gives controlled, testable Wi-Fi state transitions,
works well in real deployments where connectivity is intermittent,
meshes cleanly with event-driven embedded designs.

That’s what led me to build wifi_manager, initially for my solar automation setup but now generalized for reuse.

What it does

wifi_manager wraps the low-level esp_wifi driver behind a state machine and a singleton interface. Key features include:

Dedicated task for Wi-Fi operations, decoupled from your main application.
Automatic reconnection with exponential backoff on disconnects.
Graceful handling of timeouts and failures.
Thread-safe API via mutexes and queues.
Persistent credentials stored in NVS.
Both blocking (sync) and non-blocking (async) APIs.
Built with C++, but usable from C projects too.

It’s designed to be used like this:

auto &wm = WiFiManager::get_instance();
wm.init();
wm.start();
wm.set_credentials("SSID", "PASSWORD");
if (wm.connect(10000) == ESP_OK) {
    printf("Connected!\n");
}

This approach gives you fine-grained control over how your application handles Wi-Fi without forcing you into a particular pattern.

Credentials handling and persistence

In the example above, credentials are passed directly in code:

wm.set_credentials("SSID", "PASSWORD");

This is one of the supported paths.

Credentials can also be configured via Kconfig (idf.py menuconfig). Internally, Wi-Fi credentials are stored by the ESP-IDF Wi-Fi driver itself in NVS, and are automatically reused across reboots.

The component maintains an additional is_credential_valid (private) flag, also stored in NVS, to decide which source to use in boot:

If credentials are marked as valid, the saved credentials from NVS are used.
If not, the component falls back to credentials provided via Kconfig (if configured).

This validity flag is managed through Wi-Fi events:

A successful connection marks the credentials as valid.
A disconnection caused by authentication errors invalidates them.

This allows the system to recover cleanly from wrong credentials without hardcoding values or requiring recompilation.

Current limitations

At the moment, the component does not implement provisioning or signal quality evaluation.

In particular:

There is no RSSI-based logic to distinguish very weak signal conditions.
The WIFI_REASON_4WAY_HANDSHAKE_TIMEOUT usually occurs when the access point aborts the handshake due to invalid credentials. Currently, it is treated only as an authentication failure, even though in practice it may also occur under marginal signal conditions.

These cases are known limitations and candidates for future improvement.

Testing from the start

The component comes with a comprehensive test suite (40+ cases) covering lifecycle, state machine behavior, persistence, stress tests, and error handling. Running these tests on real hardware is part of how I validate changes.

Design decisions

A few decisions you’ll find in the code:

Thread safety first — Wi-Fi in real products often runs concurrently with other tasks.
State machine core — lets you reason about connection state instead of relying on sequences of esp_wifi_* calls scattered around your code.
CMake / IDF component layout — makes integration with existing ESP-IDF apps trivial.

Where it fits

While popular Arduino-based Wi-Fi managers are great for quick prototypes, for embedded production systems I find I need more structure:

reliable recovery from disconnects,
testability,
integration with FreeRTOS tasks and event loops.

Esp-IDF’s own netif and event system are solid foundations, but a clean wrapper like wifi_manager makes it easier to build bigger systems on top of them.

Try it out

Check out the repo: https://github.com/aluiziotomazelli/wifi_manager

It’s MIT-licensed and ready for use or adaptation. Contributions welcome.