{"id":8525,"library":"pytest-embedded-jtag","title":"pytest-embedded-jtag","description":"pytest-embedded-jtag is a plugin for pytest-embedded that enables interaction with JTAG-connected devices, providing services for OpenOCD and GDB utilities. It allows for advanced embedded testing scenarios by integrating debugging and flashing tools directly into pytest tests. The current version is 2.7.0, and it follows the release cadence of the broader pytest-embedded project.","status":"active","version":"2.7.0","language":"en","source_language":"en","source_url":"https://github.com/espressif/pytest-embedded","tags":["pytest","embedded","jtag","openocd","gdb","testing","hardware","esp32"],"install":[{"cmd":"pip install pytest-embedded-jtag","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Core pytest-embedded functionality is required as pytest-embedded-jtag is a plugin for it.","package":"pytest-embedded"}],"imports":[{"note":"The `Dut` fixture is fundamental for interacting with the device under test, provided by the base `pytest-embedded` library.","symbol":"Dut","correct":"from pytest_embedded import Dut"},{"note":"This imports the Gdb class, which can be used for more direct GDB control if not relying solely on the 'gdb' fixture.","symbol":"Gdb","correct":"from pytest_embedded_jtag.gdb import Gdb"},{"note":"This imports the OpenOcd class, useful for direct OpenOCD interaction beyond the 'openocd' fixture.","symbol":"OpenOcd","correct":"from pytest_embedded_jtag.openocd import OpenOcd"}],"quickstart":{"code":"import pytest\nfrom pytest_embedded import Dut\n\ndef test_jtag_connection(dut: Dut, openocd, gdb):\n    # To enable these fixtures, run pytest with --embedded-services jtag\n    # The 'openocd' and 'gdb' fixtures are automatically provided when 'jtag' service is active.\n    # 'openocd' is an instance of pytest_embedded_jtag.openocd.OpenOcd\n    # 'gdb' is an instance of pytest_embedded_jtag.gdb.Gdb\n    \n    print(f\"OpenOCD instance: {openocd}\")\n    print(f\"GDB instance: {gdb}\")\n    \n    # Example: Send a command to OpenOCD (requires OpenOCD to be running and connected)\n    # In a real test, you'd interact with OpenOCD or GDB to flash, debug, or verify state.\n    try:\n        openocd.write(\"version\") # Assuming 'version' is a valid OpenOCD command\n        version_output = dut.expect(\"Open On-Chip Debugger\").group(0)\n        print(f\"OpenOCD version output: {version_output}\")\n    except Exception as e:\n        print(f\"Could not interact with OpenOCD: {e}\")\n    \n    # Example: Basic DUT interaction (from pytest-embedded)\n    dut.expect_exact(\"Hello from target\") # Replace with expected output from your embedded target\n    print(\"Target responded 'Hello from target'\")\n","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade your Python environment to version 3.10 or newer.","message":"pytest-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.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"When installing or upgrading, use a compatible release specifier like `pip install -U pytest-embedded-jtag~=2.0` to manage updates effectively.","message":"The 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.","severity":"gotcha","affected_versions":"All 2.x versions"},{"fix":"Troubleshoot 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.","message":"Common 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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Run pytest with the `--embedded-services jtag` command-line option, for example: `pytest --embedded-services jtag test_jtag.py`","cause":"The JTAG service was not enabled when running pytest, so the `openocd` or `gdb` fixtures were not registered.","error":"pytest.FixtureLookupError: Unknown fixture 'openocd' or 'gdb'"},{"fix":"Verify 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.","cause":"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.","error":"Target not responding / No JTAG device found"},{"fix":"Consider 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`.","cause":"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.","error":"Writing to DUT doesn't work when application console is configured with ESP_CONSOLE_USB_SERIAL_JTAG"}]}