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
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.396s · 32.8MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 3.1s · import 0.348s · 33MB
31MB installed
● package 31MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Dut
✓ from pytest_embedded import Dut
The `Dut` fixture is fundamental for interacting with the device under test, provided by the base `pytest-embedded` library.
Gdb
✓ from pytest_embedded_jtag.gdb import Gdb
This imports the Gdb class, which can be used for more direct GDB control if not relying solely on the 'gdb' fixture.
OpenOcd
✓ from pytest_embedded_jtag.openocd import OpenOcd
This imports the OpenOcd class, useful for direct OpenOCD interaction beyond the 'openocd' fixture.
This quickstart demonstrates a basic pytest test using the `dut`, `openocd`, and `gdb` fixtures provided by `pytest-embedded-jtag`. To run this test, you need an embedded target, OpenOCD, and GDB configured. Save the code as `test_jtag.py` and execute with `pytest -s --embedded-services jtag` to enable the JTAG services and see stdout. The `openocd` and `gdb` fixtures are instances of their respective classes, allowing direct interaction.
import pytest
from pytest_embedded import Dut
def test_jtag_connection(dut: Dut, openocd, gdb):
# To enable these fixtures, run pytest with --embedded-services jtag
# The 'openocd' and 'gdb' fixtures are automatically provided when 'jtag' service is active.
# 'openocd' is an instance of pytest_embedded_jtag.openocd.OpenOcd
# 'gdb' is an instance of pytest_embedded_jtag.gdb.Gdb
print(f"OpenOCD instance: {openocd}")
print(f"GDB instance: {gdb}")
# Example: Send a command to OpenOCD (requires OpenOCD to be running and connected)
# In a real test, you'd interact with OpenOCD or GDB to flash, debug, or verify state.
try:
openocd.write("version") # Assuming 'version' is a valid OpenOCD command
version_output = dut.expect("Open On-Chip Debugger").group(0)
print(f"OpenOCD version output: {version_output}")
except Exception as e:
print(f"Could not interact with OpenOCD: {e}")
# Example: Basic DUT interaction (from pytest-embedded)
dut.expect_exact("Hello from target") # Replace with expected output from your embedded target
print("Target responded 'Hello from target'")
Debug
Known issues
breakingpytest-embedded-jtag, as part of the pytest-embedded ecosystem, dropped support for Python 3.7, 3.8, and 3.9 in version 2.0.0. It now requires Python 3.10 or higher.fixUpgrade your Python environment to version 3.10 or newer.
affects: >=2.0.0
gotchaThe pytest-embedded project, including pytest-embedded-jtag, recommends installing with `~=2.0` (e.g., `pip install -U pytest-embedded-jtag~=2.0`). This is because bug fix versions might sometimes introduce non-breaking new features, and using a compatible release specifier helps avoid unintended breaking changes while still getting new features.fixWhen installing or upgrading, use a compatible release specifier like `pip install -U pytest-embedded-jtag~=2.0` to manage updates effectively.
affects: All 2.x versions
gotchaCommon JTAG connectivity issues (e.g., clock speed mismatch, voltage level mismatch, faulty physical connections, or PCB layout problems) can manifest as 'target not responding' or unexpected behavior during tests. These are often hardware-related and not issues with the `pytest-embedded-jtag` library itself.fixTroubleshoot physical JTAG connections, verify power supplies, ensure clock speed compatibility, and check for signal integrity issues on the PCB. Consult your JTAG debugger and target device documentation for proper setup.
affects: All versions
Errors
Common errors & fixes
pytest.FixtureLookupError: Unknown fixture 'openocd' or 'gdb'
The JTAG service was not enabled when running pytest, so the `openocd` or `gdb` fixtures were not registered.
fixRun pytest with the `--embedded-services jtag` command-line option, for example: `pytest --embedded-services jtag test_jtag.py`
Target not responding / No JTAG device found
OpenOCD or GDB failed to connect to the target device. This is typically an external environmental issue, such as the JTAG probe not being connected, incorrect target configuration, or power issues.
fixVerify that your JTAG probe is correctly connected to the target and the host machine. Ensure the target device is powered on and correctly configured (e.g., boot mode). Check your OpenOCD configuration files (`.cfg`) for correct target and interface settings.
Writing to DUT doesn't work when application console is configured with ESP_CONSOLE_USB_SERIAL_JTAG
This is a known issue, specifically observed with ESP32-S3 targets, where writing to the DUT via serial might fail if the application console uses the USB Serial/JTAG interface instead of UART.
fixConsider reconfiguring the embedded application to use UART for console output if possible. Alternatively, review the `pytest-embedded` and `pytest-embedded-jtag` documentation or GitHub issues for workarounds specific to `ESP_CONSOLE_USB_SERIAL_JTAG`.
Upgrade
Version history
2.8.0latest on PyPI · released May 15, 2026
Audit
Dependencies
pytest-embeddedrequiredCore pytest-embedded functionality is required as pytest-embedded-jtag is a plugin for it.