pytest-embedded-idf Integration for ESP-IDF

2.7.0 · active · verified Fri Apr 17

pytest-embedded-idf is a pytest plugin that extends pytest-embedded to provide a robust testing framework specifically designed for ESP-IDF based firmware. It streamlines the process of building, flashing, and testing applications on Espressif hardware, integrating directly with `idf.py` tools. The current version is 2.7.0, and it follows the release cadence of `pytest-embedded` and ESP-IDF updates.

Common errors

```
ModuleNotFoundError: No module named 'pytest_embedded_idf'
```
cause The `pytest-embedded-idf` library is not installed in the current Python environment.

fix Install the library: `pip install pytest-embedded-idf`.
```
FileNotFoundError: [Errno 2] No such file or directory: 'idf.py'
```
cause The `idf.py` command, which is part of the ESP-IDF build system, cannot be found in the system's PATH. This usually means the ESP-IDF environment has not been sourced or `IDF_PATH` is incorrect.

fix Ensure `IDF_PATH` is set correctly (e.g., `export IDF_PATH=/path/to/esp-idf`) and that the ESP-IDF tools are in your PATH (often done by sourcing the `export.sh` or `export.bat` script from your ESP-IDF installation).
```
Permission denied: '/dev/ttyUSB0' (or similar serial port device path)
```
cause The current user does not have sufficient permissions to open and write to the serial port device connected to the ESP board.

fix On Linux, add your user to the `dialout` group: `sudo usermod -a -G dialout $USER`. Log out and log back in for changes to apply. On Windows, ensure drivers are installed and no other process is holding the port.
```
Failed to flash DUT: flash command exited with non-zero exit code
```
cause The flashing process (invoked by `idf.py flash`) failed. This can be due to a variety of reasons including incorrect board connection, wrong baud rate, corrupted firmware, or issues with the esptool utility.

fix Check the detailed error messages preceding this output for clues from `esptool.py`. Ensure the board is properly connected, drivers are installed, and the correct serial port is being detected (or specified with `--port`). Try flashing manually using `idf.py flash` to debug the underlying issue.

Warnings

breaking pytest-embedded-idf versions 2.x.x require pytest-embedded versions 2.x.x. Using incompatible major versions (e.g., pytest-embedded-idf 2.x.x with pytest-embedded 1.x.x) will lead to API mismatches and runtime errors.
Fix: Ensure both `pytest-embedded` and `pytest-embedded-idf` are on compatible major versions. The `pytest-embedded-idf` package's `install_requires` will typically handle this during installation: `pip install --upgrade pytest-embedded pytest-embedded-idf`.
gotcha The `IDF_PATH` environment variable must be correctly set and point to your ESP-IDF installation directory for `idf.py` commands (used for building and flashing) to function correctly. Without it, tests involving building or flashing will fail.
Fix: Before running tests, ensure `IDF_PATH` is set in your environment. Example: `export IDF_PATH=/path/to/your/esp-idf`. It's often set when you source the ESP-IDF export script.
gotcha On Linux, serial port access often requires the user to be a member of the `dialout` group. If not, `pytest-embedded-idf` will encounter 'Permission denied' errors when trying to open serial ports.
Fix: Add your user to the `dialout` group: `sudo usermod -a -G dialout $USER`. Then, log out and log back in (or reboot) for the changes to take effect.
gotcha If your ESP-IDF project fails to build or flash using `idf.py build` or `idf.py flash` directly, it will also fail when `pytest-embedded-idf` attempts these actions. Common causes include incorrect CMakeLists.txt, missing components, or build environment issues.
Fix: Verify that your ESP-IDF project builds and flashes successfully outside of `pytest-embedded-idf` by running `idf.py build` and `idf.py flash` from your project directory. Address any errors reported by `idf.py` first.

Install

pip install pytest-embedded-idf Install package

Imports

IdfDut
wrong:
```
from pytest_embedded.dut import Dut
```
correct:
```
from pytest_embedded_idf.dut import IdfDut
```
While `pytest-embedded` provides a generic `Dut`, `pytest-embedded-idf` provides `IdfDut` which has additional ESP-IDF specific methods and properties.

Quickstart

This quickstart demonstrates a basic `pytest-embedded-idf` test. It uses the `IdfDut` fixture to interact with an ESP-IDF device. The test asserts that the device outputs 'Hello world!'. Ensure your ESP-IDF environment (`IDF_PATH`) is set up and an ESP device is connected. Run with `pytest` from your ESP-IDF project directory.

# Save this as 'test_hello.py' in your ESP-IDF project directory (e.g., esp-idf/examples/get-started/hello_world)
# Requirements:
# 1. An ESP-IDF project directory.
# 2. ESP-IDF environment variable IDF_PATH correctly set.
# 3. A compatible Espressif development board connected via USB.
# 4. pip install pytest pytest-embedded pytest-embedded-idf

import pytest
from pytest_embedded_idf.dut import IdfDut
import os

# Example: Mark the test to run on an ESP32 target.
# You can change this to esp32s2, esp32s3, esp32c3, esp32c6, etc.,
# depending on your target and --target option if specified.
@pytest.mark.esp32
def test_hello_world_output(dut: IdfDut):
    """
    Tests that the ESP-IDF 'hello_world' example prints the expected output.
    The 'dut' fixture automatically handles building, flashing, and connecting.
    """
    print(f"\nConnected DUT target: {dut.target}")
    print(f"DUT COM Port: {dut.serial.port}")
    print(f"Application path: {dut.app.path}")

    # Expect 'Hello world!' from the device's serial output
    dut.expect(r'Hello world!')
    print("Successfully received 'Hello world!' from DUT.")

    # Example: Send a command (if your application supports it)
    # dut.write('get_heap')
    # dut.expect(r'Free heap: \d+ bytes')

view raw JSON →