pytest-embedded-serial-esp

Common errors

• error: invalid command 'bdist_wheel'

  cause The `wheel` package is not installed or pip is outdated, preventing the creation of a wheel distribution.
  fix Run `python -m pip install -U pip` to upgrade pip, then `python -m pip install wheel` to install the wheel package.

• Package requirements (dbus-1 >= 1.8) were not met: No package 'dbus-1' found

  cause Missing system-level D-Bus development libraries, common on Linux distributions.
  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.

• AttributeError: 'EspSerial' object has no attribute 'stub'

  cause Attempting to access the deprecated `stub` property on the `EspSerial` object after upgrading to `pytest-embedded` v2.x.
  fix Replace `dut.stub` with `dut.esp` in your test code.

• TypeError: use_esptool() got an unexpected keyword argument 'no_stub'

  cause Using the `no_stub` parameter with the `use_esptool()` decorator, which was removed in `pytest-embedded` v2.x.
  fix Remove the `no_stub` parameter from your `use_esptool()` decorator calls.

Warnings

• breaking 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+.
  Fix: Upgrade your Python environment to 3.10 or newer.
• breaking 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.
  Fix: Update `esptool` to the specified version. Replace `dut.stub` with `dut.esp`. Remove `EsptoolArgs` class usage and the deprecated parameters from `use_esptool()`.
• gotcha 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.
  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()`.
• gotcha 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.
  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.

Install

• pip install pytest-embedded-serial-esp Install only this plugin
• pip install -U pytest-embedded~=2.0 pytest-embedded-serial-esp Recommended: Install with pytest-embedded core

Imports

• EspSerial

  from pytest_embedded_serial_esp.serial import EspSerial

  Represents the serial device connected to an Espressif product.
• Dut

  from pytest_embedded import Dut

  The primary fixture to interact with the Device Under Test in pytest-embedded. Used across all embedded plugins.

Quickstart

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.

import pytest
from pytest_embedded import Dut

@pytest.mark.parametrize('embedded_services', ['serial', 'esp'], indirect=True)
def test_basic_expect(dut: Dut):
    # Example: wait for a specific output from the ESP device
    # The 'serial' service provides basic serial communication.
    # The 'esp' service enables esptool-specific functionalities like auto-flashing.
    dut.expect_exact('Hello world!', timeout=10)
    print(f"Device output: {dut.before.decode()}")
    # Additional interaction, e.g., sending commands or expecting more output
    # dut.write('command\n')
    # dut.expect('response')