index.rst (12191B)
1 ======= 2 UI Tour 3 ======= 4 5 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 6 7 8 - :ref:`Source list pane <debugger-ui-tour-source-list-pane>` 9 - :ref:`Source pane <debugger_ui_tour_source_pane>` 10 - The contents of the third pane depend on the current state of the debugger and may include the following sections: 11 12 - :ref:`Toolbar <debugger-ui-tour-toolbar>` 13 - Watch expressions 14 - :ref:`Breakpoints <debugger-ui-tour-breakpoints-list>` 15 - :ref:`Call stack <debugger-ui-tour-call-stack>` 16 - :ref:`Scopes <debugger-ui-tour-scopes>` 17 - XHR Breakpoints 18 - Event Listener Breakpoints 19 - DOM Mutation Breakpoints 20 21 .. image:: debugger_uitour_01.png 22 :class: border 23 24 25 .. _debugger-ui-tour-source-list-pane: 26 27 Source list pane 28 **************** 29 30 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. 31 32 .. image:: debugger_uitour_02.png 33 :class: border 34 35 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). 36 37 WebExtensions are listed in the Source List pane using the extension's name. 38 39 .. image:: source_list_pane.png 40 :class: border 41 42 There are several context menu options available for individual files and folders or groups; typically viewed by right-clicking on the item. 43 44 For files, the following context menu options are available: 45 46 .. image:: debugger-source-list-cxt-menu.png 47 :alt: Screenshot showing the context menu options for files in the source list pane 48 :class: border 49 50 51 - **Copy source URI** copies the full identifier of the file to the clipboard. 52 - **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. 53 - **Download file** opens a file dialog so you can save the file locally. 54 55 56 For folders and groups, the following context menu options are available: 57 58 .. image:: debugger-source-folder-cxt-menu.png 59 :alt: Screenshot showing context menu options for folders in the source list pane 60 :class: border 61 62 63 - **Collapse all** collapses all subfolders of the item. 64 - **Expand all** expands all subfolders of the item. 65 - **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. 66 - **Ignore** 67 68 - **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**. 69 - **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**. 70 71 72 Outline View 73 ------------ 74 75 The Outline view shows a tree for navigating the currently open file. Use it to jump directly to a function, class or method definition. 76 77 78 .. _debugger_ui_tour_source_pane: 79 80 Source pane 81 *********** 82 83 This shows the JavaScript file currently loaded. 84 85 .. image:: debugger_uitour_02.5.png 86 :class: border 87 88 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). 89 90 :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: 91 92 93 - line 82 has a normal breakpoint and execution is paused here 94 - line 85 has a logpoint which logs the contents of table row to the console 95 - line 100 has a conditional breakpoint 96 97 .. image:: debugger_uitour_03.png 98 :class: border 99 100 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. 101 102 The source pane provides the following context menu options: 103 104 .. image:: firefox_source_pane_context_menu.jpg 105 :alt: Debugger Source Pane Context Menu v2 106 :class: center 107 108 109 - **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. 110 - **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"). 111 - **Copy to clipboard** copies selected text in the pane into the system clipboard. 112 - **Copy source text** copies all text in the file into the clipboard. 113 - **Copy source URI** copies the file location into the clipboard. 114 - **Download file** opens a file dialog so you can save the file locally. 115 - **Reveal in tree** highlights the file in the source pane list hierarchy. 116 - **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. 117 - **Show inline preview** toggles the inline preview feature, which displays the value of the variable right next to the source when execution is paused. 118 - **Wrap lines**/**Unwap lines** toggles the wrapping of long lines in the pane. 119 120 121 .. _debugger-ui-tour-toolbar: 122 123 Toolbar 124 ******* 125 126 At the top of the right-hand pane, there's a toolbar: 127 128 .. image:: debugger_toolbar_with_settings_menu_four_items.jpg 129 :class: center 130 131 The toolbar consists of: 132 133 - Four buttons to :doc:`control the debugger's movement through the script <../how_to/step_through_code/index>`: 134 135 - **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. 136 - **Step over** (:kbd:`F10`): steps to the next line of JavaScript code. 137 - **Step in** (:kbd:`F11`): steps into the function call on the current line of JavaScript code. 138 - **Step out** (:kbd:`Shift`-:kbd:`F11`): runs the script until the current function exits. 139 140 141 - A button that deactivates all breakpoints. 142 - A settings menu that contains: 143 144 - **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. 145 - **Inline Variable Preview**: enabled by default, this option displays variable values within the source pane when the debugger is paused. 146 - **Wrap Lines**: Toggles wrapping of long lines in the :ref:`source pane <debugger_ui_tour_source_pane>`. 147 - **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. 148 149 150 .. _debugger-ui-tour-breakpoints-list: 151 152 Breakpoints list 153 **************** 154 155 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>`: 156 157 .. image:: debugger_uitour_breakpoints.png 158 :class: border 159 160 161 Watch expressions 162 ***************** 163 164 You can add watch expressions in the right pane. They will be evaluated when code execution is paused: 165 166 .. image:: watch-expressions.png 167 :class: center 168 169 170 Variable tooltip 171 **************** 172 173 Hover on a variable show a tooltip with its value inside: 174 175 .. image:: tooltip-1.gif 176 :class: center 177 178 179 .. _debugger-ui-tour-call-stack: 180 181 Call stack 182 ********** 183 184 The *call stack* becomes visible when the debugger is paused. 185 186 .. image:: debugger_uitour_call_stack.png 187 :class: border 188 189 190 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. 191 192 .. note:: 193 194 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. 195 196 197 Call stack lines for frames in your own code show the function name and the file location in which it was called. 198 199 .. note:: 200 201 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). 202 203 204 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**. 205 206 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! 207 208 .. image:: ff_debugger_callstack_ignore_source.png 209 :alt: FF Debugger showing callstack with right-menu and marked up unignore/ignore source "eye" 210 :class: border 211 212 Right-/Ctrl- clicking in the call stack pane opens a context menu with the following items: 213 214 215 - **Restart frame** restarts execution at the beginning of the current frame. 216 - **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**. 217 - **Copy source URI** copies the full identifier of the source file to the clipboard. 218 - **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.) 219 - **Copy stack trace** copies all items in the call stack (including their URIs and line number) to the clipboard. 220 221 222 .. _debugger-ui-tour-scopes: 223 224 Scopes 225 ****** 226 227 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: 228 229 .. image:: debugger_scopes_fx78.png 230 :alt: A screenshot of the Debugger, with the Scopes pane highlighted 231 :class: border 232 233 Objects are organized by scope: the most local appears first, and the global scope (Window, in the case of page scripts) appears last. 234 235 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.