Skip to content

Commit 66b2fd7

Browse files
evanlesmezevanlesmez
committed
JS Debuggers
1 parent 7d1be6c commit 66b2fd7

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

60 files changed

+912
-0
lines changed

‎debug-adapters/js-debug/.vscodeignore

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
# note: this is moved into `dist` during compilation, and does not actually apply here
2+
**/*.map
3+
src/build/**
4+
src/testRunner.js

‎debug-adapters/js-debug/LICENSE

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) Microsoft Corporation. All rights reserved.
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE

‎debug-adapters/js-debug/README.md

Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
<h1>
2+
<img alt="vscode-js-debug" src="resources/readme/logo-with-text.png" width="500">
3+
</h1>
4+
5+
This is a [DAP](https://microsoft.github.io/debug-adapter-protocol/)-based JavaScript debugger. It debugs Node.js, Chrome, Edge, WebView2, VS Code extensions, Blazor, React Native, and more. It is the default JavaScript debugger in Visual Studio Code and Visual Studio, and the standalone debug server can also be used in other tools such as [nvim](https://github.com/mxsdev/nvim-dap-vscode-js).
6+
7+
## Usage
8+
9+
If you're using Visual Studio or Visual Studio Code, `js-debug` is already installed. Otherwise, please consult your editor's documentation for possible installation instructions. Builds of the VS Code extension and standalone DAP server are available on the [releases](https://github.com/microsoft/vscode-js-debug/releases) page.
10+
11+
See [OPTIONS.md](./OPTIONS.md) for a list of options you can use in your launch configurations.
12+
13+
- For usage in VS Code, please check out our guides for [Node.js debugging](https://code.visualstudio.com/docs/nodejs/nodejs-debugging), [Browser debugging](https://code.visualstudio.com/docs/nodejs/browser-debugging).
14+
- For debugging React Native, install and read through the [React Native](https://marketplace.visualstudio.com/items?itemName=msjsdiag.vscode-react-native) extension which builds upon `js-debug`.
15+
- For debugging Blazor, check out [its documentation here](https://learn.microsoft.com/en-us/aspnet/core/blazor/debug?view=aspnetcore-8.0&tabs=visual-studio-code).
16+
- For debugging WebView2 apps, check out [documentation here](https://learn.microsoft.com/en-us/microsoft-edge/webview2/how-to/debug-visual-studio-code).
17+
18+
### Nightly Extension
19+
20+
The shipped version of VS Code includes the js-debug version at the time of its release, however you may want to install our nightly build to get the latest fixes and features. The nightly build runs at 5PM PST on each day that there are changes ([see pipeline](https://dev.azure.com/vscode/VS%20Code%20debug%20adapters/_build?definitionId=28)). To get the build:
21+
22+
1. Open the extensions view (ctrl+shift+x) and search for `@builtin @id:ms-vscode.js-debug`
23+
2. Right click on the `JavaScript Debugger` extension and `Disable` it.
24+
3. Search for `@id:ms-vscode.js-debug-nightly` in the extensions view.
25+
4. Install that extension.
26+
27+
## Notable Features
28+
29+
In `js-debug` we aim to provide rich debugging for modern applications, with no or minimal configuration required. Here are a few distinguishing features of `js-debug` beyond basic debugging capabilities. Please refer to the VS Code documentation for a complete overview of capabilities.
30+
31+
### Debug child processes, web workers, service workers, and worker threads
32+
33+
In Node.js, child processes and worker threads will automatically be debugged. In browsers, service workers, webworkers, and iframes will be debugged as well. While debugging workers, you can also step through `postMessage()` calls.
34+
35+
<details>
36+
<summary>Preview</summary>
37+
<img src="resources/readme/web-worker.png" width="302">
38+
</details>
39+
40+
### Debug WebAssembly with DWARF symbols
41+
42+
The debugger automatically reads DWARF symbols from WebAssembly binaries, and debugs them. The usual debugging features are available, including limited evaluation support via `lldb-eval`.
43+
44+
<details>
45+
<summary>Preview</summary>
46+
<img src="resources/readme/wasm-dwarf.png" width="302">
47+
</details>
48+
49+
### Debug Node.js processes in the terminal
50+
51+
You can debug any Node.js process you run in the terminal with Auto Attach. If auto attach isn't on, you can run the command `Debug: Toggle Auto Attach` to turn it on. Next time you run a command like `npm start`, we'll debug it.
52+
53+
<details>
54+
<summary>Preview</summary>
55+
<img src="resources/readme/auto-attach.png" width="554">
56+
</details>
57+
58+
Once enabled, you can toggle Auto Attach by clicking the `Auto Attach: On/Off` button in the status bar on the bottom of your screen. You can also create a one-off terminal for debugging via the `Debug: Create JavaScript Debug Terminal` command.
59+
60+
### Profiling Support
61+
62+
You can capture and view performance profiles natively in VS Code, by clicking on the ⚪ button in the Call Stack view, or through the `Debug: Take Performance Profile` command. The profile information collected through VS Code is sourcemap-aware.
63+
64+
We support taking and visualizating CPU profiles, heap profiles, and heap snapshots.
65+
66+
<details>
67+
<summary>Preview</summary>
68+
<img src="resources/readme/flame-chart.png" width="845">
69+
</details>
70+
71+
### Instrumentation breakpoints
72+
73+
When debugging web apps, you can configure instrumentation breakpoints from VS Code in the "Event Listener Breakpoints" view.
74+
75+
<details>
76+
<summary>Preview</summary>
77+
<img src="resources/readme/instrumentation-breakpoints.png" width="367">
78+
<img src="resources/readme/instrumentation-breakpoints2.png" width="602">
79+
</details>
80+
81+
### Return value interception
82+
83+
On a function's return statement, you can use, inspect, and modify the `$returnValue`.
84+
85+
<details>
86+
<summary>Preview</summary>
87+
<img src="resources/readme/returnvalue.png">
88+
</details>
89+
90+
Note that you can use and modify properties on the `$returnValue`, but not assign it to--it is effectively a `const` variable.
91+
92+
### Pretty-print minified sources
93+
94+
The debugger can pretty print files, especially useful when dealing with minified sources. You can trigger pretty printing by clicking on the braces `{}` icon in editor actions, or via the `Debug: Pretty print for debugging` command.
95+
96+
<details>
97+
<summary>Preview</summary>
98+
<img src="resources/readme/pretty-print.png">
99+
</details>
100+
101+
### Experimental Network View
102+
103+
The debugger allows viewing network traffic of browser targets and Node.js >22.6.0. This requires enabling the `debug.javascript.enableNetworkView` setting.
104+
105+
<details>
106+
<summary>Preview</summary>
107+
<img src="resources/readme/network-view.png">
108+
</details>
109+
110+
### Advanced Rename Support
111+
112+
When using a tool that emits renames in its sourcemap, the debugger maps renamed variables in all displayed views, and also rewrites evaluation requests to use the renamed identifiers, allowing near-source-level debugging of minified code.
113+
114+
### Conditional Exception Breakpoints
115+
116+
As in most debuggers, you can pause on caught exceptions, but you can also filter the exceptions you want to pause on by checking against the `error` object. In VS Code, you can do this by clicking the pencil icon in the Breakpoints view.
117+
118+
<details>
119+
<summary>Preview</summary>
120+
<img src="resources/readme/conditional-exception-breakpoints.png">
121+
</details>
122+
123+
### Excluded Callers
124+
125+
If you have a breakpoint you want to pause on, but not when called from certain frames, you can right click on call frames in the stack trace view to "exclude caller" which prevents pausing on that breakpoint when the requested caller is in the stack trace.
126+
127+
<details>
128+
<summary>Preview</summary>
129+
<img src="resources/readme/exclude-caller.png">
130+
</details>
131+
132+
### Step-in Targets
133+
134+
When paused on a location with multiple calls or expressions, the debugger supports the **Debug: Step Into Target** action that allows you to request a specific expression you wish to step into.

0 commit comments

Comments
 (0)