diff options
Diffstat (limited to 'devtools/docs/user/debugger')
96 files changed, 1203 insertions, 0 deletions
diff --git a/devtools/docs/user/debugger/break_on_dom_mutation/dom_breakpoint_context.png b/devtools/docs/user/debugger/break_on_dom_mutation/dom_breakpoint_context.png Binary files differnew file mode 100644 index 0000000000..c8d8a78d0d --- /dev/null +++ b/devtools/docs/user/debugger/break_on_dom_mutation/dom_breakpoint_context.png diff --git a/devtools/docs/user/debugger/break_on_dom_mutation/dom_mutation_breakpoint.png b/devtools/docs/user/debugger/break_on_dom_mutation/dom_mutation_breakpoint.png Binary files differnew file mode 100644 index 0000000000..a36526b8ed --- /dev/null +++ b/devtools/docs/user/debugger/break_on_dom_mutation/dom_mutation_breakpoint.png diff --git a/devtools/docs/user/debugger/break_on_dom_mutation/dom_mutation_paused.png b/devtools/docs/user/debugger/break_on_dom_mutation/dom_mutation_paused.png Binary files differnew file mode 100644 index 0000000000..f193b9878a --- /dev/null +++ b/devtools/docs/user/debugger/break_on_dom_mutation/dom_mutation_paused.png diff --git a/devtools/docs/user/debugger/break_on_dom_mutation/index.rst b/devtools/docs/user/debugger/break_on_dom_mutation/index.rst new file mode 100644 index 0000000000..a16f3a0c0c --- /dev/null +++ b/devtools/docs/user/debugger/break_on_dom_mutation/index.rst @@ -0,0 +1,52 @@ +===================== +Break on DOM mutation +===================== + +A DOM Mutation Breakpoint pauses the code when the DOM node on which you have set the breakpoint is modified. + +You set a DOM Mutation Breakpoint in the :doc:`Page Inspector <../../page_inspector/index>`. Navigate to the DOM node in which you are interested and use the context menu to set the breakpoint. + + +.. image:: dom_breakpoint_context.png + :class: center + +There are three choices: + +**Subtree Modification** + + Execution pauses if any of the element's descendant nodes are modified.<br> + That means, the script execution is stopped whenever a child node or descendant node deeper in the DOM structure is added to or removed from the element the option is set on. + + Examples for when this breakpoint is triggered are calling `Node.appendChild() <https://developer.mozilla.org/en-US/docs/Web/API/Node/appendChild>`_ and `Node.removeChild() <https://developer.mozilla.org/en-US/docs/Web/API/Node/removeChild>`_, calling `Element.remove() <https://developer.mozilla.org/en-US/docs/Web/API/Element/remove>`_ or setting `Element.innerHTML <https://developer.mozilla.org/en-US/docs/Web/API/Element/innerHTML>`_ on one of the subnodes. + +**Attribute Modification** + + Execution pauses when any of the elements' attributes are modified.<br> + That means, the script execution is stopped whenever an attribute is added to or removed from the element the option is set on or the value of one of its attributes is changed. + + Examples for when this breakpoint is triggered are calling `Element.setAttribute() <https://developer.mozilla.org/en-US/docs/Web/API/Element/setAttribute>`_, `Element.removeAttribute() <https://developer.mozilla.org/en-US/docs/Web/API/Element/removeAttribute>`_, and `Element.classList.add() <https://developer.mozilla.org/en-US/docs/Web/API/Element/classList#methods>`_, or setting `Element.id <https://developer.mozilla.org/en-US/docs/Web/API/Element/id>`_. + +**Node Removal** + Execution pauses if the element the option is set on is removed. + + Examples for when this breakpoint is triggered are calling `Element.remove() <https://developer.mozilla.org/en-US/docs/Web/API/Element/remove>`_ or `Node.removeChild() <https://developer.mozilla.org/en-US/docs/Web/API/Node/removeChild>`_ on its parent node. + + +Once you set the breakpoint, go to the Debugger. You can see the breakpoint listed in the right-most panel under **DOM Mutation Breakpoints**. + +.. image:: dom_mutation_breakpoint.png + :class: border + +Click on the icon following the node name to go back to the Page Inspector with the node selected. + +When you execute the code, the debugger will pause execution when the DOM mutation occurs. In the following example, the selected node (the unordered list) is modified by adding a new child node. + +.. image:: dom_mutation_paused.png + :class: border + +The panel on the right shows that execution is "Paused on DOM mutation" and you, as with any other breakpoint, you can see the call stack and view any Watch expressions you may have set up. + +Inline variable preview +*********************** + +New in Firefox 71, the :ref:`source pane <debugger_ui_tour_source_pane>` now gives you an instant preview of the variables on each line of code you've stepped through. See :ref:`Set a breakpoint > Inline variable preview <debugger-how-to-set-a-breakpoint-variable-preview>` for more information. diff --git a/devtools/docs/user/debugger/how_to/access_debugging_in_add-ons/index.rst b/devtools/docs/user/debugger/how_to/access_debugging_in_add-ons/index.rst new file mode 100644 index 0000000000..d6aac55b0f --- /dev/null +++ b/devtools/docs/user/debugger/how_to/access_debugging_in_add-ons/index.rst @@ -0,0 +1,24 @@ +=========================== +Access debugging in add-ons +=========================== + +.. warning:: + We are planning to deprecate the use by Firefox add-ons of the techniques described in this document. Don't write new add-ons that use these techniques. + +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 <https://bugzilla.mozilla.org/show_bug.cgi?id=653545>`_.) diff --git a/devtools/docs/user/debugger/how_to/breaking_on_exceptions/exception-tooltip-stacktrace.png b/devtools/docs/user/debugger/how_to/breaking_on_exceptions/exception-tooltip-stacktrace.png Binary files differnew file mode 100644 index 0000000000..9aabff2c97 --- /dev/null +++ b/devtools/docs/user/debugger/how_to/breaking_on_exceptions/exception-tooltip-stacktrace.png diff --git a/devtools/docs/user/debugger/how_to/breaking_on_exceptions/index.rst b/devtools/docs/user/debugger/how_to/breaking_on_exceptions/index.rst new file mode 100644 index 0000000000..56a5de4335 --- /dev/null +++ b/devtools/docs/user/debugger/how_to/breaking_on_exceptions/index.rst @@ -0,0 +1,20 @@ +====================== +Breaking on exceptions +====================== + +To instruct the debugger to pause on an `exception <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error>`_, tick these checkboxes in the :ref:`Breakpoints list <debugger-ui-tour-breakpoints-list>`: + + +- Pause on exceptions +- Pause on caught exceptions + + +.. image:: version64ui.png + :alt: Screen shot showing "Pause on exceptions + :class: center + +When an exception occurs, the line where it occurs is highlighted in the source pane, with a squiggly red line under the problematic code. A tooltip describes the exception. Starting in Firefox 80, a disclosure triangle within the tooltip reveals a stack trace. + +.. image:: exception-tooltip-stacktrace.png + :alt: Screenshot of a tooltip for an exception + :class: center diff --git a/devtools/docs/user/debugger/how_to/breaking_on_exceptions/version64ui.png b/devtools/docs/user/debugger/how_to/breaking_on_exceptions/version64ui.png Binary files differnew file mode 100644 index 0000000000..98c04d8795 --- /dev/null +++ b/devtools/docs/user/debugger/how_to/breaking_on_exceptions/version64ui.png diff --git a/devtools/docs/user/debugger/how_to/debug_eval_sources/index.rst b/devtools/docs/user/debugger/how_to/debug_eval_sources/index.rst new file mode 100644 index 0000000000..a43dc580a2 --- /dev/null +++ b/devtools/docs/user/debugger/how_to/debug_eval_sources/index.rst @@ -0,0 +1,32 @@ +================== +Debug eval sources +================== + +You can debug JavaScript code that is evaluated dynamically, either as a string passed to `eval() <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/eval>`_ or as a string passed to the `Function <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function>`_ constructor. + +In the video below, we load a page containing a source like this: + +.. code-block:: javascript + + var script = `function foo() { + console.log('called foo'); + } + //# sourceURL=my-foo.js`; + + eval(script); + + var button = document.getElementById("foo"); + button.addEventListener("click", foo, false); + + +The evaluated string is given the name "my-foo.js" using the ``//# sourceURL`` directive. This source is then listed in the :ref:`source list pane <debugger-ui-tour-source-list-pane>`, and can be opened and debugged like any other source. + +.. raw:: html + + <iframe width="560" height="315" src="https://www.youtube.com/embed/AkvN40-y1NE" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe> + <br/> + <br/> + +The name of the source will also appear in stack traces appearing in the :doc:`Web Console <../../../web_console/index>`. + +The debugger will also stop at `debugger; <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/debugger>`_ statements in unnamed eval sources. diff --git a/devtools/docs/user/debugger/how_to/disable_breakpoints/disable_breakpoints.png b/devtools/docs/user/debugger/how_to/disable_breakpoints/disable_breakpoints.png Binary files differnew file mode 100644 index 0000000000..d80e3b4b85 --- /dev/null +++ b/devtools/docs/user/debugger/how_to/disable_breakpoints/disable_breakpoints.png diff --git a/devtools/docs/user/debugger/how_to/disable_breakpoints/index.rst b/devtools/docs/user/debugger/how_to/disable_breakpoints/index.rst new file mode 100644 index 0000000000..72a2dbd955 --- /dev/null +++ b/devtools/docs/user/debugger/how_to/disable_breakpoints/index.rst @@ -0,0 +1,15 @@ +=================== +Disable breakpoints +=================== + +To disable a single breakpoint, uncheck the checkbox next to it in the :ref:`breakpoints list <debugger-ui-tour-breakpoints-list>`. + +.. |image1| image:: toggle-all.png + :width: 20 + +To disable all breakpoints, click this icon: |image1| in the :ref:`toolbar <debugger-ui-tour-toolbar>`. + +After you click the icon to disable breakpoints, the appearance of the breakpoints will change to a lighter color with a dark-colored border. For example: + +.. image:: disable_breakpoints.png + :class: border diff --git a/devtools/docs/user/debugger/how_to/disable_breakpoints/toggle-all.png b/devtools/docs/user/debugger/how_to/disable_breakpoints/toggle-all.png Binary files differnew file mode 100644 index 0000000000..719589f4a8 --- /dev/null +++ b/devtools/docs/user/debugger/how_to/disable_breakpoints/toggle-all.png diff --git a/devtools/docs/user/debugger/how_to/highlight_and_inspect_dom_nodes/highlight_dom_node.png b/devtools/docs/user/debugger/how_to/highlight_and_inspect_dom_nodes/highlight_dom_node.png Binary files differnew file mode 100644 index 0000000000..5a1131a377 --- /dev/null +++ b/devtools/docs/user/debugger/how_to/highlight_and_inspect_dom_nodes/highlight_dom_node.png diff --git a/devtools/docs/user/debugger/how_to/highlight_and_inspect_dom_nodes/index.rst b/devtools/docs/user/debugger/how_to/highlight_and_inspect_dom_nodes/index.rst new file mode 100644 index 0000000000..18cd1d5116 --- /dev/null +++ b/devtools/docs/user/debugger/how_to/highlight_and_inspect_dom_nodes/index.rst @@ -0,0 +1,18 @@ +=============================== +Highlight and inspect DOM nodes +=============================== + +If you hover over a DOM node in the Watch Expressions, it will be highlighted in the page. + +When you are working with DOM nodes in the debugger, you can easily highlight the node on the page or view it in the Page Inspector. A DOM object in the Watch Expressions area, for example, includes a target. Hover over the target to highlight the item on the page, Click on the target to switch to the Page Inspector with the item highlighted. + +.. raw:: html + + <iframe width="560" height="315" src="https://www.youtube.com/embed/G8KUW87zkK8" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe> + <br/> + <br/> + +Also, when you view the details of a DOM node in the code panel, objects that you can highlight in the list will also have a target next to them. You can click any one of these targets to switch to the Page Inspector with this item highlighted. + +.. image:: highlight_dom_node.png + :class: border diff --git a/devtools/docs/user/debugger/how_to/ignoring_sources/ignore-line.png b/devtools/docs/user/debugger/how_to/ignoring_sources/ignore-line.png Binary files differnew file mode 100644 index 0000000000..7b3b30eda3 --- /dev/null +++ b/devtools/docs/user/debugger/how_to/ignoring_sources/ignore-line.png diff --git a/devtools/docs/user/debugger/how_to/ignoring_sources/ignore-lines.png b/devtools/docs/user/debugger/how_to/ignoring_sources/ignore-lines.png Binary files differnew file mode 100644 index 0000000000..a880e26345 --- /dev/null +++ b/devtools/docs/user/debugger/how_to/ignoring_sources/ignore-lines.png diff --git a/devtools/docs/user/debugger/how_to/ignoring_sources/ignore-source.png b/devtools/docs/user/debugger/how_to/ignoring_sources/ignore-source.png Binary files differnew file mode 100644 index 0000000000..38e8e40975 --- /dev/null +++ b/devtools/docs/user/debugger/how_to/ignoring_sources/ignore-source.png diff --git a/devtools/docs/user/debugger/how_to/ignoring_sources/ignore-third-party-sources.png b/devtools/docs/user/debugger/how_to/ignoring_sources/ignore-third-party-sources.png Binary files differnew file mode 100644 index 0000000000..30b4878b74 --- /dev/null +++ b/devtools/docs/user/debugger/how_to/ignoring_sources/ignore-third-party-sources.png diff --git a/devtools/docs/user/debugger/how_to/ignoring_sources/index.rst b/devtools/docs/user/debugger/how_to/ignoring_sources/index.rst new file mode 100644 index 0000000000..92b9f9f1c4 --- /dev/null +++ b/devtools/docs/user/debugger/how_to/ignoring_sources/index.rst @@ -0,0 +1,70 @@ +================ +Ignoring sources +================ + +In modern web development, we often rely on libraries like `jQuery <https://jquery.com/>`_, `Ember <https://emberjs.com/>`_, or `Angular <https://angularjs.org/>`_, and 99% of the time we can safely assume that they “just work”. We don’t care about the internal implementation of these libraries. 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. However, you can tell the debugger to ignore the details of selected sources. + +What happens when source(s) or line(s) are ignored: + +- Any breakpoints defined are disabled and are not hit on execution. +- When “Pause on Exceptions” is enabled in the :ref:`Debugger settings <settings-debugger>`, the debugger won’t pause when an exception is thrown in the ignored source; instead it waits until (and if) the stack unwinds to a frame in a source that isn’t ignored. +- The debugger skips through ignored sources when stepping. +- Any ``debugger`` statements are skipped when stepping. +- Any frames related to the source/line/lines won't be visible in the call stack. + +Ignore a source +**************** + +To enable or disable ignoring a source file: + + +- In the :ref:`source list pane <debugger-ui-tour-source-list-pane>`, right-click the filename and choose **Ignore source** (or **Unignore source**). +- If the source file is displayed in the :ref:`source pane <debugger_ui_tour_source_pane>`, click the "crossed out source" icon at the bottom. + +.. image:: ignore-source.png + :alt: Screenshot showing the context menu item to ignore a source file, and highlighting the "ignore" icon. + :width: 1150px + :class: border + + +Ignore a single line +********************** + +To ignore a single line in a source file: + +- When the source file is displayed in the :ref:`source pane <debugger_ui_tour_source_pane>`, right-click the content on the specific line and choose **Ignore line** (or **Unignore line**) +- Also right-click on the gutter at the specific line and choose **Ignore line** (or **Unignore line**) + +.. image:: ignore-line.png + :alt: Screenshot showing the context menu item to ignore a single line in source file. + :width: 1150px + :class: border + + +Ignore multiple lines +*********************** + +To ignore multiple lines in a source file: + +- When the source file is displayed in the :ref:`source pane <debugger_ui_tour_source_pane>`, select the specific lines, then right-click on the selection and choose **Ignore lines** (or **Unignore lines**) + +.. image:: ignore-lines.png + :alt: Screenshot showing the context menu item to ignore a selection of lines in a source file. + :width: 1150px + :class: border + + +Ignore third-party scripts +**************************** + +Frameworks and bundlers can define third-party scripts which should be ignored, using the `x_google_ignoreList <https://developer.chrome.com/articles/x-google-ignore-list/>`_ sourcemap extension. +The debugger parses and reads this field from the sourcemap to automatically ignore these sources. + +To ignore third-party scripts: + +- Click the debugger settings menu and choose **Ignore Known Third-party Scripts** + +.. image:: ignore-third-party-sources.png + :alt: Screenshot showing the settings menu item to ignore third party sources off the sourcemaps x_google_ignoreList field. + :width: 1150px + :class: border diff --git a/devtools/docs/user/debugger/how_to/index.rst b/devtools/docs/user/debugger/how_to/index.rst new file mode 100644 index 0000000000..6e4e1678ec --- /dev/null +++ b/devtools/docs/user/debugger/how_to/index.rst @@ -0,0 +1,21 @@ +====== +How to +====== + +These articles describe how to use the debugger. + +- :doc:`Access debugging in add-ons <access_debugging_in_add-ons/index>` +- :doc:`Breaking on exceptions <breaking_on_exceptions/index>` +- :doc:`Debug eval sources <debug_eval_sources/index>` +- :doc:`Disable breakpoints <disable_breakpoints/index>` +- :doc:`Highlight and inspect DOM nodes <highlight_and_inspect_dom_nodes/index>` +- :doc:`Ignoring sources <ignoring_sources/index>` +- :doc:`Open the debugger <open_the_debugger/index>` +- :doc:`Pretty-print a minified file <pretty-print_a_minified_file/index>` +- :doc:`Search <search/index>` +- :doc:`Set a breakpoint <set_a_breakpoint/index>` +- :doc:`Set a conditional breakpoint <set_a_conditional_breakpoint/index>` +- :doc:`Set watch expressions <set_watch_expressions/index>` +- :doc:`Step through code <step_through_code/index>` +- :doc:`Use a source map <use_a_source_map/index>` +- :doc:`Use watchpoints <use_watchpoints/index>` diff --git a/devtools/docs/user/debugger/how_to/open_the_debugger/hamburger.png b/devtools/docs/user/debugger/how_to/open_the_debugger/hamburger.png Binary files differnew file mode 100644 index 0000000000..0a86806250 --- /dev/null +++ b/devtools/docs/user/debugger/how_to/open_the_debugger/hamburger.png diff --git a/devtools/docs/user/debugger/how_to/open_the_debugger/index.rst b/devtools/docs/user/debugger/how_to/open_the_debugger/index.rst new file mode 100644 index 0000000000..157a95c75f --- /dev/null +++ b/devtools/docs/user/debugger/how_to/open_the_debugger/index.rst @@ -0,0 +1,20 @@ +================= +Open the debugger +================= + +There are three ways to open the debugger: + +- Select the *Debugger* panel in the Web Developer Tools, accessible from the Browser Tools submenu + +- Press :kbd:`Ctrl` + :kbd:`Shift` + :kbd:`Z` on Windows and Linux, or :kbd:`Cmd` + :kbd:`Opt` + :kbd:`Z` on macOS (starting in Firefox 71; prior to Firefox 66, the letter in this shortcut was :kbd:`S`). + +- Press the menu button |image1|, select "Developer", then "Debugger". + +.. |image1| image:: hamburger.png + :width: 20 + +.. raw:: html + + <iframe width="560" height="315" src="https://www.youtube.com/embed/yI5SlVQiZtI" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe> + <br/> + <br/> diff --git a/devtools/docs/user/debugger/how_to/pretty-print_a_minified_file/index.rst b/devtools/docs/user/debugger/how_to/pretty-print_a_minified_file/index.rst new file mode 100644 index 0000000000..b44ac3c48f --- /dev/null +++ b/devtools/docs/user/debugger/how_to/pretty-print_a_minified_file/index.rst @@ -0,0 +1,22 @@ +============================ +Pretty-print a minified file +============================ + +To prettify a minified file, click the **Pretty print source** icon |image1| at the bottom of the :ref:`source pane <debugger_ui_tour_source_pane>`. The debugger formats the source and displays it as a new file with a name like: "{ } [original-name]". + +.. |image1| image:: pretty_print_icon.png + :width: 20 + +.. image:: pretty_print_source.png + :class: border + +After you click the icon, the source code looks like this: + +.. image:: pretty_print_after.png + :class: border + +The **Pretty print source** icon is available only if the source file is minified (i.e., not an original file), and is not already "prettified". + +.. note:: + + Currently Firefox `does not support <https://bugzilla.mozilla.org/show_bug.cgi?id=1010150>`_ pretty printing inline Javascript. diff --git a/devtools/docs/user/debugger/how_to/pretty-print_a_minified_file/pretty_print_after.png b/devtools/docs/user/debugger/how_to/pretty-print_a_minified_file/pretty_print_after.png Binary files differnew file mode 100644 index 0000000000..fe65a39d40 --- /dev/null +++ b/devtools/docs/user/debugger/how_to/pretty-print_a_minified_file/pretty_print_after.png diff --git a/devtools/docs/user/debugger/how_to/pretty-print_a_minified_file/pretty_print_icon.png b/devtools/docs/user/debugger/how_to/pretty-print_a_minified_file/pretty_print_icon.png Binary files differnew file mode 100644 index 0000000000..5fa79884e6 --- /dev/null +++ b/devtools/docs/user/debugger/how_to/pretty-print_a_minified_file/pretty_print_icon.png diff --git a/devtools/docs/user/debugger/how_to/pretty-print_a_minified_file/pretty_print_source.png b/devtools/docs/user/debugger/how_to/pretty-print_a_minified_file/pretty_print_source.png Binary files differnew file mode 100644 index 0000000000..116183c87c --- /dev/null +++ b/devtools/docs/user/debugger/how_to/pretty-print_a_minified_file/pretty_print_source.png diff --git a/devtools/docs/user/debugger/how_to/search/ctrlshiftf.png b/devtools/docs/user/debugger/how_to/search/ctrlshiftf.png Binary files differnew file mode 100644 index 0000000000..31edbbea22 --- /dev/null +++ b/devtools/docs/user/debugger/how_to/search/ctrlshiftf.png diff --git a/devtools/docs/user/debugger/how_to/search/index.rst b/devtools/docs/user/debugger/how_to/search/index.rst new file mode 100644 index 0000000000..2b1868b7d1 --- /dev/null +++ b/devtools/docs/user/debugger/how_to/search/index.rst @@ -0,0 +1,61 @@ +====== +Search +====== + +.. _debugger-how-to-search-searching-for-files: + +Searching for files +******************* + +To search for a particular file, press :kbd:`Control` + :kbd:`P` (or :kbd:`Command` + :kbd:`P` on a Mac) and type the search term. The :ref:`source pane <debugger_ui_tour_source_pane>` will display a list of all matching files as you type. You can use the up and down arrows to move through the list, and :kbd:`Return` to open the file you want: + +.. raw:: html + + <iframe width="560" height="315" src="https://www.youtube.com/embed/xXsfYx0THWg" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe> + <br/> + <br/> + + +.. _debugger-how-to-search-searching-within-a-file: + +Searching within a file +*********************** + +To search for a particular substring in the file currently loaded into the :ref:`source pane <debugger_ui_tour_source_pane>`, press :kbd:`Control` + :kbd:`F` (or :kbd:`Command` + :kbd:`F` on a Mac) while the source pane is focused. Press :kbd:`Return` to search. The debugger will display the number of matches in the code and highlight each result: + +.. image:: search_code.png + :class: border + + +Using the Outline tab +--------------------- + +If you are searching for a specific function within the current JavaScript file, you can use the Outline tab in the debugger to find it quickly. The Outline tab lists the functions in the current file. The default sort order is by the order in the file but you can simplify the search by click on "Sort by name" at the bottom of the tab. + +.. image:: outline_sorted.png + :class: center + +You can further simplify the search by filtering the list. Enter text into the text input above the list to limit the results in the Outline. For example, if I enter "load" when viewing the above list, I get the following: + +.. image:: outline_filtered.png + :class: center + +Only the functions with load in their name are shown. + +This feature may not seem terribly useful when searching a file with a handful of functions in it but when you are searching through a file with dozens of functions, it comes in handy. + + +Searching in all files +********************** + +You can also search for a string in all of the files included in the currently opened project. Press :kbd:`Shift` + :kbd:`Ctrl` + :kbd:`F` (Windows and Linux) or :kbd:`Shift` + :kbd:`Cmd` + :kbd:`F` (macOS) and then enter the string you are trying to find. + +.. image:: searchinallfiles.png + :class: border + +If the string exists in any of the files in the project, the search will return a list showing a list by file and line number. + +.. image:: ctrlshiftf.png + :class: border + +Click on any entry in the list to go directly to the line in the file where the string occurs. diff --git a/devtools/docs/user/debugger/how_to/search/outline_filtered.png b/devtools/docs/user/debugger/how_to/search/outline_filtered.png Binary files differnew file mode 100644 index 0000000000..598c1446a2 --- /dev/null +++ b/devtools/docs/user/debugger/how_to/search/outline_filtered.png diff --git a/devtools/docs/user/debugger/how_to/search/outline_sorted.png b/devtools/docs/user/debugger/how_to/search/outline_sorted.png Binary files differnew file mode 100644 index 0000000000..bee1b25e9f --- /dev/null +++ b/devtools/docs/user/debugger/how_to/search/outline_sorted.png diff --git a/devtools/docs/user/debugger/how_to/search/search_code.png b/devtools/docs/user/debugger/how_to/search/search_code.png Binary files differnew file mode 100644 index 0000000000..2ff118890e --- /dev/null +++ b/devtools/docs/user/debugger/how_to/search/search_code.png diff --git a/devtools/docs/user/debugger/how_to/search/searchinallfiles.png b/devtools/docs/user/debugger/how_to/search/searchinallfiles.png Binary files differnew file mode 100644 index 0000000000..7b9954d0c9 --- /dev/null +++ b/devtools/docs/user/debugger/how_to/search/searchinallfiles.png diff --git a/devtools/docs/user/debugger/how_to/set_a_breakpoint/add-breakpoint-context.png b/devtools/docs/user/debugger/how_to/set_a_breakpoint/add-breakpoint-context.png Binary files differnew file mode 100644 index 0000000000..3ca54d6995 --- /dev/null +++ b/devtools/docs/user/debugger/how_to/set_a_breakpoint/add-breakpoint-context.png diff --git a/devtools/docs/user/debugger/how_to/set_a_breakpoint/breakpoints-list.png b/devtools/docs/user/debugger/how_to/set_a_breakpoint/breakpoints-list.png Binary files differnew file mode 100644 index 0000000000..6f4eaca3cf --- /dev/null +++ b/devtools/docs/user/debugger/how_to/set_a_breakpoint/breakpoints-list.png diff --git a/devtools/docs/user/debugger/how_to/set_a_breakpoint/breakpoints-on-line.png b/devtools/docs/user/debugger/how_to/set_a_breakpoint/breakpoints-on-line.png Binary files differnew file mode 100644 index 0000000000..17a929eb63 --- /dev/null +++ b/devtools/docs/user/debugger/how_to/set_a_breakpoint/breakpoints-on-line.png diff --git a/devtools/docs/user/debugger/how_to/set_a_breakpoint/conditional-set.png b/devtools/docs/user/debugger/how_to/set_a_breakpoint/conditional-set.png Binary files differnew file mode 100644 index 0000000000..5abc6a258e --- /dev/null +++ b/devtools/docs/user/debugger/how_to/set_a_breakpoint/conditional-set.png diff --git a/devtools/docs/user/debugger/how_to/set_a_breakpoint/index.rst b/devtools/docs/user/debugger/how_to/set_a_breakpoint/index.rst new file mode 100644 index 0000000000..e92deb573d --- /dev/null +++ b/devtools/docs/user/debugger/how_to/set_a_breakpoint/index.rst @@ -0,0 +1,108 @@ +================ +Set a breakpoint +================ + +There are many different types of breakpoint that can be set in the debugger; this article covers standard (unconditional) breakpoints and conditional breakpoints. + +Breakpoints in brief +******************** + +Breakpoints are very useful when debugging JavaScript — you basically set a point in your code where you would like execution of the code to pause. At this point you can do useful things like studying the value of different variables at that point, allowing you to work out why a problem is occurring. + + +The source pane context menu +**************************** + +In the :ref:`source pane <debugger_ui_tour_source_pane>`, you can handle setting breakpoints by bringing up the context menu over a line number. + +.. image:: add-breakpoint-context.png + :class: border + +There are a few options available here: + +- *Add breakpoint*: Add a standard **unconditional breakpoint** at this line number (see below). + +- *Add condition*: Add a condition and create a **conditional breakpoint** (see below). + +- *Add log*: Add a :doc:`log point <../../set_a_logpoint/index>`, which logs a value to your console rather than pausing execution as a breakpoint does. + +- *Continue to here*: When :doc:`stepping through code <../step_through_code/index>`, this option tells the debugging to continue execution through to this point. + + +Unconditional breakpoints +************************* + +An unconditional breakpoint is one where the code will always pause execution when it is reached. You can set an unconditional breakpoint using the context menu (see above), or by: + +- Clicking on the line number for the line you want to break at in the source pane. +- Highlighting the line you want to break at in the source pane and pressing :kbd:`Ctrl` + :kbd:`B` (Windows/Linux) or :kbd:`Cmd` + :kbd:`B` (macOS). + +The line number is highlighted in blue: + +.. image:: breakpoints-on-line.png + :class: border + +In addition, if the line contains multiple function calls, each one will be given a small blue arrow icon to the left of it. These are called **column breakpoints**, and allow you to set the breakpoint to happen exactly on any one of the function calls in the line (or multiple calls), by clicking on each relevant one. + + +Conditional breakpoints +*********************** + +A conditional breakpoint is one where the code will pause execution when it is reached, only if a certain condition is met, such a variable having a certain value at the time. You can set a conditional breakpoint using the context menu (see above), or by highlighting the line you want to break at in the source pane and pressing :kbd:`Ctrl` + :kbd:`Shift` + :kbd:`B` (Windows/Linux) or :kbd:`Cmd` + :kbd:`Shift` + :kbd:`B` (macOS). + +When you first choose to set a conditional breakpoint, a text entry line will appear into which you add the condition you want it to break on: + +.. image:: updated-conditional.png + :class: border + +Once you've entered your condition and pressed :kbd:`Enter`/:kbd:`Return`, the line number will be highlighted in orange: + +.. image:: conditional-set.png + :class: border + + +Breakpoints list +**************** + +Once you've set some breakpoints, the :ref:`breakpoints list <debugger-ui-tour-breakpoints-list>` in the right-hand column shows the filename and line number for each one: + +.. image:: breakpoints-list.png + :class: border + + +Unsetting a breakpoint +********************** + +Once a breakpoint has been set, you can unset it again in various ways: + +- Click on the line number highlight. +- Highlight the line of code the breakpoint is set on and pressing :kbd:`Ctrl` + :kbd:`B` (Windows/Linux) or :kbd:`Cmd` + :kbd:`B` (macOS). +- Bring up the context menu over the line highlight and choose the *Remove Breakpoint* option. + +.. image:: remove-breakpoint-context.png + :class: border + +Other context menu options worth mentioning are: + + +- *Disable Breakpoint:* turn it off, but don't remove it completely. +- *Disable breakpoints on line* and *Remove breakpoints on line*: Remove or disable column breakpoints. +- If the breakpoint is an unconditional breakpoint, you'll get an option *Add condition*, which allows you to turn it into a conditional breakpoint. +- If the breakpoint is a conditional breakpoint, you'll get an option *Edit condition*, which allows you to change the previously set condition. + + +.. _debugger-how-to-set-a-breakpoint-variable-preview: + +Inline variable preview +*********************** + +New in Firefox 71, the :ref:`source pane <debugger_ui_tour_source_pane>` now gives you an inline preview of the variables on each line of code you've stepped through: + +.. image:: inline-variables.png + :class: border + +This is a very useful timesaver when stepping through your code. Previously you’d have to scroll through the Scopes panel to find variable values, or hover over a variable in the source pane. Now when execution pauses, you can view relevant variables immediately. + +.. note:: + + There is also a new option in the context menu for the actual code in the source pane — *Hide inline preview*/*Show inline preview* — which allows you to turn the inline variables on/off. diff --git a/devtools/docs/user/debugger/how_to/set_a_breakpoint/inline-variables.png b/devtools/docs/user/debugger/how_to/set_a_breakpoint/inline-variables.png Binary files differnew file mode 100644 index 0000000000..fe3913356d --- /dev/null +++ b/devtools/docs/user/debugger/how_to/set_a_breakpoint/inline-variables.png diff --git a/devtools/docs/user/debugger/how_to/set_a_breakpoint/remove-breakpoint-context.png b/devtools/docs/user/debugger/how_to/set_a_breakpoint/remove-breakpoint-context.png Binary files differnew file mode 100644 index 0000000000..99132dd05e --- /dev/null +++ b/devtools/docs/user/debugger/how_to/set_a_breakpoint/remove-breakpoint-context.png diff --git a/devtools/docs/user/debugger/how_to/set_a_breakpoint/updated-conditional.png b/devtools/docs/user/debugger/how_to/set_a_breakpoint/updated-conditional.png Binary files differnew file mode 100644 index 0000000000..70c86c6adc --- /dev/null +++ b/devtools/docs/user/debugger/how_to/set_a_breakpoint/updated-conditional.png diff --git a/devtools/docs/user/debugger/how_to/set_a_conditional_breakpoint/index.rst b/devtools/docs/user/debugger/how_to/set_a_conditional_breakpoint/index.rst new file mode 100644 index 0000000000..7226f08049 --- /dev/null +++ b/devtools/docs/user/debugger/how_to/set_a_conditional_breakpoint/index.rst @@ -0,0 +1,14 @@ +============================ +Set a conditional breakpoint +============================ + +A normal breakpoint is just associated with a line: when the program reaches that line, the debugger pauses. A conditional breakpoint also has a condition associated with it, which is represented as an `expression <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Expressions_and_Operators#expressions>`_. When the program reaches the line, the debugger pauses only if the breakpoint's specified expression evaluates to ``true``. + +This makes it possible to debug specific scenarios, such as bugs that only happen on odd entries in a list, or errors that occur the last time through a loop. + + +To set a conditional breakpoint, activate the context menu in the :ref:`source pane <debugger_ui_tour_source_pane>`, on the line where you want the breakpoint, and select "Add Conditional Breakpoint". You'll then see a textbox where you can enter the expression. Press :kbd:`Return` to finish. + +Conditional breakpoints are shown as orange arrows laid over the line number. + +If you context-click on any breakpoint, you'll see a menu item "Edit Breakpoint". You can use this to modify an existing condition or to add a condition to a normal breakpoint. diff --git a/devtools/docs/user/debugger/how_to/set_watch_expressions/ff_watch_expressions_add.png b/devtools/docs/user/debugger/how_to/set_watch_expressions/ff_watch_expressions_add.png Binary files differnew file mode 100644 index 0000000000..77b918e50b --- /dev/null +++ b/devtools/docs/user/debugger/how_to/set_watch_expressions/ff_watch_expressions_add.png diff --git a/devtools/docs/user/debugger/how_to/set_watch_expressions/ff_watch_expressions_remove.png b/devtools/docs/user/debugger/how_to/set_watch_expressions/ff_watch_expressions_remove.png Binary files differnew file mode 100644 index 0000000000..36a2ce6204 --- /dev/null +++ b/devtools/docs/user/debugger/how_to/set_watch_expressions/ff_watch_expressions_remove.png diff --git a/devtools/docs/user/debugger/how_to/set_watch_expressions/index.rst b/devtools/docs/user/debugger/how_to/set_watch_expressions/index.rst new file mode 100644 index 0000000000..db67729c59 --- /dev/null +++ b/devtools/docs/user/debugger/how_to/set_watch_expressions/index.rst @@ -0,0 +1,25 @@ +===================== +Set watch expressions +===================== + +The Debugger *Watch expressions* pane allows you to specify JavaScript expressions that will be reevaluated and displayed every time the debugger pauses. As you step through code, the debugger will watch the expression and return any results.Watches are most commonly used to group individual*variables* of interest for easier observation. Watching more complicated expressions can sometimes also be useful:for example, to check that variables are within certain limits or values. + +The screenshot below shows the *Watch expressions* panel with a number of expressions already defined. Each line shows the expression and its value at the current step,separated by a colon. Expressions that evaluate to an object can be expanded using the caret symbol to the left. + +.. image:: ff_watch_expressions_add.png + :alt: Screenshot showing the Watch expressions dialog after the + button has been pressed (for entry of a new watch expression) + :class: border + +To add a watch expression click the **+** button in the top right corner of the panel. Then type the expression into the text entry field that appears at the bottom of the panel, and press :kbd:`Enter` to save it. The expression will be evaluated when you save, when you step through the code, or when you select the *Refresh* icon (next to **+**). + +You can enter any valid expression into the watch, and even declare new "watch" variables and reuse them. For example, ``mywatchvar1 = 3`` and ``mywatchvar2 = mywatchvar1 + 2`` will evaluate ``mywatchvar2`` as 5. You can also declare an expression that modifies a variable value in the code, and this will be re-evaluated whenever you step through the code or refresh the watch expression. + +.. warning:: + + **Important**: Changing values in the code using a watch expression may affect normal code execution. + +To remove a watch expression, select the **X** button that appears when you hover over a line. + +.. image:: ff_watch_expressions_remove.png + :alt: Hover over watch expression to get X that can be clicked to remove an expression. + :class: border diff --git a/devtools/docs/user/debugger/how_to/step_through_code/breakpoint_toolbar.png b/devtools/docs/user/debugger/how_to/step_through_code/breakpoint_toolbar.png Binary files differnew file mode 100644 index 0000000000..df6feec180 --- /dev/null +++ b/devtools/docs/user/debugger/how_to/step_through_code/breakpoint_toolbar.png diff --git a/devtools/docs/user/debugger/how_to/step_through_code/debugger-overlay.png b/devtools/docs/user/debugger/how_to/step_through_code/debugger-overlay.png Binary files differnew file mode 100644 index 0000000000..1ee92845d8 --- /dev/null +++ b/devtools/docs/user/debugger/how_to/step_through_code/debugger-overlay.png diff --git a/devtools/docs/user/debugger/how_to/step_through_code/index.rst b/devtools/docs/user/debugger/how_to/step_through_code/index.rst new file mode 100644 index 0000000000..85d4c5c325 --- /dev/null +++ b/devtools/docs/user/debugger/how_to/step_through_code/index.rst @@ -0,0 +1,42 @@ +================= +Step through code +================= + +When the debugger is stopped at a breakpoint, you can step through it using four buttons in the :ref:`toolbar <debugger-ui-tour-toolbar>`: + +.. image:: breakpoint_toolbar.png + +In order, the buttons are: + + +- Play: run to the next breakpoint +- Step over: advance to the next line in the same function. +- Step in: 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, in which case, the debugger will skip the return value from a function, returning execution to the caller + + +Split console +************* + +When paused, you can press the Esc key to open and close the split console to gain more insight into errors and variables: + +.. image:: split_console.png + :class: border + + +Pause on breakpoints overlay +**************************** + +Since Firefox 70, when your code is paused on a breakpoint an overlay appears on the viewport of the tab you are debugging. + +.. image:: debugger-overlay.png + :alt: border + + +This lets you know what kind of breakpoint the code is paused on (breakpoint, event breakpoint, etc.), and also provides a step button and a play button. The thinking here is that if you've got your DevTools open in a separate window, as many people do, it can be easier to have the buttons available right there to move the code forward while you are looking at the result. + + +Inline variable preview +*********************** + +New in Firefox 71, the :ref:`source pane <debugger_ui_tour_source_pane>` now gives you an instant preview of the variables on each line of code you've stepped through. See :ref:`Set a breakpoint > Inline variable preview <debugger-how-to-set-a-breakpoint-variable-preview>` for more information. diff --git a/devtools/docs/user/debugger/how_to/step_through_code/split_console.png b/devtools/docs/user/debugger/how_to/step_through_code/split_console.png Binary files differnew file mode 100644 index 0000000000..46a5ecd141 --- /dev/null +++ b/devtools/docs/user/debugger/how_to/step_through_code/split_console.png diff --git a/devtools/docs/user/debugger/how_to/use_a_source_map/index.rst b/devtools/docs/user/debugger/how_to/use_a_source_map/index.rst new file mode 100644 index 0000000000..e78bdc905b --- /dev/null +++ b/devtools/docs/user/debugger/how_to/use_a_source_map/index.rst @@ -0,0 +1,34 @@ +================ +Use a source map +================ + +The JavaScript sources executed by the browser are often transformed in some way from the original sources created by a developer. For example: + +- sources are often combined and `minified <https://en.wikipedia.org/wiki/Minification_(programming)>`_ to make delivering them from the server more efficient. + +- JavaScript running in a page is often machine-generated, as when compiled from a language like `CoffeeScript <https://coffeescript.org/>`_ or `TypeScript <https://www.typescriptlang.org/>`_ + +In these situations, it's much easier to debug the original source, rather than the source in the transformed state that the browser has downloaded. A `source map <https://www.html5rocks.com/en/tutorials/developertools/sourcemaps/>`_ is a file that maps from the transformed source to the original source, enabling the browser to reconstruct the original source and present the reconstructed original in the debugger. + +To enable the debugger to work with a source map, you must: + +- generate the source map +- include a comment in the transformed file, that points to the source map. The comment's syntax is like this: + +.. code-block:: JavaScript + + //# sourceMappingURL=http://example.com/path/to/your/sourcemap.map + +.. raw:: html + + <iframe width="560" height="315" src="https://www.youtube.com/embed/Fqd15gHC4Pg" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe> + <br/> + <br/> + +In the video above we load https://firefox-devtools.github.io/devtools-examples/sourcemaps-in-console/index.html. This page loads a source called "main.js" that was originally written in CoffeeScript and compiled to JavaScript. The compiled source contains a comment like this, that points to a source map: + +.. code-block:: JavaScript + + //# sourceMappingURL=main.js.map + +In the Debugger's :ref:`source list pane <debugger-ui-tour-source-list-pane>`, the original CoffeeScript source now appears as "main.coffee", and we can debug it just like any other source. diff --git a/devtools/docs/user/debugger/how_to/use_watchpoints/index.rst b/devtools/docs/user/debugger/how_to/use_watchpoints/index.rst new file mode 100644 index 0000000000..eb4c803882 --- /dev/null +++ b/devtools/docs/user/debugger/how_to/use_watchpoints/index.rst @@ -0,0 +1,53 @@ +=============== +Use watchpoints +=============== + +When debugging JavaScript code, it can be useful to know when properties on objects are read or modified. In a large, complex codebase, it's not always easy to know where in the code a given property is accessed. In the Firefox Debugger, this information can be provided by *watchpoints*. By setting a watchpoint on the property, rather than a breakpoint at a particular line, you can discover where that access occurs. + +There are three types of watchpoints: *get*, *set*, and *get or set*. A *get* watchpoint pauses whenever a property is read; a *set* watchpoint pauses whenever a property value changes; a *get or set* watchpoint pauses whenever a property value is accessed in either way. + +Set a watchpoint +**************** + +1. Run and then pause the debugger. +2. In the Scopes pane on the right side of the Debugger user interface, find an object you want to watch, and right-click it to open its context menu. +3. Choose **Break on**, and then one of + + - **Property set** + - **Property get** + - **Property get or set** + + .. image:: watchpoint-get-or-set.png + :alt: Screenshot showing the context menu for setting a watchpoint on an object + :class: border + + A watchpoint icon appears to the right of the property in the Scopes pane. *Set* watchpoint icons are blue, *get* watchpoint icons are reddish, and *get or set* watchpoint icons are dark yellow. + + + .. image:: watchpoint-icons.png + :alt: Screenshot highlighting the 3 types of watchpoint icons + :class: border + +4. Click **Play** or press :kbd:`F8` to resume execution. + + +View a watchpoint +***************** + +When the watched property is accessed in the way specified by the watchpoint type (get or set), the debugger pauses, enabling you to see line of code responsible, and to inspect anything else you wish at that time. + +In the following screenshot, the debugger pauses at line 7, where ``obj.a`` is set. The message panel in the upper right corner indicates that the debugger is "Paused on property set". + +.. image:: watchpoint_pause.png + :class: border + +Delete a watchpoint +******************* + +- Locate the watched property in the Scopes pane. +- Click the watchpoint icon, or right-click and choose **Remove watchpoint**. The watchpoint is removed. + +See also +******** + +- `Debugging variables with watchpoints in Firefox 72 <https://hacks.mozilla.org/2019/12/debugging-variables-with-watchpoints-in-firefox-72/>`_ diff --git a/devtools/docs/user/debugger/how_to/use_watchpoints/watchpoint-get-or-set.png b/devtools/docs/user/debugger/how_to/use_watchpoints/watchpoint-get-or-set.png Binary files differnew file mode 100644 index 0000000000..ddd349b393 --- /dev/null +++ b/devtools/docs/user/debugger/how_to/use_watchpoints/watchpoint-get-or-set.png diff --git a/devtools/docs/user/debugger/how_to/use_watchpoints/watchpoint-icons.png b/devtools/docs/user/debugger/how_to/use_watchpoints/watchpoint-icons.png Binary files differnew file mode 100644 index 0000000000..f6e97c04df --- /dev/null +++ b/devtools/docs/user/debugger/how_to/use_watchpoints/watchpoint-icons.png diff --git a/devtools/docs/user/debugger/how_to/use_watchpoints/watchpoint_pause.png b/devtools/docs/user/debugger/how_to/use_watchpoints/watchpoint_pause.png Binary files differnew file mode 100644 index 0000000000..df9e39a217 --- /dev/null +++ b/devtools/docs/user/debugger/how_to/use_watchpoints/watchpoint_pause.png diff --git a/devtools/docs/user/debugger/index.rst b/devtools/docs/user/debugger/index.rst new file mode 100644 index 0000000000..e67ff59412 --- /dev/null +++ b/devtools/docs/user/debugger/index.rst @@ -0,0 +1,70 @@ +=============================== +The Firefox JavaScript Debugger +=============================== + +The JavaScript Debugger enables you to step through JavaScript code and examine or modify its state to help track down bugs. + +.. raw:: html + + <iframe width="560" height="315" src="https://www.youtube.com/embed/QK4hKWmJVLo" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe> + <br/> + <br/> + + +You can use it to debug code running locally in Firefox or running remotely, for example on an Android device running Firefox for Android. See :doc:`about debugging <../about_colon_debugging/index>` to learn how to connect the debugger to a remote target. + +To find your way around the debugger, here's a :doc:`quick tour of the UI<ui_tour/index>`. + + +How to +****** + +To find out what you can do with the debugger, refer to the following how-to guides. + +- :doc:`Open the debugger <how_to/open_the_debugger/index>` +- :doc:`Pretty-print a minified file <how_to/pretty-print_a_minified_file/index>` +- :doc:`Search <how_to/search/index>` +- :doc:`Use a source map <how_to/use_a_source_map/index>` +- `Debug worker threads <https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Using_web_workers#debugging_worker_threads>`_ + + +Pause execution +--------------- + +You probably want to pause the execution of your code, in order to see what is going on at various points. There are multiple ways to tell the Debugger how and when to pause: + + +- :doc:`Set a breakpoint <how_to/set_a_breakpoint/index>` +- :doc:`Set a conditional breakpoint <how_to/set_a_conditional_breakpoint/index>` +- :doc:`Set an XHR breakpoint <set_an_xhr_breakpoint/index>` +- :doc:`Set event listener <set_event_listener_breakpoints/index>` +- :doc:`Break on exceptions <how_to/breaking_on_exceptions/index>` +- :doc:`Use watchpoints for property reads and writes <how_to/use_watchpoints/index>` +- :doc:`Break on DOM Mutation <break_on_dom_mutation/index>` +- :doc:`Disable breakpoints <how_to/disable_breakpoints/index>` + + +Control execution +----------------- + +What can you do after execution pauses? + +- :doc:`Step through code <how_to/step_through_code/index>` +- :doc:`Ignoring sources <how_to/ignoring_sources/index>` +- `Debug worker threads <https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Using_web_workers#debugging_worker_threads>`_ +- :doc:`Debug eval sources <how_to/debug_eval_sources/index>` + + +Look at values +-------------- + +You probably want to see the value of variables or expressions, either during execution or when it is paused. + +- :doc:`Set a logpoint <set_a_logpoint/index>` +- :doc:`Set watch expressions <how_to/set_watch_expressions/index>` + +Reference +********* + +- :ref:`Keyboard shortcuts <keyboard-shortcuts-debugger>` +- :doc:`Source map errors <source_map_errors/index>` diff --git a/devtools/docs/user/debugger/set_a_logpoint/add_logpoint.png b/devtools/docs/user/debugger/set_a_logpoint/add_logpoint.png Binary files differnew file mode 100644 index 0000000000..35d4630f4d --- /dev/null +++ b/devtools/docs/user/debugger/set_a_logpoint/add_logpoint.png diff --git a/devtools/docs/user/debugger/set_a_logpoint/creating_the_log_point.png b/devtools/docs/user/debugger/set_a_logpoint/creating_the_log_point.png Binary files differnew file mode 100644 index 0000000000..42ab3a6bcf --- /dev/null +++ b/devtools/docs/user/debugger/set_a_logpoint/creating_the_log_point.png diff --git a/devtools/docs/user/debugger/set_a_logpoint/index.rst b/devtools/docs/user/debugger/set_a_logpoint/index.rst new file mode 100644 index 0000000000..b8ecd4d56a --- /dev/null +++ b/devtools/docs/user/debugger/set_a_logpoint/index.rst @@ -0,0 +1,52 @@ +============== +Set a logpoint +============== + +Sometimes you want to view a value in your code but you don't want to pause execution. Rather than sprinkle `console.log() <https://developer.mozilla.org/en-US/docs/Web/API/console/log>`_ statements throughout your code, you can use a special type of breakpoint, the logpoint. Logpoints print a message to the Console panel instead of pausing code execution. + +The logpoint is especially useful in cases where breaking the execution breaks testing procedures, such as when you are debugging popup windows, or executing focus-related logic. + +To create a logpoint: + +1. Right click on a line number in the Debugger panel and pick **Add log** action from the context menu. + + .. image:: add_logpoint.png + :class: center + +2. Create an expression inline. The result is logged in the console panel every time the line with the logpoint executes. You can use any variable or function available in the current scope. + + .. image:: creating_the_log_point.png + :class: center + +Working with logpoints +********************** + +When you set a logpoint, the indicator is purple, rather than the blue of an unconditional breakpoint or the orange of a conditional breakpoint. + +You can view the list of logpoints in the Breakpoints side panel. + +.. image:: list_logpoints.png + :class: border + +When execution hits a logpoint, the message you have defined is logged to the console. You can make it easier to see the message by opening a split console under the debugger. (Either press :kbd:`Esc` or select the ellipsis menu (**...**) and then click **Show Split Console**.) + +.. image:: logpoints.png + :class: border + + +When should you use logpoints? +------------------------------ + +- When you want to know that a specific line in your code has executed, but you don’t want to break code execution, set a logpoint. +- Logpoints are useful to log the value of a variable at a specific point in the code. It’s faster than changing the underlying source code itself to add calls to the ``console.log`` method. +- If you need to execute additional logic related to the source code and you can’t change the source code itself, you can use a logpoint. +- Note that you can use logpoints with :doc:`source-mapped code <../using_the_debugger_map_scopes_feature/index>`, as well as with your unmapped source files. + + +See also +******** + +- :doc:`Set a breakpoint <../how_to/set_a_breakpoint/index>` +- :doc:`Set a conditional breakpoint <../how_to/set_a_conditional_breakpoint/index>` +- :doc:`Set an XHR breakpoint <../set_an_xhr_breakpoint/index>` +- :doc:`Disable breakpoints <../how_to/disable_breakpoints/index>` diff --git a/devtools/docs/user/debugger/set_a_logpoint/list_logpoints.png b/devtools/docs/user/debugger/set_a_logpoint/list_logpoints.png Binary files differnew file mode 100644 index 0000000000..bb7834fe09 --- /dev/null +++ b/devtools/docs/user/debugger/set_a_logpoint/list_logpoints.png diff --git a/devtools/docs/user/debugger/set_a_logpoint/logpoints.png b/devtools/docs/user/debugger/set_a_logpoint/logpoints.png Binary files differnew file mode 100644 index 0000000000..dc4891df1c --- /dev/null +++ b/devtools/docs/user/debugger/set_a_logpoint/logpoints.png diff --git a/devtools/docs/user/debugger/set_an_xhr_breakpoint/index.rst b/devtools/docs/user/debugger/set_an_xhr_breakpoint/index.rst new file mode 100644 index 0000000000..e831df49f1 --- /dev/null +++ b/devtools/docs/user/debugger/set_an_xhr_breakpoint/index.rst @@ -0,0 +1,33 @@ +===================== +Set an XHR breakpoint +===================== + +An XHR (XMLHttpRequest) breakpoint breaks code execution when an XHR request is dispatched so that you can examine the current state of the program. You can break on all requests or on those that include a specific URL. To turn on the feature: + +1. Open the debugger +2. Click on "Pause on any URL" which acts as a wild card, causing the code to pause on any call, or, +3. Click the plus sign next to the XHR breakpoints header, enter the URL in which you are interested, and press :kbd:`Enter`. + +.. note:: + + If you enter a key word instead of a URL, code execution will pause on any call to a URL that contains that keyword. + +.. image:: xhr_breakpoint.png + :class: border + +When your code breaks on an XHR request, the right hand pane will have two additional sections: + +**Call stack** + The list of functions that were executed in order to get to the currently executing code. Click on an item in the call stack to jump to the associated line in the code display. + +**Scopes** + A list of the values that are in scope in the function, method, or event handler where the break occurred. + +.. image:: xhr_break.png + :class: border + + +Inline variable preview +*********************** + +New in Firefox 71, the :ref:`source pane <debugger_ui_tour_source_pane>` now gives you an instant preview of the variables on each line of code you've stepped through. See :ref:`Set a breakpoint > Inline variable preview <debugger-how-to-set-a-breakpoint-variable-preview>` for more information. diff --git a/devtools/docs/user/debugger/set_an_xhr_breakpoint/xhr_break.png b/devtools/docs/user/debugger/set_an_xhr_breakpoint/xhr_break.png Binary files differnew file mode 100644 index 0000000000..3da3ad0a82 --- /dev/null +++ b/devtools/docs/user/debugger/set_an_xhr_breakpoint/xhr_break.png diff --git a/devtools/docs/user/debugger/set_an_xhr_breakpoint/xhr_breakpoint.png b/devtools/docs/user/debugger/set_an_xhr_breakpoint/xhr_breakpoint.png Binary files differnew file mode 100644 index 0000000000..ebdd338d39 --- /dev/null +++ b/devtools/docs/user/debugger/set_an_xhr_breakpoint/xhr_breakpoint.png diff --git a/devtools/docs/user/debugger/set_event_listener_breakpoints/event-listener-breakpoints.png b/devtools/docs/user/debugger/set_event_listener_breakpoints/event-listener-breakpoints.png Binary files differnew file mode 100644 index 0000000000..31775c92e0 --- /dev/null +++ b/devtools/docs/user/debugger/set_event_listener_breakpoints/event-listener-breakpoints.png diff --git a/devtools/docs/user/debugger/set_event_listener_breakpoints/filter-event-breakpoints.png b/devtools/docs/user/debugger/set_event_listener_breakpoints/filter-event-breakpoints.png Binary files differnew file mode 100644 index 0000000000..5a0a14a332 --- /dev/null +++ b/devtools/docs/user/debugger/set_event_listener_breakpoints/filter-event-breakpoints.png diff --git a/devtools/docs/user/debugger/set_event_listener_breakpoints/index.rst b/devtools/docs/user/debugger/set_event_listener_breakpoints/index.rst new file mode 100644 index 0000000000..b087ba903a --- /dev/null +++ b/devtools/docs/user/debugger/set_event_listener_breakpoints/index.rst @@ -0,0 +1,72 @@ +============================== +Set event listener breakpoints +============================== + +Starting with Firefox 69, debugging an application that includes event handlers is simplified because the debugger now includes the ability to automatically break when the code hits an event handler. This article explains how to use it. + +Using a standard event breakpoint +********************************* + +To use an event breakpoint, you open up the JavaScript debugger, and find and expand the Event Listener Breakpoints section in the right hand column. + +.. image:: event-listener-breakpoints.png + :alt: The list of event listener breakpoints in the right hand column + :class: border + +To break when event listeners are hit, check the boxes next the events you are interested in. All of the standard events supported in your version of Firefox are listed, arranged by which API or API area they're part of. + +Now when a `keydown <https://developer.mozilla.org/en-US/docs/Web/API/Document/keydown_event>`_, `keyup <https://developer.mozilla.org/en-US/docs/Web/API/Document/keyup_event>`_, `keypress <https://developer.mozilla.org/en-US/docs/Web/API/Document/keypress_event>`_, or `input <https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/input_event>`_ event occurs, execution will pause as soon as it enters the listener code. + +.. image:: paused-on-breakpoint.png + :alt: execution is paused on an event breakpoint and the source panel shows what line it is paused on + :class: border + +When execution pauses, the :ref:`source pane <debugger_ui_tour_source_pane>` displays the highlighted line of the JavaScript code that is next to be executed, along with the surrounding code for context. In addition, you get a box overlaid on the viewport saying "Paused on event breakpoint", with buttons to step over that line of code or resume execution. + +You *could* add regular breakpoints at the entry point of the listener to achieve the same effect. If however you have multiple elements, all of which have event listeners attached that you want to break on, this becomes an enormous time saver. + +This is also useful when debugging code that you're unfamiliar with, to save time over hunting down your event handler within your code, or when trying to understand why a web site isn't working as expected in your browser. Use event breakpoints to stop execution at the triggering event for the action that fails, then step through the code or watch the console to see what happens. + +Logging on events +***************** + +In Firefox 71 onwards, the “Log” checkbox is available in the *Event Listener Breakpoints* list. Selecting this and then choosing some events to break on will mean that when you step through code, information about events fired will be logged to the console instead of the DevTools breaking on each one. + +So if we choose to log keyboard events, for example, the code no longer pauses as each event is fired: + +.. image:: log-events-1.png + :alt: log on events checkbox + :class: border + + +Instead, we can then switch to the console, and whenever we press a key we are given a log of where related events were fired. + +.. image:: log-events-2.png + :alt: events logged in console + + +There's an issue here — the console is showing that the `keypress event <https://developer.mozilla.org/en-US/docs/Web/API/Document/keypress_event>`_ is being fired somewhere inside jQuery. Instead, it’d be far more useful if we showed where in our own app code is calling the jQuery that fired the event. This can be done by finding ``jquery.js`` in the Sources panel, and choosing the **Ignore source option** from its context menu. + +.. image:: log-events-3.png + :alt: blackbox jquery source + :class: border + +Now the logs will show where in your app jQuery was called, rather than where in jQuery the event was fired: + +.. image:: log-events-4.png + :alt: events logged in console with lines shown where our source calls jQuery. + :class: border + +Filter by event type +******************** + +Also added to Firefox 71 is a new *Filter by event type...* text input, which can also be found at the top of the *Event Listener Breakpoints* list. When you click in this input and type a search term, the list of event listener types will filter by that term allowing you to find the events you want to break on more easily. + +.. image:: filter-event-breakpoints.png + :class: border + + +Inline variable preview +*********************** + +New in Firefox 71, the :ref:`source pane <debugger_ui_tour_source_pane>` now gives you an instant preview of the variables on each line of code you've stepped through. See :ref:`Set a breakpoint > Inline variable preview <debugger-how-to-set-a-breakpoint-variable-preview>` for more information. diff --git a/devtools/docs/user/debugger/set_event_listener_breakpoints/log-events-1.png b/devtools/docs/user/debugger/set_event_listener_breakpoints/log-events-1.png Binary files differnew file mode 100644 index 0000000000..60cf92cd78 --- /dev/null +++ b/devtools/docs/user/debugger/set_event_listener_breakpoints/log-events-1.png diff --git a/devtools/docs/user/debugger/set_event_listener_breakpoints/log-events-2.png b/devtools/docs/user/debugger/set_event_listener_breakpoints/log-events-2.png Binary files differnew file mode 100644 index 0000000000..323847b740 --- /dev/null +++ b/devtools/docs/user/debugger/set_event_listener_breakpoints/log-events-2.png diff --git a/devtools/docs/user/debugger/set_event_listener_breakpoints/log-events-3.png b/devtools/docs/user/debugger/set_event_listener_breakpoints/log-events-3.png Binary files differnew file mode 100644 index 0000000000..de94a8d9ee --- /dev/null +++ b/devtools/docs/user/debugger/set_event_listener_breakpoints/log-events-3.png diff --git a/devtools/docs/user/debugger/set_event_listener_breakpoints/log-events-4.png b/devtools/docs/user/debugger/set_event_listener_breakpoints/log-events-4.png Binary files differnew file mode 100644 index 0000000000..26c69aa3e4 --- /dev/null +++ b/devtools/docs/user/debugger/set_event_listener_breakpoints/log-events-4.png diff --git a/devtools/docs/user/debugger/set_event_listener_breakpoints/paused-on-breakpoint.png b/devtools/docs/user/debugger/set_event_listener_breakpoints/paused-on-breakpoint.png Binary files differnew file mode 100644 index 0000000000..ea42ec5dbe --- /dev/null +++ b/devtools/docs/user/debugger/set_event_listener_breakpoints/paused-on-breakpoint.png diff --git a/devtools/docs/user/debugger/source_map_errors/debugger-tab.png b/devtools/docs/user/debugger/source_map_errors/debugger-tab.png Binary files differnew file mode 100644 index 0000000000..869db51aac --- /dev/null +++ b/devtools/docs/user/debugger/source_map_errors/debugger-tab.png diff --git a/devtools/docs/user/debugger/source_map_errors/index.rst b/devtools/docs/user/debugger/source_map_errors/index.rst new file mode 100644 index 0000000000..d657faa433 --- /dev/null +++ b/devtools/docs/user/debugger/source_map_errors/index.rst @@ -0,0 +1,81 @@ +================= +Source map errors +================= + +Source maps are JSON files providing a way to associate transformed sources, as seen by the browser, with their original sources, as written by the developer. You can sometimes encounter problems working with source maps. This page explains the most common problems and how to fix them. + +.. note:: + + If you're new to source maps, you can learn more about them in :doc:`How to use a source map <../how_to/use_a_source_map/index>`. + + +General source map error reporting +********************************** + +If you do see a problem, a message will appear in the webconsole. This message will show an error message, the resource URL, and the source map URL: + +.. image:: invalid-json.png + :alt: Error from invalid JSON + :class: border + +Here, the resource URL tells us that ``bundle.js`` mentions a source map, and the source map URL tells us where to find the source map data (in this case, relative to the resource). The error tells us that the source map is not JSON data — so we're serving the wrong file. + +There are a few common ways that source maps can go wrong; they are detailed in the following sections. + + +Source map missing or inaccessible +********************************** + +The source map resource can be missing or inaccessible. + +.. image:: missing-map.png + :alt: Source map file is missing + :class: border + +The fix here is to make sure the file is being served and is accessible to the browser + + +Invalid source map +****************** + +The source map data can be invalid — either not a JSON file at all, or with an incorrect structure. Typical error messages here are: + + +- ``SyntaxError: JSON.parse: unexpected character at line 1 column 1 of the JSON data`` +- ``Error: "version" is a required argument`` + +.. image:: missing-field.png + :class: border + :alt: Error: "version" is a required argument + + +Original source missing +*********************** + +An original source may be missing. You may encounter this when trying to open one of the original sources in the debugger. The message looks a little different in this case: + +.. image:: screenshot_from_2017-09-15_14-32-02.png + :alt: Debugger source tab showing the error + :class: border + + +In this case, the error will also be displayed in the source tab in the debugger: + +.. image:: debugger-tab.png + :alt: Debugger source tab showing the error + :class: border + + +NetworkError when attempting to fetch resource +********************************************** + +A bug in Firefox prevents it from loading source maps for WebExtensions. + +See `Bug 1437937: WebExtensions Doesn't Find Source Maps <https://bugzilla.mozilla.org/show_bug.cgi?id=1437937>`_ for details. + +.. code-block: html + Source-Map-Fehler: TypeError: NetworkError when attempting to fetch resource. + Ressourcen-Adresse: moz-extension://c7f0f003-4fcf-49fd-8ec0-c49361266581/background.js + Source-Map-Adresse: background.js.map</pre> + +The only workaround is to manually change the map URL to a public one (http://localhost:1234/file.map.js) and start a local webserver at this port. diff --git a/devtools/docs/user/debugger/source_map_errors/invalid-json.png b/devtools/docs/user/debugger/source_map_errors/invalid-json.png Binary files differnew file mode 100644 index 0000000000..6d47d35325 --- /dev/null +++ b/devtools/docs/user/debugger/source_map_errors/invalid-json.png diff --git a/devtools/docs/user/debugger/source_map_errors/missing-field.png b/devtools/docs/user/debugger/source_map_errors/missing-field.png Binary files differnew file mode 100644 index 0000000000..bece5fd7ca --- /dev/null +++ b/devtools/docs/user/debugger/source_map_errors/missing-field.png diff --git a/devtools/docs/user/debugger/source_map_errors/missing-map.png b/devtools/docs/user/debugger/source_map_errors/missing-map.png Binary files differnew file mode 100644 index 0000000000..8d8ad7db4b --- /dev/null +++ b/devtools/docs/user/debugger/source_map_errors/missing-map.png diff --git a/devtools/docs/user/debugger/source_map_errors/screenshot_from_2017-09-15_14-32-02.png b/devtools/docs/user/debugger/source_map_errors/screenshot_from_2017-09-15_14-32-02.png Binary files differnew file mode 100644 index 0000000000..f71030fd7a --- /dev/null +++ b/devtools/docs/user/debugger/source_map_errors/screenshot_from_2017-09-15_14-32-02.png diff --git a/devtools/docs/user/debugger/ui_tour/debugger-source-folder-cxt-menu.png b/devtools/docs/user/debugger/ui_tour/debugger-source-folder-cxt-menu.png Binary files differnew file mode 100644 index 0000000000..8e49ffe00f --- /dev/null +++ b/devtools/docs/user/debugger/ui_tour/debugger-source-folder-cxt-menu.png diff --git a/devtools/docs/user/debugger/ui_tour/debugger-source-list-cxt-menu.png b/devtools/docs/user/debugger/ui_tour/debugger-source-list-cxt-menu.png Binary files differnew file mode 100644 index 0000000000..df837ac5ba --- /dev/null +++ b/devtools/docs/user/debugger/ui_tour/debugger-source-list-cxt-menu.png diff --git a/devtools/docs/user/debugger/ui_tour/debugger_scopes_fx78.png b/devtools/docs/user/debugger/ui_tour/debugger_scopes_fx78.png Binary files differnew file mode 100644 index 0000000000..bf99b6c010 --- /dev/null +++ b/devtools/docs/user/debugger/ui_tour/debugger_scopes_fx78.png diff --git a/devtools/docs/user/debugger/ui_tour/debugger_toolbar_with_settings_menu_four_items.jpg b/devtools/docs/user/debugger/ui_tour/debugger_toolbar_with_settings_menu_four_items.jpg Binary files differnew file mode 100644 index 0000000000..9c4c7ff5b8 --- /dev/null +++ b/devtools/docs/user/debugger/ui_tour/debugger_toolbar_with_settings_menu_four_items.jpg diff --git a/devtools/docs/user/debugger/ui_tour/debugger_uitour_01.png b/devtools/docs/user/debugger/ui_tour/debugger_uitour_01.png Binary files differnew file mode 100644 index 0000000000..2c2e57c256 --- /dev/null +++ b/devtools/docs/user/debugger/ui_tour/debugger_uitour_01.png diff --git a/devtools/docs/user/debugger/ui_tour/debugger_uitour_02.5.png b/devtools/docs/user/debugger/ui_tour/debugger_uitour_02.5.png Binary files differnew file mode 100644 index 0000000000..becf3b7221 --- /dev/null +++ b/devtools/docs/user/debugger/ui_tour/debugger_uitour_02.5.png diff --git a/devtools/docs/user/debugger/ui_tour/debugger_uitour_02.png b/devtools/docs/user/debugger/ui_tour/debugger_uitour_02.png Binary files differnew file mode 100644 index 0000000000..bdede32e71 --- /dev/null +++ b/devtools/docs/user/debugger/ui_tour/debugger_uitour_02.png diff --git a/devtools/docs/user/debugger/ui_tour/debugger_uitour_03.png b/devtools/docs/user/debugger/ui_tour/debugger_uitour_03.png Binary files differnew file mode 100644 index 0000000000..ddb14442e3 --- /dev/null +++ b/devtools/docs/user/debugger/ui_tour/debugger_uitour_03.png diff --git a/devtools/docs/user/debugger/ui_tour/debugger_uitour_breakpoints.png b/devtools/docs/user/debugger/ui_tour/debugger_uitour_breakpoints.png Binary files differnew file mode 100644 index 0000000000..5f44a76ccf --- /dev/null +++ b/devtools/docs/user/debugger/ui_tour/debugger_uitour_breakpoints.png diff --git a/devtools/docs/user/debugger/ui_tour/debugger_uitour_call_stack.png b/devtools/docs/user/debugger/ui_tour/debugger_uitour_call_stack.png Binary files differnew file mode 100644 index 0000000000..084b4c3bbf --- /dev/null +++ b/devtools/docs/user/debugger/ui_tour/debugger_uitour_call_stack.png diff --git a/devtools/docs/user/debugger/ui_tour/ff_debugger_callstack_ignore_source.png b/devtools/docs/user/debugger/ui_tour/ff_debugger_callstack_ignore_source.png Binary files differnew file mode 100644 index 0000000000..839eb35f31 --- /dev/null +++ b/devtools/docs/user/debugger/ui_tour/ff_debugger_callstack_ignore_source.png diff --git a/devtools/docs/user/debugger/ui_tour/firefox_source_pane_context_menu.jpg b/devtools/docs/user/debugger/ui_tour/firefox_source_pane_context_menu.jpg Binary files differnew file mode 100644 index 0000000000..9a6f2c6a09 --- /dev/null +++ b/devtools/docs/user/debugger/ui_tour/firefox_source_pane_context_menu.jpg diff --git a/devtools/docs/user/debugger/ui_tour/index.rst b/devtools/docs/user/debugger/ui_tour/index.rst new file mode 100644 index 0000000000..7d7f149e2d --- /dev/null +++ b/devtools/docs/user/debugger/ui_tour/index.rst @@ -0,0 +1,235 @@ +======= +UI Tour +======= + +This article is a quick tour of the main sections of the JavaScript Debugger's user interface. The UI is split vertically into three panels + + +- :ref:`Source list pane <debugger-ui-tour-source-list-pane>` +- :ref:`Source pane <debugger_ui_tour_source_pane>` +- The contents of the third pane depend on the current state of the debugger and may include the following sections: + + - :ref:`Toolbar <debugger-ui-tour-toolbar>` + - Watch expressions + - :ref:`Breakpoints <debugger-ui-tour-breakpoints-list>` + - :ref:`Call stack <debugger-ui-tour-call-stack>` + - :ref:`Scopes <debugger-ui-tour-scopes>` + - XHR Breakpoints + - Event Listener Breakpoints + - DOM Mutation Breakpoints + +.. image:: debugger_uitour_01.png + :class: border + + +.. _debugger-ui-tour-source-list-pane: + +Source list pane +**************** + +The source list pane lists all the JavaScript source files loaded into the page (`including scripts for active web workers <https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Using_web_workers#debugging_worker_threads>`_), and enables you to select one to debug. At the top level sources are organized by origin, and under that they're organized by the directory structure from which they are served. + +.. image:: debugger_uitour_02.png + :class: border + +You can :ref:`search for a file <debugger-how-to-search-searching-for-files>` using :kbd:`Ctrl` + :kbd:`P` (:kbd:`Cmd` + :kbd:`P` on a Mac). + +WebExtensions are listed in the Source List pane using the extension's name. + +.. image:: source_list_pane.png + :class: border + +There are several context menu options available for individual files and folders or groups; typically viewed by right-clicking on the item. + +For files, the following context menu options are available: + +.. image:: debugger-source-list-cxt-menu.png + :alt: Screenshot showing the context menu options for files in the source list pane + :class: border + + +- **Copy source URI** copies the full identifier of the file to the clipboard. +- **Ignore source** causes the debugger to skip the file when "stepping into" functions; this can be helpful for avoiding stepping into libraries used by your code. When a file is ignored, it has a small eye icon next to it in place of its regular icon. +- **Download file** opens a file dialog so you can save the file locally. + + +For folders and groups, the following context menu options are available: + +.. image:: debugger-source-folder-cxt-menu.png + :alt: Screenshot showing context menu options for folders in the source list pane + :class: border + + +- **Collapse all** collapses all subfolders of the item. +- **Expand all** expands all subfolders of the item. +- **Set directory root** changes the Source List view so that only that item and its children are visible. The name of the selected directory is shown at the top of the Source List pane; clicking this name reverts the pane to showing all source items. +- **Ignore** (since Firefox 76) + + - **Ignore files in this directory** causes all files within the selected directory to be skipped by the debugger. All child files acquired the eye icon, and the folder menu option changes to **Unignore files in this directory**. + - **Ignore files outside this directory** causes all files other than those within the selected directory to be skipped by the debugger. All such files acquire the eye icon, and the menu option for that folder changes to **Unignore files outside this directory**. + + +Outline View +------------ + +The Outline view shows a tree for navigating the currently open file. Use it to jump directly to a function, class or method definition. + + +.. _debugger_ui_tour_source_pane: + +Source pane +*********** + +This shows the JavaScript file currently loaded. + +.. image:: debugger_uitour_02.5.png + :class: border + +When the source pane is focused you can :ref:`search for a string in the file <debugger-how-to-search-searching-within-a-file>` using :kbd:`Ctrl` + :kbd:`F` (:kbd:`Cmd` + :kbd:`F` on a Mac). + +:doc:`Breakpoints <../how_to/set_a_breakpoint/index>` have a blue arrow overlaid on the line number. :doc:`Conditional breakpoints <../how_to/set_a_conditional_breakpoint/index>` have an orange arrow. If you're stopped at a breakpoint, the entire line gets a green overlay. In the screenshot below there are three breakpoints: + + +- line 82 has a normal breakpoint and execution is paused here +- line 85 has a logpoint which logs the contents of table row to the console +- line 100 has a conditional breakpoint + +.. image:: debugger_uitour_03.png + :class: border + +The third column shows more information about the breakpoints. For example, the logpoint at line 85 logs the value of the tableRow variable to the console and the conditional breakpoint at line 100 breaks if the contents of the todoList is undefined. + +The source pane provides the following context menu options: + +.. image:: firefox_source_pane_context_menu.jpg + :alt: Debugger Source Pane Context Menu v2 + :class: center + + +- **Jump to generated location** is used when you have a sourcemap in a project and are currently viewing the original file. Selecting it takes you to the generated file where the selected item was placed. +- **Continue to here** causes the debugger to continue execution to the currently selected line (execution will stop before it gets there if there is a breakpoint "on the way"). +- **Copy to clipboard** copies selected text in the pane into the system clipboard. +- **Copy source text** copies all text in the file into the clipboard. +- **Copy source URI** copies the file location into the clipboard. +- **Download file** opens a file dialog so you can save the file locally. +- **Reveal in tree** highlights the file in the source pane list hierarchy. +- **Ignore source** causes the debugger to skip the file when "stepping into" functions; this can be helpful for avoiding stepping into libraries used by your code. +- **Show inline preview** toggles the inline preview feature, which displays the value of the variable right next to the source when execution is paused. +- **Wrap lines**/**Unwap lines** toggles the wrapping of long lines in the pane. + + +.. _debugger-ui-tour-toolbar: + +Toolbar +******* + +At the top of the right-hand pane, there's a toolbar: + +.. image:: debugger_toolbar_with_settings_menu_four_items.jpg + :class: center + +The toolbar consists of: + +- Four buttons to :doc:`control the debugger's movement through the script <../how_to/step_through_code/index>`: + + - **Play/pause** (:kbd:`F8`): pauses or resumes execution of the script you're debugging. When it displays a "play" icon, that means the script is paused, either because you've paused it with this button or because you've hit a breakpoint. + - **Step over** (:kbd:`F10`): steps to the next line of JavaScript code. + - **Step in** (:kbd:`F11`): steps into the function call on the current line of JavaScript code. + - **Step out** (:kbd:`Shift`-:kbd:`F11`): runs the script until the current function exits. + + +- A button that deactivates all breakpoints. +- A settings menu that contains: + + - **Disable JavaScript**: disables JavaScript for this tab. This option enables you to see how your web page looks if the user has disabled JavaScript via an extension or a configuration setting. The setting is reset when the Developer Tools are closed (except in Firefox 77, see `bug 1640318 <https://bugzilla.mozilla.org/show_bug.cgi?id=1640318>`_). + - **Inline Variable Preview**: enabled by default, this option displays variable values within the source pane when the debugger is paused. + - **Wrap Lines**: Toggles wrapping of long lines in the :ref:`source pane <debugger_ui_tour_source_pane>`. + - **Source Maps**: enabled by default, this option directs the Debugger to load the original versions of files, and map them to the generated ones loaded in a page, to ease debugging of transformed sources. See :doc:`Use a source map <../how_to/use_a_source_map/index>` for details. + + +.. _debugger-ui-tour-breakpoints-list: + +Breakpoints list +**************** + +Under the toolbar, you'll see all the breakpoints you've set. Next to each breakpoint is a checkbox which you can use to :doc:`enable/disable it <../how_to/disable_breakpoints/index>`: + +.. image:: debugger_uitour_breakpoints.png + :class: border + + +Watch expressions +***************** + +You can add watch expressions in the right pane. They will be evaluated when code execution is paused: + +.. image:: watch-expressions.png + :class: center + + +Variable tooltip +**************** + +Hover on a variable show a tooltip with its value inside: + +.. image:: tooltip-1.gif + :class: center + + +.. _debugger-ui-tour-call-stack: + +Call stack +********** + +The *call stack* becomes visible when the debugger is paused. + +.. image:: debugger_uitour_call_stack.png + :class: border + + +The stack lists the chain of functions that are waiting to complete, with the frame for the function that was called last at the top (i.e. the most deeply nested function).Selecting a line opens the associated file in the source pane, at the specified location. It also updates the :ref:`Scopes <debugger-ui-tour-scopes>` section with the variables for that frame/scope. + +.. note:: + + The call stack is a useful tool for tracking execution flow through your application! It allows you to confirm that functions are called in the order you expect, and with sensible variable values. + + +Call stack lines for frames in your own code show the function name and the file location in which it was called. + +.. note:: + + If you click **Step over** (:kbd:`F10`) after changing the selected line in the source pane, the debugger executes until reaching the line following the newly-selected line (disregarding whatever line the debugger originally stopped at). + + +Lines for JavaScript frameworks/libraries *used* by your code (React, jQuery, Angular, Webpack, Backbone etc.) are grouped by default,and represented by a framework-specific icon (see the *jQuery* frame in the screenshot above).Generally you won't want to debug into the code of frameworks or libraries, so grouping these reduces the complexity of the call stack list. You can still expand and inspect the grouped frames if needed, or disableframework grouping using a context menu option: **Disable framework grouping**. + +You can also use the context menu to **Ignore source** for a particular line. This will remove the line from the call stack, and the debugger will subsequently skip through any calls into that file. Note that you'll have to use the source pane "eye icon" or source list if you want to *Unignore* the source later! + +.. image:: ff_debugger_callstack_ignore_source.png + :alt: FF Debugger showing callstack with right-menu and marked up unignore/ignore source "eye" + :class: border + +Right-/Ctrl- clicking in the call stack pane opens a context menu with the following items: + + +- **Restart frame** restarts execution at the beginning of the current frame. +- **Enable framework grouping** collects items belonging to a framework into a collapsible group (for example, Webpack in the screenshot immediately above). When grouping is enabled, the menu option changes to **Disable framework grouping**. +- **Copy source URI** copies the full identifier of the source file to the clipboard. +- **Ignore source** causes the debugger to skip the file when "stepping into" functions. Any stack frames from the ignored source file are hidden in the call stack pane. (To remove this restriction, choose **Unignore source** in the context menu of the Sources list or the Source pane.) +- **Copy stack trace** copies all items in the call stack (including their URIs and line number) to the clipboard. + + +.. _debugger-ui-tour-scopes: + +Scopes +****** + +In the right-hand pane you'll see a label "Scopes" with a disclosure arrow next to it. When the debugger's paused, you'll be able to expand this section to see all objects that are in scope at this point in the program: + +.. image:: debugger_scopes_fx78.png + :alt: A screenshot of the Debugger, with the Scopes pane highlighted + :class: border + +Objects are organized by scope: the most local appears first, and the global scope (Window, in the case of page scripts) appears last. + +Within the Scopes pane, you can create :doc:`watchpoints <../how_to/use_watchpoints/index>` that pause the debugger when a value is read or assigned. diff --git a/devtools/docs/user/debugger/ui_tour/source_list_pane.png b/devtools/docs/user/debugger/ui_tour/source_list_pane.png Binary files differnew file mode 100644 index 0000000000..8d31cbc3a2 --- /dev/null +++ b/devtools/docs/user/debugger/ui_tour/source_list_pane.png diff --git a/devtools/docs/user/debugger/ui_tour/tooltip-1.gif b/devtools/docs/user/debugger/ui_tour/tooltip-1.gif Binary files differnew file mode 100644 index 0000000000..c3f24431b7 --- /dev/null +++ b/devtools/docs/user/debugger/ui_tour/tooltip-1.gif diff --git a/devtools/docs/user/debugger/ui_tour/watch-expressions.png b/devtools/docs/user/debugger/ui_tour/watch-expressions.png Binary files differnew file mode 100644 index 0000000000..eabace5088 --- /dev/null +++ b/devtools/docs/user/debugger/ui_tour/watch-expressions.png diff --git a/devtools/docs/user/debugger/using_the_debugger_map_scopes_feature/debugger_map_scope.png b/devtools/docs/user/debugger/using_the_debugger_map_scopes_feature/debugger_map_scope.png Binary files differnew file mode 100644 index 0000000000..ab769339e4 --- /dev/null +++ b/devtools/docs/user/debugger/using_the_debugger_map_scopes_feature/debugger_map_scope.png diff --git a/devtools/docs/user/debugger/using_the_debugger_map_scopes_feature/index.rst b/devtools/docs/user/debugger/using_the_debugger_map_scopes_feature/index.rst new file mode 100644 index 0000000000..c48d56f0e4 --- /dev/null +++ b/devtools/docs/user/debugger/using_the_debugger_map_scopes_feature/index.rst @@ -0,0 +1,29 @@ +===================================== +Using the Debugger map scopes feature +===================================== + +This feature is useful when debugging source-mapped code. It enables you to see the variables from the original source. It’s also possible to inspect variables from the generated scopes (e.g., a bundle file with all concatenated module files). + +Let's take a look at how this works. If you want to follow along, use `this example <https://firefox-dev.tools/debugger-examples/examples/increment/>`_. + +1. Open the `example page <https://firefox-dev.tools/debugger-examples/examples/increment/>`_ and then open the debugger using **Tools > Web Developer > Debugger** (or press :kbd:`Ctrl` + :kbd:`I` and then select the debugger). + +2. Select the "bundle.js" file in the Sources panel on the left and then set a breakpoint at line 102 in the ``increment`` function. + +3. When you click the **increment** button on the page and hit the breakpoint, an additional section is added to the right-hand panel below the Call stack to display variables mapped from the original scope, like this: + + + .. image:: debugger_map_scope.png + :class: border + +4. As useful as this is, it would be even nicer if you could view the original code (before it was packages into the "bundle.js" file. Right-click on the source code and the context menu now includes an option to **Jump to original location** as shown below. + + .. image:: map_scopes_context_menu.png + :class: border + +5. Click **Jump to original location**. The debugger opens the file "increment.js" so you can view the original code. Notice that your breakpoint is set here in the original code as it was in the corresponding line in the "bundle.js" file. And, since Map has been checked in the Scopes panel, you also see variable symbols from the original code. + + .. image:: map_scopes_original_code.png + :class: border + +Using this feature is expensive in terms of resources, but it certainly makes your life easier when you have to debug source code that has been packaged webpack or a similar tool. diff --git a/devtools/docs/user/debugger/using_the_debugger_map_scopes_feature/map_scopes_context_menu.png b/devtools/docs/user/debugger/using_the_debugger_map_scopes_feature/map_scopes_context_menu.png Binary files differnew file mode 100644 index 0000000000..ee235f7e00 --- /dev/null +++ b/devtools/docs/user/debugger/using_the_debugger_map_scopes_feature/map_scopes_context_menu.png diff --git a/devtools/docs/user/debugger/using_the_debugger_map_scopes_feature/map_scopes_original_code.png b/devtools/docs/user/debugger/using_the_debugger_map_scopes_feature/map_scopes_original_code.png Binary files differnew file mode 100644 index 0000000000..2dc8e558fa --- /dev/null +++ b/devtools/docs/user/debugger/using_the_debugger_map_scopes_feature/map_scopes_original_code.png |
