Debugging With Node.js

I feel that debugging is as crucial a part of the development cycle as any other. So it's always good practice to demystify the job of debugging, making it easier and less time-consuming, so that we can end work on time and reduce stress.

Like the majority of languages out there, Node provides some excellent debugging tools which make defects in code easily found and fixed. I always advocate the usage of a debugger because personally I find using debuggers really eliminates the need for any guesswork and makes us better developers in general.

This guide is for developers and administrators that work with Node already. It presumes a fundamental understanding of the language at a practical level.

Using the Debugger

Node.js includes a full-featured out-of-process debugging utility accessible via a simple TCP-based protocol and built-in debugging client.

For example, to use the debugger to debug a file named script.js, you can simply call node using the debug flag as so:

$ node debug script.js
< debugger listening on port 5858
connecting... ok
debug>

Breakpoints

Now that you have started a debugging session, anywhere in your script that you call debugger from will be a breakpoint for the debugger.

So, for example, let's add a debugger statement to the script.js:

foo = 2;
setTimeout(() => {
  debugger;
  console.log('bugger');
}, 1000);
console.log('de');

Now if we run this script the debugger will be called on our breakpoint and we can control the script control via using the cont or next commands (c or n for short).

We can pause the script execution at any time by using p.

$ node debug script.js
< debugger listening on port 5858
connecting... ok
break in /home/tom/web/envatodebug/myscript.js:1
  1 foo = 5;
  2 setTimeout(() => {
  3   debugger;
debug> cont
< de
break in /home/tom/web/envatodebug/myscript.js:3
  1 foo = 5;
  2 setTimeout(() => {
  3   debugger;
  4   console.log('bugger');
  5 }, 1000);
debug> next
break in /home/tom/web/envatodebug/myscript.js:4
  2 setTimeout(() => {
  3   debugger;
  4   console.log('bugger');
  5 }, 1000);
  6 console.log('de');
debug> next
< bugger
break in /home/tom/web/envatodebug/myscript.js:5
  3   debugger;
  4   console.log('bugger');
  5 }, 1000);
  6 console.log('de');
  7
debug> quit

REPL

$ node debug script.js
< debugger listening on port 5858
connecting... ok
debug> repl
Press Ctrl + C to leave debug repl
> foo
2
> 2+2
4

The Read-Eval-Print-Loop of the debugger allows you to enter code interactively during execution and thus access the state of the application and all of its variables and methods at the point of breaking execution. This is a very powerful tool which you can use to quickly sanitize your app.

In general, the REPL is available as a standalone and as part of the debugger, and it allows you to run JavaScript interactively. For example, just type node at the prompt with no options, and you will be given a REPL interface that you can write code into and see the output.

Stepping In & Stepping Out

Earlier I mentioned the cont and next (c and n) commands, which allow us to continue code execution once a breakpoint has been reached. In addition to this, as we walk through the code we can also step in to a method or step out to its parent scope.

Use the commands step to step in and out to step out, or s and o for short.

Backtracing

Use backtrace or bt to get an output of the backtrace for the current execution frame.

Restarting

Use restart or r to restart your script from the beginning of execution.

Alternative Ways to Connect to the Debugger

Advanced users can access the debugger also by starting Node.js with the --debug command-line flag, or alternatively by signaling an existing Node.js process with SIGUSR1.

Once a process has been set into the debug mode this way, it can then be connected to by using the Node.js debugger by either using the pid of the running process or via a URI reference (e.g localhost:port) to connect the listening debugger:

node debug -p <pid> connects to the process via the pid.
node debug <URI> connects to the process via the URI such as localhost:5858.

Using Node Inspector

In addition to the CLI debug tool, Node Inspector also provides a GUI inspector inside the web browser (currently only supporting Chrome and Opera).

To use the debugger, simply install as so:

npm install -g node-inspector

Now that we have the Node inspector installed, we can debug our script.js with:

node-debug script.js

Your shell will now output the following, and probably open the web browser to the URL if you have Chrome or Opera set as your default on your development OS.

Node Inspector is now available from http://127.0.0.1:8080/?ws=127.0.0.1:8080&port=5858 
Debugging `script.js`  

Debugger listening on port 5858

In your web browser, you will now be able to debug your application in a similar environment to the developer tools package. Setting breakpoints and viewing code is now integrated with your browser view. Enjoy!

Conclusion

Debugging doesn't need to be a nightmare, nor does it need to be stressful.

Setting breakpoints and stepping through code is so simple in Node. It's a very similar experience to Ruby, and if you are trying to understand an application you have been given, opening the app in debug mode and pausing execution is a fantastic way to learn in a rapid timeframe.

HIGHLIGHTS OF THE DAY