Remote JavaScript debugging with Chrome Developer Tools

I have been using Chrome Developer Tools (CDT) for the past couple of weeks to build a JavaScript debugger. Though you can debug JavaScript in Chrome browser itself, my requirement was such that I needed a debugger that runs outside Chrome and debugs pages running in Chrome. I found that Chrome Developer Tools provides a JavaScript debugger plugin for Eclipse. CDT has exposed Java APIs, if you want to build the debugger yourself. It also has exposed JavaScript APIs for its debugger.

So I first evaluated Eclipse plugin that CDT provides. Before I get to that plugin, here are some useful links about CDT –

• Chrome Debugger – Eclipse Plugin : This is a tutorial for installing and using Eclipse plugin for Chrome debugger
• Tutorial for using Java SDK for Chrome Debugger : Useful if you want to create your own Chrome debugger. The above Eclipse plugin uses this SDK
• Javadoc for Chrome Debugger SDK : Java API reference for the debugger classes
• JavaScript APIs for Chrome Debugger : Useful if you want to build Chrome debugger using JavaScript
• Debugging Chrome on Mobile : This is not part of the CDT, but I found this link interesting because it explains how to connect to Chrome running on mobile from your desktop and debug pages running on mobile.

Eclipse Plugin for Chrome Debugger:

From the documentation of Eclipse Chrome debugger plugin , it seemed like a perfect fit for my requirements. However when I actually installed and tried to use it, I ran into a few issues.

1. This plugin creates a virtual project from your JS project. It copies only those files that have JavaScript code in this Virtual project. Even in HTML file has JS code, it masks all non-JS code and shows only the JS code. Though I did not necessarily have any problem with this approach, I did not really understand the need to create Virtual project. Also I preferred looking at the entire code, than one in which non-JS code is masked.
2. I set a breakpoint in the JS code (you have to set breakpoints in the file created in the virtual project, not in the original file) and was not able to make the debugger hit the breakpoint. It was a simple JS script for testing, but breakpoints did not work. Whenever I refreshed the page, all breakpoints in scripts in that page were removed. A colleague of mine then told me that I needed to set breakpoints after the script was loaded and then execute scripts without loading the page, e.g. on click of a button in the same page.
3. I needed to customize how this debugger worked. I could have probably done that by making changes in the source code,but did not do so because of above two issues.

So I decided to create my own Eclipse plugin using Java SDK for Chrome debugger.

Java SDK for Chrome Debugger:

Using the SDK for debugger was quite easy. I created an Eclipse debugger plugin and called debugger SDK from the plugin to perform operations like setting breakpoints, stepping and handling debugger events. The tutorial I mentioned above was very helpful. However I still have a few issues –

1. The way my debugger plugin works is -user right clicks on a file and selects option to debug the page. Chrome is launched in the debug mode and the page is opened in Chrome. I wanted the debugger to hit any breakpoints that were set before the page was launched. However I did not find any way to tell Chrome to wait for the debugger to attach, after it was launched. I tried many of the launch related command line switches, but could not make Chrome to wait for the debugger to attach.Therefore the page executes without hitting any breakpoint on the first launch. For in-browser debugger this is not a big limitation because you have to execute the page once before you can set breakpoints in the scripts in that page. However that is not how a typical Eclipse debugger work.
2. The debugger has to work properly on HTML pages where some of the content might be inserted dynamically, e,g, by the server that is serving the page. Because of this the line numbers of JS code in the generated output might be different from ones in the source file. So when user sets a breakpoint in the source file, that same code may not be at the same line number in the generated output. Therefore I have to resolve line numbers when the script is loaded.Good thing is that, Chrome informs debugger when it loads a script – so the debugger could set breakpoints on the script if they are not already set. However Chrome does not pause execution of the script to give chance to the debugger to set breakpoints. Sometimes breakpoints may not be hit when the script is loaded the first time – e.g. suppose a HTML page has one JS block and you have set 5 breakpoints in it. When the page is executed, Chrome sends an event notification to the debugger when the script is loaded. If the debugger starts setting breakpoints at this point, some of the initial breakpoints may not be hit because Chrome has already executed the script past those breakpoints.
3. This is not really an issue, but incorrect documentation. JavaDoc for setBreakpoint method says that line number is 1-based, but in fact it is 0-based.
   You also need to pass correct value of column number to this function. Do not pass Breakpoint.EMPTY_VALUE. Column numbers are also zero based.

Other than uncertainty about debugging the page on the first load (breakpoints may not be hit), the debugger works fine. The issues related to the first time load of the page may not be very severe, because all breakpoints works fine if you refresh the page after running the page once, which is not very different from in-browser debugger where you have to load a page once before setting breakpoints. However the debugger could be made much better if CDT provides following two APIs –

1. Make Chrome wait for debugger to connect
2. Notify debugger before executing the script (not just after script is loaded) and wait till debugger returns from the event notification (function). This would give debugger a chance to set breakpoints where there is need to compute JS line numbers at runtime.

-Ram Kulkarni