Debugger support

[thejchap]

[thejchap]

Pointers on debugger support, focused on the IDE/VS Code path.

Key point: VS Code's "Debug Test" is not implemented in pytest. pytest's source only has terminal pdb (--pdb/--trace). The IDE path is debugpy (Debug Adapter Protocol) over a socket.

How DAP/debugpy work (high level)

• DAP = a JSON-over-socket protocol the editor (client) speaks to any debug adapter (server). One protocol, every language.
• debugpy is Python's DAP adapter (wraps pydevd). It installs sys.settrace; breakpoints, stepping, and variable inspection all flow over a dedicated TCP socket — never stdin/stdout.
• "Debug Test" just launches the test process under debugpy, then a thin pytest plugin reports results. The debugger isn't pytest's concern.
• Fits tryke well: the worker can debugpy.connect() back to the editor and wait_for_client() before running a test, then run it normally. debugpy's own socket means no clash with our stdin/stdout JSON-RPC.

pytest-xdist (≈ our worker pool)

• xdist makes terminal --pdb and multi-process distribution mutually exclusive: with -n auto it forces workers to 0, and with an explicit -n it errors out — "--pdb is incompatible with distributing tests" (xdist/plugin.py, pytest_cmdline_main). Same root cause as ours: pool workers have no controlling TTY. → Path A debug runs must be pinned to a single serial worker.
• DAP under xdist needs a per-worker attach — one global attach can't cover the pool, because each xdist worker is its own process. There are two ways debugpy gets the debugger into a child, and the xdist case is where the automatic one breaks down (details below). → in tryke, the worker that runs the debugged test must attach itself; route the debug run to one known worker.

How the per-worker attach actually happens (and why xdist is the hard case)

• Transparent auto-attach (subProcess: true): debugpy monkey-patches the Python process-creation calls — os.execv/posix_spawn/fork, _posixsubprocess.fork_exec, subprocess._fork_exec (pydev_monkey.py monkey_patch_os / create_*). Every Python child then has its argv rewritten by patch_args to inject a pydevd.settrace(host, port, patch_multiprocessing=True, access_token=...) (for -c) or pydevd --multiprocess --client <host> --port <port> (for script/-m), so the child dials back to the same adapter with the session's token. That's how "one click debugs all subprocesses" works — but it only fires for processes spawned by patched Python OS calls.
• Why xdist breaks it: xdist spawns workers via execnet popen gateways, commonly python -u -c <bootstrap> that then reads its real payload over stdin — and patch_args explicitly bails on the stdin form (if arg == "-": ... "Unable to fix arguments ... reading from stdin"; return original_args). So the auto-attach can silently no-op, which is why the practical guidance for debugging under xdist is "use -n0," and why the legacy pydevd test plugin instead wires each node explicitly via env (is_in_xdist_node() / PYDEV_MAIN_PID / PYDEV_PYTEST_SERVER).
• Why this is simpler for tryke: our workers are spawned by the Rust runner (WorkerProcess::spawn, crates/tryke_runner/src/worker.rs:51), so there's no patched Python OS call in the chain — the transparent path can never fire, and we don't have to fight it. We do the explicit thing by construction: the runner passes a debug endpoint (host:port + access token) to the chosen worker via env or the run-test RPC, and the worker self-attaches with debugpy.connect(endpoint) + wait_for_client(). One attach per worker, and we pick the worker — i.e. a debug run overrides the normal load-balancing in schedule.rs/pool.rs and pins the debugged test to the single worker that holds the debug session, since breakpoints only fire in the process debugpy is attached to (otherwise the scheduler could dispatch it to a worker that never attached).

Source pointers

• debugpy public API — listen / connect / wait_for_client / debug_this_thread: https://github.com/microsoft/debugpy/blob/main/src/debugpy/public_api.py
• debugpy subprocess auto-attach — argv patching + patched OS calls: pydev_monkey.py (patch_args, _get_python_c_args, monkey_patch_os)
• debugpy's vendored pytest results bridge — also shows the explicit per-xdist-node wiring (is_in_xdist_node, PYDEV_MAIN_PID): https://github.com/microsoft/debugpy/blob/main/src/debugpy/_vendored/pydevd/_pydev_runfiles/pydev_runfiles_pytest2.py
• DAP spec: https://microsoft.github.io/debug-adapter-protocol/
• pytest terminal pdb, for the separate --pdb/--trace path only: https://github.com/pytest-dev/pytest/blob/main/src/_pytest/debugging.py

[thejchap]

Proposed debugger support plan

Use a dedicated debug lane for server-side debug runs.

• Add debugpy>=1.8,<2 as a hard Python dependency.
• Extend server RunParams with optional debug: true.
• Route debug runs to a reserved debug worker instead of the normal shared queue.
• With N >= 2 workers, split capacity into N - 1 normal workers plus 1 debug worker. With N == 1, reuse the single worker serially and restart it after debug runs.
• Add a debug_ready notification containing run_id, adapter, host, port, and pid.
• Have the debug worker start debugpy on 127.0.0.1:0, return the actual port, then wait once for the editor to attach before running selected tests.
• Run all selected debug tests serially on the debug worker.
• Restart the debug worker before each debug run to avoid stale imports, stale ports, or debugger session state.
• Keep the current global server run_lock for v1, so paused debug runs block other run requests instead of introducing cross-lane concurrency yet.

“Selected tests” means the final server-resolved run list after explicit test IDs, paths, -k, and -m filters are applied. The existing run_start.tests payload should remain the source of truth for what will run.

Test coverage should include pool splitting, debug/normal queue isolation, N == 1 fallback behavior, debug_ready ordering, fake-debugpy worker setup, and unchanged normal scheduling behavior.