You can use it to debug code running locally in Firefox or running remotely, for example in a Firefox OS device or Firefox on Android. This guide assumes you're debugging locally, but it's mostly applicable to remote debugging as well. See the guide to remote debugging for the differences.
To open the Debugger select "Debugger" 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 by pressing its Control-Shift-S (Command-Option-S on the Mac) keyboard shortcut.
The Toolbox will appear at the bottom of the browser window, with the Debugger activated. Here's what it looks like when you first open it:
And here's what it looks like in the middle of a debugging session:
In this guide we'll first have a quick tour of the debugger's user interface, then we'll describe how to perform some common debugging tasks.
The debugger user interface
The debugger's UI is split into six main sections, which we'll cover one at a time:
The source list pane lists all the JS source files loaded into the page, and enables you to select one to debug. From Firefox 29, the source list pane shares its screen real estate with the call stack pane, and you can use the tabs at the top of the pane to switch between them.
Source files are grouped under different headings according to where they are loaded from. You can select any of these files and they will be loaded into the Source pane.
Any breakpoints you've set in a source file are listed in the source list pane under the filename. The check box next to each breakpoint lets you enables you to enable/disable it. Right-clicking on the breakpoint's entry in the list shows a context menu enabling you to:
- enable, disable or remove this breakpoint, all breakpoints, or all breakpoints except this one
- make this breakpoint conditional (or edit its conditions, if it is already conditional)
The three icons at the bottom of the source list pane enable you to black box a source, pretty-print minified JS files, and toggle all breakpoints on or off.
The eyeball at the bottom-left of the pane is a button that enables you to black box the currently selected source. Black boxing is useful for sources which you are using but not debugging, such as libraries like jQuery. If a source is black boxed, it's assumed to be of no interest to the debugger: any breakpoints in it will be disabled, and the debugger will skip through it when stepping through code.
In versions of Firefox before 27, the eyeball icon appears next to the source file name when you hover over it.
Toggle all breakpoints
The Toggle all breakpoints button is new in Firefox 29.
The button lets you disable all breakpoints, or reenable them, in a single action. This makes it easy to switch between running a program and stepping through it.
Call stack pane
The call stack pane is new in Firefox 29.
The other tab on the left-hand side of the debugger displays a vertical call stack:
Each row represents a level in the call stack, with the current stack frame on top. The row shows the name of the function currently executing, and a link to its source file and line number.
In the source pane, the context menu enables you to:
- set a breakpoint
- set a conditional breakpoint
- add a watch expression for the selection
- search or filter using the script filter
The Variables popup is new in Firefox 28.
If you hover the mouse over a variable in the variables pane, a popup appears showing you that variable's current value:
This enables you to get a quick look at a variable without having to open and search the Variables pane.
The toolbar consists of four sections:
- a row of buttons to control movement through a script
- a visualisation of the call stack
- the script filter
- buttons to expand/collapse the variables and events panes and to control debugger settings
The four buttons on the left perform the following functions:
- Pause/Resume (F6): pauses or resumes execution of the script you're debugging. When it's blue and "pressed", as above, that means the script is paused, either because you've paused it with this button or because you've hit a breakpoint.
- Step Out (Shift-F8): runs the script until the current function exits.
The call stack visualisation shows the call stack at the point execution is paused.
The script filter enables you to search in all three of the debugger's panes. By prefixing the filter expression with one of several special characters, the filter provides various different functions.
|None||Filter the scripts shown in the source list pane.|
|!||Search for the string across all files.|
|@||Search for function definitions, across all files, containing the string.|
|#||Search for the string in the file currently open in the source pane.|
|:||Go to the line given in the file currently open in the source pane.|
|*||Filter the variables shown in the variables pane.|
These options are shown in a pop-up when you click in the filter, and they're also accessible from the context menu in the source pane. Prefixes can be combined to form more powerful queries, like "file.js:12", which will open file.js and highlight line 12, or "mod#onLoad", which will find the string onLoad in all files containing mod in their name. Hitting the Enter key after searching will cycle between the matches found.
|Auto Prettify Minified Sources||
With this option enabled, the debugger will automatically detect minified JS files and pretty-print them.
This option is new in Firefox 29.
|Ignore Caught Exceptions||If this option is set (it is set by default) and "Pause on exceptions" is set, then execution will pause on an exception only if that exception is not caught. This is usually the behavior you want (you don't generally want to pause execution when an exception that is thrown is caught, since that generally indicates that your program is handling it properly).|
|Show Panes on Startup||When this option is enabled, the debugger's variables pane is visible when you first start the debugger.|
|Show Only Enumerable Properties||Enabling this option adds a "Filter variables" search box to the variables panel, so that you can filter the displayed list of variables.|
The variables pane is where you can examine, and modify, the internal state of the script as it's executing:
The variables pane shares its screen real estate with the events pane, and you can use the tabs at the top of the pane to switch between them.
Variables are grouped by scope: in Function scope you'll see the built-in
this variables as well as local variables defined by the function like
greeting. Similarly, in Global scope you'll see global variables you've defined, like
greetme, as well as built-in globals like
Each object can be expanded using a disclosure triangle to show its members.
Pointing your cursor at a variable's name displays a tooltip that provides additional information about the variable; for example, pointing at the
greeting object displays "
configurable enumerable writable". See
Object.defineProperty() for details on what these property descriptors mean.
You can change a variable's value by clicking on its current value and entering a new one; for example, if you click on
"Hi, Dr. Nick!" next to
greeting, you can edit the value.
Then start running your code. The watch expression does nothing until you begin to step through your code, so nothing happens until you reach a breakpoint. At that point, a box showing your active watch expressions and their current values will appear:
You can step through your code, watching the value of the expression as it changes; each time it does, the box will flash briefly yellow. You can remove a watch expression by clicking the "x" icon next to it, and, of course, you can have more than one watch expression at a time.
Highlight and inspect DOM nodes
This feature is new in Firefox 29.
If you hover over a DOM node in the Variables pane, it will be highlighted in the page:
Also, a target icon will appear next to the variableIf you click on this target, the Inspector will open with this DOM element selected.
The events pane is new in Firefox 27.
The events pane lists all DOM events that currently have listeners bound from your code:
It shares its screen real estate with the variables pane, and you can use the tabs at the top of the pane to switch between them.
It groups events by type. The screenshot above shows four types: Interaction, Keyboard, Mouse, and Navigation. Under each type it lists all events which have listeners in your code, with the following syntax:
[event name] on [event target] in [source file]
If you check the checkbox next to the event, the debugger will break at the first line of the event's listener. If you check the checkbox next to the event type, then the debugger will break for any of the events listed under that type.
How do I...?
Open the debugger
To open the debugger, select "Debugger" 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 Control-Shift-S (Command-Option-S on the Mac).
Find a source file
Find inside a file
Set a breakpoint
To set a breakpoint in a file open in the source pane:
- either click on the line number for the line you want to break at
- or activate the context menu while on the line you want to break at, and select "Add breakpoint"
Each breakpoint is shown in two places in the debugger:
- they're listed in the source list pane underneath the file's name
- the line in the source pane is marked with a blue circle
The screenshot below shows breakpoints at lines 3 and 10 of the file:
Set a conditional breakpoint
To set a conditional breakpoint, activate the context menu while on the line you want to break at, and select "Add conditional breakpoint". Then enter the conditional expression in the popup that appears:
To edit the condition, or to add a condition to a normal breakpoint, activate the context menu and select "Configure conditional breakpoint":
Disable a breakpoint
To disable a breakpoint:
- either: uncheck the check box next to the breakpoint's entry in the source list pane
- or: activate the context menu while your mouse pointer is over the breakpoint's entry in the source list pane, and select "Disable breakpoint"
Disable/enable all breakpoints
This feature is new in Firefox 29.
To switch all breakpoints on or off, use the "Toggle all breakpoints" button in the Source list pane.
Break on a DOM event
This feature is new in Firefox 27.
If you're listening to a particular DOM event, you can tell the debugger to break when the event is triggered without having to track down the listener and set a breakpont manually.
First, open the events pane: click the button in the toolbar that opens the shared variables/events pane, then click the tab labeled "Events". The events pane will list all events for which you have assigned a listener:
Then check the box next to the event you want to break at.
When the event is triggered the code will break at the start of your listener.
Step through my code
When your code stops at a breakpoint, you can step through it using the four buttons on the left of the toolbar:
In order, the buttons are:
- Play: run to the next breakpoint
- Step over: advance to the next line in the same function.
- Step into: advance to the next line in the function, unless on a function call, in which case enter the function being called
- Step out: run to the end of the current function
Use a source map
To tell the Debugger to use source maps if they are available, click the "Debugger settings" button and select "Show original sources" from the list of settings that pops up:
When the code has stopped at a breakpoint, you can examine its state in the variables pane of the debugger:
Variables in global scope and in function, block, "with" scopes, etc. are listed separately, and you can expand objects to see their properties. You can also filter the variables shown using the "*" prefix in the script filter:
When the code has stopped at a breakpoint, you can modify variables in the variables pane of the debugger. Just click on the variable's current value and you'll be able to type there:
Watch an expression
Debug mobile devices
To learn how to debug mobile devices, see the guide to remote debugging.
In modern web development, we often rely on libraries like jQuery, Ember, or Angular, and 99% of the time we can safely assume that they “just work”. We don’t care about the internal implementation of these libraries: we treat them like a black box. However, a library’s abstraction leaks during debugging sessions when you are forced to step through its stack frames in order to reach your own code. With black boxing, you can tell the debugger to ignore the details of selected sources.
In versions of Firefox before Firefox 27, you can black box a source by clicking the eyeball icon next to the source in the source list pane:
From Firefox 27 onwards, enable or disable black boxing for a source by selecting the source in the source list pane and clicking the eyeball icon at the bottom left:
You can black box several sources at once by opening the developer toolbar and using the
dbg blackbox command:
When a source is black boxed:
- Any breakpoints it may have are disabled.
- When “pause on exceptions” is enabled, the debugger won’t pause when an exception is thrown in the black boxed source; instead it will wait until (and if) the stack unwinds to a frame in a source that isn’t black boxed.
- The debugger will skip through black boxed sources when stepping.
Pretty-print a minified file
Pretty-printing is new in Firefox 28.
To pretty-print a file that has been minified, open the minified file and click the icon that contains a pair of braces:
The file will now appear in a more readable format:
From Firefox 29 onwards, you can instruct the debugger to detect minified sources and pretty-print them for you automatically, by selecting "Auto Prettify Minified Sources" in the Debugger settings.
Access debugging in add-ons
The following items are accessible in the context of chrome://browser/content/debugger.xul (or, in version 23 beta, chrome://browser/content/devtools/debugger.xul):
- window.addEventListener("Debugger:EditorLoaded") - called when the read-only script panel loaded.
Unfortunately there is not yet any API to evaluate watches/expressions within the debugged scope, or highlight elements on the page that are referenced as variables in the debugged scope. (currently a work in progress, see bug 653545.)
|Windows||Mac OS X||Linux|
|Open the Debugger||Ctrl + Shift + S||Cmd + Opt + S||Ctrl + Shift + S|
|Search in the current source using the script filter||Ctrl + F||Cmd + F||Ctrl + F|
|Find next in the current source||Enter / Up arrow||Enter / Up arrow||Enter / Up arrow|
|Find previous in the current source||Shift + Enter / Down arrow||Shift + Enter / Down arrow||Shift + Enter / Down arrow|
|Search in all sources using the script filter||Ctrl + Alt + F||Cmd + Opt + F||Ctrl + Alt + F|
|Search for scripts by name||Ctrl + P / Ctrl + O||Cmd + P / Ctrl + O||Ctrl + P / Ctrl + O|
|Search for function definitions||Ctrl + D||Cmd + D||Ctrl + D|
|Filter variables when execution is paused||Ctrl + Alt + V||Cmd + Opt + V||Ctrl + Alt + V|
|Resume execution when at a breakpoint||F8||F81||F8|
|Step out||Shift + F11||Shift + F111||Shift + F11|
|Toggle breakpoint on the currently selected line||Ctrl + B||Cmd + B||Ctrl + B|
|Toggle conditional breakpoint on the currently selected line||Ctrl + Shift + B||Cmd + Shift + B||Ctrl + Shift + B|
|Add selected text to Watch expressions||Ctrl + Shift + E||Cmd + Shift + E||Ctrl + Shift + E|
|Go to line using the script filter||Ctrl + L||Cmd + L||Ctrl + L|
|Search using the script filter||Ctrl + O||Cmd + O||Ctrl + O|
1. By default, on some Macs, the function key is remapped to use a special feature: for example, to change the screen brightness or the volume. See this guide to using these keys as standard function keys. To use a remapped key as a standard function key, hold the Function key down as well (so to open the Profiler, use Shift + Function + F5).
These shortcuts work in all tools that are hosted in the toolbox.
|Windows||Mac OS X||Linux|
|Increase font size||Ctrl + +||Cmd + +||Ctrl + +|
|Decrease font size||Ctrl + -||Cmd + -||Ctrl + -|
|Reset font size||Ctrl + 0||Cmd + 0||Ctrl + 0|