diff options
Diffstat (limited to 'devtools/docs/user/debugger/how_to')
49 files changed, 579 insertions, 0 deletions
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..e70de5391a --- /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 re-use 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 |
