{"id":9244,"library":"pytest-embedded-qemu","title":"Pytest Embedded QEMU Plugin","description":"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.","status":"active","version":"2.7.0","language":"en","source_language":"en","source_url":"https://github.com/espressif/pytest-embedded","tags":["pytest-plugin","embedded","qemu","testing","hardware-in-loop-simulation","esp32","espressif"],"install":[{"cmd":"pip install pytest-embedded-qemu","lang":"bash","label":"Install `pytest-embedded-qemu`"},{"cmd":"pip install -U 'pytest-embedded~=2.0' pytest-embedded-qemu","lang":"bash","label":"Install with `pytest-embedded` (recommended)"}],"dependencies":[{"reason":"Core framework that this plugin extends for embedded testing.","package":"pytest-embedded","optional":false},{"reason":"The underlying test runner framework.","package":"pytest","optional":false},{"reason":"The QEMU emulator must be installed on the system and accessible via PATH. This Python package provides the interface but not the emulator itself.","package":"QEMU","optional":false},{"reason":"Provides additional functionalities for creating QEMU bootable images and flashing ESP-IDF projects. Required if using `--embedded-services idf,qemu`.","package":"pytest-embedded-idf","optional":true},{"reason":"Implicit dependency for `pytest-embedded-idf` service even when running with QEMU.","package":"pytest-embedded-serial-esp","optional":true}],"imports":[{"note":"The primary interface for interacting with the device under test.","symbol":"Dut","correct":"from pytest_embedded import Dut"},{"note":"For advanced direct interaction with the QEMU instance. Typically accessed via fixtures.","symbol":"Qemu","correct":"from pytest_embedded_qemu.qemu import Qemu"},{"note":"For advanced control over QEMU application image creation.","symbol":"QemuApp","correct":"from pytest_embedded_qemu.app import QemuApp"}],"quickstart":{"code":"import pytest\nfrom pytest_embedded import Dut\n\ndef test_qemu_basic(dut: Dut):\n    # This test requires QEMU to be running the target application.\n    # The 'dut' fixture provides access to the QEMU's console output.\n    # Run with: pytest --embedded-services qemu\n    print(f\"QEMU DUT received: {dut.read_until_timeout(1)}\")\n    dut.write(\"hello from pytest\\n\")\n    dut.expect_exact(\"hello from pytest\")\n    print(\"Successfully communicated with QEMU DUT\")","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade your Python environment to 3.10 or newer.","message":"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.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Refer to the pytest-embedded 2.x migration guide for detailed instructions on updating your test code.","message":"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.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Ensure `pytest-embedded-serial-esp` is installed: `pip install pytest-embedded-serial-esp`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<8.0.0 of QEMU"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Install the `pytest-embedded` package: `pip install pytest-embedded`.","cause":"The core `pytest-embedded` library is not installed, which `pytest-embedded-qemu` depends on.","error":"ModuleNotFoundError: No module named 'pytest_embedded'"},{"fix":"Install `pytest-embedded-serial-esp`: `pip install pytest-embedded-serial-esp`.","cause":"The `idf` service, when enabled, expects `pytest-embedded-serial-esp` to be available even if not directly using a physical serial port.","error":"ModuleNotFoundError: No module named 'pytest_embedded_serial_esp' (when running `pytest --embedded-services idf,qemu`)"},{"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.","cause":"The `pytest-embedded-qemu` plugin cannot find the QEMU emulator executable on your system.","error":"RuntimeError: Please install QEMU or add qemu-system-xtensa to your PATH"}]}