Debugging

This article explains how you can use the Firefox developer tools to debug extensions built with WebExtension APIs.

An extension can consist of various different pieces — background scripts, popups, options pages, content scripts — and you'll need to use a slightly different workflow to debug each piece. So each piece gets a top-level section in this article, and the intention is that these sections can be read in isolation. We'll begin by introducing the Add-on Debugger, which you'll use to debug most of the pieces of your extension.

The Add-on Debugger

For most of this article we'll use the Add-on Debugger. To open the Add-on Debugger:

• open Firefox
• enter "about:debugging" in the URL bar
• check the box labeled "Enable add-on debugging"
• click the "Debug" button next to your extension
• click "OK" in the warning dialog.

You'll then see a new window open. The main Firefox window will be switched into the foreground, so you'll have to click on the new window to bring it in front.

This new window is sometimes called a "toolbox" and contains the debugging tools we'll use. It has a tabbed interface: the row of tabs along the top lets you switch between the different tools:

In this article we'll use three debugging tools:

• The Console: this displays messages logged by the extension as well as error messages logged by the browser as it runs the extension. It also provides a command line enabling you to execute JavaScript in the extension's context.
• The Debugger: this enables you to set breakpoints and watchpoints in your extension's JavaScript, and examine and modify its internal state.
• The Inspector: this enables you to examine and modify the HTML and CSS used to build your extension's pages.

Debugging background scripts

Background scripts stay loaded for the lifetime of the extension. They're loaded inside an invisible "background page": by default this is an empty HTML document, but you can specify your own HTML content using the "background" key in "manifest.json".

You can debug background scripts using the Add-on Debugger.

In the Add-on Debugger's Console you'll see logged output, including calls to console.log() from your own background scripts and any errors the browser raises as it executes them. Note that at the moment, the console shows all errors raised by the browser, not just errors related to your extensions code.

For example, the notify-link-clicks-i18n example extension logs a message from its background script when it receives a message from one of its content scripts:

Using the Console's command line, you can access and modify the objects created by your background scripts.

For example, here we call the notify() function defined in the extension's background script:

If you switch to the Debugger, you'll see all your extension's background scripts. You can set breakpoints, step through code, and do everything else you'd expect to be able to do in a debugger.

If you press the Escape key while you're in the Debugger, the toolbox will be split, with the bottom half now occupied by the Console. While you're at a breakpoint, you can now modify the program's state using the console. See Split console for more on this.

Debugging options pages

Options pages are HTML pages that the extension developer can supply, that contain options for the extension. They are typically displayed in an iframe in the Add-ons Manager (to see the Add-ons Manager, visit the "about:addons" page).

To debug options pages:

• open the Add-on Debugger for your extension
• open your extension's option page.

Any JavaScript sources it includes are then listed in the Debugger:

You'll also see any messages logged by your code in the Add-on Debugger's Console.

You can also use the Add-on Debugger to debug the page's HTML and CSS. First, though, you need to point the tools at the iframe that hosts the options page. To do this: open the options page, click the icon highlighted in the screenshot below, and select the options page from the drop-down list:

Now switch to the Inspector tab, and you'll be able to examine and edit HTML and CSS for the page:

Debugging popups

Popups are dialogs that are attached to browser actions or page actions. They are specified using an HTML document that can include CSS and JavaScript sources for styling and behavior. Whenever the popup is visible, you can use the Add-on Debugger to debug its code.

One problem with popups is that if a popup is open and you click outside the popup, the popup is closed and its code is unloaded. This obviously makes them impossible to debug. To suppress this behavior, click the button in the Add-on Debugger that we've highlighted in the screenshot below:

Now, when you open a popup it will stay open until you press Escape.

When the popup is open, its JavaScript sources will be listed in the Debugger. You can set breakpoints and modify the program's internal state:

You can also use the Add-on Debugger to debug the popup's HTML and CSS. First, though, you need to point the tools at the popup's document. To do this: open the popup, then click the icon highlighted in the screenshot below and select the popup's page from the drop-down list:

Now switch to the Inspector, and you'll be able to examine and edit the popup's HTML and CSS:

Debugging content scripts

You can use the Add-on Debugger to debug background pages, options pages, and popups. However, you can't use it to debug content scripts. This is because, in multiprocess Firefox, content scripts run in a different process from the other parts of your extension.

To debug content scripts attached to a web page, use the normal web developer tools for that page:

• either select "Toggle Tools" from the Web Developer submenu in the Firefox Menu (or Tools menu if you display the menu bar or are on Mac OS X)
• or press the CtrlShiftI (CommandOptionI on OS X) keyboard shortcut.

By default, the tools are shown attached to the bottom of browser tab, to reflect the fact that they are attached to this tab. You'll see any output from console.log() statements in your content scripts. You will also see your content scripts listed in the Debugger, where you'll be able to set breakpoints, step through the code, and so on.