{"id":10141,"library":"pytest-embedded-idf","title":"pytest-embedded-idf Integration for ESP-IDF","description":"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.","status":"active","version":"2.7.0","language":"en","source_language":"en","source_url":"https://github.com/espressif/pytest-embedded-idf","tags":["pytest","testing","esp-idf","embedded","hardware","espressif"],"install":[{"cmd":"pip install pytest-embedded-idf","lang":"bash","label":"Install package"}],"dependencies":[{"reason":"pytest-embedded-idf is a plugin for pytest-embedded and requires it to function. It explicitly depends on `pytest-embedded>=2.0.0`.","package":"pytest-embedded","optional":false}],"imports":[{"note":"While `pytest-embedded` provides a generic `Dut`, `pytest-embedded-idf` provides `IdfDut` which has additional ESP-IDF specific methods and properties.","wrong":"from pytest_embedded.dut import Dut","symbol":"IdfDut","correct":"from pytest_embedded_idf.dut import IdfDut"}],"quickstart":{"code":"# Save this as 'test_hello.py' in your ESP-IDF project directory (e.g., esp-idf/examples/get-started/hello_world)\n# Requirements:\n# 1. An ESP-IDF project directory.\n# 2. ESP-IDF environment variable IDF_PATH correctly set.\n# 3. A compatible Espressif development board connected via USB.\n# 4. pip install pytest pytest-embedded pytest-embedded-idf\n\nimport pytest\nfrom pytest_embedded_idf.dut import IdfDut\nimport os\n\n# Example: Mark the test to run on an ESP32 target.\n# You can change this to esp32s2, esp32s3, esp32c3, esp32c6, etc.,\n# depending on your target and --target option if specified.\n@pytest.mark.esp32\ndef test_hello_world_output(dut: IdfDut):\n    \"\"\"\n    Tests that the ESP-IDF 'hello_world' example prints the expected output.\n    The 'dut' fixture automatically handles building, flashing, and connecting.\n    \"\"\"\n    print(f\"\\nConnected DUT target: {dut.target}\")\n    print(f\"DUT COM Port: {dut.serial.port}\")\n    print(f\"Application path: {dut.app.path}\")\n\n    # Expect 'Hello world!' from the device's serial output\n    dut.expect(r'Hello world!')\n    print(\"Successfully received 'Hello world!' from DUT.\")\n\n    # Example: Send a command (if your application supports it)\n    # dut.write('get_heap')\n    # dut.expect(r'Free heap: \\d+ bytes')\n","lang":"python","description":"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."},"warnings":[{"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`.","message":"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.","severity":"breaking","affected_versions":"<2.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All (Linux specific)"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Install the library: `pip install pytest-embedded-idf`.","cause":"The `pytest-embedded-idf` library is not installed in the current Python environment.","error":"ModuleNotFoundError: No module named 'pytest_embedded_idf'"},{"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).","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.","error":"FileNotFoundError: [Errno 2] No such file or directory: 'idf.py'"},{"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.","cause":"The current user does not have sufficient permissions to open and write to the serial port device connected to the ESP board.","error":"Permission denied: '/dev/ttyUSB0' (or similar serial port device path)"},{"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.","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.","error":"Failed to flash DUT: flash command exited with non-zero exit code"}]}