Debugging Python Modules

You can perform step into debugging operations on Python modules using the Python Adapter.

Before you can step into Python modules, you must install the following software and configure the Python Adapter:
  1. Install the debugpy package in Python.
  2. Install Visual Studio Code. Select either User Installer or System Installer from the download page. TestStand uses VS Code as the IDE for debugging Python modules.
  3. Install NI TestStand Support for Debugging Python Code. This VS Code extension also installs the Python extension if your computer is connected to the internet. If the computer is not connected to the internet, you must install the Python extension for VS Code.

    If your computer had VS Code installed before installing TestStand, the TestStand installation process also installs the VS Code extension. In VS Code, confirm that NITestStand Support for Debugging Python Code is installed. Otherwise, complete the following steps:

    1. Launch the TestStand Version Selector.
    2. Under Installed TestStand Versions, select TestStand 2021 SP1 or later, then click Activate or Configure. The TestStand Version Selector performs the action of installing the extension when you activate TestStand 2021 SP1 or later.
      Note   If you ever uninstall the extension, repeat this step to reinstall it.
  4. Configure Workspace Trust in VS Code.
    1. Click Manage»Workspace Trust.
    2. Click Add Folder.
    3. Add C:\<My Documents>\TestStand\Python as a trusted folder.
      Note   You may need to create the folder first.
  5. Configure the Python Adapter for Debugging.
    1. In the TestStand Sequence Editor, click Configure»Adapters, select Python, and click Configure.
    2. Select the Enable Debugging option.
    3. Select Enable Just My Code to debug only your Python code and exclude installed libraries when debugging. Otherwise, deselect Enable Just My Code to debug both your Python code and any installed libraries your code imports.
    4. For the Executable Path option, browse to the location of python.exe you want to use to debug Python modules. The version number of the executable must match the version number in the Version option.
Complete the following steps to debug functions you call from TestStand using the Python Adapter.
  1. Place a breakpoint at a step that calls a Python module.
  2. Select Execute»Run MainSequence. The execution pauses at the Python step.
  3. Click the Step Into button at the top of the Execution window. VS Code becomes the active application, in which the Python module is open and in a suspended state.
  4. Click Step Into or Step Over on the VS Code toolbar to begin stepping through the function. You can click Continue at any time to finish stepping through the module and return to TestStand.
  5. Click the Resume button on the Execution toolbar in TestStand to complete the execution.

Known Limitations of Python Step-Into Debugging

The following considerations are important to keep in mind when debugging Python modules.

  • Sometimes VS Code will not come to front when you step into a Python module, but it will blink in the taskbar.
  • You cannot step into set/get attributes.
  • You cannot step into Python code if the step overrides Python Adapter settings.
  • During debugging, if you come out from VS Code to TestStand by clicking step into or step over, VS Code stops when any additional Python code is executed, regardless of whether you step into that Python code from TestStand.

Attaching the Python Debugger to an External Process

Python code modules are executed in an external process on the system where the Python interpreter is hosted. You can attach the Python debugger to the external process.

Use the following code as the first line in the function that is being called from the Python Adapter to attach the debugger to the Python code module.
Python Version Code
3.6+ 
import os
import ctypes
ctypes.windll.user32.MessageBoxW(None, "Process name: niPythonHost.exe and Process ID: " + str(os.getpid()), "Attach debugger", 0)

A dialog box with the process name is displayed upon execution. Attach the Python debugger to the specified process and click OK to start debugging the code module in your debugger.