doc/api/debugger.markdown

   1 # Debugger
   2
   3     Stability: 2 - Stable
   4
   5 <!-- type=misc -->
   6
   7 Node.js includes a full-featured out-of-process debugging utility accessible
   8 via a simple [TCP-based protocol][] and built-in debugging client. To use it,
   9 start Node.js with the `debug` argument followed by the path to the script to
  10 debug; a prompt will be displayed indicating successful launch of the debugger:
  11
  12 ```
  13 % node debug myscript.js
  14 < debugger listening on port 5858
  15 connecting... ok
  16 break in /home/indutny/Code/git/indutny/myscript.js:1
  17   1 x = 5;
  18   2 setTimeout(function () {
  19   3   debugger;
  20 debug>
  21 ```
  22
  23 Node.js's debugger client does not yet support the full range of commands, but
  24 simple step and inspection are possible.
  25
  26 Inserting the statement `debugger;` into the source code of a script will
  27 enable a breakpoint at that position in the code.
  28
  29 For example, suppose `myscript.js` is written as:
  30
  31 ```js
  32 // myscript.js
  33 x = 5;
  34 setTimeout(function () {
  35   debugger;
  36   console.log('world');
  37 }, 1000);
  38 console.log('hello');
  39 ```
  40
  41 Once the debugger is run, a breakpoint will occur at line 4:
  42
  43 ```
  44 % node debug myscript.js
  45 < debugger listening on port 5858
  46 connecting... ok
  47 break in /home/indutny/Code/git/indutny/myscript.js:1
  48   1 x = 5;
  49   2 setTimeout(function () {
  50   3   debugger;
  51 debug> cont
  52 < hello
  53 break in /home/indutny/Code/git/indutny/myscript.js:3
  54   1 x = 5;
  55   2 setTimeout(function () {
  56   3   debugger;
  57   4   console.log('world');
  58   5 }, 1000);
  59 debug> next
  60 break in /home/indutny/Code/git/indutny/myscript.js:4
  61   2 setTimeout(function () {
  62   3   debugger;
  63   4   console.log('world');
  64   5 }, 1000);
  65   6 console.log('hello');
  66 debug> repl
  67 Press Ctrl + C to leave debug repl
  68 > x
  69 5
  70 > 2+2
  71 4
  72 debug> next
  73 < world
  74 break in /home/indutny/Code/git/indutny/myscript.js:5
  75   3   debugger;
  76   4   console.log('world');
  77   5 }, 1000);
  78   6 console.log('hello');
  79   7
  80 debug> quit
  81 %
  82 ```
  83
  84 The `repl` command allows code to be evaluated remotely. The `next` command
  85 steps over to the next line. Type `help` to see what other commands are
  86 available.
  87
  88 ## Watchers
  89
  90 It is possible to watch expression and variable values while debugging. On
  91 every breakpoint, each expression from the watchers list will be evaluated
  92 in the current context and displayed immediately before the breakpoint's
  93 source code listing.
  94
  95 To begin watching an expression, type `watch('my_expression')`. The command
  96 `watchers` will print the active watchers. To remove a watcher, type
  97 `unwatch('my_expression')`.
  98
  99 ## Commands reference
 100
 101 ### Stepping
 102
 103 * `cont`, `c` - Continue execution
 104 * `next`, `n` - Step next
 105 * `step`, `s` - Step in
 106 * `out`, `o` - Step out
 107 * `pause` - Pause running code (like pause button in Developer Tools)
 108
 109 ### Breakpoints
 110
 111 * `setBreakpoint()`, `sb()` - Set breakpoint on current line
 112 * `setBreakpoint(line)`, `sb(line)` - Set breakpoint on specific line
 113 * `setBreakpoint('fn()')`, `sb(...)` - Set breakpoint on a first statement in
 114 functions body
 115 * `setBreakpoint('script.js', 1)`, `sb(...)` - Set breakpoint on first line of
 116 script.js
 117 * `clearBreakpoint('script.js', 1)`, `cb(...)` - Clear breakpoint in script.js
 118 on line 1
 119
 120 It is also possible to set a breakpoint in a file (module) that
 121 isn't loaded yet:
 122
 123 ```
 124 % ./node debug test/fixtures/break-in-module/main.js
 125 < debugger listening on port 5858
 126 connecting to port 5858... ok
 127 break in test/fixtures/break-in-module/main.js:1
 128   1 var mod = require('./mod.js');
 129   2 mod.hello();
 130   3 mod.hello();
 131 debug> setBreakpoint('mod.js', 23)
 132 Warning: script 'mod.js' was not loaded yet.
 133   1 var mod = require('./mod.js');
 134   2 mod.hello();
 135   3 mod.hello();
 136 debug> c
 137 break in test/fixtures/break-in-module/mod.js:23
 138  21
 139  22 exports.hello = function() {
 140  23   return 'hello from module';
 141  24 };
 142  25
 143 debug>
 144 ```
 145
 146 ### Info
 147
 148 * `backtrace`, `bt` - Print backtrace of current execution frame
 149 * `list(5)` - List scripts source code with 5 line context (5 lines before and
 150 after)
 151 * `watch(expr)` - Add expression to watch list
 152 * `unwatch(expr)` - Remove expression from watch list
 153 * `watchers` - List all watchers and their values (automatically listed on each
 154 breakpoint)
 155 * `repl` - Open debugger's repl for evaluation in debugging script's context
 156
 157 ### Execution control
 158
 159 * `run` - Run script (automatically runs on debugger's start)
 160 * `restart` - Restart script
 161 * `kill` - Kill script
 162
 163 ### Various
 164
 165 * `scripts` - List all loaded scripts
 166 * `version` - Display V8's version
 167
 168 ## Advanced Usage
 169
 170 An alternative way of enabling and accessing the debugger is to start
 171 Node.js with the `--debug` command-line flag or by signaling an existing
 172 Node.js process with `SIGUSR1`.
 173
 174 Once a process has been set in debug mode this way, it can be connected to
 175 using the Node.js debugger by either connecting to the `pid` of the running
 176 process or via URI reference to the listening debugger:
 177
 178 * `node debug -p <pid>` - Connects to the process via the `pid`
 179 * `node debug <URI>` - Connects to the process via the URI such as
 180 localhost:5858
 181
 182 [TCP-based protocol]: https://github.com/v8/v8/wiki/Debugging-Protocol