Repository navigation
Debugging design
github-actions[bot] edited this page Nov 10, 2026
·
2 revisions
How the feature is built. What it does for users is in Debugging; what it must do is in the requirements, and the IDs below (D2, D5…) point there.
flowchart LR
lens["▷ Debug CodeLens<br/>or Debug Test at Line"] --> sm["SessionManager.debugFromEditor<br/>resolve scope from LineMap"]
sm --> adapter["adapter.getDebugConfig<br/>(file's framework)"]
adapter --> vs[vscode.debug.startDebugging]
| File | Role |
|---|---|
src/framework/JestAdapter.ts → getDebugConfig
|
Jest's JS entry point from the project root, CRA's extracted config, test-script flags, --runTestsByPath, an anchored --testNamePattern, --runInBand --no-coverage, Node options as runtimeArgs
|
src/framework/VitestAdapter.ts → getDebugConfig
|
vitest.mjs run <file>, the config, -t <pattern>, --no-file-parallelism --test-timeout=0 --hook-timeout=0 --coverage.enabled=false, autoAttachChildProcesses
|
src/framework/PytestAdapter.ts → getDebugConfig / buildDebugConfig
|
type: debugpy, module: pytest, the node id, the project's interpreter; checks the Python Debugger extension first (D5) |
src/extension.ts → debugFromEditor, src/session/SessionManager.ts → debugFromEditor
|
Resolve the test or suite on the line, then ask the file's framework for the config and start it |
- The line is resolved to a test or suite through the file's
LineMap. A suite debugs every test in it: the Jest pattern is anchored as^(?:name)(?: |$), a single test as^(?:name)$. - The file's framework builds the launch config. The program is always a JS file, never
.bin/jest, which is a shell script on Windows and can't be a debug program (D2). The working folder is the project root. - The run is a plain framework run: none of our instrumentation, coverage or reporters. The debugger steps through the user's code only, and the result is what the framework gives on its own.
| Decision | Reason | Alternatives considered |
|---|---|---|
| Plain runs, no instrumentation | Stepping must show the user's code; our counters would show up in it | Debug the instrumented run |
| Jest in band | Breakpoints in workers need extra attach steps; one process is simple and reliable | Workers with auto-attach |
| Vitest with auto-attach and no timeouts | Vitest always uses workers; a test paused at a breakpoint must not time out | Run in one thread: differs from the user's config |
| pytest through the Python Debugger | It is the standard Python debugger in VS Code, and the user's interpreter runs it | Our own debug adapter |
Jest / Vitest: console: 'internalConsole', outputCapture: 'std' (D8) |
The debugger starts the process itself, so nothing goes through a shell. In the integrated terminal VS Code types the command into a new shell: while a slow profile (nvm, pyenv, oh-my-zsh: a few seconds) is still loading, the command is lost on every VS Code version, and VS Code before 1.90 leaves ? unescaped, which zsh reads as a filename wildcard (no matches found). Either way the test never starts and the session waits forever. std shows the runner's own output, not only console.*
|
The integrated terminal (colours, but fragile); rewriting patterns without ? (fixes only the second cause) |
- e2e:
basic-debug(Jest, a path with spaces, the config replayed with plain Node),vitest-debug,pytest-debug,cra-app; the debug scenarios also run on the minimum VS Code and wait for every session to end. - Gaps: the test script's flags and Node options in debug configs (D6), debugging without a session (D7).
Source: docs/development/design/debugging.md. This Wiki is generated from the repository; to change a page, open a pull request that edits its file in docs/.
Features
- Test runs
- Test Explorer and editor
- On-save reruns
- Results panel
- Coverage
- Debugging
- Monorepos and mixed frameworks
- AI assistants
Requirements
- Project-wide requirements
- Test runs: requirements
- Test Explorer and editor: requirements
- On-save reruns: requirements
- Results panel: requirements
- Coverage: requirements
- Debugging: requirements
- Monorepos and mixed frameworks: requirements
- AI assistants: requirements
Development
- Developer Guide
- Architecture
- Framework feature matrix
- AI context
- Feature designs
Generated from docs/. Edits made here are overwritten: change a page with a pull request.