Pytest Embedded QEMU Plugin

2.7.0 · active · verified Thu Apr 16

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.

Common errors

```
ModuleNotFoundError: No module named 'pytest_embedded'
```
cause 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`)
```
cause 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
```
cause 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.

Warnings

breaking Pytest-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.
breaking Pytest-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.
gotcha When 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`.
gotcha QEMU 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.

Install

pip install pytest-embedded-qemu Install `pytest-embedded-qemu`
pip install -U 'pytest-embedded~=2.0' pytest-embedded-qemu Install with `pytest-embedded` (recommended)

Imports

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.

Quickstart

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

view raw JSON →