xref: /third_party/node/doc/api/debugger.md (revision 1cb0ef41) 
1# Debugger
2
3<!--introduced_in=v0.9.12-->
4
5> Stability: 2 - Stable
6
7<!-- type=misc -->
8
9Node.js includes a command-line debugging utility. The Node.js debugger client
10is not a full-featured debugger, but simple stepping and inspection are
11possible.
12
13To use it, start Node.js with the `inspect` argument followed by the path to the
14script to debug.
15
16```console
17$ node inspect myscript.js
18< Debugger listening on ws://127.0.0.1:9229/621111f9-ffcb-4e82-b718-48a145fa5db8
19< For help, see: https://nodejs.org/en/docs/inspector
20<
21connecting to 127.0.0.1:9229 ... ok
22< Debugger attached.
23<
24 ok
25Break on start in myscript.js:2
26  1 // myscript.js
27> 2 global.x = 5;
28  3 setTimeout(() => {
29  4   debugger;
30debug>
31```
32
33The debugger automatically breaks on the first executable line. To instead
34run until the first breakpoint (specified by a [`debugger`][] statement), set
35the `NODE_INSPECT_RESUME_ON_START` environment variable to `1`.
36
37```console
38$ cat myscript.js
39// myscript.js
40global.x = 5;
41setTimeout(() => {
42  debugger;
43  console.log('world');
44}, 1000);
45console.log('hello');
46$ NODE_INSPECT_RESUME_ON_START=1 node inspect myscript.js
47< Debugger listening on ws://127.0.0.1:9229/f1ed133e-7876-495b-83ae-c32c6fc319c2
48< For help, see: https://nodejs.org/en/docs/inspector
49<
50connecting to 127.0.0.1:9229 ... ok
51< Debugger attached.
52<
53< hello
54<
55break in myscript.js:4
56  2 global.x = 5;
57  3 setTimeout(() => {
58> 4   debugger;
59  5   console.log('world');
60  6 }, 1000);
61debug> next
62break in myscript.js:5
63  3 setTimeout(() => {
64  4   debugger;
65> 5   console.log('world');
66  6 }, 1000);
67  7 console.log('hello');
68debug> repl
69Press Ctrl+C to leave debug repl
70> x
715
72> 2 + 2
734
74debug> next
75< world
76<
77break in myscript.js:6
78  4   debugger;
79  5   console.log('world');
80> 6 }, 1000);
81  7 console.log('hello');
82  8
83debug> .exit
84$
85```
86
87The `repl` command allows code to be evaluated remotely. The `next` command
88steps to the next line. Type `help` to see what other commands are available.
89
90Pressing `enter` without typing a command will repeat the previous debugger
91command.
92
93## Watchers
94
95It is possible to watch expression and variable values while debugging. On
96every breakpoint, each expression from the watchers list will be evaluated
97in the current context and displayed immediately before the breakpoint's
98source code listing.
99
100To begin watching an expression, type `watch('my_expression')`. The command
101`watchers` will print the active watchers. To remove a watcher, type
102`unwatch('my_expression')`.
103
104## Command reference
105
106### Stepping
107
108* `cont`, `c`: Continue execution
109* `next`, `n`: Step next
110* `step`, `s`: Step in
111* `out`, `o`: Step out
112* `pause`: Pause running code (like pause button in Developer Tools)
113
114### Breakpoints
115
116* `setBreakpoint()`, `sb()`: Set breakpoint on current line
117* `setBreakpoint(line)`, `sb(line)`: Set breakpoint on specific line
118* `setBreakpoint('fn()')`, `sb(...)`: Set breakpoint on a first statement in
119  function's body
120* `setBreakpoint('script.js', 1)`, `sb(...)`: Set breakpoint on first line of
121  `script.js`
122* `setBreakpoint('script.js', 1, 'num < 4')`, `sb(...)`: Set conditional
123  breakpoint on first line of `script.js` that only breaks when `num < 4`
124  evaluates to `true`
125* `clearBreakpoint('script.js', 1)`, `cb(...)`: Clear breakpoint in `script.js`
126  on line 1
127
128It is also possible to set a breakpoint in a file (module) that
129is not loaded yet:
130
131```console
132$ node inspect main.js
133< Debugger listening on ws://127.0.0.1:9229/48a5b28a-550c-471b-b5e1-d13dd7165df9
134< For help, see: https://nodejs.org/en/docs/inspector
135<
136connecting to 127.0.0.1:9229 ... ok
137< Debugger attached.
138<
139Break on start in main.js:1
140> 1 const mod = require('./mod.js');
141  2 mod.hello();
142  3 mod.hello();
143debug> setBreakpoint('mod.js', 22)
144Warning: script 'mod.js' was not loaded yet.
145debug> c
146break in mod.js:22
147 20 // USE OR OTHER DEALINGS IN THE SOFTWARE.
148 21
149>22 exports.hello = function() {
150 23   return 'hello from module';
151 24 };
152debug>
153```
154
155It is also possible to set a conditional breakpoint that only breaks when a
156given expression evaluates to `true`:
157
158```console
159$ node inspect main.js
160< Debugger listening on ws://127.0.0.1:9229/ce24daa8-3816-44d4-b8ab-8273c8a66d35
161< For help, see: https://nodejs.org/en/docs/inspector
162<
163connecting to 127.0.0.1:9229 ... ok
164< Debugger attached.
165Break on start in main.js:7
166  5 }
167  6
168> 7 addOne(10);
169  8 addOne(-1);
170  9
171debug> setBreakpoint('main.js', 4, 'num < 0')
172  1 'use strict';
173  2
174  3 function addOne(num) {
175> 4   return num + 1;
176  5 }
177  6
178  7 addOne(10);
179  8 addOne(-1);
180  9
181debug> cont
182break in main.js:4
183  2
184  3 function addOne(num) {
185> 4   return num + 1;
186  5 }
187  6
188debug> exec('num')
189-1
190debug>
191```
192
193### Information
194
195* `backtrace`, `bt`: Print backtrace of current execution frame
196* `list(5)`: List scripts source code with 5 line context (5 lines before and
197  after)
198* `watch(expr)`: Add expression to watch list
199* `unwatch(expr)`: Remove expression from watch list
200* `unwatch(index)`: Remove expression at specific index from watch list
201* `watchers`: List all watchers and their values (automatically listed on each
202  breakpoint)
203* `repl`: Open debugger's repl for evaluation in debugging script's context
204* `exec expr`, `p expr`: Execute an expression in debugging script's context and
205  print its value
206* `profile`: Start CPU profiling session
207* `profileEnd`: Stop current CPU profiling session
208* `profiles`: List all completed CPU profiling sessions
209* `profiles[n].save(filepath = 'node.cpuprofile')`: Save CPU profiling session
210  to disk as JSON
211* `takeHeapSnapshot(filepath = 'node.heapsnapshot')`: Take a heap snapshot
212  and save to disk as JSON
213
214### Execution control
215
216* `run`: Run script (automatically runs on debugger's start)
217* `restart`: Restart script
218* `kill`: Kill script
219
220### Various
221
222* `scripts`: List all loaded scripts
223* `version`: Display V8's version
224
225## Advanced usage
226
227### V8 inspector integration for Node.js
228
229V8 Inspector integration allows attaching Chrome DevTools to Node.js
230instances for debugging and profiling. It uses the
231[Chrome DevTools Protocol][].
232
233V8 Inspector can be enabled by passing the `--inspect` flag when starting a
234Node.js application. It is also possible to supply a custom port with that flag,
235e.g. `--inspect=9222` will accept DevTools connections on port 9222.
236
237To break on the first line of the application code, pass the `--inspect-brk`
238flag instead of `--inspect`.
239
240```console
241$ node --inspect index.js
242Debugger listening on ws://127.0.0.1:9229/dc9010dd-f8b8-4ac5-a510-c1a114ec7d29
243For help, see: https://nodejs.org/en/docs/inspector
244```
245
246(In the example above, the UUID dc9010dd-f8b8-4ac5-a510-c1a114ec7d29
247at the end of the URL is generated on the fly, it varies in different
248debugging sessions.)
249
250If the Chrome browser is older than 66.0.3345.0,
251use `inspector.html` instead of `js_app.html` in the above URL.
252
253Chrome DevTools doesn't support debugging [worker threads][] yet.
254[ndb][] can be used to debug them.
255
256[Chrome DevTools Protocol]: https://chromedevtools.github.io/devtools-protocol/
257[`debugger`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/debugger
258[ndb]: https://github.com/GoogleChromeLabs/ndb/
259[worker threads]: worker_threads.md
260