Debugging frame scripts

The Browser Content Toolbox is only available if you're running Firefox in multiprocess mode.

You can use the Browser Content Toolbox to debug frame scripts. The Browser Content Toolbox is a separate window that includes some of the standard Firefox Developer Tools - specifically: the console, the JavaScript debugger, and Scratchpad - but attaches them to the browser's content process. This means you can debug the frame scripts in your add-on.

Opening the Browser Content Toolbox

To open the Browser Content Toolbox, you'll need to:

You should now see an item labeled "Browser Content Toolbox" in the Developer submenu in the Firefox Menu (or Tools menu if you display the menu bar or are on OS X). It opens in a separate window:

If you've used the Firefox Developer Tools before, this should look pretty familiar.

Along the top is a row of tabs that you can use to switch the active tool. Currently, we only support the Console, the Debugger, and Scratchpad in the Browser Content Toolbox. At the right of this row are three buttons that activate the split console, open settings, and close the toolbox.

The rest of the toolbox is taken up with the tool you've currently selected.


The Debugger

The Debugger lists all the scripts that are loaded into the content process. You'll find your frame scripts listed under the chrome:// URL you registered for them:

You can set breakpoints, of course, and do all the other things supported by the debugger.

The Console

The Console logs output from your frame scripts. You can access an array of globals for each tab in the content process using the tabs getter e.g. to get the nodePrincipal of an element in the first-opened tab of the content process: tabs[0].content.document.querySelector("#myEl").nodePrincipal

If you want to use it to evaluate JavaScript in your frame script's scope, there's a trick you need to know:

  • Set a breakpoint in your frame script.
  • When you hit the breakpoint, switch to the Console, or activate the split console by pressing "Escape".

Now the console's scope is your frame script's scope, and you can interact directly with it: