This article explains how to use the Firefox developer tools to debug extensions.
An extension can consist of several components—background scripts, popups, options pages, content scripts, sidebars, and alike—and you'll use slightly different workflows to debug each component. Each component has a section in this article, and you can read each section in isolation. We'll begin by introducing the developer tools, which you'll use to debug all the pieces of your extension.
You use an implementation of the developer tools called Toolbox to debug extensions. To open Toolbox for an extension:
about:debugging in the URL bar.A new tab opens showing Inspector in the Toolbox.
To debug your extension, you'll use:
This console shows messages from your background script and extension pages; other logs may appear elsewhere.
There is an overview of all relevant places to look for messages at Viewing log output.
For much of the debugging work, it's useful to be able to view Console with Inspector or Debugger. You do this using the split console, press esc to activate this mode.
You can now drag the toolbox tab to a separate window, so you can place it alongside the window where you're executing the extension.
Your extension can generate log messages, e.g. with the Console API or by triggering (uncaught) errors.
Log messages can usually be viewed via the Console of the context where the script runs.
The Developer tools toolbox at about:debugging shows log messages from extension scripts. For specific cases, see:
Log messages from content scripts can be viewed in the developer tools of the tab where the content script runs instead of about:debugging, see:
Log messages not associated with an extension script, such as the stderr output of the nativeMessaging API
can only be viewed via the Browser Console. This console contains messages from the whole browser, including your and other extensions.
It occasionally contains more detailed information about errors reported to your extension. For more information, see:
We use the notify-link-clicks-i18n extension example to illustrate the debugging features relevant to background scripts. This example is in the webextensions-examples repository.
Background scripts enable an extension to monitor and react to events in the browser, such as navigating to a new page, removing a bookmark, or closing a tab. These scripts can be persistent or non-persistent. Persistent background scripts remain loaded for the lifetime of the extension. In contrast, non-persistent background scripts load when needed to respond to an event and unloaded when they become idle. Non-persistent background scripts are recommended because they consume less of the browser's resources.
Background scripts are loaded inside an invisible background page: by default, this is an empty HTML document, but you can specify a custom page and define it as the background page using the manifest.json background key.
To debug background scripts, use the Toolbox Debugger in the split console view so you can view the Console below Debugger.
To get started, open your background script in Sources.
As you run your extension, the Console displays logged output, including calls to console.log() made by the extension's background scripts and any errors the browser raises as it executes these scripts. Note that the console shows all errors raised by the browser, not just errors related to your extension's code.
When you debug a non-persistent background script, the background script won't go idle while the toolbox is open. However, if you need to terminate the background page, you can do so in about:debugging.
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 command line, you can access and modify the objects created by your background scripts. For example, you can call the notify() function:
In the Debugger you can set breakpoints, step through code, modify the extension's state, and do everything else you'd expect to be able to do in a debugger.
For more information about using the debugger, see the Debugger guide.
We use the favourite-colour extension example to illustrate the debugging features relevant to options pages. This example is in the webextensions-examples repository.
An options pages is an HTML page shown when the user accesses your extension's preferences in Add-ons Manager, either by opening Add-ons Manager themselves or using a link provided in your extension. You use an options page to enable the user to set and save options and settings that affect the behavior of your extension. Options pages display in an iframe in Add-ons Manager.
To debug options pages, use the Toolbox Debugger in the split console view so you can view the Console below Debugger.
To get started:
about:addons in the URL bar, to open Add-ons Manager.
In the Debugger you can set breakpoints, step through code, modify the extension's state, and do everything else you'd expect to be able to do in a debugger. Any messages logged by your code display in Console.
To debug the options page's HTML and CSS, point the tools at the iframe that hosts the page. To do this:
For more information about using Inspector, see the Inspector guide.
We use the beastify extension example to illustrate the debugging features relevant to popups. This example is in the webextensions-examples repository.
Popups are dialogs attached to browser or page actions. Popups are specified using an HTML document that can include CSS and JavaScript, which define styling and behavior.
To debug popups, use the Toolbox Debugger in the split console view so you can view the Console below Debugger.
To debug a popup it needs to be visible (so that its HTML document is loaded). However, having opened a popup, if you click outside the popup it closes and its code unloads. This would appear to make debugging rather difficult. To overcome this challenge, in the options menu, click Disable Popup Auto-Hide.
Now, when you open a popup it stays open and its code remains loaded.
Disable popup auto-hide also applies to built-in browser popups, such as the options menu. The setting doesn't persist across sessions. When you close the window, the setting reverts to auto-hide popups.
Internally, this option toggles the ui.popup.disable_autohide preference, which you can toggle manually from about:config.
With the popup open, its JavaScript sources are listed in Debugger. In the Debugger you can set breakpoints, step through code, modify the extension's state, and do everything else you'd expect to be able to do in a debugger. Any messages logged by your code display in Console.
To inspect the popup's HTML and CSS, use Inspector in the split console view so you can view the Console below Inspector. You can review and modify the popup's HTML and CSS in Inspector, as you would with any webpage.
If your extension has multiple HTML documents open, click the page select icon (
) to open the popup's document.
We use the notify-link-clicks-i18n extension example to illustrate the debugging features relevant to content scripts. This example is in the webextensions-examples repository.
A content script is a part of your extension that runs in the context of a webpage; it enables your extension to react to events on the webpage and make changes to a webpage's content.
Because Firefox is multiprocess, content scripts run in a different process to other parts of an extension. Therefore, to debug content scripts, you use the developer tools for the page containing the script. To do this:
Ctrl + Shift + i (Command + Option + i on macOS) and click Debugger.If you've already activated the split console view, so you can view the Console below Debugger, the tools open in this mode. Otherwise, press esc to activate this mode.
Select your content scripts listed in Sources. You can set breakpoints, step through code, modify the extension's state, and do everything else you'd expect to be able to do in a debugger. Any messages logged by your code display in Console.
If the developer tools tab was not open when the content script injected, the content script may not be list in Sources. If you experience this behavior, reloading the page with the developer tools open should provide a fix.
We use the annotate-page extension example to illustrate the debugging features relevant to sidebars. This example is in the webextensions-examples repository.
A Sidebar is a pane displayed at the side of the browser window, next to the web page. Sidebars are specified using an HTML document that can include CSS and JavaScript, which define styling and behavior.
To debug a sidebar, use the Toolbox Debugger in the split console view so you can view the Console below Debugger.
To debug a sidebar, open the sidebar and locate its JavaScript in Debugger.
In the Debugger you can set breakpoints, step through code, modify the extension's state, and do everything else you'd expect to be able to do in a debugger. Any messages logged by your code display in Console.
To inspect the sidebar's HTML and CSS, use Inspector in the split console view so you can view the Console below Inspector. You can review and modify the sidebar's HTML and CSS in Inspector, as you would with any webpage.
If your extension has multiple HTML documents open, click the page select icon () to open the sidebar's document.
We use the annotate-page extension example to illustrate the debugging features relevant to extension storage. This example is in the webextensions-examples repository.
An extension can store data using the Storage API. To view this data, in the Toolbox open the Storage tab and locate Extension Storage.
We use the devtools-panels extension example to illustrate the debugging features relevant to developer tools pages and panels. This example is in the webextensions-examples repository.
Developer tools are extended with a hidden HTML page that is loaded when the tools are opened. From the hidden HTML page, developer tools panels can be added; these are HTML pages displayed as a tool tab in the browser UI.
To debug development tools pages and panels, use the Toolbox Debugger in the split console view so you can view the Console below Debugger.
To debug additions to the developer tools, open the developer tools and any custom panels, and locate their JavaScript in Debugger.
In the Debugger you can set breakpoints, step through code, modify the extension's state, and do everything else you'd expect to be able to do in a debugger. Any messages logged by your code display in Console.
To debug the custom developer tools pages' HTML and CSS:
You can review and modify the custom development tools page HTML and CSS in Inspector, as you would with any webpage.
For information on debugging permission requests, see Test permission requests.
If your extension could be affected by the browser restarting, such as when a session is restored, you may want to test to ensure your code works as expected in those conditions.
For more details, see Testing persistent and restart features.
Develop
Develop
Develop