{"id":8526,"library":"pytest-embedded-serial-esp","title":"pytest-embedded-serial-esp","description":"pytest-embedded-serial-esp is a pytest plugin that extends the pytest-embedded framework to work specifically with Espressif target boards via serial communication. As part of the broader pytest-embedded ecosystem, it enables automated testing, flashing, and interaction with ESP32, ESP8266, and other Espressif SoCs. The library is actively maintained by Espressif Systems, with version 2.7.0 being the latest, and undergoes frequent updates, often including new features and bug fixes.","status":"active","version":"2.7.0","language":"en","source_language":"en","source_url":"https://github.com/espressif/pytest-embedded","tags":["pytest-plugin","embedded","espressif","serial","testing","esp32","esp8266","esp-idf"],"install":[{"cmd":"pip install pytest-embedded-serial-esp","lang":"bash","label":"Install only this plugin"},{"cmd":"pip install -U pytest-embedded~=2.0 pytest-embedded-serial-esp","lang":"bash","label":"Recommended: Install with pytest-embedded core"}],"dependencies":[{"reason":"Core pytest-embedded framework, required for the base functionality and the `Dut` fixture.","package":"pytest-embedded","optional":false},{"reason":"pytest-embedded-serial-esp depends on pytest-embedded-serial for generic serial port utilities.","package":"pytest-embedded-serial","optional":false},{"reason":"Used for automatic target detection, flashing, and interacting with Espressif SoCs. Requires `esptool>=5.1.dev1,<6` for v2.x of pytest-embedded.","package":"esptool","optional":false}],"imports":[{"note":"Represents the serial device connected to an Espressif product.","symbol":"EspSerial","correct":"from pytest_embedded_serial_esp.serial import EspSerial"},{"note":"The primary fixture to interact with the Device Under Test in pytest-embedded. Used across all embedded plugins.","symbol":"Dut","correct":"from pytest_embedded import Dut"}],"quickstart":{"code":"import pytest\nfrom pytest_embedded import Dut\n\n@pytest.mark.parametrize('embedded_services', ['serial', 'esp'], indirect=True)\ndef test_basic_expect(dut: Dut):\n    # Example: wait for a specific output from the ESP device\n    # The 'serial' service provides basic serial communication.\n    # The 'esp' service enables esptool-specific functionalities like auto-flashing.\n    dut.expect_exact('Hello world!', timeout=10)\n    print(f\"Device output: {dut.before.decode()}\")\n    # Additional interaction, e.g., sending commands or expecting more output\n    # dut.write('command\\n')\n    # dut.expect('response')\n","lang":"python","description":"This quickstart demonstrates a basic test using `pytest-embedded-serial-esp` to communicate with an Espressif target. The `@pytest.mark.parametrize('embedded_services', ['serial', 'esp'], indirect=True)` decorator is crucial to activate the necessary services for serial communication and Espressif-specific features, including auto-flashing by esptool. The `dut: Dut` fixture provides the interface to interact with the device under test, primarily using `expect_exact()` to wait for specific serial output. Ensure an Espressif device with appropriate firmware (e.g., a 'Hello World' example) is connected via serial."},"warnings":[{"fix":"Upgrade your Python environment to 3.10 or newer.","message":"pytest-embedded v2.0.0 (which pytest-embedded-serial-esp v2.x depends on) dropped support for Python 3.7, 3.8, and 3.9. It now requires Python 3.10+.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Update `esptool` to the specified version. Replace `dut.stub` with `dut.esp`. Remove `EsptoolArgs` class usage and the deprecated parameters from `use_esptool()`.","message":"With pytest-embedded v2.0.0, the `esptool` requirement was updated to `>=5.1.dev1,<6`. Also, the `EsptoolArgs` class was removed from `pytest-embedded-serial-esp`, and the `stub` property on `EspSerial` was deprecated in favor of `esp`. Additionally, `hard_reset_after` and `no_stub` parameters were removed from the `use_esptool()` decorator.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"For literal matches, use `dut.expect_exact()`. If using `dut.expect()` with literal strings that might contain regex special characters, escape them or use `re.escape()`.","message":"When using `dut.expect()` or `dut.expect_exact()`, be mindful of regular expression special characters (e.g., parentheses, square brackets) in your expected strings, as `expect()` uses regex by default. Use `dut.expect_exact()` for literal string matching.","severity":"gotcha","affected_versions":"All"},{"fix":"If `dut.write()` is critical, ensure your target's ESP-IDF console output is configured for UART. Otherwise, rely on `dut.expect()` for output validation.","message":"The `dut.write()` function might not work as expected when the target application's console is configured to use `ESP_CONSOLE_USB_SERIAL_JTAG` instead of UART. `dut.expect()` generally works regardless of the console interface.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Run `python -m pip install -U pip` to upgrade pip, then `python -m pip install wheel` to install the wheel package.","cause":"The `wheel` package is not installed or pip is outdated, preventing the creation of a wheel distribution.","error":"error: invalid command 'bdist_wheel'"},{"fix":"On Ubuntu/Debian, install with `sudo apt-get install libdbus-glib-1-dev` or `sudo apt-get install libdbus-1-dev`. For other distributions, consult their package manager.","cause":"Missing system-level D-Bus development libraries, common on Linux distributions.","error":"Package requirements (dbus-1 >= 1.8) were not met: No package 'dbus-1' found"},{"fix":"Replace `dut.stub` with `dut.esp` in your test code.","cause":"Attempting to access the deprecated `stub` property on the `EspSerial` object after upgrading to `pytest-embedded` v2.x.","error":"AttributeError: 'EspSerial' object has no attribute 'stub'"},{"fix":"Remove the `no_stub` parameter from your `use_esptool()` decorator calls.","cause":"Using the `no_stub` parameter with the `use_esptool()` decorator, which was removed in `pytest-embedded` v2.x.","error":"TypeError: use_esptool() got an unexpected keyword argument 'no_stub'"}]}