Install & Compatibility
Where this runs
tested against v2.8.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 0.000s · 34.7MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 3.3s · import 0.000s · 35MB
33MB installed
● package 33MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
CaseTester
✓ from pytest_embedded_idf import CaseTester
✗ from pytest_embedded_idf.dut import IdfDut
IdfApp
✓ from pytest_embedded_idf import IdfApp
LinuxDut
✓ from pytest_embedded_idf import LinuxDut
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')
Debug
Known issues
breakingpytest-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.fixEnsure 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`.
affects: <2.0.0
gotchaThe `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.fixBefore 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.
affects: All
gotchaOn 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.fixAdd 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.
affects: All (Linux specific)
gotchaIf 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.fixVerify 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.
affects: All
Upgrade
Version history
2.8.1latest on PyPI · released Jun 16, 2026
Audit
Dependencies
pytest-embeddedrequiredpytest-embedded-idf is a plugin for pytest-embedded and requires it to function. It explicitly depends on `pytest-embedded>=2.0.0`.