Add-on Debugger

The Add-on Debugger lets you run a subset of the Firefox developer tools in the context of your add-on:

• JavaScript Debugger, to set breakpoints and examine the internal state of your code
• Console, to see logged messages and evaluate JavaScript in the add-on's context
• Scratchpad, to conveniently evaluate multiline JavaScript in the add-on context and save it to a file.

The Add-on Debugger is not available for restart-required XUL overlay add-ons. To debug add-ons like that, use the Browser Toolbox instead.

For a quick introduction to the Add-on Debugger, see this screencast:

Opening the Add-on Debugger

To connect the Add-on Debugger to an add-on, open the about:debugging page in Firefox, make sure the "Enable add-on debugging" box is checked, and click the "Debug" button next to your add-on's entry in the page.

Next you'll see a dialog asking you to accept an incoming connection. Click "OK", and the debugger will start in a separate window. Note that sometimes the debugger window is hidden by the main Firefox window.

Using the Add-on Debugger

The Add-on Debugger looks and behaves very much like the Browser Toolbox, except that while the scope of the Browser Toolbox is the whole browser, the Add-on Debugger is focused on the specific add-on for which you launched it. Like the Browser Toolbox, a toolbar along the top lets you switch between a number of different tools. In Firefox 31 there's only one such tool, the JavaScript Debugger, but with Firefox 32 you also get the Console and Scratchpad.

The JavaScript Debugger

This behaves just like the normal JavaScript Debugger, except its scope is the add-on rather than a web page. On the left-hand side it lists JavaScript sources:

• at the top is bootstrap.js: either the one you've written if your add-on is a manually written bootstrapped add-on, or the one included by the SDK if your add-on is an SDK add-on.
• next, if your add-on is an SDK add-on, you'll find your add-on's main.js, any local modules shipping with your add-on, and any content scripts that are currently loaded
• next, all the SDK modules used directly or indirectly by your add-on

Content scripts

Content scripts are only listed if and when they are loaded. So, if your Add-on loads a content script with contentScriptFile, the file will not appear in the debugger sources until you go to a page that loads the content script.

If you set a breakpoint in a content script, it will not be active for instances of the content script which are loaded after the breakpoint is set.

For example, suppose you have an add-on that attaches a content script to every tab the user loads. The content script adds a click handler to the page. As soon as you open a tab, this content script will be listed in the debugger. If you then set a breakpoint in the content script's click handler, then execution will pause whenever you click the page. But if you open a new tab, there are now two instances of the content script, and the breakpoint will not be enabled for the second instance You'll need to set a new breakpoint now if you want to it work for the second instance.

We're investigating improvements to this in bug 1016046.

The Console

The Console behaves just like the Web Console, but its scope is the add-on rather than the web page.

However, note that it actually runs in the context of the add-on's bootstrap.js, which may not be what you expect if your add-on uses the SDK: you won't see any objects defined in your add-on's main.js, and you won't see require() either. This issue is being tracked as bug 1005193.

You can execute Console statements in the context of main.js while execution is paused inside main.js.

The Scratchpad

The Scratchpad behaves just like the normal Scratchpad, but its scope is the add-on rather than the web page.

Like the Console, the add-on Scratchpad runs in the context of the add-on's bootstrap.js even if the add-on uses the SDK, and as with the Console you can execute Scratchpad code in the context of main.js while execution is paused inside main.js.

Debugging chrome: and about: pages

From Firefox 37 onwards, you can debug chrome: and about: pages using the normal Debugger, just as if they were ordinary content pages.