Registry / testing / pytest-embedded-serial-esp

pytest-embedded-serial-esp

library2.8.0pypypi✓ verified 87d ago

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.

testing devops

pip install pytest-embedded-serial-esp

github ↗package ↗docs ↗changelog ↗

INSTALL

IMPORT

SIG · PYTEST-EMBEDDED-SE

pytest-embedded-serial-esp

testingpythonv2.8.0

Install

7.3s avg

Import

552ms

Disk

64MB

Pass rate

8/ 10

Env Coverage8 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v2.8.0 · 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

musl

glibc

py 3.10

✓ —

✓ 8.04s

py 3.11

✓ —

✓ 7.51s

py 3.12

✓ —

✓ 7s

py 3.13

✓ —

✓ 6.85s

py 3.9

4/8 runs

64MB installed

● package 64MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

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.

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')

Debug

Known issues

breakingpytest-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.

affects: >=2.0.0

breakingWith 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()`.

affects: >=2.0.0

gotchaWhen 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()`.

affects: All

gotchaThe `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.

affects: All

Errors

Common errors & fixes

error: invalid command 'bdist_wheel'

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

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'

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'

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.

Upgrade

Version history

2.8.0latest on PyPI · released May 15, 2026

Audit

Dependencies

pytest-embeddedrequiredCore pytest-embedded framework, required for the base functionality and the `Dut` fixture.

pytest-embedded-serialrequiredpytest-embedded-serial-esp depends on pytest-embedded-serial for generic serial port utilities.

esptoolrequiredUsed for automatic target detection, flashing, and interacting with Espressif SoCs. Requires `esptool>=5.1.dev1,<6` for v2.x of pytest-embedded.

Agent activity

16 hits · last 30 days

node

Amazon

Resources

githubhttps://github.com/espressif/pytest-embedded ↗

packagehttps://pypi.org/project/pytest-embedded-serial-esp/ ↗

docshttps://docs.espressif.com/projects/pytest-embedded/en/latest/ ↗

changeloghttps://github.com/espressif/pytest-embedded/blob/main/CHANGELOG.md ↗