Debugger

  • Revision slug: Tools/Debugger
  • Revision title: Debugger
  • Revision id: 478489
  • Created:
  • Creator: wbamberg
  • Is current revision? No
  • Comment

Revision Content

The JavaScript Debugger enables you to step through JavaScript code and examine or modify its state to help track down bugs.

It can be used to debug code running locally in Firefox or to debug code 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 four main sections, which we'll cover one at a time:

  • the toolbar
  • the source list pane
  • the source pane
  • the variables pane

Source list pane

The left-hand side of the debugger lists all the JS source files loaded into the page, and enables you to select one to debug.

Source files are grouped under different headings according to where they are loaded from. For example, this is part of the source list pane when a page on developer.mozilla.org is loaded:

This corresponds to the following script tags in the page:

<script src="/en-US/jsi18n/build:8987063"></script>
<script src="https://login.persona.org/include.js" type="text/javascript"></script>
<script src="//mozorg.cdn.mozilla.net/en-US/libs/jquery-1.7.1.min.js" type="text/javascript"></script>
<script src="//mozorg.cdn.mozilla.net/en-US/tabzilla/tabzilla.js" async></script>

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 under the filenameThe check box enables you to enable/disable the breakpoint. 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 eyeball enables you to enable/disable black boxing a particular source. See "Black box a source" for more info about this.

Source pane

This shows the JavaScript file currently loaded. Breakpoints have a blue circle next to the line number, while breakpoints you've hit have a green arrow inside the circle:

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

Toolbar

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 pane 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 Over (F7): steps across the current line of JavaScript code.
  • Step Into (F8): steps into the function call on the current line of JavaScript code.
  • 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.

Script filter

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.

Prefix Function
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.

Debugger settings

At the right-hand end of the toolbar are two more buttons. The first of these shows and hides the variables pane, and the second enables you to toggle various debugger settings:

Pause on exceptions When this option is enabled, execution of the script will automatically pause whenever a JavaScript exception is thrown.
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).

This option is new in Firefox 26.

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.
Show variables filter box Do not display non-enumerable JavaScript properties
Show original sources Enabling this option will make the debugger use source maps, if they are available, to display the original source for code which has been combined, minified, or even compiled to JavaScript from a language like CoffeeScript.

Variables pane

The variables pane is where you can examine, and modify, the internal state of the script as it's executing:

Examining variables

Variables are grouped by scope: in Function scope you'll see the built-in arguments and this variables as well as local variables defined by the function like user and greeting. Similarly, in Global scope you'll see global variables you've defined, like greetme, as well as built-in globals like localStorage and console.

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 filter the variables that are displayed, either by using the "*" modifier in the script filter, or by typing into the filter variables box, if you have enabled this in the debugger settings.

Modifying variables

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.

Watch expressions

Watch expressions are expressions that are evaluated each time execution pauses. You can then examine the results of these expressions. These are useful in that they let you inspect invariants in your code that you know are there but aren't necessarily in the code ready for inspection. To add a watch expression, click in the box that says "Add watch expression" and enter a JavaScript expression whose output you'd like to monitor as you step through code.

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.

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

When the debugger's open, all the JavaScript source files are listed in the source list pane. You can browse the list to find the one you want, or search for a particular file using the script filter.

Find inside a file

To find a function, search for a string, or jump to a line in a file open in the source pane, you can use one of the special modifiers in the script filter.

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 three 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 gray vertical bar at the right of the source pane shows each breakpoint in the file as a small blue bar

The screenshot below shows breakpoints at lines 7 and 65 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"

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

JavaScript sources are often combined and minified to make delivering them from the server more efficient. Increasingly, too, JavaScript running in a page is machine-generated, as when compiled from a language like CoffeeScript. By using source maps, the debugger can map the code being executed to the original source files, making debugging much, much easier.

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:Of course, for this to work, you will need to have supplied a source map for the JavaScript running in the page. Do this by appending a comment directive to your source file:

//@ sourceMappingURL=http://example.com/path/to/your/sourcemap.map

Examine variables

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:

Modify variables

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

You can watch the value of a JavaScript expression using the "Add watch expression" function in the variables pane.

Debug mobile devices

To learn how to debug mobile devices, see the guide to remote debugging.

Black box a source

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.

You can enable/disable black boxing for a individual source by clicking the eyeball to the left of the source in the sources list. Or you can black box many sources at once by bringing up the developer toolbar with Shift+F2 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.

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.
  • window.addEventListener("Debugger:EditorUnloaded")

Relevant files:

  • chrome://browser/content/devtools/debugger-controller.js
  • chrome://browser/content/devtools/debugger-toolbar.js
  • chrome://browser/content/devtools/debugger-view.js
  • chrome://browser/content/devtools/debugger-panes.js

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.)

See also

Revision Source

<p>The JavaScript Debugger enables you to step through JavaScript code and examine or modify its state to help track down bugs.</p>
<p>It can be used to debug code running locally in Firefox or to debug code 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 <a href="/en-US/docs/Tools/Remote_Debugging" title="/en-US/docs/Tools/Remote_Debugging">guide to remote debugging</a> for the differences.</p>
<p>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&nbsp;X), or by pressing its Control-Shift-S (Command-Option-S on the Mac) keyboard shortcut.</p>
<p>The <a href="https://developer.mozilla.org/en-US/docs/Tools/DevTools_Window" title="/en-US/docs/Tools/DevTools_Window">Toolbox</a> will appear at the bottom of the browser window, with the Debugger activated. Here's what it looks like when you first open it:</p>
<p><img alt="" src="https://mdn.mozillademos.org/files/5955/debugger-startup.png" style="display: block; margin-left: auto; margin-right: auto;" /></p>
<p>And here's what it looks like in the middle of a debugging session:</p>
<p><img alt="" src="https://mdn.mozillademos.org/files/5957/debugger-breakpoint-hit.png" style="display: block; margin-left: auto; margin-right: auto;" />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.</p>
<h2 id="The_debugger_user_interface">The debugger user interface</h2>
<p>The debugger's UI is split into four main sections, which we'll cover one at a time:</p>
<ul>
  <li>the toolbar</li>
  <li>the source list pane</li>
  <li>the source pane</li>
  <li>the variables pane</li>
</ul>
<p><img alt="" src="https://mdn.mozillademos.org/files/5959/debugger-sections.png" style="display: block; margin-left: auto; margin-right: auto;" /></p>
<h3 id="Source_list_pane"><a name="source-list-pane">Source list pane</a></h3>
<p>The left-hand side of the debugger lists all the JS source files loaded into the page, and enables you to select one to debug.</p>
<p><img alt="" src="https://mdn.mozillademos.org/files/5961/debugger-source-list-pane.png" style="display: block; margin-left: auto; margin-right: auto;" />Source files are grouped under different headings according to where they are loaded from. For example, this is part of the source list pane when a page on developer.mozilla.org is loaded:</p>
<p><img alt="" src="https://mdn.mozillademos.org/files/5965/debugger-source-list-pane-only.png" style="width: 250px; height: 275px; display: block; margin-left: auto; margin-right: auto;" /></p>
<p>This corresponds to the following <code>script</code> tags in the page:</p>
<pre class="brush: html">
<span>&lt;<span class="start-tag">script</span> <span class="attribute-name">src</span>="<a class="attribute-value" href="view-source:https://developer.mozilla.org/en-US/jsi18n/build:8987063">/en-US/jsi18n/build:8987063</a>"&gt;</span><span>&lt;/<span class="end-tag">script</span>&gt;</span><span>
</span><span>&lt;<span class="start-tag">script</span> <span class="attribute-name">src</span>="<a class="attribute-value" href="view-source:https://login.persona.org/include.js">https://login.persona.org/include.js</a>" <span class="attribute-name">type</span>="<a class="attribute-value">text/javascript</a>"&gt;</span><span>&lt;/<span class="end-tag">script&gt;
<span>&lt;<span class="start-tag">script</span> <span class="attribute-name">src</span>="<span><a class="attribute-value" href="view-source:https://mozorg.cdn.mozilla.net/en-US/tabzilla/tabzilla.js">//mozorg.cdn.mozilla.net/en-US/</a>libs/jquery-1.7.1.min.js</span>" <span class="attribute-name">type</span>="<a class="attribute-value">text/javascript</a>"&gt;</span><span>&lt;/<span class="end-tag">script&gt;</span></span></span></span>
<span>&lt;<span class="start-tag">script</span> <span class="attribute-name">src</span>="<a class="attribute-value" href="view-source:https://mozorg.cdn.mozilla.net/en-US/tabzilla/tabzilla.js">//mozorg.cdn.mozilla.net/en-US/tabzilla/tabzilla.js</a>" <span class="attribute-name">async</span>&gt;</span><span>&lt;/<span class="end-tag">script</span>&gt;</span></pre>
<p>You can select any of these files and they will be loaded into the <a href="#source-pane" title="#source-pane">Source pane</a>.</p>
<p>&nbsp;</p>
<p>&nbsp;</p>
<p>Any breakpoints you've set in a source file are listed under the filename<img alt="" src="https://mdn.mozillademos.org/files/5967/debugger-breakpoints-set.png" style="display: block; margin-left: auto; margin-right: auto;" />The check box enables you to enable/disable the breakpoint. Right-clicking on the breakpoint's entry in the list shows a context menu enabling you to:</p>
<ul>
  <li>enable, disable or remove this breakpoint, all breakpoints, or all breakpoints except this one</li>
  <li>make this breakpoint conditional (or edit its conditions, if it is already conditional)</li>
</ul>
<p>The eyeball enables you to enable/disable black boxing a particular source. See "<a href="#black-box-a-source" title="#black-box-a-source">Black box a source</a>" for more info about this.</p>
<h3 id="Source_pane"><a name="source-pane">Source pane</a></h3>
<p>This shows the JavaScript file currently loaded. Breakpoints have a blue circle next to the line number, while breakpoints you've hit have a green arrow inside the circle:</p>
<p><img alt="" src="https://mdn.mozillademos.org/files/5969/debugger-breakpoint-hit-annotated.png" style="display: block; margin-left: auto; margin-right: auto;" />In the source pane, the context menu enables you to:</p>
<ul>
  <li>set a breakpoint</li>
  <li>set a conditional breakpoint</li>
  <li>add a watch expression for the selection</li>
  <li>search or filter using the <a href="#script filter" title="#script filter">script filter</a></li>
</ul>
<h3 id="Toolbar"><a name="toolbar">Toolbar</a></h3>
<p>The toolbar consists of four sections:</p>
<ul>
  <li>a row of buttons to control movement through a script</li>
  <li>a visualisation of the call stack</li>
  <li>the script filter</li>
  <li>buttons to expand/collapse the <a href="#variables-pane" title="#variables-pane">variables pane</a> and to control debugger settings</li>
</ul>
<p><img alt="" src="https://mdn.mozillademos.org/files/5733/debugger-toolbar.png" style="display: block; margin-left: auto; margin-right: auto;" /></p>
<p>The four buttons on the left perform the following functions:</p>
<ul>
  <li><strong>Pause/Resume</strong> (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.</li>
  <li><strong>Step Over</strong> (F7): steps across the current line of JavaScript code.</li>
  <li><strong>Step Into</strong> (F8): steps into the function call on the current line of JavaScript code.</li>
  <li><strong>Step Out</strong> (Shift-F8): runs the script until the current function exits.</li>
</ul>
<p>The call stack visualisation shows the call stack at the point execution is paused.</p>
<h4 id="Script_filter"><a name="script filter">Script filter</a></h4>
<p>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.</p>
<dl>
</dl>
<table class="standard-table">
  <thead>
    <tr>
      <th scope="col">Prefix</th>
      <th scope="col">Function</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>None</td>
      <td>Filter the scripts shown in the <a href="#source-list-pane" title="#source-list-pane">source list pane</a>.</td>
    </tr>
    <tr>
      <td>!</td>
      <td>Search for the string across all files.</td>
    </tr>
    <tr>
      <td>@</td>
      <td>Search for function definitions, across all files, containing the string.</td>
    </tr>
    <tr>
      <td>#</td>
      <td>Search for the string in the file currently open in the <a href="#source-pane" title="#source-pane">source pane</a>.</td>
    </tr>
    <tr>
      <td>:</td>
      <td>Go to the line given in the file currently open in the <a href="#source-pane" title="#source-pane">source pane</a>.</td>
    </tr>
    <tr>
      <td>*</td>
      <td>Filter the variables shown in the <a href="#variables-pane" title="#variables-pane">variables pane</a>.</td>
    </tr>
  </tbody>
</table>
<p>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 <a href="#source-pane" title="#source-pane">source pane</a>.</p>
<h4 id="Debugger_settings"><a name="debugger-settings">Debugger settings</a></h4>
<p>At the right-hand end of the toolbar are two more buttons. The first of these shows and hides the <a href="#variables-pane" title="#variables-pane">variables pane</a>, and the second enables you to toggle various debugger settings:</p>
<table class="standard-table">
  <tbody>
    <tr>
      <td><strong>Pause on exceptions</strong></td>
      <td>When this option is enabled, execution of the script will automatically pause whenever a JavaScript exception is thrown.</td>
    </tr>
    <tr>
      <td><strong>Ignore caught exceptions</strong></td>
      <td>
        <p>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).</p>
        <div class="geckoVersionNote">
          <p>This option is new in Firefox 26.</p>
        </div>
      </td>
    </tr>
    <tr>
      <td><strong>Show panes on startup</strong></td>
      <td>When this option is enabled, the debugger's <a href="#variables-pane" title="#variables-pane">variables pane</a> is visible when you first start the debugger.</td>
    </tr>
    <tr>
      <td><strong>Show only enumerable properties</strong></td>
      <td>Enabling this option adds a "Filter variables" search box to the <a href="#variables-pane" title="#variables-pane">variables panel</a>, so that you can filter the displayed list of variables.</td>
    </tr>
    <tr>
      <td><strong>Show variables filter box</strong></td>
      <td>Do not display non-enumerable JavaScript properties</td>
    </tr>
    <tr>
      <td><strong>Show original sources</strong></td>
      <td>Enabling this option will make the debugger use <a href="http://www.html5rocks.com/en/tutorials/developertools/sourcemaps/" title="http://www.html5rocks.com/en/tutorials/developertools/sourcemaps/">source maps</a>, if they are available, to display the original source for code which has been combined, minified, or even compiled to JavaScript from a language like CoffeeScript.</td>
    </tr>
  </tbody>
</table>
<dl>
</dl>
<h3 id="Variables_pane"><a name="variables-pane">Variables pane</a></h3>
<p>The variables pane is where you can examine, and modify, the internal state of the script as it's executing:</p>
<p><img alt="" src="https://mdn.mozillademos.org/files/5737/debugger-variables-pane.png" style="display: block; margin-left: auto; margin-right: auto;" /></p>
<h4 id="Examining_variables">Examining variables</h4>
<p>Variables are grouped by scope: in Function scope you'll see the built-in <code>arguments</code> and <code>this</code> variables as well as local variables defined by the function like <code>user</code> and <code>greeting</code>. Similarly, in Global scope you'll see global variables you've defined, like <code>greetme</code>, as well as built-in globals like <code>localStorage</code> and <code>console</code>.</p>
<p>Each object can be expanded using a disclosure triangle to show its members.</p>
<p>Pointing your cursor at a variable's name displays a tooltip that provides additional information about the variable; for example, pointing at the <code>greeting</code> object displays "<strike>configurable</strike> enumerable writable". See <a href="/en-US/docs/JavaScript/Reference/Global_Objects/Object/defineProperty" title="/en-US/docs/JavaScript/Reference/Global_Objects/Object/defineProperty"><code>Object.defineProperty()</code></a> for details on what these property descriptors mean.</p>
<p>You can filter the variables that are displayed, either by using the "*" modifier in the <a href="#script-filter" title="#script-filter">script filter</a>, or by typing into the filter variables box, if you have enabled this in the <a href="#debugger-settings" title="#debugger-settings">debugger settings</a>.</p>
<h4 id="Modifying_variables">Modifying variables</h4>
<p>You can change a variable's value by clicking on its current value and entering a new one; for example, if you click on <code>"Hi, Dr. Nick!"</code> next to <code>greeting</code>, you can edit the value.</p>
<h4 id="Watch_expressions"><a name="watch-expressions">Watch expressions</a></h4>
<p>Watch expressions are expressions that are evaluated each time execution pauses. You can then examine the results of these expressions. These are useful in that they let you inspect invariants in your code that you know are there but aren't necessarily in the code ready for inspection. To add a watch expression, click in the box that says "Add watch expression" and enter a JavaScript expression whose output you'd like to monitor as you step through code.</p>
<p>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:</p>
<p><img alt="" src="https://mdn.mozillademos.org/files/5765/debugger-watch.png" style="display: block; margin-left: auto; margin-right: auto;" />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.</p>
<h2 id="How_do_I....3F">How do I...?</h2>
<h3 id="Open_the_debugger">Open the debugger</h3>
<p>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&nbsp;X), or press Control-Shift-S (Command-Option-S on the Mac).</p>
<h3 id="Find_a_source_file">Find a source file</h3>
<p>When the debugger's open, all the JavaScript source files are listed in the <a href="#source-list-pane" title="#source-list-pane">source list pane</a>. You can browse the list to find the one you want, or search for a particular file using the <a href="#script filter" title="#script filter">script filter</a>.</p>
<h3 id="Find_inside_a_file">Find inside a file</h3>
<p>To find a function, search for a string, or jump to a line in a file open in the <a href="#source-pane" title="#source-pane">source pane</a>, you can use one of the special modifiers in the <a href="#script filter" title="#script filter">script filter</a>.</p>
<h3 id="Set_a_breakpoint">Set a breakpoint</h3>
<p>To set a breakpoint in a file open in the <a href="#source-pane" title="#source-pane">source pane</a>:</p>
<ul>
  <li>either click on the line number for the line you want to break at</li>
  <li>or activate the context menu while on the line you want to break at, and select "Add breakpoint"</li>
</ul>
<p>Each breakpoint is shown in three places in the debugger:</p>
<ul>
  <li>they're listed in the <a href="#source-list-pane" title="#source-list-pane">source list pane</a> underneath the file's name</li>
  <li>the line in the source pane is marked with a blue circle</li>
  <li>the gray vertical bar at the right of the source pane shows each breakpoint in the file as a small blue bar</li>
</ul>
<p>The screenshot below shows breakpoints at lines 7 and 65 of the file:</p>
<p><img alt="" src="https://mdn.mozillademos.org/files/5743/debugger-breakpoint-set-annotated.png" style="display: block; margin-left: auto; margin-right: auto;" /></p>
<h3 id="Set_a_conditional_breakpoint">Set a conditional breakpoint</h3>
<p>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:</p>
<p><img alt="" src="https://mdn.mozillademos.org/files/5747/debugger-conditional-breakpoint.png" style="display: block; margin-left: auto; margin-right: auto;" />To edit the condition, or to add a condition to a normal breakpoint, activate the context menu and select "Configure conditional breakpoint":</p>
<p><img alt="" src="https://mdn.mozillademos.org/files/5749/debugger-configure-conditional-breakpoint.png" style="display: block; margin-left: auto; margin-right: auto;" /></p>
<h3 id="Disable_a_breakpoint">Disable a breakpoint</h3>
<p>To disable a breakpoint:</p>
<ul>
  <li>either: uncheck the check box next to the breakpoint's entry in the <a href="#source-list-pane" title="#source-list-pane">source list pane</a></li>
  <li>or: activate the context menu while your mouse pointer is over the breakpoint's entry in the source list pane, and select "Disable breakpoint"</li>
</ul>
<h3 id="Step_through_my_code">Step through my code</h3>
<p>When your code stops at a breakpoint, you can step through it using the four buttons on the left of the toolbar:</p>
<p><img alt="" src="https://mdn.mozillademos.org/files/5769/debugger-stepping-through.png" style="display: block; margin-left: auto; margin-right: auto;" />In order, the buttons are:</p>
<ul>
  <li>Play: run to the next breakpoint</li>
  <li>Step over: advance to the next line in the same function.</li>
  <li>Step into: advance to the next line in the function, unless on a function call, in which case enter the function being called</li>
  <li>Step out: run to the end of the current function</li>
</ul>
<h3 id="Use_a_source_map">Use a source map</h3>
<p>JavaScript sources are often combined and minified to make delivering them from the server more efficient. Increasingly, too, JavaScript running in a page is machine-generated, as when compiled from a language like CoffeeScript. By using <a href="http://www.html5rocks.com/en/tutorials/developertools/sourcemaps/" title="http://www.html5rocks.com/en/tutorials/developertools/sourcemaps/">source maps</a>, the debugger can map the code being executed to the original source files, making debugging much, much easier.</p>
<p>To tell the Debugger to use source maps if they are available, click the "<a href="#debugger-settings" title="#debugger-settings">Debugger settings</a>" button and select "Show original sources" from the list of settings that pops up:<img alt="" src="https://mdn.mozillademos.org/files/5763/debugger-show-original-sources.png" style="display: block; margin-left: auto; margin-right: auto;" />Of course, for this to work, you will need to have supplied a source map for the JavaScript running in the page. Do this by appending a comment directive to your source file:</p>
<p><code>//@ sourceMappingURL=http://example.com/path/to/your/sourcemap.map</code></p>
<h3 id="Examine_variables">Examine variables</h3>
<p>When the code has stopped at a breakpoint, you can examine its state in the <a href="#variables-pane" title="#variables-pane">variables pane</a> of the debugger:</p>
<p><img alt="" src="https://mdn.mozillademos.org/files/5737/debugger-variables-pane.png" style="display: block; margin-left: auto; margin-right: auto;" />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 <a href="#script filter" title="#script filter">script filter</a>:</p>
<p><img alt="" src="https://mdn.mozillademos.org/files/5767/debugger-filter-variables.png" style="display: block; margin-left: auto; margin-right: auto;" /></p>
<h3 id="Modify_variables">Modify variables</h3>
<p>When the code has stopped at a breakpoint, you can modify variables in the <a href="#variables-pane" title="#variables-pane">variables pane</a> of the debugger. Just click on the variable's current value and you'll be able to type there:<img alt="" src="https://mdn.mozillademos.org/files/5761/debugger-modify-variable.png" style="display: block; margin-left: auto; margin-right: auto;" /></p>
<h3 id="Watch_an_expression">Watch an expression</h3>
<p>You can watch the value of a JavaScript expression using the "<a href="#watch-expressions" title="#watch-expressions">Add watch expression</a>" function in the variables pane.</p>
<h3 id="Debug_mobile_devices">Debug mobile devices</h3>
<p>To learn how to debug mobile devices, see the guide to <a href="/en-US/docs/Tools/Remote_Debugging" title="/en-US/docs/Tools/Remote_Debugging">remote debugging</a>.</p>
<h3 id="Black_box_a_source"><a name="black-box-a-source">Black box a source</a></h3>
<p>In modern web development, we often rely on libraries like <a href="http://jquery.com/">jQuery</a>, <a href="http://emberjs.com/">Ember</a>, or <a href="http://angularjs.org/">Angular</a>, 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 <a href="http://en.wikipedia.org/wiki/Black_box">black box</a>. 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.</p>
<p>You can enable/disable black boxing for a individual source by clicking the eyeball to the left of the source in the sources list. Or you can black box many sources at once by bringing up the developer toolbar with Shift+F2 and using the <code>dbg blackbox</code> command:</p>
<p><img alt="" src="https://mdn.mozillademos.org/files/5997/command.png" style="height: 48px; display: block; margin-left: auto; margin-right: auto; width: 537px;" />When a source is black boxed:</p>
<ul>
  <li>Any breakpoints it may have are disabled.</li>
  <li>When <a href="#debugger-settings">“pause on exceptions”</a> 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.</li>
  <li>The debugger will skip through black boxed sources when stepping.</li>
</ul>
<h3 id="Access_debugging_in_add-ons">Access debugging in add-ons</h3>
<p>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):</p>
<ul>
  <li>window.addEventListener("Debugger:EditorLoaded") - called when the read-only script panel loaded.</li>
  <li>window.addEventListener("Debugger:EditorUnloaded")</li>
</ul>
<p>Relevant files:</p>
<ul>
  <li>chrome://browser/content/devtools/debugger-controller.js</li>
  <li>chrome://browser/content/devtools/debugger-toolbar.js</li>
  <li>chrome://browser/content/devtools/debugger-view.js</li>
  <li>chrome://browser/content/devtools/debugger-panes.js</li>
</ul>
<p>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 <a href="https://bugzilla.mozilla.org/show_bug.cgi?id=653545" title="https://bugzilla.mozilla.org/show_bug.cgi?id=653545">653545</a>.)</p>
<h2 id="See_also">See also</h2>
<ul>
  <li><a href="/en-US/docs/Mozilla/Firefox_OS/Debugging" title="/en-US/docs/Mozilla/Firefox_OS/Debugging">Debugging on Firefox OS</a></li>
  <li><a href="https://wiki.mozilla.org/Remote_Debugging_Protocol" title="https://wiki.mozilla.org/Remote_Debugging_Protocol">Remote debugging protocol</a></li>
  <li><a href="https://hacks.mozilla.org/2012/08/remote-debugging-on-firefox-for-android/" title="https://hacks.mozilla.org/2012/08/remote-debugging-on-firefox-for-android/">Remote Debugging on Firefox for Android</a> (blog post)</li>
</ul>
Revert to this revision