When developing new software, a good debugging tool is essential to making sure your code is functioning as expected.  The console is most often used as a poor-mans debugging system by including extra code in your script that prints out status to the hosted console.  Is some simple cases this is suitable, but with Node.js's asynchronous nature, you cannot rely on the synchronous nature of log statements in helping you diagnose issues with your code.  Fortunately, the Node.js runtime has built in tools to help.

Node.js is built on the JavaScript engine "V8" built for Google Chrome that was open sourced by Google in 2008.  V8 includes with it an extensive debugging system for use when development your Node.js applications.  The debugger can be accessed by a TCP based TCP DebuggerProtocol  .

Having an API to access the debugger is useful for 3rd party developer tools but is a bit overkill for the average developer trying to diagnose an issue with a script.  Fortunately, Node.js also has a built-in client to access the debugger.

THE BUILT-IN CONSOLE DEBUGGER

To use this client, start Node with the "debug" argument.

$ node debug sample.js
< debugger listening on port 5858
connection... ok
break in sample.js:1
1 var str = "";
2 for(var i=0; i<10; i++) {}
3   str += i.toString();
debug>

COMMANDS REFERENCE

Stepping

cont,c Continue execution
next,n Step to next statement
step,s Step in to function
out,o Step out to calling function
pause Pause running code similar to the pause button in the browser developer tools.

 

$ node debug sample.js 
< debugger listening on port 5858
connecting... ok
break in sample.js:1   1 var str = "";
  2 for(var i=0; i<10; i++) {   3     str += i.toString();
debug> n
break in sample.js:2   1 var str = "";
  2 for(var i=0; i<10; i++) {
  3     str += i.toString();
  4 }
debug> n
break in sample.js:3
  1 var str = "";
  2 for(var i=0; i<10; i++) {
  3     str += i.toString();
  4 }
  5 console.log(str);

Breakpoints

 

setBreakpoint(),sb() Set a breakpoint on the current line
setBreakpoint(line),sb(line) Set a breakpoint on the specified line
setBreakpoint('fn()'),sb('fn()') Set a breakpoint on the first statement in a given functions body
setBreakpoint('script.js',n),sb('script.js',n) Set a break point on the nth line of script.js
clearBreakpoint,cb() Clear the current breakpoint

 

$ node debug sample.js 
< debugger listening on port 5858
connecting... ok
break in sample.js:1
  1 var str = "";
  2 for(var i=0; i<10; i++) {
  3 	str += i.toString();
debug> setBreakpoint(3)
  1 var str = "";
  2 for(var i=0; i<10; i++) {
* 3 	str += i.toString();
  4 }
  5 console.log(str);
  6 
debug> c
break in sample.js:3
  1 var str = "";
  2 for(var i=0; i<10; i++) {
* 3 	str += i.toString();
  4 }
  5 console.log(str);

Information

backtrace,bt Print the callstack for the current execution frame.
list(n) List scripts source code with n line context (n lines before and after)
watch(expr) Add an expression to the watch list
unwatch(expr) Remove an expression from the watch list.
watchers List all watchers and their values (which are also automatically listed on each breakpoint).
repl Evaluate code remotely for evaluation in the debugging scripts context.

 

$ node debug sample.js 
< debugger listening on port 5858
connecting... ok
break in sample.js:1
  1 var str = "";
  2 for(var i=0; i<10; i++) {
  3 	str += i.toString();
debug> watch("str")
debug> setBreakpoint(3)
  1 var str = "";
  2 for(var i=0; i<10; i++) {
* 3 	str += i.toString();
  4 }
  5 console.log(str);
  6 
debug> c
break in sample.js:3
Watchers:
  0: str = ""

  1 var str = "";
  2 for(var i=0; i<10; i++) {
* 3 	str += i.toString();
  4 }
  5 console.log(str);
debug> c
break in sample.js:3
Watchers:
  0: str = "0"

  1 var str = "";
  2 for(var i=0; i<10; i++) {
* 3 	str += i.toString();
  4 }
  5 console.log(str);
debug> c
break in sample.js:3
Watchers:
  0: str = "01"

  1 var str = "";
  2 for(var i=0; i<10; i++) {
* 3 	str += i.toString();
  4 }
  5 console.log(str);

Execution Control

run Run a script
restart Restart a script
kill Kill the current scripts execution

Misc

scripts List all loaded scripts
version Display V8's version.

THIRD PARTY SOLUTIONS

If Console debugging doesn't do it for you, there are several great third party node packages out there that make use of the Debugger API.  I prefer the node-inspector package that is maintained by the folks at StrongLoop.  If you have done any debugging with the built-in debugger in FireFox, then the user interface will look very familiar.  Installing the package will create a new command node-debug on your system that will start your default browser and connect to a local hosted web app that runs the debugger interface. 

$ node-debug program.js

 

node-debugger