Registry / testing / pytest-embedded-qemu

pytest-embedded-qemu

library2.8.0pypypi✓ verified 88d ago

pytest-embedded-qemu is a plugin for the pytest-embedded framework that enables running embedded tests on QEMU instead of actual hardware targets. It extends pytest-embedded with QEMU-specific functionalities, allowing for automated creation of QEMU bootable images and handling device output. It is currently at version 2.7.0 and is actively maintained with a regular release cadence as part of the broader `pytest-embedded` ecosystem by Espressif Systems.

testing

pip install pytest-embedded-qemu

github ↗package ↗docs ↗changelog ↗

INSTALL

IMPORT

SIG · PYTEST-EMBEDDED-QE

pytest-embedded-qemu

testingpythonv2.8.0

Install

2.9s avg

Import

396ms

Disk

31MB

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

✓ —

✓ 2.98s

py 3.11

✓ —

✓ 3.03s

py 3.12

✓ —

✓ 2.85s

py 3.13

✓ —

✓ 2.8s

py 3.9

2/4 runs

31MB installed

● package 31MB

Code

Verified usage

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

Dut

✓ from pytest_embedded import Dut

The primary interface for interacting with the device under test.

Qemu

✓ from pytest_embedded_qemu.qemu import Qemu

For advanced direct interaction with the QEMU instance. Typically accessed via fixtures.

QemuApp

✓ from pytest_embedded_qemu.app import QemuApp

For advanced control over QEMU application image creation.

This quickstart demonstrates a basic test using the `dut` fixture provided by `pytest-embedded`, configured to interact with a QEMU instance. To run this test, save it as a Python file (e.g., `test_qemu.py`) and execute `pytest --embedded-services qemu` in your terminal. You will also need a QEMU-compatible application to run in the simulated environment.

import pytest from pytest_embedded import Dut def test_qemu_basic(dut: Dut): # This test requires QEMU to be running the target application. # The 'dut' fixture provides access to the QEMU's console output. # Run with: pytest --embedded-services qemu print(f"QEMU DUT received: {dut.read_until_timeout(1)}") dut.write("hello from pytest\n") dut.expect_exact("hello from pytest") print("Successfully communicated with QEMU DUT")

Debug

Known issues

breakingPytest-embedded (and its plugins, including pytest-embedded-qemu) dropped support for Python 3.7, 3.8, and 3.9 in version 2.0.0. Python 3.10 or higher is now required.

fix

Upgrade your Python environment to 3.10 or newer.

affects: >=2.0.0

breakingPytest-embedded version 2.0.0 introduced significant breaking changes in its core API, affecting how `esptool` arguments are handled, removing the `EsptoolArgs` class, and altering the `dut.stub` property. Users migrating from 1.x to 2.x will need to update their test code to align with these changes.

fix

Refer to the pytest-embedded 2.x migration guide for detailed instructions on updating your test code.

affects: >=2.0.0

gotchaWhen using the `idf` embedded service alongside `qemu` (e.g., `pytest --embedded-services idf,qemu`), you might encounter a `ModuleNotFoundError: No module named 'pytest_embedded_serial_esp'` if `pytest-embedded-serial-esp` is not installed. This is because the `idf` service often implicitly depends on serial-related functionalities.

fix

Ensure `pytest-embedded-serial-esp` is installed: `pip install pytest-embedded-serial-esp`.

affects: All versions

gotchaQEMU versions older than 8.0 have a limitation where they only support a 4MB flash image size for Xtensa targets when used with `pytest-embedded-qemu` for image creation.

fix

Use QEMU version 8.0 or newer for larger flash images, or configure your application to fit within a 4MB flash size for older QEMU versions.

affects: <8.0.0 of QEMU

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'pytest_embedded'

The core `pytest-embedded` library is not installed, which `pytest-embedded-qemu` depends on.

fix

Install the `pytest-embedded` package: `pip install pytest-embedded`.

ModuleNotFoundError: No module named 'pytest_embedded_serial_esp' (when running `pytest --embedded-services idf,qemu`)

The `idf` service, when enabled, expects `pytest-embedded-serial-esp` to be available even if not directly using a physical serial port.

fix

Install `pytest-embedded-serial-esp`: `pip install pytest-embedded-serial-esp`.

RuntimeError: Please install QEMU or add qemu-system-xtensa to your PATH

The `pytest-embedded-qemu` plugin cannot find the QEMU emulator executable on your system.

fix

Install QEMU on your system (e.g., `sudo apt install qemu-system-xtensa` on Debian/Ubuntu, or follow QEMU's official installation guide) and ensure the QEMU executable (e.g., `qemu-system-xtensa`) is included in your system's PATH environment variable.

Upgrade

Version history

2.8.0latest on PyPI · released May 15, 2026

Audit

Dependencies

pytest-embeddedrequiredCore framework that this plugin extends for embedded testing.

pytestrequiredThe underlying test runner framework.

QEMUrequiredThe QEMU emulator must be installed on the system and accessible via PATH. This Python package provides the interface but not the emulator itself.

pytest-embedded-idfoptionalProvides additional functionalities for creating QEMU bootable images and flashing ESP-IDF projects. Required if using `--embedded-services idf,qemu`.

pytest-embedded-serial-espoptionalImplicit dependency for `pytest-embedded-idf` service even when running with QEMU.

Agent activity

10 hits · last 30 days

node

Resources

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

packagehttps://pypi.org/project/pytest-embedded-qemu/ ↗

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

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