Nossos voluntários ainda não traduziram este artigo para o Português (do Brasil). Junte-se a nós e ajude-nos a fazer o trabalho!
Você também pode ler o artigo em English (US).

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.

Developer tools toolbox

You use an implementation of the developer tools called Toolbox to debug extensions. To open Toolbox for an extension:

  • enter about:debugging in the URL bar.
  • in the left-hand menu, click This Firefox (or This Nightly).
  • click Inspect next to your extension.

A new tab opens showing Inspector in the Toolbox. 

Initial developer tools view, following a click on Inspect against an extension in about:debugging, showing the inspector

To debug your extension, you'll use:

  • Inspector to examine and modify the HTML and CSS used to build your extension's pages.
  • Console to view messages logged by the extension and error messages logged by the browser as it runs the extension. It also provides a command line, where you can execute JavaScript in the extension's context.
  • Debugger to set breakpoints and watchpoints in your extension's JavaScript, and examine and modify the extension's state.

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.

Following a click on Inspect against an extension in about:debugging, the initial developer tools view shows the inspector. Here we have turned on the split view as well.

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.

Drag the toolbox to a new window, so you can observe it alongside your executing extension.

Debugging background scripts

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 maintain a long-term state or perform long-term operations, independently of any web page or browser window. These scripts remain loaded for the lifetime of the extension. 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.

Opening a background script from the sources panel

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.

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.

As the background script executes the console shows any messages generated by console.log

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:

Functions in the extension can be run from the console.

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.

The developer tools debugger enables you to perform the usual debugger tasks, such as adding breakpoints

For more information about using the debugger, see the Debugger guide.

Debugging options pages

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:

  •  enter about:addons in the URL bar, to open Add-ons Manager.
  • open your extension's preferences:
    To debug an options page, first, open the extension's preferences from Add-on Manager.
  • locate the options page script in Sources.

With your extension's preferences page open, you can locate any scripts from the page in the 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 options page's HTML and CSS, point the tools at the iframe that hosts the page. To do this:

  • switch to Inspector.
  • click the page selector (1).
  • click the options page's HTML item (2).

Selecting the iframe containing an options page's HTML to open it in Inspector.

For more information about using Inspector, see the Inspector guide.

Debugging popups

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.

To enable popups to remain visible and be available to debug, turn on the disable popup auto-hide option

Now, when you open a popup it stays open and its code remains loaded.

Note: 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.

With the popup auto-hide disabled, you can locate its JavaScript in the debugger

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.

With popup auto-hide disabled, you can inspect the popup page's HTML and CSS in Inspector.

If your extension has multiple HTML documents open, click the page select icon (If your extension has multiple pages open, use the page selector to load the one you want to review in Inspector.) to open the popup's document.

Debugging content scripts

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:

  • in the Firefox menu (or Tools menu if you display the menu bar or are on Mac OS X), click Web Developer then Debugger.
  • press CtrlShifti (CommandOptioni on OS X) 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.

You debug content scripts in the page in which they are injected using the standard web developer tools.

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.

Debugging sidebars

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.

With an extension's sidebar open, the sidebar's JavaScript can be debugged.

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.

With an extension's sidebar open, the sidebar document's HTML and CSS can be inspected.

If your extension has multiple HTML documents open, click the page select icon (If your extension has multiple pages open, use the page selector to load the one you want to review in Inspector.) to open the sidebar's document.

Debugging developer tools pages and panels

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.

With the developer tools open and any panels added visible, JavaScript associated with developer tools extensions is visible in the 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:

  • switch to Inspector.
  • click the page selector (1).
  • click the custom development tools page item you want to inspect (2).

With the developer tools open and any panels added visible, the HTML documents associated with developer tools extensions can be selected in inspector so that their HTML and CSS can be inspected.

You can review and modify the custom development tools page HTML and CSS in Inspector, as you would with any webpage.

Debug permission requests

 For information on debugging permission requests, see Test permission requests.

Debugging Browser Restarts

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.

Etiquetas do documento e colaboradores

Última atualização por: rebloor,