diff options
Diffstat (limited to 'devtools/docs/user')
655 files changed, 15810 insertions, 0 deletions
diff --git a/devtools/docs/user/3d_view/3dview.png b/devtools/docs/user/3d_view/3dview.png Binary files differnew file mode 100644 index 0000000000..5cce08c8f5 --- /dev/null +++ b/devtools/docs/user/3d_view/3dview.png diff --git a/devtools/docs/user/3d_view/index.rst b/devtools/docs/user/3d_view/index.rst new file mode 100644 index 0000000000..dfe0bb83a3 --- /dev/null +++ b/devtools/docs/user/3d_view/index.rst @@ -0,0 +1,88 @@ +======= +3D view +======= + +.. warning:: + + From Firefox 47 onwards, 3D view is no longer available. + +When you click on the 3D view button, the page goes into 3D view mode; in this mode, you can see your page presented in a 3D view in which nested blocks of HTML are increasingly "tall," projecting outward from the bottom of the page. This view makes it easy to visualize the nesting of your content. + +.. image:: 3dview.png + :class: center + +By clicking and dragging the view, you can rotate and re-orient the 3D presentation of the DOM hierarchy of your page to see it from different angles, to better examine its structure. Off-screen elements become visible, so that you can see where your elements are located in relation to the visible content. You can click on elements to see their HTML in the :doc:`HTML panel <page_inspector_ui_tour_html_pane>` or the :doc:`Style panel <page_inspector_ui_tour_rules_view>`. Conversely, you can click on elements in the breadcrumb bar to change which element is selected in the 3D view. + +If you do not see the 3D button in the page inspector, it is possible that your graphics driver needs to be updated. See the `blocklisted drivers page <https://wiki.mozilla.org/Blocklisting/Blocked_Graphics_Drivers>`_ for more information. + + +Controlling the 3D view +*********************** + +There are keyboard shortcuts and mouse controls available for the 3D view. + +.. list-table:: + :widths: 20 20 60 + :header-rows: 1 + + * - Function + - Keyboard + - Mouse + + * - Zoom in/out + - :kbd:`+` / :kbd:`-` + - Scroll wheel up/down + + * - Rotate left/right + - :kbd:`a` / :kbd:`d` + - Mouse left/right + + * - Rotate up/down + - :kbd:`w` / :kbd:`s` + - Mouse up/down + + * - Pan left/right + - :kbd:`←` / :kbd:`→` + - Mouse left/right + + * - Pan up/down + - :kbd:`↑` / :kbd:`↓` + - Mouse up/down + + * - Reset zoom level + - :kbd:`0` + - Resets the zoom level to the default + + * - Focus on selected node + - :kbd:`f` + - Makes sure the currently selected node is visible + + * - Reset view + - :kbd:`r` + - Resets zoom, rotation, and panning to the default + + * - Hide current node + - :kbd:`x` + - Makes the currently selected node invisible; this can be helpful if you need to get at a node that's obscured + + +Use cases for the 3D view +************************* + +There are a variety of ways the 3D view is useful: + + +- If you have broken HTML causing layout problems, looking at the 3D view can help find where you've gone wrong. Often, layout problems are caused by improper nesting of content. This can become much more obvious when looking at the 3D view and seeing where your elements are nested wrong. +- If content isn't displaying, you may be able to figure out why; since the 3D view lets you zoom out to see elements that are rendering outside the visible area of the page, you can find stray content this way. +- You can get a look at how your page is structured to see if there may be ways to optimize your layout. +- And, of course, it looks **awesome**. + + +See also +******** + +- :doc:`Page Inspector <../page_inspector/index>` +- :ref:`HTML panel <page_inspector_ui_tour_html_pane>` +- :ref:`Style panel <page_inspector_ui_tour_rules_view>` +- :doc:`Tools <../index>` +- `New Developer Tools in Firefox 11 Aurora <https://hacks.mozilla.org/2011/12/new-developer-tools-in-firefox-11-aurora>`_ (blog post) diff --git a/devtools/docs/user/about_colon_debugging/about_debugging_setup.png b/devtools/docs/user/about_colon_debugging/about_debugging_setup.png Binary files differnew file mode 100644 index 0000000000..f3f7df8960 --- /dev/null +++ b/devtools/docs/user/about_colon_debugging/about_debugging_setup.png diff --git a/devtools/docs/user/about_colon_debugging/about_debugging_this_firefox.png b/devtools/docs/user/about_colon_debugging/about_debugging_this_firefox.png Binary files differnew file mode 100644 index 0000000000..31de51f77b --- /dev/null +++ b/devtools/docs/user/about_colon_debugging/about_debugging_this_firefox.png diff --git a/devtools/docs/user/about_colon_debugging/about_debugging_workers.png b/devtools/docs/user/about_colon_debugging/about_debugging_workers.png Binary files differnew file mode 100644 index 0000000000..fbcd7f133f --- /dev/null +++ b/devtools/docs/user/about_colon_debugging/about_debugging_workers.png diff --git a/devtools/docs/user/about_colon_debugging/always_use_private_browsing_mode.png b/devtools/docs/user/about_colon_debugging/always_use_private_browsing_mode.png Binary files differnew file mode 100644 index 0000000000..55690bbac1 --- /dev/null +++ b/devtools/docs/user/about_colon_debugging/always_use_private_browsing_mode.png diff --git a/devtools/docs/user/about_colon_debugging/connect_network_location.png b/devtools/docs/user/about_colon_debugging/connect_network_location.png Binary files differnew file mode 100644 index 0000000000..dae6c25dda --- /dev/null +++ b/devtools/docs/user/about_colon_debugging/connect_network_location.png diff --git a/devtools/docs/user/about_colon_debugging/device_information.png b/devtools/docs/user/about_colon_debugging/device_information.png Binary files differnew file mode 100644 index 0000000000..b4f81f3d7e --- /dev/null +++ b/devtools/docs/user/about_colon_debugging/device_information.png diff --git a/devtools/docs/user/about_colon_debugging/fxand-68-error.png b/devtools/docs/user/about_colon_debugging/fxand-68-error.png Binary files differnew file mode 100644 index 0000000000..9e61e87e3d --- /dev/null +++ b/devtools/docs/user/about_colon_debugging/fxand-68-error.png diff --git a/devtools/docs/user/about_colon_debugging/index.rst b/devtools/docs/user/about_colon_debugging/index.rst new file mode 100644 index 0000000000..fb6bbf68ea --- /dev/null +++ b/devtools/docs/user/about_colon_debugging/index.rst @@ -0,0 +1,364 @@ +=============== +about:debugging +=============== + +The ``about:debugging`` page provides a single place from which you can attach the Firefox Developer Tools to a number of debugging targets. At the moment it supports three main sorts of targets: restartless add-ons, tabs, and workers. + +This is also the main entry point to remotely debug Firefox, in particular Firefox for Android. + +Opening the about:debugging page +******************************** + +There are two ways to open ``about:debugging``: + +- Type ``about:debugging`` in the Firefox URL bar. +- In the **Tools** > **Browser Tools** menu, click **Remote Debugging**. + + +When about:debugging opens, on the left-hand side, you'll see a sidebar with two options and information about your remote debugging setup: + + +Setup + Use the Setup tab to configure the connection to your remote device. +This Firefox + Provides information about temporary extensions you have loaded for debugging, extensions that are installed in Firefox, the tabs that you currently have open, and service workers running on Firefox. + +.. image:: about_debugging_setup.png + :class: border + + +If your ``about:debugging`` page is different from the one displayed here, go to ``about:config``, find and set the option ``devtools.aboutdebugging.new-enabled`` to **true**. + + +Setup tab +********* + +.. _about-colon-debugging-connecting-to-a-remote-device: + +Connecting to a remote device +----------------------------- + +Firefox supports debugging over USB with Android devices, using the about:debugging page. + +Before you connect: + +1. Enable Developer settings on your Android device. +2. Enable USB debugging in the Android Developer settings. +3. Enable **Remote Debugging via USB** in the Advanced Settings in Firefox on the Android device. +4. Connect the Android device to your computer using a USB cable. + If a USB cable is not available, :ref:`connect to Android over Wi-Fi <about-colon-debugging-connecting-to-android-over-wi-fi>`. + + +If your device doesn't appear in the lefthand side of the about:debugging page, try clicking the **Refresh devices** button. + +**If it still doesn't appear**, it may be because the link between your Android device and your computer is not authorized yet. First make sure you have installed `Android Debug Bridge <https://developer.android.com/studio/command-line/adb.html>`_ from Android Tools on your computer in order for it to be able to connect to your device. Next, disable every debugging setting already activated and repeat the steps described before. Your device should show a popup to authorize your computer to connect to it — accept this and then click the **Refresh devices** button again. The device should appear. + +.. note:: + + You do not need to install the full Android Studio SDK. Only adb is needed. + + +To start a debugging session, first open the page that you wish to debug and then click **Connect** next to the device name to open a connection to it. If the connection was successful, you can now click the name of the device to switch to a tab with information about the device. + +.. image:: device_information.png + :alt: Screenshot of the debugging page for an Android device + :class: border + + +The information on this page is the same as the information on the **This Firefox** tab, but instead of displaying information for your computer, it displays the information for the remote device with the addition of a **Tabs** section with an entry for each of the tabs open on the remote device. + +Note: If the version of Firefox on your remote device is more than one major version older than the version running on your computer, you may see a message like the following: + +.. image:: version_warning.png + :alt: The connected browser has an old version (68.2.0). The minimum supported version (69.0a1). This is an unsupported setup and may cause DevTools to fail. Please update the connected browser. + :class: center + + +In Firefox 76 and above, the message can look like the following: + +.. image:: fxand-68-error.png + :alt: This version of Firefox cannot debug Firefox for Android (68). We recommend installing Firefox for Android Nightly on your phone for testing. More details + :class: center + +See Connection for Firefox for Android 68 for more information. + +In the image above, there are three tabs open: **Network or cache Recipe**, **Nightly Home**, and **About Nightly**. To debug the contents of one of these tabs, click the **Inspect** button next to its title. When you do, the Developer Tools open in a new tab. + + +.. image:: remote-debugger-w-url-buttons.png + :class: border + :alt: Screenshot showing the remote debugging window, with the editable URL bar + + +Above the usual list of tools, you can see information about the device you are connected to, including the fact that you are connected (in this example) via USB, to Firefox Preview, on a Pixel 2, as well as the title of the page that you are debugging, and the address of the page. + +Starting in Firefox 78, the URL bar is editable, so that you can change the URL used by the browser on the remote device, by typing in Firefox for Desktop. You can also reload the page by clicking the **Reload** button next to the URL bar, and (starting 79), navigate backward or forward in the browsing history with the **Back** and **Forward** buttons. + + +.. _about-colon-debugging-connecting-to-android-over-wi-fi: + +Connecting to Android over Wi-Fi +-------------------------------- + +Firefox can debug Firefox for Android through `adb` and the `"Wireless debugging" feature <https://developer.android.com/tools/adb#connect-to-a-device-over-wi-fi>`_ of Android 11+, without requiring any USB cable. + +Prerequisites: + +- Device must run Android 11 or later. +- The `adb <https://developer.android.com/tools/adb>`_ program is available. You do not need Android Studio nor the full Android SDK. +- The Android device and the computer with ``about:debugging`` are in the same network. + +Steps to connect wirelessly with the Android device: + +1. Determine the IP address of your Android device on your local network. For example by locating the Internet/Wi-Fi setting and viewing details of the current (Wi-Fi) network. +2. `Enable Developer options <https://developer.android.com/studio/debug/dev-options#enable>`_ on your Android device. +3. Enable Wireless debugging by tapping on the toggle at the "Wireless debugging" bar at the Developer options, then tap on the "Wireless debugging" bar (before the toggle) to open the "Wireless debugging" screen. + + 1. An alternative to the previous step is to open "Quick settings developer tiles" at Developer options, and enabling the "Wireless debugging" tile. After this, you can long-press the "Wireless debugging" tile from the Quick Settings panel to launch the "Wireless debugging" screen. + +4. Tap on "Pair device with pairing code" in the "Wireless debugging" screen. This displays a six-digit code and an IP address and port. The port is unique to the pairing setup. +5. From the terminal, run ``adb pair [ip address from step 1]:[port from step 4]`` and enter the six-digit code from step 4. +6. To finally connect wirelessly, look up the (random) port at the "IP address & Port" section of the "Wireless debugging" screen. The port is distinct from step 4. Run ``adb connect [ip address from step 1]:[port from step 6]`` to connect. + +Now, the adb server on your computer is connected with the adb daemon on the Android device. All Firefox apps with the "Remote Debugging via USB" setting enabled will now appear in ``about:debugging``. + +If you do not see any Firefox for Android debugging target: + +- Confirm that adb is connected by running ``adb devices``. +- Confirm that the Firefox app is running and that the "Remote Debugging via USB" setting is checked. + + +Connecting over the Network +--------------------------- + +.. note:: + The steps below do not work for Android. Follow the instructions at :ref:`Connecting to Android over Wi-Fi <about-colon-debugging-connecting-to-android-over-wi-fi>` instead. + + +You can connect to a Firefox Debug server on your network, or on your debugging machine using the **Network Location** settings of the about:debugging page. + +.. image:: network_location.png + :class: center + + +Enter the location and port on which the debugger server is running. When you do, it is added to the Network locations list along with the devices, as shown below: + +.. image:: connect_network_location.png + :class: center + + +This Firefox +************ + +The **This Firefox** tab combines the features of Extensions, Tabs, and Workers into a single tab with the following sections: + + +Temporary Extensions + Displays a list of the extensions that you have loaded using the **Load Temporary Add-on** button. +Extensions + This section lists information about the extensions that you have installed on your system. +Service Workers, Shared Workers, and Other Workers + There are three sections on this page that deal with Service Workers, Shared Workers, and Other Workers. + + +.. image:: about_debugging_this_firefox.png + :class: border + + +Whether internal extensions appear in the list on this page depends on the setting of the ``devtools.aboutdebugging.showHiddenAddons`` preference. If you need to see these extensions, navigate to ``about:config`` and make sure that the preference is set to ``true``. + + +Extensions +********** + +Loading a temporary extension +----------------------------- + +With the **Load Temporary Add-on** button you can temporarily load a WebExtension from a directory on disk. Click the button, navigate to the directory containing the add-on and select its manifest file. The temporary extension is then displayed under the **Temporary Extensions** header. + +You don't have to package or sign the extension before loading it, and it stays installed until you restart Firefox. + +The major advantages of this method, compared with installing an add-on from an XPI, are: + + +- You don't have to rebuild an XPI and reinstall when you change the add-on's code; +- You can load an add-on without signing it and without needing to disable signing. + + +Once you have loaded a temporary extension, you can see information about it and perform operations on it. + +.. image:: temporary_extension.png + :alt: Screenshot of the debugging information panel for a temporary extension + :class: center + + +You can use the following buttons: + + +Inspect + Loads the extension in the debugger. +Reload + Reloads the temporary extension. This is handy when you have made changes to the extension. +Remove + Unloads the temporary extension. + + +Other information about the extension is displayed: + + +Location + The location of the extension's source code on your local system. +Extension ID + The temporary ID assigned to the extension. +Internal UUID + The internal UUID assigned to the extension. +Manifest URL + If you click the link, the manifest for this extension is loaded in a new tab. + + +Updating a temporary extension +------------------------------ + +If you install an extension in this way, what happens when you update the extension? + + +- If you change files that are loaded on demand, like `content scripts <https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Content_scripts>`_ or `popups <https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Anatomy_of_a_WebExtension#browser_actions_2>`_, then changes you make are picked up automatically, and you'll see them the next time the content script is loaded or the popup is shown. + +- For other changes, click the **Reload** button. This does what it says: + + - Reloads any persistent scripts, such as `background scripts <https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Anatomy_of_a_WebExtension#background_scripts>`_ + - Parses the ``manifest.json`` file again, so changes to `permissions <https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions>`_, `content_scripts <https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/content_scripts>`_, `browser_action <https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/browser_action>`_ or any other keys take effect + + +Installed Extensions +-------------------- + +The permanently installed extensions are listed in the next section, **Extensions**. For each one, you see something like the following: + +.. image:: installed_extension.png + :alt: Screenshot of the debugging information panel for an installed extension + :class: center + + +The **Inspect** button, and the **Extension ID** and **Internal UUID** fields are the same as for temporary extensions. + +Just as it does with temporarily loaded extensions, the link next to **Manifest URL** opens the loaded manifest in a new tab. + +.. note:: + + It's recommended that you use the Browser Toolbox, not the Add-on Debugger, for debugging WebExtensions. See `Debugging WebExtensions <https://extensionworkshop.com/documentation/develop/debugging/>`_ for all the details. + + +The Add-ons section in about:debugging lists all WebExtensions that are currently installed. Next to each entry is a button labeled **Inspect**. + +.. note:: + + This list may include add-ons that came preinstalled with Firefox. + + +If you click **Inspect**, the Add-on Debugger will start in a new tab. + +.. raw:: html + + <iframe width="560" height="315" src="https://www.youtube.com/embed/efCpDNuNg_c" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe> + <br/> + <br/> + + +Workers +******* + +The Workers section shows all the workers you've got registered on your Firefox, categorized as follows: + + +- All registered `Service Workers <https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API>`_ +- All registered `Shared Workers <https://developer.mozilla.org/en-US/docs/Web/API/SharedWorker>`_ +- Other workers, including Chrome Workers and `Dedicated Workers <https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Using_web_workers#dedicated_workers>`_ + + +You can connect the developer tools to each worker, and send push notifications to service workers. + +.. image:: about_debugging_workers.png + :class: border + + +Service worker state +-------------------- + +The list of service workers shows the state of the service worker in its `lifecycle <https://developers.google.com/web/fundamentals/primers/service-workers/lifecycle>`_. Three states are possible: + + +- *Registering*: this covers all states between the service worker's initial registration, and its assuming control of pages. That is, it subsumes the *installing*, *activating*, and *waiting* states. +- *Running*: the service worker is currently running. It's installed and activated, and is currently handling events. +- *Stopped*: the service worker is installed and activated, but has been terminated after being idle. + + +.. image:: sample_service_worker.png + :alt: Screenshot of the debugging panel for a service worker that is in the Running state + :class: center + + +This section uses a simple ServiceWorker demo, hosted at https://serviceworke.rs/push-simple/. + +.. note:: + + From Firefox 79 onwards, you can access similar information on the Service Workers registered on a particular domain by going to the Firefox DevTools :doc:`Application panel <../application/index>`. + + +Unregistering service workers +----------------------------- + +Click the **Unregister** button to unregister the service worker. + + +Sending push events to service workers +-------------------------------------- + +To debug push notifications, you can set a breakpoint in the `push event <https://developer.mozilla.org/en-US/docs/Web/API/PushEvent>`_ listener. However, you can also debug push notifications locally, without needing the server. Click the **Push** button to send a push event to the service worker. + + +Service workers not compatible +------------------------------ + +A warning message is displayed at the top of the **This Firefox** tab if service workers are incompatible with the current browser configuration, and therefore cannot be used or debugged. + +.. image:: worker_warning.png + :class: center + + +Service workers can be unavailable if: + +- ``dom.serviceWorkers.enable`` preference is set to false in ``about:config``. +- ``browser.privatebrowsing.autostart`` preference is set to true in ``about:config`` or through Firefox preferences UI. + + +The ``browser.privatebrowsing.autostart`` preference is set to true if the user selects **Never remember history** option or enables **Always use private browsing mode** in preferences UI, see about:preferences#privacy + + +Always use private browsing mode: + +.. image:: always_use_private_browsing_mode.png + :class: center + + +Never remember history: + +.. image:: never_remember_history.png + :class: center + + +Connection to Firefox for Android 68 +************************************ + +Releases of Firefox for Android that are based on version 68 cannot be debugged from desktop Firefox versions 69 or later, because of the difference in release versions. Until such time as Firefox for Android is updated to a newer major release, in synch with desktop Firefox, you should use one of the following Firefox for Android versions: + + +- `Firefox Preview <https://play.google.com/store/apps/details?id=org.mozilla.fenix>`_, if your desktop Firefox is the main release or Developer Edition +- `Firefox for Android Nightly <https://play.google.com/store/apps/details?id=org.mozilla.fenix>`_ + + +If you prefer to test with the main release of Firefox for Android (i.e., based on release 68), you can do so with the desktop `Firefox Extended Support Release (ESR) <https://support.mozilla.org/en-US/kb/switch-to-firefox-extended-support-release-esr>`_, which is also based on version 68. + +Note that ``about:debugging`` is not enabled by default in Firefox ESR. To enable it, open the `Configuration Editor <https://support.mozilla.org/en-US/kb/about-config-editor-firefox>`_ (``about:config``) and set ``devtools.aboutdebugging.new-enabled`` to **true**. + +If you used a higher version of Firefox prior to installing Firefox ESR, you will be prompted to create a new user profile, in order to protect your user data. For more information, see `What happens to my profile if I downgrade to a previous version of Firefox? <https://support.mozilla.org/en-US/kb/dedicated-profiles-firefox-installation#w_what-happens-to-my-profile-if-i-downgrade-to-a-previous-version-of-firefox>`_ diff --git a/devtools/docs/user/about_colon_debugging/installed_extension.png b/devtools/docs/user/about_colon_debugging/installed_extension.png Binary files differnew file mode 100644 index 0000000000..f2c5b068c1 --- /dev/null +++ b/devtools/docs/user/about_colon_debugging/installed_extension.png diff --git a/devtools/docs/user/about_colon_debugging/network_location.png b/devtools/docs/user/about_colon_debugging/network_location.png Binary files differnew file mode 100644 index 0000000000..a80abb4d69 --- /dev/null +++ b/devtools/docs/user/about_colon_debugging/network_location.png diff --git a/devtools/docs/user/about_colon_debugging/never_remember_history.png b/devtools/docs/user/about_colon_debugging/never_remember_history.png Binary files differnew file mode 100644 index 0000000000..cfc7c8f07f --- /dev/null +++ b/devtools/docs/user/about_colon_debugging/never_remember_history.png diff --git a/devtools/docs/user/about_colon_debugging/remote-debugger-w-url-buttons.png b/devtools/docs/user/about_colon_debugging/remote-debugger-w-url-buttons.png Binary files differnew file mode 100644 index 0000000000..6cc3ce1a15 --- /dev/null +++ b/devtools/docs/user/about_colon_debugging/remote-debugger-w-url-buttons.png diff --git a/devtools/docs/user/about_colon_debugging/sample_service_worker.png b/devtools/docs/user/about_colon_debugging/sample_service_worker.png Binary files differnew file mode 100644 index 0000000000..cda75521b1 --- /dev/null +++ b/devtools/docs/user/about_colon_debugging/sample_service_worker.png diff --git a/devtools/docs/user/about_colon_debugging/temporary_extension.png b/devtools/docs/user/about_colon_debugging/temporary_extension.png Binary files differnew file mode 100644 index 0000000000..218f33f4a3 --- /dev/null +++ b/devtools/docs/user/about_colon_debugging/temporary_extension.png diff --git a/devtools/docs/user/about_colon_debugging/version_warning.png b/devtools/docs/user/about_colon_debugging/version_warning.png Binary files differnew file mode 100644 index 0000000000..6602624fe6 --- /dev/null +++ b/devtools/docs/user/about_colon_debugging/version_warning.png diff --git a/devtools/docs/user/about_colon_debugging/worker_warning.png b/devtools/docs/user/about_colon_debugging/worker_warning.png Binary files differnew file mode 100644 index 0000000000..c85a3a9d31 --- /dev/null +++ b/devtools/docs/user/about_colon_debugging/worker_warning.png diff --git a/devtools/docs/user/accessibility_inspector/accessibility-inspector-check_for_issues.png b/devtools/docs/user/accessibility_inspector/accessibility-inspector-check_for_issues.png Binary files differnew file mode 100644 index 0000000000..5ab84fa847 --- /dev/null +++ b/devtools/docs/user/accessibility_inspector/accessibility-inspector-check_for_issues.png diff --git a/devtools/docs/user/accessibility_inspector/accessibility-inspector-hidden_item_revealed.png b/devtools/docs/user/accessibility_inspector/accessibility-inspector-hidden_item_revealed.png Binary files differnew file mode 100644 index 0000000000..799406052b --- /dev/null +++ b/devtools/docs/user/accessibility_inspector/accessibility-inspector-hidden_item_revealed.png diff --git a/devtools/docs/user/accessibility_inspector/accessibility-inspector-hidden_items.png b/devtools/docs/user/accessibility_inspector/accessibility-inspector-hidden_items.png Binary files differnew file mode 100644 index 0000000000..41d88d9552 --- /dev/null +++ b/devtools/docs/user/accessibility_inspector/accessibility-inspector-hidden_items.png diff --git a/devtools/docs/user/accessibility_inspector/accessibility-inspector-picker.png b/devtools/docs/user/accessibility_inspector/accessibility-inspector-picker.png Binary files differnew file mode 100644 index 0000000000..18ddda6078 --- /dev/null +++ b/devtools/docs/user/accessibility_inspector/accessibility-inspector-picker.png diff --git a/devtools/docs/user/accessibility_inspector/accessibility-inspector-print_tree_to_json.png b/devtools/docs/user/accessibility_inspector/accessibility-inspector-print_tree_to_json.png Binary files differnew file mode 100644 index 0000000000..58c557a9f8 --- /dev/null +++ b/devtools/docs/user/accessibility_inspector/accessibility-inspector-print_tree_to_json.png diff --git a/devtools/docs/user/accessibility_inspector/accessibility-inspector-show_tab_order.png b/devtools/docs/user/accessibility_inspector/accessibility-inspector-show_tab_order.png Binary files differnew file mode 100644 index 0000000000..7cf96d8cb7 --- /dev/null +++ b/devtools/docs/user/accessibility_inspector/accessibility-inspector-show_tab_order.png diff --git a/devtools/docs/user/accessibility_inspector/accessibility-inspector-tabbing_order.png b/devtools/docs/user/accessibility_inspector/accessibility-inspector-tabbing_order.png Binary files differnew file mode 100644 index 0000000000..147eaa1b6c --- /dev/null +++ b/devtools/docs/user/accessibility_inspector/accessibility-inspector-tabbing_order.png diff --git a/devtools/docs/user/accessibility_inspector/accessibility_json.png b/devtools/docs/user/accessibility_inspector/accessibility_json.png Binary files differnew file mode 100644 index 0000000000..3115c47ce8 --- /dev/null +++ b/devtools/docs/user/accessibility_inspector/accessibility_json.png diff --git a/devtools/docs/user/accessibility_inspector/dom-inspector-context-menu.png b/devtools/docs/user/accessibility_inspector/dom-inspector-context-menu.png Binary files differnew file mode 100644 index 0000000000..54806b806f --- /dev/null +++ b/devtools/docs/user/accessibility_inspector/dom-inspector-context-menu.png diff --git a/devtools/docs/user/accessibility_inspector/dom-inspector-picker.png b/devtools/docs/user/accessibility_inspector/dom-inspector-picker.png Binary files differnew file mode 100644 index 0000000000..dab01116af --- /dev/null +++ b/devtools/docs/user/accessibility_inspector/dom-inspector-picker.png diff --git a/devtools/docs/user/accessibility_inspector/dom-node-target-icon.png b/devtools/docs/user/accessibility_inspector/dom-node-target-icon.png Binary files differnew file mode 100644 index 0000000000..0079299ff2 --- /dev/null +++ b/devtools/docs/user/accessibility_inspector/dom-node-target-icon.png diff --git a/devtools/docs/user/accessibility_inspector/image_accessibility.png b/devtools/docs/user/accessibility_inspector/image_accessibility.png Binary files differnew file mode 100644 index 0000000000..ecb9611393 --- /dev/null +++ b/devtools/docs/user/accessibility_inspector/image_accessibility.png diff --git a/devtools/docs/user/accessibility_inspector/index.rst b/devtools/docs/user/accessibility_inspector/index.rst new file mode 100644 index 0000000000..6574f893de --- /dev/null +++ b/devtools/docs/user/accessibility_inspector/index.rst @@ -0,0 +1,288 @@ +======================= +Accessibility Inspector +======================= + +The Accessibility Inspector provides a means to access important information exposed to assistive technologies on the current page via the accessibility tree, allowing you to check what's missing or otherwise needs attention. This article takes you through the main features of the Accessibility Inspector and how to use it. + +A (very) brief guide to accessibility +************************************* + +Accessibility is the practice of making your websites usable by as many people as possible. This means trying your best to not lock anyone out of accessing information because of any disability they may have, or any other personal circumstances such as the device they are using, the speed of their network connection, or their geographic location or locale. You can find more extensive information in the `Accessibility <https://developer.mozilla.org/en-US/docs/Web/Accessibility>`_ section of MDN Web Docs. + +Here we are mainly talking about exposing information to people with visual disabilities — this is done via the `accessibility APIs <https://www.smashingmagazine.com/2015/03/web-accessibility-with-accessibility-api/>`_ available inside web browsers, which expose information on what roles the different elements on your page play (e.g., are they just text, or are they buttons, links, form elements, etc.?). + +Semantic DOM elements have roles assigned to them by default that hint at what their purpose is. Sometimes, however, you need to use some non-semantic markup (e.g., `div <https://developer.mozilla.org/en-US/docs/Web/HTML/Element/div>`_ s) to build a complex custom control, and the control won't have a default role that reflects its purpose. In such a situation, you can use `WAI-ARIA <https://developer.mozilla.org/en-US/docs/Learn/Accessibility/WAI-ARIA_basics>`_ role attributes to provide your own roles. + +Roles and other information exposed by browser accessibility APIs are presented in a hierarchical structure called the accessibility tree. This is a bit like the DOM tree, except that it contains a more limited set of elements and slightly different information about them. + +Assistive technologies like screenreaders use this information to find out what's on a web page, tell their users what's there, and enable them to interact with the page. The Accessibility Inspector also uses this information to provide valuable accessibility debugging capabilities in the DevTools. + + +Accessing the Accessibility Inspector +************************************* + +When you first open any of the other Developer Tools, the accessibility features are turned off (unless you've already got them turned on in another browser tab, or got the Firefox accessibility engine started already, e.g., you might be a screenreader user or tester). + +The accessibility inspector is automatically enabled when you do one of the following(beforeFirefox 79, it had to be explicitly enabled): + + +- Choose **Accessibility** in the **Tools > Browser Tools** menu. +- Select the **Accessibility** tab in the Developer Tools toolbox. +- Right-click in the main browser window, and choose **Inspect Accessibility Properties** in the context menu. +- Right-click an item in the HTML pane of the :doc:`Page Inspector <../page_inspector/index>`, and choose **Show Accessibility Properties** in the context menu. + + +Once activated, the accessibility engine remains running until you close the Developer Tools toolbox. + +.. note:: + + The accessibility engine runs in the background when the accessibility features are turned on. When enabled it may affect the metrics from other panels such as :doc:`Memory <../memory/index>` and :doc:`Performance <../performance/index>`, and have some impact onoverall browser performance. + + +If you don't wish to allow the accessibility features to be automatically enabled, you can use the `Configuration Editor <https://support.mozilla.org/en-US/kb/about-config-editor-firefox>`__ (also known as ``about:config``) to define the preference ``devtools.accessibility.auto-init.enabled``, and set it to ``False``. + +If you don't wish to use the accessibility features at all, you can use the `Configuration Editor <https://support.mozilla.org/en-US/kb/about-config-editor-firefox>`__ to set the preference ``devtools.accessibility.enabled`` to ``False``. If you do this, the methods listed above for activating the Accessibility Inspector do nothing. + + +Features of the Accessibility panel +*********************************** + +The enabled accessibility panel looks like so: + +.. image:: accessibility-inspector-tabbing_order.png + :class: border + :alt: Shows issue checker toolbar with "contrast" and "text label" options + + +On the left-hand side, there is a tree diagram representing all the items in the accessibility tree for the current page. Items with nested children have arrows that can be clicked to reveal the children, so you can move deeper into the hierarchy. Each item has two properties listed: + + +- *Role* — the role this item has on the page (e.g., ``pushbutton``, or ``footer``). This can be either a default role provided by the browser, or a role given to it via a WAI-ARIA ``role`` attribute. +- *Name* — the name this item has on the page. The name depends on the element; for example, the name of most text elements is their ``textContent``, whereas form elements' names are the contents of their associated `label <https://developer.mozilla.org/en-US/docs/Web/HTML/Element/label>`_. + + +On the right-hand side, you can see further information about the currently selected item. The listed properties are as follows: + + +- *name* — the item's name, as described above. +- *role* — the item's role, as described above. +- *actions* — a list of actions that can be performed on the item, for example, a pushbutton would have "Press" listed, while a link would have "Jump" listed. +- *value* — the value of the item. This can mean different things depending on the type of the item; for example, a form input (role: entry) would have a value of whatever is entered in the input, whereas a link's value would be the URL in the corresponding ``<a>`` element's ``href``. +- *DOMNode* — the type of DOM node that the item in the accessibility tree represents. You can click on the "target" icon that comes after it to select the node in the :doc:`Page Inspector <../page_inspector/index>`. Hovering over the "target" icon highlights the DOM node in the page content. + + .. image:: dom-node-target-icon.png + :alt: DOMNode property in accessibility inspector with target icon highlighted + +- *description* — any further description provided on the element, usually by the content of a title attribute. +- *keyboardShortcut* — any keyboard shortcut that is available to activate the element, as specified in an ``accessKey`` attribute. Note that this works correctly as of Firefox 62 `bug 1467381 <https://bugzilla.mozilla.org/show_bug.cgi?id="1467381>`_. +- *childCount* — the number of child items the current item has in the accessibility tree hierarchy. +- *indexInParent* — an index value indicating what number child the item is, inside its parent. If the item is the first item inside its parent, it has a value of 0. If it is the second, it has a value of 1. And so on. +- *states* — a list of the different accessibility-relevant states that can apply to the current item. For example, one of the links in one demo has states of focusable, linked, selectable text, opaque, enabled, and sensitive. For a full list of internal states, see Gecko states. +- *relations* — a list of the accessibility-relevant relationships between this item and other items. For example, in a form, an entry item could have a "labelled by" relation with a label item, which in turn has a "label for" relation to the entry item. +- *attributes* — a list of all the accessibility-relevant attributes that are applied to the item. This can include style-related attributes such as margin-left and text-indent, and other useful states for accessibility information, such as draggable and level (e.g., what heading level is it, in the case of headings). For a full list of possible attributes, see Gecko object attributes. + + +.. note:: + The exposed information is the same across all platforms — the inspector exposes Gecko's accessibility tree, rather than information from the platform accessibility layer. + + +Keyboard controls +----------------- + +The *Accessibility* tab is fully keyboard-accessible: + +- You can tab between *Check for Issues*, *Simulate*, *Show tabbing order*, and left and right panels. +- When one of the panels is focused, you can move the focus up and down items using the up and down arrow keys, and use the left and right arrow keys to expand and collapse expandable rows (e.g., different hierarchy levels of the accessibility tree). + + +Print accessibility tree to JSON +-------------------------------- + +You can print the contents of the accessibility tree to JSON by right-clicking on an entry in the Accessibility tab and selecting **Print to JSON:** + +.. image:: accessibility-inspector-print_tree_to_json.png + :alt: Print to JSON right-click menu in left panel + :class: border + +When you do, you will get a new tab with the selected accessibility tree loaded into the JSON viewer: + +.. image:: accessibility_json.png + :alt: Accessibility tree loaded in new tab JSON viewer + :class: center + +Once opened, you can save or copy the data as necessary. The JSON viewer can also show you the raw JSON data on a separate tab in the viewer. + + +Show web page tabbing order +--------------------------- + +People who are unable to navigate a page with the mouse or a trackpad can use the :kbd:`tab` key to toggle through focusable items on the page (i.e. buttons, links, form controls).The order that items are focused is one of the most important aspects of web accessibility, as it allows keyboard users to properly navigate a web page — if the tab order is incorrect, the page may be confusing! + +Firefox 84 and later can enable a visual overlay showing the tabbing order. This provides a high-level overview of how the page will be navigated using the :kbd:`tab` key, which may highlight problems more effectively than tabbing through the elements. The overlay is toggled on/off using the**Show Tabbing Order** checkbox. + +.. image:: accessibility-inspector-show_tab_order.png + :alt: Accessibility inspector and page with checkbox Show tab order selected. + :class: border + + +All focusable items have a numbered marker and the currently focused item is highlighted in a different color. In some cases the marker may be hidden by other elements, as is true for items 1 and 2 in the page below. + +.. image:: accessibility-inspector-hidden_items.png + :alt: A page where some of the markers for selection items are hidden + :class: center + +These become visible in the overlay when the item is the current item. + +.. image:: accessibility-inspector-hidden_item_revealed.png + :alt: Shows a hidden selection item in the tabbing order overlay when it is selected. + :class: center + + +.. note:: + + The overlay reflects the tab order at the time that the checkbox is selected (i.e. it is not dynamic). If a user does anything that adds items to the tab order (e.g. opens a visual element that contains more links), these new items will not be reflected in the overlay until the Accessibility Inspector is re-launched. + + +Check for accessibility issues +------------------------------ + +You can check for accessibility issues by clicking the drop-down menu next to: **Check for issues**. The available menu items include: + + +- **None** — Don't show the possible list of issues. +- **All Issues** — Check for all types of issues. +- **Contrast** — Check for `issues with visual contrast. <https://developer.mozilla.org/en-US/docs/Web/Accessibility/Understanding_WCAG/Perceivable/Color_contrast>`_ +- **Keyboard** — Check for `issues with navigating via a keyboard. <https://developer.mozilla.org/en-US/docs/Web/Accessibility/Understanding_WCAG/Keyboard>`_ +- **Text Labels** — Check for `issues with missing text labels. <https://developer.mozilla.org/en-US/docs/Web/Accessibility/Understanding_WCAG/Text_labels_and_names>`_ + + +When you select one of the menu items, Firefox scans your document for the type of issues you selected. Depending on the size and complexity of your document, this may take a few seconds. When the scan is complete, the left side of the Accessibility Inspector panel displays only the items that have that type of issue. In the right side of the panel, the *Checks* subpanel lists the specific issue with the selected node. For each type of issue, there is a **Learn more** link to further information on *MDN Web Docs* about the issue. + + +.. image:: accessibility-inspector-check_for_issues.png + :alt: Accessibility Inspector - Showing the options when you select the Check for Issues button + :class: border + + +The menu items act as toggles. Select the item to view that type of issue; select the item again to clear the display of issues of that type. + +Issues with a particular item are always displayed in the *Checks* subpanel as you browse the tree. The **Check for issues** menuitems are a quick way to view all and only those items that have issues. + + +Simulate +-------- + +The Accessibility Inspector offers (as of Firefox 70), a :doc:`simulator <simulation/index>` that lets you see what a web page would look like to users with various forms of *color vision deficiency* (better known as "color blindness"), as well as *contrast sensitivity loss*. + + +Notable related features +************************ + +When the accessibility features are turned on, there are a number of useful additional features available in the DevTools, which are detailed below: + +Context menu options +-------------------- + +An extra context menu option is added, both for the general context menu on the web page when right-clicking a UI feature, and the HTML pane of the page inspector when right-clicking a DOM element: + +.. image:: web-page-context-menu.png + :alt: context menu in the browser viewport, with a highlighted option: Inspect Accessibility Properties + :class: border + + +.. image:: dom-inspector-context-menu.png + :alt: context menu in the DOM inspector, with a highlighted option: Show Accessibility Properties + :class: border + +When you choose the *Inspect Accessibility Properties*/*Show Accessibility Properties* context menu options, the *Accessibility* tab is immediately opened to show the corresponding accessibility tree item and its properties. + +.. note:: + + Some DOM elements do not have accessibility properties — in that case, the *Inspect Accessibility Properties*/*Show Accessibility Properties* context menu item is grayed out. + + +Highlighting of UI items +------------------------ + +In the Accessibility tab, when the mouse hovers over accessibility items, you can see a semi-transparent highlight appear over the UI items they relate to, if appropriate. The role and name of the item will be shown in a small information bar along with color contrast information if appropriate. This is useful for determining how the items in the accessibility tree relate to the UI items on the actual page. + +In the following example, you can see that the image has been highlighted and its role, graphic, name, "Road, Asphalt, Sky, Clouds, Fall", and the color contrast ratio, 3.46, appears in the information bar above it. + +.. image:: image_accessibility.png + :alt: image has been highlighted and graphic, "Road, Asphalt, Sky, Clouds, Fall", and Contrast:3.46 warning sign, appears in the information bar above it + :class: border + + +Color contrast +~~~~~~~~~~~~~~ + +Contrast ratio information is particularly useful when you are designing the color palette for your website because if the contrast is not sufficient, readers with visual impairments such as low vision or color blindness will be unable to read the text. See `Color contrast <https://developer.mozilla.org/en-US/docs/Web/Accessibility/Understanding_WCAG/Perceivable/Color_contrast>`_ for details about recommended contrast ratios. + +For example: + +.. image:: screen_shot_2019-01-29_at_10.11.13.png + :alt: A screenshot of color contrast highlighter with warning sign where text contrast if below the AA WCAG threshold. + :class: center + +The color contrast in the image above is 2.86, so potentially not enough contrast to make it easy to read. Notice the warning symbol that indicates that the contrast fails to meet the acceptable contrast ratio. + +As of Firefox 65, viewing this information for some foreground text that has a complex background image (e.g. a gradient) gives you a range of color contrast values. For example: + +.. image:: screen_shot_2019-01-29_at_10.21.07.png + :alt: A screenshot of color contrast highlighter with checked sign where for text over gradient background with contrast satisfying the AAA WCAG guidelines. + :class: center + + +In this example, the contrast ranges from 4.72 to 5.98. The numbers are followed by AAA and a checkmark in green, indicating that the large text has a contrast ratio of 4.5:1 or more, meeting the criteria for enhanced contrast, or Level AAA. + +See `Color contrast <https://developer.mozilla.org/en-US/docs/Web/Accessibility/Understanding_WCAG/Perceivable/Color_contrast>`_ for more information on color contrast. + + +Accessibility picker +-------------------- + +Like the element picker button on the :ref:`Page Inspector <page-inspector-how-to-select-an-element-with-the-node-picker>`, the *Accessibility* tab's element picker button allows you to hover and select UI items on the current pageto highlight objects in the accessibility tree. + +The accessibility tab element picker looks slightly different from the Page Inspector HTML pane picker, as shown below: + +.. image:: dom-inspector-picker.png + :alt: highlighted DOM inspector picker button, with a tooltip saying Pick an element from the page + :class: border + + +.. image:: accessibility-inspector-picker.png + :alt: highlighted accessibility inspector button, with a tooltip saying Pick accessible object from the page + :class: border + + +When you "perform a pick", you see the accessibility object highlighted in the accessibility tree, and the picker is then deactivated. Note, however, that if you hold the :kbd:`Shift` key down when "performing a pick", you can "preview" the accessibility object in the tree (and its properties in the right-hand pane), but then continue picking as many times as you like(the picker does not get cancelled) until you release the :kbd:`Shift` key. + +When the picker is activated, you can also deactivate it by pressing the picker button a second time, or pressing the :kbd:`Esc` key. + + +Typical use cases +***************** + +The Accessibility Inspector is very useful for spotting accessibility problems at a glance. For a start, you can investigate items that don't have a proper text equivalent — images without ``alt`` text and form elements without proper labels have a ``name`` property of ``null``, for example. + +.. image:: use-case-no-label.png + :alt: A form input highlighted in the UI, with information about it shown in the accessibility inspector to reveal that it has no label — it has a name property of null + :class: border + + +It is also very handy for verifying semantics — you can use the *Inspect Accessibility Properties* context menu option to quickly see whether an item has the correct role set on it (e.g., whether a button is really a button, or a link is really a link). + +.. image:: use-case-fake-button.png + :alt: A UI element that looks like a button, with information about it shown in the accessibility inspector to reveal that it isn't a button, it is a section element. It has a name property of null + :class: border + + +See also +******** + +- `Accessibility tutorials <https://developer.mozilla.org/en-US/docs/Learn/Accessibility>`_ +- `Web accessibility overview <https://developer.mozilla.org/en-US/docs/Web/Accessibility>`_ +- `Practical debugging information <https://developer.mozilla.org/en-US/docs/Learn/Tools_and_testing/Cross_browser_testing/Accessibility>`_ +- `Understanding WCAG <https://developer.mozilla.org/en-US/docs/Web/Accessibility/Understanding_WCAG>`_ +- `WAI-ARIA basics <https://developer.mozilla.org/en-US/docs/Learn/Accessibility/WAI-ARIA_basics>`_ +- `Accessibility APIs: A Key To Web Accessibility <https://www.smashingmagazine.com/2015/03/web-accessibility-with-accessibility-api/>`_ by Léonie Watson diff --git a/devtools/docs/user/accessibility_inspector/screen_shot_2019-01-29_at_10.11.13.png b/devtools/docs/user/accessibility_inspector/screen_shot_2019-01-29_at_10.11.13.png Binary files differnew file mode 100644 index 0000000000..acdc675ceb --- /dev/null +++ b/devtools/docs/user/accessibility_inspector/screen_shot_2019-01-29_at_10.11.13.png diff --git a/devtools/docs/user/accessibility_inspector/screen_shot_2019-01-29_at_10.21.07.png b/devtools/docs/user/accessibility_inspector/screen_shot_2019-01-29_at_10.21.07.png Binary files differnew file mode 100644 index 0000000000..edadcac9fb --- /dev/null +++ b/devtools/docs/user/accessibility_inspector/screen_shot_2019-01-29_at_10.21.07.png diff --git a/devtools/docs/user/accessibility_inspector/simulation/28369550088_617db0d6f2_m.jpg b/devtools/docs/user/accessibility_inspector/simulation/28369550088_617db0d6f2_m.jpg Binary files differnew file mode 100644 index 0000000000..2b0243ab10 --- /dev/null +++ b/devtools/docs/user/accessibility_inspector/simulation/28369550088_617db0d6f2_m.jpg diff --git a/devtools/docs/user/accessibility_inspector/simulation/accessibily_color_simulation_menu.jpg b/devtools/docs/user/accessibility_inspector/simulation/accessibily_color_simulation_menu.jpg Binary files differnew file mode 100644 index 0000000000..8b68f4c026 --- /dev/null +++ b/devtools/docs/user/accessibility_inspector/simulation/accessibily_color_simulation_menu.jpg diff --git a/devtools/docs/user/accessibility_inspector/simulation/colorcat_achromatopsia.png b/devtools/docs/user/accessibility_inspector/simulation/colorcat_achromatopsia.png Binary files differnew file mode 100644 index 0000000000..6a3f960682 --- /dev/null +++ b/devtools/docs/user/accessibility_inspector/simulation/colorcat_achromatopsia.png diff --git a/devtools/docs/user/accessibility_inspector/simulation/colorcat_contrastloss.png b/devtools/docs/user/accessibility_inspector/simulation/colorcat_contrastloss.png Binary files differnew file mode 100644 index 0000000000..01f0df8e4f --- /dev/null +++ b/devtools/docs/user/accessibility_inspector/simulation/colorcat_contrastloss.png diff --git a/devtools/docs/user/accessibility_inspector/simulation/colorcat_deuteranopia.png b/devtools/docs/user/accessibility_inspector/simulation/colorcat_deuteranopia.png Binary files differnew file mode 100644 index 0000000000..a784aa09bc --- /dev/null +++ b/devtools/docs/user/accessibility_inspector/simulation/colorcat_deuteranopia.png diff --git a/devtools/docs/user/accessibility_inspector/simulation/colorcat_protanopia.png b/devtools/docs/user/accessibility_inspector/simulation/colorcat_protanopia.png Binary files differnew file mode 100644 index 0000000000..1bfe43b40f --- /dev/null +++ b/devtools/docs/user/accessibility_inspector/simulation/colorcat_protanopia.png diff --git a/devtools/docs/user/accessibility_inspector/simulation/colorcat_tritanopia.png b/devtools/docs/user/accessibility_inspector/simulation/colorcat_tritanopia.png Binary files differnew file mode 100644 index 0000000000..891ddeebcc --- /dev/null +++ b/devtools/docs/user/accessibility_inspector/simulation/colorcat_tritanopia.png diff --git a/devtools/docs/user/accessibility_inspector/simulation/index.rst b/devtools/docs/user/accessibility_inspector/simulation/index.rst new file mode 100644 index 0000000000..2265a44ebf --- /dev/null +++ b/devtools/docs/user/accessibility_inspector/simulation/index.rst @@ -0,0 +1,89 @@ +======================= +Color vision simulation +======================= + +The simulator in the :doc:`Accessibility Inspector <../index>` in Firefox Developer Tools lets you see what a web page would look like to users with various forms of *color vision deficiency* (better known as "color blindness"), as well as *contrast sensitivity loss*. + +"Color blindness" is a bit of a misnomer, since most people with these disorders can see colors, but do not see all of the distinctions that people with normal color vision can see; color vision deficiencies affect perception across the color spectrum, not only of specific colors like red or green. Color vision deficiencies affect about 8% of men, and 0.5% of women. The most common forms of color blindness (commonly lumped together as "red-green color blindness") affect more men than women, because they are due to a mutation in a gene in the X chromosome, which men usually have only one copy of. + +Contrast sensitivity loss can be caused by cataracts, glaucoma, diabetic retinopathy, and other disorders of the retina; it can be age-related, congenital, or due to an injury. + +.. note:: + + This feature depends on webrender, an experimental featurethat is not enabled by default on all platforms. You can force-enablewebrender by settingthe preference ``gfx.webrender.all`` to ``true`` using the `Firefox Configuration Editor <https://support.mozilla.org/en-US/kb/about-config-editor-firefox>`_ (note that if webrender is enabled by default on your platform, the setting has no effect. + + +The current color simulation option may be selected from the **Simulate** menu as shown. + +.. image:: accessibily_color_simulation_menu.jpg + :alt: Simulate menu in Accessibility panel. Used for selecting the simulation mode: None, Protanopia (no red), Deuteranopia (no green), Tritanopia (no blue), Achromatopsia (no color), Contrast loss + :class: center + + +The following table shows a colorful image of a cat's face, and what it looks like in the each of the simulations. + +.. |image1| image:: 28369550088_617db0d6f2_m.jpg + :alt: Colorful image of a cat's face, without modification + +.. |image2| image:: colorcat_protanopia.png + :alt: Colorful image of a cat's face, with protanopia simulation + +.. |image3| image:: colorcat_deuteranopia.png + :alt: Colorful image of a cat's face, with deuteranopia simulation + +.. |image4| image:: colorcat_tritanopia.png + :alt: Colorful image of a cat's face, with tritanopia simulation + +.. |image5| image:: colorcat_achromatopsia.png + :alt: Colorful image of a cat's face, with achromatopsia simulation + +.. |image6| image:: colorcat_contrastloss.png + :alt: Colorful image of a cat's face, with contrast loss simulation + + +.. list-table:: + :widths: 50 50 + :header-rows: 1 + + * - Simulation + - Image displayed + + * - None (Choose this to return to normal display) + - |image1| + + * - Protanopia (no red) + - |image2| + + * - Deuteranopia (no green) + - |image3| + + * - Tritanopia (no blue) + - |image4| + + * - Achromatopsia (no color) + - |image5| + + * - Contrast loss + - |image6| + + +.. note:: + + The simulation transformation matrices are based on the paper: `A Physiologically-based Model for Simulation of Color Vision Deficiency <https://www.inf.ufrgs.br/~oliveira/pubs_files/CVD_Simulation/CVD_Simulation.html>`_, Gustavo M. Machado, Manuel M. OliveiraLeandro A. F. Fernandes, IEEE Transactions on Visualization and Computer Graphics, Volume 15 (2009). + + +.. note:: + Firefox 81 removed unnecessary simulations for *protanomaly*, *deuteranomaly*, and *tritanomaly*, and added a simulation for *achromatopsia* (no color). + + +See also +******** + + +- `Types of color blindness <https://www.color-blindness.com/types-of-color-blindness/>`_ +- `Color blindness simulator <https://www.color-blindness.com/coblis-color-blindness-simulator/>`_ +- `Contrast sensitivity <http://www.vision-and-eye-health.com/contrast-sensitivity.html>`_ +- `Color palettes for color blindness <http://mkweb.bcgsc.ca/colorblind/>`_ +- `Color universal design <https://jfly.uni-koeln.de/color/>`_ +- `WCAG success criterion 1.4.1: Use of color <https://www.w3.org/TR/WCAG21/#use-of-color>`_ +- `WCAG success criterion 1.4.11: Non-text contrast <https://www.w3.org/TR/WCAG21/#non-text-contrast>`_ diff --git a/devtools/docs/user/accessibility_inspector/use-case-fake-button.png b/devtools/docs/user/accessibility_inspector/use-case-fake-button.png Binary files differnew file mode 100644 index 0000000000..1e39c78f4c --- /dev/null +++ b/devtools/docs/user/accessibility_inspector/use-case-fake-button.png diff --git a/devtools/docs/user/accessibility_inspector/use-case-no-label.png b/devtools/docs/user/accessibility_inspector/use-case-no-label.png Binary files differnew file mode 100644 index 0000000000..255aaa35ee --- /dev/null +++ b/devtools/docs/user/accessibility_inspector/use-case-no-label.png diff --git a/devtools/docs/user/accessibility_inspector/web-page-context-menu.png b/devtools/docs/user/accessibility_inspector/web-page-context-menu.png Binary files differnew file mode 100644 index 0000000000..aa7b242b72 --- /dev/null +++ b/devtools/docs/user/accessibility_inspector/web-page-context-menu.png diff --git a/devtools/docs/user/application/index.rst b/devtools/docs/user/application/index.rst new file mode 100644 index 0000000000..d07d4b02b6 --- /dev/null +++ b/devtools/docs/user/application/index.rst @@ -0,0 +1,32 @@ +=========== +Application +=========== + +The **Application panel** provides tools for inspecting and debugging modern web apps (also known as `Progressive Web Apps <https://developer.mozilla.org/en-US/docs/Glossary/Progressive_web_apps>`_). This includes inspection of `service workers <https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API>`_ and `web app manifests <https://developer.mozilla.org/en-US/docs/Web/Manifest>`_. + +.. image:: sw-registered.jpg + :alt: the firefox application panel zoomed out view showing a picture of two arctic foxes + :class: border + + +Accessing the Application panel +******************************* + +The Application panel is available on the standard DevTools tab menu under *Application*, in Firefox 79+. If you can’t see it there, you can enable it by going to the "three dot" menu and selecting *Settings* (also accessible by pressing F1), then checking the *Application* checkbox under *Default Developer Tools*. + + +Finding an example +****************** + +If you want to test this functionality and you don't have a handy PWA available, you can grab one of our simple examples to use: + +- Add to homescreen demo: Shows pictures of foxes (`source code <https://github.com/mdn/pwa-examples/tree/master/a2hs>`__ | `live version <https://mdn.github.io/pwa-examples/a2hs/>`__) + +- Js13kpwa demo: Show information on entries to the JS13K annual competition (`source code <https://github.com/mdn/pwa-examples/tree/master/js13kpwa>`__ | `live version <https://mdn.github.io/pwa-examples/js13kpwa/>`__) + + +How to +****** + +- :doc:`Debug service workers <service_workers/index>` +- :doc:`Inspect web app manifests <manifests/index>` diff --git a/devtools/docs/user/application/manifests/index.rst b/devtools/docs/user/application/manifests/index.rst new file mode 100644 index 0000000000..2a17057cd0 --- /dev/null +++ b/devtools/docs/user/application/manifests/index.rst @@ -0,0 +1,47 @@ +============================ +Inspecting web app manifests +============================ + +In this article we will look at inspecting `app manifests <https://developer.mozilla.org/en-US/docs/Web/Manifest>`_ using the Firefox DevTools :doc:`Application panel <../index>`. + +When you open the Application panel’s *Manifest* view on a page that doesn't have an app manifest successfully deployed, you'll get the following output shown: + +.. image:: no-manifest.jpg + :alt: default manifest view saying that you need to add a manifest to inspect it. + :class: border + + +Deploying a manifest +******************** + +To get a manifest deployed successfully, you need to include a `<link> <https://developer.mozilla.org/en-US/docs/Web/HTML/Element/link>`_ element in the `<head> <https://developer.mozilla.org/en-US/docs/Web/HTML/Element/head>`_ of your document that points to your ``.webmanifest`` file: + + +.. code-block:: html + + <link rel="manifest" href="/manifest.webmanifest"> + + +The ``.webmanifest`` extension is recommended in the spec, and should be served with an ``application/manifest+json`` mime type, although browsers generally tend to support manifests with other appropriate extensions like ``.json`` (mime type: ``application/json``). + +You also need to make sure the JSON inside the file is of the correct format. You can test this using the `Web Manifest Validator <https://manifest-validator.appspot.com/>`_. + + +Inspecting your manifest +************************ + +If your manifest is deployed successfully, you should end up with a display like the following on the *Manifest* view: + +.. image:: manifest-deployed.jpg + :alt: manifest view showing a deployed manifest, with identity, presentation, and icon information shown + :class: border + +From here, you can inspect all the information in the manifest in an easy-to-digest way, making sure that it is all correct. It provides a link to the manifest file at the top which when clicked on brings up the JSON in a new tab. + +It also loads all the icon files into the view, so you can see the relative size of them all, and any other information associated with them. + + +List of manifest members +************************ + +We won't provide an exhaustive list of all the members that can appear in a web manifest here; you can already find that in our `web manifest documentation <https://developer.mozilla.org/en-US/docs/Web/Manifest#members>`_. diff --git a/devtools/docs/user/application/manifests/manifest-deployed.jpg b/devtools/docs/user/application/manifests/manifest-deployed.jpg Binary files differnew file mode 100644 index 0000000000..382160b121 --- /dev/null +++ b/devtools/docs/user/application/manifests/manifest-deployed.jpg diff --git a/devtools/docs/user/application/manifests/no-manifest.jpg b/devtools/docs/user/application/manifests/no-manifest.jpg Binary files differnew file mode 100644 index 0000000000..36426b94c6 --- /dev/null +++ b/devtools/docs/user/application/manifests/no-manifest.jpg diff --git a/devtools/docs/user/application/service_workers/cache-network.jpg b/devtools/docs/user/application/service_workers/cache-network.jpg Binary files differnew file mode 100644 index 0000000000..0498335155 --- /dev/null +++ b/devtools/docs/user/application/service_workers/cache-network.jpg diff --git a/devtools/docs/user/application/service_workers/index.rst b/devtools/docs/user/application/service_workers/index.rst new file mode 100644 index 0000000000..11178d741b --- /dev/null +++ b/devtools/docs/user/application/service_workers/index.rst @@ -0,0 +1,116 @@ +========================= +Debugging service workers +========================= + +In this article we will look at debugging `service workers <https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API>`_ using the Firefox DevTools :doc:`Application Panel <../index>`. + +When you open the Application panel’s *Service Workers* view on a page that doesn't have a service worker registered, you'll get the following output shown: + +.. image:: no-service-worker.jpg + :alt: the application panel with a message stating that you need to register a service worker to inspect it here + :class: border + +This gives you some advice on what to do if you don't have a service worker registered, and were perhaps expecting there to be one registered! Let's start by troubleshooting this. + + +Getting your service worker to register +*************************************** + +Before you can look at your service worker in action in the *Applications* panel, you need to successfully register it. Registration is done with a block of code along these lines, using the `register() <https://developer.mozilla.org/en-US/docs/Web/API/ServiceWorkerContainer/register>`_ method: + +.. code-block:: JavaScript + + if('serviceWorker' in navigator) { + navigator.serviceWorker + .register('sw.js') + .then(function() { console.log('Service Worker Registered'); }); + } + +If you get the path wrong, for example, you'll get an error in the :doc:`Web Console <../../web_console/index>` giving you a hint as to what's wrong, which depends on what exactly is wrong with the code. If this is not enough to help you figure out the problem, you could also try going to the :doc:`JavaScript Debugger <../../debugger/index>` and stepping through your code to pinpoint exactly where it is going wrong. + + +Debugging your service worker +***************************** + +In any case, when the service worker is successfully registered, you'll see information about it displayed in the *Application* > *Service Workers* view (along with any other service workers registered on the same domain): + +.. image:: sw-registered.jpg + :alt: the application panel showing a registered service worker + :class: border + +This gives you a variety of information about your service worker: + + +- The URL that the service worker is registered on. +- That last time the service worker was updated (if the service has not been updated, this is when it was first installed). +- The path to the service worker source file. +- The server worker’s status, which can be one of the following: + + - *Stopped*: The service worker is installed, but not currently running. When the service worker is stopped, a *Start* button is provided to start it running, allowing you to trigger the service worker lifecycle. + - *Running*: The service worker is running. + +There are a couple of other useful controls on this view, too. + + +Unregister +********** + +On the right-hand side of the *Service Workers* view there is an *Unregister* button, which when pressed unregisters the service worker. This is very useful because, once registered, the service worker will not necessarily update to the new version immediately, which can make debugging a pain. From `Updating your service worker <https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API/Using_Service_Workers#updating_your_service_worker>`_: + +*If your service worker has previously been installed, but then a new version of the worker is available on refresh or page load, the new version is installed in the background, but not yet activated. It is only activated when there are no longer any pages loaded that are still using the old service worker. As soon as there are no more such pages still loaded, the new service worker activates.* + + +Debug +***** + +.. warning:: + + **Important**: The *debugging* feature is currently enabled only in Firefox Nightly via the experimental feature "Developer Tools: Service Worker debugging". Enabling this can degrade the performance of the Debugger. See about:preferences#experimental. + + +When your service worker is running, the *Arrow* button available next to the Source information (it is disabled when the service worker is stopped). When pressed (and if service worker debugging is enabled), this takes you straight to the :doc:`JavaScript debugger <../../debugger/index>` view of your service worker code, and you can use the full power of the debugger to debug it — stepping through code, etc. + +.. image:: sw-debugger.jpg + :alt: the firefox JS debugger show the code for a service worker + :class: border + + +Testing a service worker cache +****************************** + +If you are using your service worker to store your site assets in Cache Storage (using the `Cache API <https://developer.mozilla.org/en-US/docs/Web/API/Cache>`_), which is essential for creating offline apps, it can be annoying to test the cache. When you fill up the cache with assets, but then want to alter the behavior slightly, you previously had to manually write code to empty the cache, and then fill it again. + +The :doc:`Firefox DevTools Storage tab <../../storage_inspector/index>` has a Cache Storage section that lists all the different Caches you have stored under each different origin. + +.. image:: sw-storage.jpg + :alt: the firefox storage inspector showing cache storage items + :class: border + + +Right/:kbd:`Ctrl` clicking on one of the caches gives you two options: + +- *Delete All* — delete all caches under this origin. +- *Delete "name of cache"* — delete only the highlighted cache. + +You can also click on one of the individual items stored in the cache, then Right/:kbd:`Ctrl` click on it to get options for deleting just that item, or every item in the cache. + +These options make it much easier to remove a cache if it is required for testing a code update. + +It is also worth knowing that if you are testing an app's offline capabilities, you'll be able to see whether requests are being retrieved from a service worker-initiated cache rather than from the network by looking at :doc:`Network Monitor <../../network_monitor/index>`. + +.. image:: cache-network.jpg + :alt: the network monitor, showing that requests that come from a cache are marked with service worker + :class: border + +Resources retrieved from the cache are indicated with *service worker* in the *Transferred* column. + + +.. note:: + + There is currently a bug whereby the Network Monitor cannot show network requests from a service worker running in a different process to the application `bug 1432311 <https://bugzilla.mozilla.org/show_bug.cgi?id=1432311>`_. + + +Finding registered service workers on other domains +*************************************************** + +As mentioned above, the *Service Worker* view of the *Application* panel shows all the service workers registered on the current domain. If you want to see a list of information concerning all the service workers registered on your browser, you can visit ``about:debugging#/runtime/this-firefox``. Below the list of installed extensions you'll find a list of all the service workers you have registered. diff --git a/devtools/docs/user/application/service_workers/no-service-worker.jpg b/devtools/docs/user/application/service_workers/no-service-worker.jpg Binary files differnew file mode 100644 index 0000000000..b10e3a0521 --- /dev/null +++ b/devtools/docs/user/application/service_workers/no-service-worker.jpg diff --git a/devtools/docs/user/application/service_workers/sw-debugger.jpg b/devtools/docs/user/application/service_workers/sw-debugger.jpg Binary files differnew file mode 100644 index 0000000000..6580d1b60a --- /dev/null +++ b/devtools/docs/user/application/service_workers/sw-debugger.jpg diff --git a/devtools/docs/user/application/service_workers/sw-registered.jpg b/devtools/docs/user/application/service_workers/sw-registered.jpg Binary files differnew file mode 100644 index 0000000000..d2982d5c51 --- /dev/null +++ b/devtools/docs/user/application/service_workers/sw-registered.jpg diff --git a/devtools/docs/user/application/service_workers/sw-storage.jpg b/devtools/docs/user/application/service_workers/sw-storage.jpg Binary files differnew file mode 100644 index 0000000000..b122977f19 --- /dev/null +++ b/devtools/docs/user/application/service_workers/sw-storage.jpg diff --git a/devtools/docs/user/application/sw-registered.jpg b/devtools/docs/user/application/sw-registered.jpg Binary files differnew file mode 100644 index 0000000000..e3c0aa2bb9 --- /dev/null +++ b/devtools/docs/user/application/sw-registered.jpg diff --git a/devtools/docs/user/browser_console/browser-console-addon-output.png b/devtools/docs/user/browser_console/browser-console-addon-output.png Binary files differnew file mode 100644 index 0000000000..a07d472db3 --- /dev/null +++ b/devtools/docs/user/browser_console/browser-console-addon-output.png diff --git a/devtools/docs/user/browser_console/browser-console-addon.png b/devtools/docs/user/browser_console/browser-console-addon.png Binary files differnew file mode 100644 index 0000000000..4aa274bab8 --- /dev/null +++ b/devtools/docs/user/browser_console/browser-console-addon.png diff --git a/devtools/docs/user/browser_console/browser-console-chromewindow.png b/devtools/docs/user/browser_console/browser-console-chromewindow.png Binary files differnew file mode 100644 index 0000000000..54047a7287 --- /dev/null +++ b/devtools/docs/user/browser_console/browser-console-chromewindow.png diff --git a/devtools/docs/user/browser_console/browser-console-commandline.png b/devtools/docs/user/browser_console/browser-console-commandline.png Binary files differnew file mode 100644 index 0000000000..1dd34bddb1 --- /dev/null +++ b/devtools/docs/user/browser_console/browser-console-commandline.png diff --git a/devtools/docs/user/browser_console/browser-console-modify-ui-osx.png b/devtools/docs/user/browser_console/browser-console-modify-ui-osx.png Binary files differnew file mode 100644 index 0000000000..e73b555a22 --- /dev/null +++ b/devtools/docs/user/browser_console/browser-console-modify-ui-osx.png diff --git a/devtools/docs/user/browser_console/browser-console-modify-ui-windows.png b/devtools/docs/user/browser_console/browser-console-modify-ui-windows.png Binary files differnew file mode 100644 index 0000000000..23c19bbae4 --- /dev/null +++ b/devtools/docs/user/browser_console/browser-console-modify-ui-windows.png diff --git a/devtools/docs/user/browser_console/browser_console_68.png b/devtools/docs/user/browser_console/browser_console_68.png Binary files differnew file mode 100644 index 0000000000..b1646e297b --- /dev/null +++ b/devtools/docs/user/browser_console/browser_console_68.png diff --git a/devtools/docs/user/browser_console/browser_console_68_02.png b/devtools/docs/user/browser_console/browser_console_68_02.png Binary files differnew file mode 100644 index 0000000000..bba33d4a57 --- /dev/null +++ b/devtools/docs/user/browser_console/browser_console_68_02.png diff --git a/devtools/docs/user/browser_console/index.rst b/devtools/docs/user/browser_console/index.rst new file mode 100644 index 0000000000..f0158e09b5 --- /dev/null +++ b/devtools/docs/user/browser_console/index.rst @@ -0,0 +1,159 @@ +=============== +Browser Console +=============== + +The Browser Console is like the :doc:`Web Console <../web_console/index>`, but applied to the whole browser rather than a single content tab. + +So it logs the same sorts of information as the Web Console - network requests, JavaScript, CSS, and security errors and warnings, and messages explicitly logged by JavaScript code. However, rather than logging this information for a single content tab, it logs information for all content tabs, for add-ons, and for the browser's own code. + +If you also want to use the other web developer tools in the regular Web :doc:`Toolbox <../tools_toolbox/index>` with add-on or browser code, consider using the :doc:`Browser Toolbox<../browser_toolbox/index>`. + +Similarly, you can execute JavaScript expressions using the Browser Console. But while the Web Console executes code in the page window scope, the Browser Console executes them in the scope of the browser's chrome window. This means you can interact with all the browser's tabs using the ``gBrowser`` global, and even with the XUL used to specify the browser's user interface. + +.. container:: block_quote + + NB: The Browser Console command line (to execute JavaScript expressions) is disabled by default. To enable it set the ``devtools.chrome.enabled`` preference to ``true`` in about:config, or set the "Enable browser `chrome <https://developer.mozilla.org/en-US/docs/Glossary/Chrome>`_ and add-on debugging toolboxes" (Firefox 40 and later) option in the :doc:`developer tool settings <../settings/index>`. + + +Opening the Browser Console +*************************** + +You can open the Browser Console in one of two ways: + +1. from the menu: select "Browser Console" from the Browser Tools submenu in the Firefox Menu (or Tools menu if you display the menu bar or are on macOS). + +2. from the keyboard: press :kbd:`Ctrl` + :kbd:`Shift` + :kbd:`J` (or :kbd:`Cmd` + :kbd:`Shift` + :kbd:`J` on a Mac). + + +You can also start the Browser Console by launching Firefox from the command line and passing the ``-jsconsole`` argument: + +.. code-block:: bash + + /Applications/FirefoxAurora.app/Contents/MacOS/firefox -jsconsole + +The Browser Console looks like this: + +.. image:: browser_console_68.png + + +You can see that the Browser Console looks and behaves very much like the :doc:`Web Console <../web_console/index>`: + +- most of the window is occupied by a :doc:`pane that display messages <../web_console/console_messages/index>` + +- at the top, a :ref:`toolbar <web_console_ui_tour_toolbar>` enables you to filter the messages that appear. + +- at the bottom, a :doc:`command line interpreter <../web_console/the_command_line_interpreter/index>` enables you to evaluate JavaScript expressions. + + +Beginning with Firefox 68, the Browser Console allows you to show or hide messages from the content process (i.e. the messages from scripts in all the opened pages) by setting or clearing the checkbox labeled **Show Content Messages**. The following image shows the browser console focused on the same page as above after clicking on the **Show Content Messages** checkbox. + +.. image:: browser_console_68_02.png + + +Browser Console logging +*********************** + +The Browser console logs the same sorts of messages as the Web Console: + +- :ref:`HTTP requests <web_console_console_messages>` + +- :doc:`Warnings and errors <../web_console/console_messages/index>` (including JavaScript, CSS, security warnings and errors, and messages explicitly logged by JavaScript code using the `Console API <https://developer.mozilla.org/en-US/docs/Web/API/console>`_ + +- :ref:`Input/output messages <web_console_console_messages_interpreter_io>` commands send to the browser via the command line, and the result of executing them + + +However, it displays such messages from: + +- web content hosted by all browser tabs +- the browser's own code +- add-ons + +Messages from add-ons +--------------------- + +The Browser Console displays messages logged by all Firefox add-ons. + +Console.sys.mjs +~~~~~~~~~~~~~~~ + +To use the console API from a traditional or bootstrapped add-on, get it from the Console module. + +One exported symbol from ``Console.sys.mjs`` is ``console``. Below is an example of how to access it, which adds a message to the Browser Console. + +.. code-block:: JavaScript + + const { console } = ChromeUtils.importESModule("resource://gre/modules/Console.sys.mjs"); + console.log("Hello from Firefox code"); //output messages to the console + +Learn more: + +- `Console API reference <https://developer.mozilla.org/en-US/docs/Web/API/console>`_ +- :searchfox:`Console.sys.mjs source code <toolkit/modules/Console.sys.mjs>` + + +Browser Console command line +**************************** + +.. container:: block_quote + + The Browser Console command line is disabled by default. To enable it set the ``devtools.chrome.enabled`` preference to ``true`` in ``about:config``, or set the "Enable chrome debugging" option in the :doc:`developer tool settings <../settings/index>`. + + +Like the Web Console, the command line interpreter enables you to evaluate JavaScript expressions in real time: + +.. image:: browser-console-commandline.png + +Also like the Web Console's command line interpreter, this command line supports autocomplete, history, and various :ref:`keyboard shortcuts <keyboard-shortcuts-web-console>` and :doc:`helper commands <../web_console/helpers/index>`. If the result of a command is an object, you can click on the object to see its details. + +But while the Web Console executes code in the scope of the content window it's attached to, the browser console executes code in the scope of the chrome window of the browser. You can confirm this by evaluating ``window``: + +.. image:: browser-console-chromewindow.png + +This means you can control the browser: opening, closing tabs and windows and changing the content that they host, and modify the browser's UI by creating, changing and removing XUL elements. + + +Controlling the browser +----------------------- + +The command line interpreter gets access to the ``tabbrowser`` object, through the ``gBrowser`` global, and that enables you to control the browser through the command line. Try running this code in the Browser Console's command line (remember that to send multiple lines to the Browser Console, use :kbd:`Shift` + :kbd:`Enter`): + +.. code-block:: JavaScript + + var newTabBrowser = gBrowser.getBrowserForTab(gBrowser.selectedTab); + newTabBrowser.addEventListener("load", function() { + newTabBrowser.contentDocument.body.innerHTML = "<h1>this page has been eaten</h1>"; + }, true); + newTabBrowser.contentDocument.location.href = "https://mozilla.org/"; + + +It adds a listener to the currently selected tab's ``load`` event that will eat the new page, then loads a new page. + +.. note:: + + You can restart the browser with the command :kbd:`Ctrl` + :kbd:`Alt` + :kbd:`R` (Windows, Linux) or :kbd:`Cmd` + :kbd:`Alt` + :kbd:`R` (Mac) This command restarts the browser with the same tabs open as before the restart. + + +Modifying the browser UI +------------------------ + +Since the global ``window`` object is the browser's chrome window, you can also modify the browser's user interface. On Windows, the following code will add a new item to the browser's main menu: + +.. code-block:: JavaScript + + var parent = window.document.getElementById("appmenuPrimaryPane"); + var makeTheTea = gBrowser.ownerDocument.defaultView.document.createElementNS("http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul", "menuitem"); + makeTheTea.setAttribute("label", "A nice cup of tea?"); + parent.appendChild(makeTheTea); + +.. image:: browser-console-modify-ui-windows.png + +On macOS, this similar code will add a new item to the **Tools** menu: + +.. code-block:: JavaScript + + var parent = window.document.getElementById("menu_ToolsPopup"); + var makeTheTea = gBrowser.ownerDocument.defaultView.document.createElementNS("http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul", "menuitem"); + makeTheTea.setAttribute("label", "A nice cup of tea?"); + parent.appendChild(makeTheTea); + +.. image:: browser-console-modify-ui-osx.png diff --git a/devtools/docs/user/browser_toolbox/2014-01-10-13-08-08-f52b8c.png b/devtools/docs/user/browser_toolbox/2014-01-10-13-08-08-f52b8c.png Binary files differnew file mode 100644 index 0000000000..8a1cb2b691 --- /dev/null +++ b/devtools/docs/user/browser_toolbox/2014-01-10-13-08-08-f52b8c.png diff --git a/devtools/docs/user/browser_toolbox/browser-toolbox-iframes.png b/devtools/docs/user/browser_toolbox/browser-toolbox-iframes.png Binary files differnew file mode 100644 index 0000000000..8994e023bf --- /dev/null +++ b/devtools/docs/user/browser_toolbox/browser-toolbox-iframes.png diff --git a/devtools/docs/user/browser_toolbox/browser-toolbox-warning.png b/devtools/docs/user/browser_toolbox/browser-toolbox-warning.png Binary files differnew file mode 100644 index 0000000000..9fea742a25 --- /dev/null +++ b/devtools/docs/user/browser_toolbox/browser-toolbox-warning.png diff --git a/devtools/docs/user/browser_toolbox/browser-toolbox.png b/devtools/docs/user/browser_toolbox/browser-toolbox.png Binary files differnew file mode 100644 index 0000000000..e0881c1e1d --- /dev/null +++ b/devtools/docs/user/browser_toolbox/browser-toolbox.png diff --git a/devtools/docs/user/browser_toolbox/index.rst b/devtools/docs/user/browser_toolbox/index.rst new file mode 100644 index 0000000000..cf3fbdefba --- /dev/null +++ b/devtools/docs/user/browser_toolbox/index.rst @@ -0,0 +1,74 @@ +=============== +Browser Toolbox +=============== + +The Browser Toolbox enables you to debug add-ons and the browser's own JavaScript code rather than just web pages like the normal :doc:`Toolbox <../tools_toolbox/index>`. The Browser Toolbox's context is the whole browser rather than justsingle page on a single tab. + +Enabling the Browser Toolbox +**************************** + +The Browser Toolbox is not enabled by default. To enable it you need to check the settings "Enable chrome and addon debugging" and "Enable remote debugging". + +To do this, open the Developer Tools :doc:`Settings <../settings/index>`, go to the section :ref:`Advanced Settings <settings_advanced_settings>`, and check the settings "Enable browser chrome and add-on debugging toolboxes" and "Enable remote debugging". + +.. image:: settings_for_browser_debugger.png + :alt: Developer Tools Settings + :class: border + + +Opening the Browser Toolbox +*************************** + +.. |image1| image:: 2014-01-10-13-08-08-f52b8c.png + :alt: new fx menu + +Open the Browser Toolbox through the menu button |image1| and the menu items "Developer" then "Browser Toolbox". + +You can also open it with the :kbd:`Ctrl` + :kbd:`Alt` + :kbd:`Shift` + :kbd:`I` key combination (:kbd:`Cmd` + :kbd:`Opt` + :kbd:`Shift` + :kbd:`I` on a Mac). + +You will be presented with a dialog like this (it can be removed by setting the ``devtools.debugger.prompt-connection`` property to false): + +.. image:: browser-toolbox-warning.png + +Click OK, and the Browser Toolbox will open in its own window: + +.. image:: browser-toolbox.png + +You'll be able to inspect the browser's chrome windows and see, and be able to debug, all the JavaScript files loaded by the browser itself and by any add-ons that are running. Altogether you will have access to the following developer tools: + + +- :doc:`Debugger <../debugger/index>` +- :doc:`Console <../browser_console/index>` +- :doc:`Style Editor <../style_editor/index>` +- :doc:`Performance <../performance/index>` +- :doc:`Network Monitor <../network_monitor/index>` +- :doc:`Page Inspector <../page_inspector/index>` +- :doc:`Accessibility Inspector <../accessibility_inspector/index>` + +You can debug chrome: and about: pages using the normal :doc:`Debugger <../debugger/index>`, just as if they were ordinary content pages. + + +Targeting a document +******************** + +In the normal toolbox, there's a :doc:`button in the toolbar enabling you to target specific iframes in the document <../working_with_iframes/index>`. The same button appears in the browser toolbox where it lists all the top-level chrome and content windows as well as any iframes they contain. This enables you to inspect documents in individual chrome windows and popups, as well as in content tabs. + +For example, here's what the frame selection popup lists when there are two browser windows open, one with one content tab, and one with two: + +.. image:: browser-toolbox-iframes.png + + +Debugging popups +**************** + +It's hard to debug popups, because the browser hides them as soon as you click outside them. There is a way to disable this behavior. Click the toolbox menu and select **Disable popup auto-hide**. + +.. image:: popup_auto-hide.png + :class: center + +Now when you open any popup, it will stay open until you press the :kbd:`Esc` key. You can use the Inspector's node picker to select that panel, and examine and modify its content. + +You can use the same technique to debug `popups created by add-ons <https://extensionworkshop.com/documentation/develop/debugging/#debugging_popups>`_. + +.. note:: + This change is not persistent across browser restarts. When you close the browser toolbox, the setting will be cleared. diff --git a/devtools/docs/user/browser_toolbox/popup_auto-hide.png b/devtools/docs/user/browser_toolbox/popup_auto-hide.png Binary files differnew file mode 100644 index 0000000000..ccdbeae32b --- /dev/null +++ b/devtools/docs/user/browser_toolbox/popup_auto-hide.png diff --git a/devtools/docs/user/browser_toolbox/settings_for_browser_debugger.png b/devtools/docs/user/browser_toolbox/settings_for_browser_debugger.png Binary files differnew file mode 100644 index 0000000000..a11b54b375 --- /dev/null +++ b/devtools/docs/user/browser_toolbox/settings_for_browser_debugger.png diff --git a/devtools/docs/user/camera_button.png b/devtools/docs/user/camera_button.png Binary files differnew file mode 100644 index 0000000000..330dea7056 --- /dev/null +++ b/devtools/docs/user/camera_button.png diff --git a/devtools/docs/user/close_button.png b/devtools/docs/user/close_button.png Binary files differnew file mode 100644 index 0000000000..85a1593767 --- /dev/null +++ b/devtools/docs/user/close_button.png diff --git a/devtools/docs/user/custom_formatters/custom-formatter-error.png b/devtools/docs/user/custom_formatters/custom-formatter-error.png Binary files differnew file mode 100644 index 0000000000..5686c6493f --- /dev/null +++ b/devtools/docs/user/custom_formatters/custom-formatter-error.png diff --git a/devtools/docs/user/custom_formatters/date-custom-formatter-example.png b/devtools/docs/user/custom_formatters/date-custom-formatter-example.png Binary files differnew file mode 100644 index 0000000000..15d970ad75 --- /dev/null +++ b/devtools/docs/user/custom_formatters/date-custom-formatter-example.png diff --git a/devtools/docs/user/custom_formatters/enable-custom-formatters-setting.png b/devtools/docs/user/custom_formatters/enable-custom-formatters-setting.png Binary files differnew file mode 100644 index 0000000000..6abf7aecbb --- /dev/null +++ b/devtools/docs/user/custom_formatters/enable-custom-formatters-setting.png diff --git a/devtools/docs/user/custom_formatters/index.rst b/devtools/docs/user/custom_formatters/index.rst new file mode 100644 index 0000000000..c3c4dc65a6 --- /dev/null +++ b/devtools/docs/user/custom_formatters/index.rst @@ -0,0 +1,307 @@ +================= +Custom Formatters +================= + +Custom formatters allow a website to control the display of variables within the :doc:`Web Console <../web_console/index>` and the :doc:`Debugger <../debugger/index>`. + +This feature can be particularly useful for web applications that deal with complex object structures, or for JavaScript frameworks that define objects for native variables, or for frameworks that compile to JavaScript like ClojureScript. + +Custom formatting enhances the debugging process by displaying a more intuitive and informative representation of their variables. + +Enabling custom formatting +************************** + +To enable custom formatting, switch to the :doc:`Settings <../settings/index>` panel and check the option called "Enable custom formatters" under "Advanced settings". The setting takes effect the next time you open the DevTools. + +.. image:: enable-custom-formatters-setting.png + +API +*** + +Once custom formatters are enabled, websites can customize how certain variables are displayed in the Web Console and the Debugger. This is achieved by defining custom formatters using a global array called ``devtoolsFormatters``. Each entry in this array represents a specific formatter that may handle a particular type of variable. If there's no formatter defined for a variable, it is displayed using its default formatting. + +Custom formatter structure +-------------------------- + +Each formatter must at least contain a ``header`` function. This function must either return a JsonML array or ``null``. If ``null`` is returned, the ``header`` function of the next entry in ``devtoolsFormatters`` will be called. If all ``header`` functions return ``null``, then the object will be displayed with the default rendering of the DevTools. + +In addition to the ``header`` function, a formatter can contain a ``body`` function. The existence of a ``body`` is indicated by the ``hasBody`` function. If ``hasBody`` returns ``true``, the object can be expanded to show more details. The actual body is then returned by the ``body`` function. Like the ``header`` function, it can either return a JsonML object or ``null``. + +All three functions take the object as the first parameter and an optional configuration object as the second parameter, which allows passing additional information. + +Here's a more detailed description of the functions: + +``header(object, config)`` + Returns a JsonML array or ``null``. If ``null`` is returned, the default format is used to display the object. + The ``config`` parameter is optional. This parameter can be passed using the special ``object`` template (see :ref:`generating-child-elements`). + +``hasBody(object, config)`` + Returns a boolean indicating whether the object can be expanded to show more details. + The ``config`` parameter is optional. This parameter can be passed using the special ``object`` template (see :ref:`generating-child-elements`). + +``body(object, config)`` + Returns a JsonML array or ``null``. If ``null`` is returned, the default format is used to display the object. + The ``config`` parameter is optional. This parameter can be passed using the special ``object`` template (see :ref:`generating-child-elements`). + +HTML template format +-------------------- + +Each HTML template is encoded in a format based on the `JsonML <http://www.jsonml.org/>`_ standard. Each element is represented as list in the format + +.. code-block:: javascript + + [tagName, {"style": "name: value; ..."}, child1, …] + +The following HTML tags are allowed: + +``<span>``, ``<div>``, ``<ol>``, ``<ul>``, ``<li>``, ``<table>``, ``<tr>``, and ``<td>``. + +The optional ``style`` attribute may contain a string of CSS declarations. CSS properties that can be applied are: + +- ``align*`` +- ``background*`` (``background-image`` only allows ``data:`` URLs) +- ``border*`` +- ``box*`` +- ``clear`` +- ``color`` +- ``cursor`` +- ``display`` +- ``float`` +- ``font*`` +- ``justify*`` +- ``line*`` +- ``margin*`` +- ``padding*`` +- ``position`` (only the values ``static`` and ``relative`` are accepted) +- ``text*`` +- ``transition*`` +- ``outline*`` +- ``vertical-align`` +- ``white-space`` +- ``word*`` +- ``writing*`` +- ``width`` +- ``min-width`` +- ``max-width`` +- ``height`` +- ``min-height`` +- ``max-height`` + +A child can be another element, a string, or an object reference. + +.. _generating-child-elements: + +Generating child elements +------------------------- + +Child elements can be created by defining a special ``object`` template. The format of this template is: + +.. code-block:: javascript + + ["object", {"object": objectToInspect, "config": configObject}] + +Examples +******** + +Simple example +-------------- + +Let's take a look at a simple example to illustrate the concept of custom formatters: + +.. code-block:: javascript + + window.devtoolsFormatters = [ + { + header: variable => { + if (variable.hasOwnProperty('foo')) { + return [ + 'span', { + 'style': ` + font-family: "Comic Sans MS", fantasy; + font-size: 3rem; + color: green; + ` + }, + 'foo' + ]; + } + return null; + } + } + ]; + +In the example above, a custom formatter is defined for a variable. The `header` property of the formatter is a function that determines how the variable is displayed. In this case, if the variable has a property named `foo`, it will be rendered as a `<span>` element with a specific style. It will be logged to the Web Console like this: + +.. image:: simple-custom-formatter-example.png + +Complete example +---------------- + +For a more complex example, let's consider displaying a `Date` object: + +.. code-block:: html + + <!DOCTYPE html> + <html> + <head> + <title>Custom formatter for dates</title> + </head> + <body> + <script> + window.devtoolsFormatters = [ + { + header: obj => { + if (obj instanceof Date) { + return ['div', {'style': 'font-weight: bold;'}, + `Date: ${obj.toLocaleDateString()} ${obj.toLocaleTimeString()}` + ]; + } + return null; + }, + hasBody: obj => obj instanceof Date, + body: obj => { + if (obj instanceof Date) { + return ['div', {}, + ['div', {}, `Year: ${obj.getFullYear()}`], + ['div', {}, `Month: ${obj.getMonth() + 1}`], + ['div', {}, `Day: ${obj.getDate()}`], + ['div', {}, `Hour: ${obj.getHours()}`], + ['div', {}, `Minutes: ${obj.getMinutes()}`], + ['div', {}, `Seconds: ${obj.getSeconds()}`] + ]; + } + return null; + } + } + ]; + </script> + </body> + </html> + +With this custom formatter, a ``Date`` object logged to the console will display the date and time in a formatted manner, along with separate breakdowns of its individual components. Within the console, the object will be logged like this: + +.. image:: date-custom-formatter-example.png + +Example with object references +------------------------------ + +.. code-block:: html + + <!DOCTYPE html> + <html> + <head> + <meta charset="utf-8"/> + <title>Menu custom formatter</title> + <script> + const menu = [ + { + url: '/', + text: 'Home', + }, + { + url: '/nested', + text: 'Nested', + subitems: [ + { + url: '/nested/1', + text: 'Nested 1' + }, + { + url: '/nested/2', + text: 'Nested 2', + subitems: [ + { + url: '/nested/2/1', + text: 'Nested 2.1' + }, + { + url: '/nested/2/2', + text: 'Nested 2.2' + } + ] + }, + { + url: '/nested/3', + text: 'Nested 3' + } + ] + }, + { + url: '/about', + text: 'About' + }, + { + url: '/contact', + text: 'Contact' + } + ]; + + window.devtoolsFormatters = [ + { + header: (obj, config) => { + if (obj instanceof Array && obj.every(item => item.hasOwnProperty('url') && item.hasOwnProperty('text'))) { + return ['div', {'style': 'font-weight: bold;'}, `Menu: ${obj.length} entries`]; + } + return null; + }, + hasBody: obj => obj instanceof Array && obj.every(item => item.hasOwnProperty('url') && item.hasOwnProperty('text')), + body: (obj, config) => { + const levelColors = ['red', 'blue', 'green']; + if (config === undefined) { + config = { level: 0 }; + } else { + config.level++; + } + + return ['div', {'style': `margin-left: 15px; color: ${levelColors[config.level % levelColors.length]}`}, ...obj.map(item => { + const subitem = ['div', ['div', `${item.text}: ${item.url}`]]; + if (item.hasOwnProperty('subitems')) { + subitem.push(['object', {'object': item.subitems, config: {level: config.level}}]); + } + return subitem; + })]; + } + } + ]; + console.log(menu); + </script> + </head> + <body> + </body> + </html> + +This example displays a menu object with nested subitems. The custom formatter is recursive, so it will display all subitems as well. The output of this example looks like this: + +.. image:: menu.png + +Debugging Custom Formatters +*************************** + +If a custom formatter contains an error, an error message is logged to the console, explaining the issue. Whenever possible, the error message also includes a source link pointing to the exact location of the error within the code. + +.. image:: custom-formatter-error.png + +Further tips +************ + +- Analyze the structure and behavior of the variables you intend to format, understanding the key properties or class hierarchy that differentiate them. +- When testing for an object's type, use ``instanceof`` if the objects are instances of a specific class. If the objects are plain objects, use ``hasOwnProperty`` to check for particular properties. +- Test your formatters with different types of variables to ensure they function as expected and handle various cases accurately. +- Nest formatters by :ref:`generating-child-elements` to display complex objects in a more readable manner. +- Use the ``config`` parameter to pass additional information to the formatter, such as the current level of recursion. +- If you have multiple formatters, keep in mind to check for the type of the object in each formatter, and return ``null`` if the object is not of the expected type. Otherwise, the formatter will be applied to all objects, which may result in unexpected behavior. +- Choose your formatting wisely. For large objects it may be better to display only a summary of the object, and allow the user to expand it if needed. +- Each logged object will call the formatters hooks, which can have an impact on performance. So you should aim for small and fast hooks. + +Existing Formatters +******************* + +There are existing formatters available that cover different needs. Some examples include: + +- `andrewdavey/immutable-devtools <https://github.com/andrewdavey/immutable-devtools>`_: Custom formatter for Immutable-js values +- `disjukr/vector-devtools <https://github.com/disjukr/vector-devtools#vector-devtools>`_: Custom formatter for vector values +- `binaryage/cljs-devtools <https://github.com/binaryage/cljs-devtools#cljs-devtools---->`_: Collection of DevTools enhancements for ClojureScript developers +- Three.js object formatters: + + - `twitter.com/thespite/status/656585905151545344 <https://twitter.com/thespite/status/656585905151545344>`_ + - `twitter.com/thespite/status/656499298230734849 <https://twitter.com/thespite/status/656499298230734849>`_ diff --git a/devtools/docs/user/custom_formatters/menu.png b/devtools/docs/user/custom_formatters/menu.png Binary files differnew file mode 100644 index 0000000000..76ddc83055 --- /dev/null +++ b/devtools/docs/user/custom_formatters/menu.png diff --git a/devtools/docs/user/custom_formatters/simple-custom-formatter-example.png b/devtools/docs/user/custom_formatters/simple-custom-formatter-example.png Binary files differnew file mode 100644 index 0000000000..899a0a6e1d --- /dev/null +++ b/devtools/docs/user/custom_formatters/simple-custom-formatter-example.png diff --git a/devtools/docs/user/debugger-api/debugger.environment/index.rst b/devtools/docs/user/debugger-api/debugger.environment/index.rst new file mode 100644 index 0000000000..43baa06f25 --- /dev/null +++ b/devtools/docs/user/debugger-api/debugger.environment/index.rst @@ -0,0 +1,98 @@ +==================== +Debugger.Environment +==================== + +A ``Debugger.Environment`` instance represents a lexical environment, associating names with variables. Each :doc:`Debugger.Frame <../debugger.frame/index>` instance representing a debuggee frame has an associated environment object describing the variables in scope in that frame; and each :doc:`Debugger.Object <../debugger.object/index>` instance representing a debuggee function has an environment object representing the environment the function has closed over. + +ECMAScript environments form a tree, in which each local environment is parented by its enclosing environment (in ECMAScript terms, its ‘outer’ environment). We say an environment *binds* an identifier if that environment itself associates the identifier with a variable, independently of its outer environments. We say an identifier is *in scope* in an environment if the identifier is bound in that environment or any enclosing environment. + +SpiderMonkey creates ``Debugger.Environment`` instances as needed as the debugger inspects stack frames and function objects; calling ``Debugger.Environment`` as a function or constructor raises a ``TypeError`` exception. + +SpiderMonkey creates exactly one ``Debugger.Environment`` instance for each environment it presents via a given :doc:`Debugger <../debugger/index>` instance: if the debugger encounters the same environment through two different routes (perhaps two functions have closed over the same environment), SpiderMonkey presents the same ``Debugger.Environment`` instance to the debugger each time. This means that the debugger can use the ``==`` operator to recognize when two ``Debugger.Environment`` instances refer to the same environment in the debuggee, and place its own properties on a ``Debugger.Environment`` instance to store metadata about particular environments. + +(If more than one :doc:`Debugger <../debugger/index>` instance is debugging the same code, each :doc:`Debugger <../debugger/index>` gets a separate ``Debugger.Environment`` instance for a given environment. This allows the code using each :doc:`Debugger <../debugger/index>` instance to place whatever properties it likes on its own :doc:`Debugger.Object <../debugger.object/index>` instances, without worrying about interfering with other debuggers.) + +If a ``Debugger.Environment`` instance’s referent is not a debuggee environment, then attempting to access its properties (other than ``inspectable``) or call any its methods throws an instance of ``Error``. + +``Debugger.Environment`` instances protect their referents from the garbage collector; as long as the ``Debugger.Environment`` instance is live, the referent remains live. Garbage collection has no visible effect on ``Debugger.Environment`` instances. + + +Accessor Properties of the Debugger.Environment Prototype Object +**************************************************************** + +A ``Debugger.Environment`` instance inherits the following accessor properties from its prototype: + + +``inspectable`` + + True if this environment is a debuggee environment, and can therefore be inspected. False otherwise. All other properties and methods of ``Debugger.Environment`` instances throw if applied to a non-inspectable environment. + +``type`` + + The type of this environment object, one of the following values: + + - “declarative”, indicating that the environment is a declarative environment record. Function calls, calls to ``eval``, ``let`` blocks, ``catch`` blocks, and the like create declarative environment records. + + - “object”, indicating that the environment’s bindings are the properties of an object. The global object and DOM elements appear in the chain of environments via object environments. (Note that ``with`` statements have their own environment type.) + + - “with”, indicating that the environment was introduced by a ``with`` statement. + +``parent`` + + The environment that encloses this one (the “outer” environment, in ECMAScript terminology), or ``null`` if this is the outermost environment. + +``object`` + + A :doc:`Debugger.Object <../debugger.object/index>` instance referring to the object whose properties this environment reflects. If this is a declarative environment record, this accessor throws a ``TypeError`` (since declarative environment records have no such object). Both ``"object"`` and ``"with"`` environments have ``object`` properties that provide the object whose properties they reflect as variable bindings. + +``callee`` + + If this environment represents the variable environment (the top-level environment within the function, which receives ``var`` definitions) for a call to a function *f*, then this property’s value is a :doc:`Debugger.Object <../debugger.object/index>` instance referring to *f*. Otherwise, this property’s value is ``null``. + +``optimizedOut`` + + True if this environment is optimized out. False otherwise. For example, functions whose locals are never aliased may present optimized-out environments. When true, ``getVariable`` returns an ordinary JavaScript object whose ``optimizedOut`` property is true on all bindings, and ``setVariable`` throws a ``ReferenceError``. + + +Function Properties of the Debugger.Environment Prototype Object +**************************************************************** + +The methods described below may only be called with a ``this`` value referring to a ``Debugger.Environment`` instance; they may not be used as methods of other kinds of objects. + + +``names()`` + + Return an array of strings giving the names of the identifiers bound by this environment. The result does not include the names of identifiers bound by enclosing environments. + +``getVariable(*name*)`` + + Return the value of the variable bound to *name* in this environment, or ``undefined`` if this environment does not bind *name*. *Name* must be a string that is a valid ECMAScript identifier name. The result is a debuggee value. + + JavaScript engines often omit variables from environments, to save space and reduce execution time. If the given variable should be in scope, but ``getVariable`` is unable to produce its value, it returns an ordinary JavaScript object (not a :doc:`Debugger.Object <../debugger.object/index>` instance) whose ``optimizedOut`` property is ``true``. + + This is not an :ref:`invocation function <debugger-api-debugger-frame-invf>`; if this call would cause debuggee code to run (say, because the environment is a ``"with"`` environment, and *name* refers to an accessor property of the ``with`` statement’s operand), this call throws a ``Debugger.DebuggeeWouldRun`` exception. + +``setVariable(*name*,*value*)`` + + Store *value* as the value of the variable bound to *name* in this environment. *Name* must be a string that is a valid ECMAScript identifier name; *value* must be a debuggee value. + + If this environment binds no variable named *name*, throw a ``ReferenceError``. + + This is not an :ref:`invocation function <debugger-api-debugger-frame-invf>`; if this call would cause debuggee code to run, this call throws a ``Debugger.DebuggeeWouldRun`` exception. + +``find(*name*)`` + + Return a reference to the innermost environment, starting with this environment, that binds *name*. If *name* is not in scope in this environment, return ``null``. *Name* must be a string whose value is a valid ECMAScript identifier name. + + +Source Metadata +--------------- + +Generated from file: + js/src/doc/Debugger/Debugger.Environment.md + +Watermark: + sha256:3d6f67939e351803d5d7fe201ed38c4aaf766caf032f255e168df1f1c6fe73cb + +Changeset: + `7ae377917236 <https://hg.mozilla.org/mozilla-central/rev/7ae377917236>`_ diff --git a/devtools/docs/user/debugger-api/debugger.frame/index.rst b/devtools/docs/user/debugger-api/debugger.frame/index.rst new file mode 100644 index 0000000000..b1c53f19e4 --- /dev/null +++ b/devtools/docs/user/debugger-api/debugger.frame/index.rst @@ -0,0 +1,202 @@ +============== +Debugger.Frame +============== + +A ``Debugger.Frame`` instance represents a :ref:`visible stack frame <debugger-api-debugger-frame-visible-frames>`. Given a ``Debugger.Frame`` instance, you can find the script the frame is executing, walk the stack to older frames, find the lexical environment in which the execution is taking place, and so on. + +For a given :doc:`Debugger <../debugger/index>` instance, SpiderMonkey creates only one ``Debugger.Frame`` instance for a given visible frame. Every handler method called while the debuggee is running in a given frame is given the same frame object. Similarly, walking the stack back to a previously accessed frame yields the same frame object as before. Debugger code can add its own properties to a frame object and expect to find them later, use ``==`` to decide whether two expressions refer to the same frame, and so on. + +(If more than one :doc:`Debugger <../debugger/index>` instance is debugging the same code, each :doc:`Debugger <../debugger/index>` gets a separate ``Debugger.Frame`` instance for a given frame. This allows the code using each :doc:`Debugger <../debugger/index>` instance to place whatever properties it likes on its ``Debugger.Frame`` instances, without worrying about interfering with other debuggers.) + +When the debuggee pops a stack frame (say, because a function call has returned or an exception has been thrown from it), the ``Debugger.Frame`` instance referring to that frame becomes inactive: its ``live`` property becomes ``false``, and accessing its other properties or calling its methods throws an exception. Note that frames only become inactive at times that are predictable for the debugger: when the debuggee runs, or when the debugger removes frames from the stack itself. + + +.. _debugger-api-debugger-frame-visible-frames: + +Visible frames +************** + +When inspecting the call stack, :doc:`Debugger <../debugger/index>` does not reveal all the frames that are actually present on the stack: while it does reveal all frames running debuggee code, it omits frames running the debugger’s own code, and omits most frames running non-debuggee code. We call those stack frames a :doc:`Debugger <../debugger/index>` does reveal *visible frames*. + +A frame is a visible frame if any of the following are true: + + +- it is running debuggee code; + +- its immediate caller is a frame running debuggee code; or + +- it is a :ref:`"debugger" <debugger-api-debugger-frame-invf>`, representing the continuation of debuggee code invoked by the debugger. + + +The “immediate caller” rule means that, when debuggee code calls a non-debuggee funct`on, it looks like a call to a primitive: you see a frame for the non-debuggee function that was accessible to the debuggee, but any further calls that function makes are treated as internal details, and omitted from the stack trace. If the non-debuggee function eventually calls back into debuggee code, then those frames are visible. + +(Note that the debuggee is not considered an “immediate caller” of handler methods it triggers. Even though the debuggee and debugger share the same JavaScript stack, frames pushed for SpiderMonkey’s calls to handler methods to report events in the debuggee are never considered visible frames.) + + +.. _debugger-api-debugger-frame-invf: + +Invocation functions and Debugger frames +**************************************** + +An *invocation function* is any function in this interface that allows the debugger to invoke code in the debuggee: ``Debugger.Object.prototype.call``, ``Debugger.Frame.prototype.eval``, and so on. + +While invocation functions differ in the code to be run and how to pass values to it, they all follow this general procedure: + +1. Let *older* be the youngest visible frame on the stack, or ``null`` if there is no such frame. (This is never one of the debugger’s own frames; those never appear as ``Debugger.Frame`` instances.) + +2. Push a ``"debugger"`` frame on the stack, with *older* as its ``older`` property. + +3. Invoke the debuggee code as appropriate for the given invocation function, with the ``"debugger"`` frame as its continuation. For example, ``Debugger.Frame.prototype.eval`` pushes an ``"eval"`` frame for code it runs, whereas ``Debugger.Object.prototype.call`` pushes a ``"call"`` frame. + +4. When the debuggee code completes, whether by returning, throwing an exception or being terminated, pop the ``"debugger"`` frame, and return an appropriate completion value from the invocation function to the debugger. + + +When a debugger calls an invocation function to run debuggee code, that code’s continuation is the debugger, not the next debuggee code frame. Pushing a ``"debugger"`` frame makes this continuation explicit, and makes it easier to find the extent of the stack created for the invocation. + + +Accessor properties of the Debugger.Frame prototype object +********************************************************** + +A ``Debugger.Frame`` instance inherits the following accessor properties from its prototype: + + +``type`` + + A string describing what sort of frame this is: + + - ``"call"``: a frame running a function call. (We may not be able to obtain frames for calls to host functions.) + + - ``"eval"``: a frame running code passed to ``eval``. + - ``"global"``: a frame running global code (JavaScript that is neither of the above). + - ``"module"``: a frame running code at the top level of a module. + - ``"wasmcall"``: a frame running a WebAssembly function call. + - ``"debugger"``: a frame for a call to user code invoked by the debugger (see the ``eval`` method below). + +``implementation`` + + A string describing which tier of the JavaScript engine this frame is executing in: + + - ``"interpreter"``: a frame running in the interpreter. + - ``"baseline"``: a frame running in the unoptimizing, baseline JIT. + - ``"ion"``: a frame running in the optimizing JIT. + - ``"wasm"``: a frame running in WebAssembly baseline JIT. + +``this`` + + The value of ``this`` for this frame (a debuggee value). For a ``wasmcall`` frame, this property throws a ``TypeError``. + +``older`` + + The next-older visible frame, in which control will resume when this frame completes. If there is no older frame, this is ``null``. + +``depth`` + The depth of this frame, counting from oldest to youngest; the oldest frame has a depth of zero. + +``live`` + True if the frame this ``Debugger.Frame`` instance refers to is still on the stack; false if it has completed execution or been popped in some other way. + +``script`` + The script being executed in this frame (a :doc:`Debugger.Script <../debugger.script/index>` instance), or ``null`` on frames that do not represent calls to debuggee code. On frames whose ``callee`` property is not null, this is equal to ``callee.script``. + +``offset`` + The offset of the bytecode instruction currently being executed in ``script``, or ``undefined`` if the frame’s ``script`` property is ``null``. For a ``wasmcall`` frame, this property throws a ``TypeError``. + +``environment`` + The lexical environment within which evaluation is taking place (a :doc:`Debugger.Environment <../debugger.environment/index>` instance), or ``null`` on frames that do not represent the evaluation of debuggee code, like calls non-debuggee functions, host functions or ``"debugger"`` frames. + +``callee`` + The function whose application created this frame, as a debuggee value, or ``null`` if this is not a ``"call"`` frame. + +``generator`` + True if this frame is a generator frame, false otherwise. + +``constructing`` + True if this frame is for a function called as a constructor, false otherwise. + +``arguments`` + The arguments passed to the current frame, or ``null`` if this is not a ``"call"`` frame. When non-``null``, this is an object, allocated in the same global as the debugger, with ``Array.prototype`` on its prototype chain, a non-writable ``length`` property, and properties whose names are array indices. Each property is a read-only accessor property whose getter returns the current value of the corresponding parameter. When the referent frame is popped, the argument value’s properties’ getters throw an error. + + +Handler methods of Debugger.Frame instances +******************************************* + +Each ``Debugger.Frame`` instance inherits accessor properties holding handler functions for SpiderMonkey to call when given events occur in the frame. + +Calls to frames’ handler methods are cross-compartment, intra-thread calls: the call takes place in the thread to which the frame belongs, and runs in the compartment to which the handler method belongs. + +``Debugger.Frame`` instances inherit the following handler method properties: + + +``onStep`` + + This property must be either ``undefined`` or a function. If it is a function, SpiderMonkey calls it when execution in this frame makes a small amount of progress, passing no arguments and providing this ``Debugger.Frame`` instance as the ``this`` value. The function should return a resumption value specifying how the debuggee’s execution should proceed. + + What constitutes “a small amount of progress” varies depending on the implementation, but it is fine-grained enough to implement useful “step” and “next” behavior. + + If multiple :doc:`Debugger <../debugger/index>` instances each have ``Debugger.Frame`` instances for a given stack frame with ``onStep`` handlers set, their handlers are run in an unspecified order. If any ``onStep`` handler forces the frame to return early (by returning a resumption value other than ``undefined``), any remaining debuggers’ ``onStep`` handlers do not run. + + This property is ignored on frames that are not executing debuggee code, like ``"call"`` frames for calls to host functions and ``"debugger"`` frames. + +``onPop`` + + This property must be either ``undefined`` or a function. If it is a function, SpiderMonkey calls it just before this frame is popped, passing a completion value indicating how this frame’s execution completed, and providing this ``Debugger.Frame`` instance as the ``this`` value. The function should return a resumption value indicating how execution should proceed. On newly created frames, this property’s value is ``undefined``. + + When this handler is called, this frame’s current execution location, as reflected in its ``offset`` and ``environment`` properties, is the operation which caused it to be unwound. In frames returning or throwing an exception, the location is often a return or a throw statement. In frames propagating exceptions, the location is a call. + + When an ``onPop`` call reports the completion of a construction call (that is, a function called via the ``new`` operator), the completion value passed to the handler describes the value returned by the function body. If this value is not an object, it may be different from the value produced by the ``new`` expression, which will be the value of the frame’s ``this`` property. (In ECMAScript terms, the ``onPop`` handler receives the value returned by the ``[[Call]]`` method, not the value returned by the ``[[Construct]]`` method.) + + When a debugger handler function forces a frame to complete early, by returning a ``{ return:... }``, ``{ throw:... }``, or ``null`` resumption value, SpiderMonkey calls the frame’s ``onPop`` handler, if any. The completion value passed in this case reflects the resumption value that caused the frame to complete. + + When SpiderMonkey calls an ``onPop`` handler for a frame that is throwing an exception or being terminated, and the handler returns ``undefined``, then SpiderMonkey proceeds with the exception or termination. That is, an ``undefined`` resumption value leaves the frame’s throwing and termination process undisturbed. + + If multiple :doc:`Debugger <../debugger/index>` instances each have ``Debugger.Frame`` instances for a given stack frame with ``onPop`` handlers set, their handlers are run in an unspecified order. The resumption value each handler returns establishes the completion value reported to the next handler. + + This handler is not called on ``"debugger"`` frames. It is also not called when unwinding a frame due to an over-recursion or out-of-memory exception. + + +Function properties of the Debugger.Frame prototype object +********************************************************** + +The functions described below may only be called with a ``this`` value referring to a ``Debugger.Frame`` instance; they may not be used as methods of other kinds of objects. + +.. _debugger-api-debugger-frame-eval: + +``eval(code, [options])`` + + Evaluate *code* in the execution context of this frame, and return a completion value describing how it completed. *Code* is a string. If this frame’s ``environment`` property is ``null`` or ``type`` property is ``wasmcall``, throw a ``TypeError``. All extant handler methods, breakpoints, and so on remain active during the call. This function follows the :ref:`invocation function convention <debugger-api-debugger-frame-invf>`. + + *Code* is interpreted as strict mode code when it contains a Use Strict Directive, or the code executing in this frame is strict mode code. + + If *code* is not strict mode code, then variable declarations in *code* affect the environment of this frame. (In the terms used by the ECMAScript specification, the ``VariableEnvironment`` of the execution context for the eval code is the ``VariableEnvironment`` of the execution context that this frame represents.) If implementation restrictions prevent SpiderMonkey from extending this frame’s environment as requested, this call throws an Error exception. + + If given, *options* should be an object whose properties specify details of how the evaluation should occur. The ``eval`` method recognizes the following properties: + + + ``url`` + The filename or URL to which we should attribute *code*. If this property is omitted, the URL defaults to ``"debugger eval code"``. + ``lineNumber`` + The line number at which the evaluated code should be claimed to begin within *url*. + + +``evalWithBindings(*code*,*bindings*, [*options*])`` + + Like ``eval``, but evaluate *code* in the environment of this frame, extended with bindings from the object *bindings*. For each own enumerable property of *bindings* named *name* whose value is *value*, include a variable in the environment in which *code* is evaluated named *name*, whose value is *value*. Each *value* must be a debuggee value. (This is not like a ``with`` statement: *code* may access, assign to, and delete the introduced bindings without having any effect on the *bindings* object.) + + This method allows debugger code to introduce temporary bindings that are visible to the given debuggee code and which refer to debugger-held debuggee values, and do so without mutating any existing debuggee environment. + + Note that, like ``eval``, declarations in the *code* passed to ``evalWithBindings`` affect the environment of this frame, even as that environment is extended by bindings visible within *code*. (In the terms used by the ECMAScript specification, the ``VariableEnvironment`` of the execution context for the eval code is the ``VariableEnvironment`` of the execution context that this frame represents, and the *bindings* appear in a new declarative environment, which is the eval code’s ``LexicalEnvironment``.) If implementation restrictions prevent SpiderMonkey from extending this frame’s environment as requested, this call throws an ``Error`` exception. + + The *options* argument is as for :ref:`Debugger.Frame.prototype.eval <debugger-api-debugger-frame-eval>`, described above. Also like ``eval``, if this frame’s ``environment`` property is ``null`` or ``type`` property is ``wasmcall``, throw a ``TypeError``. + + +Source Metadata +--------------- + +Generated from file: + js/src/doc/Debugger/Debugger.Frame.md + +Watermark: + sha256:b1894f88b76b7afd661f3044a05690d76d1498c54c596ca729c6ee0d150d2da1 + +Changeset: + `e91b2c85aacd <https://hg.mozilla.org/mozilla-central/rev/e91b2c85aacd>`_ diff --git a/devtools/docs/user/debugger-api/debugger.memory/index.rst b/devtools/docs/user/debugger-api/debugger.memory/index.rst new file mode 100644 index 0000000000..17f659bba8 --- /dev/null +++ b/devtools/docs/user/debugger-api/debugger.memory/index.rst @@ -0,0 +1,240 @@ +=============== +Debugger.Memory +=============== + +The :doc:`Debugger API <../index>` can help tools observe the debuggee’s memory use in various ways: + + +- It can mark each new object with the JavaScript call stack at which it was allocated. + +- It can log all object allocations, yielding a stream of JavaScript call stacks at which allocations have occurred. + +- It can compute a *census* of items belonging to the debuggee, categorizing items in various ways, and yielding item counts. + + +If *dbg* is a :doc:`Debugger <../debugger/index>` instance, then the methods and accessor properties of ``dbg.memory`` control how *dbg* observes its debuggees’ memory use. The ``dbg.memory`` object is an instance of ``Debugger.Memory``; its inherited accessors and methods are described below. + + +Allocation Site Tracking +************************ + +The JavaScript engine marks each new object with the call stack at which it was allocated, if: + + +- the object is allocated in the scope of a global object that is a debuggee of some :doc:`Debugger <../debugger/index>` instance *dbg*; and + +- :ref:`dbg.memory.trackingAllocationSites <debugger-api-debugger-memory-tracking-allocation-sites>` is set to ``true``. + +- A `Bernoulli trial <https://en.wikipedia.org/wiki/Bernoulli_trial>`_ succeeds, with probability equal to the maximum of :ref:`d.memory.allocationSamplingProbability <debugger-api-debugger-memory-alloc-sampling-probability>` of all ``Debugger`` instances ``d`` that are observing the global that this object is allocated within the scope of. + + +Given a :doc:`Debugger.Object <../debugger.object/index>` instance *dobj* referring to some object, :ref:`dobj.allocationSite <debugger-api-debugger-object-allocation-site>` returns a saved call stack indicating where *dobj*’s referent was allocated. + + +Allocation Logging +****************** + +If *dbg* is a :doc:`Debugger <../debugger/index>` instance, and :ref:`dbg.memory.trackingAllocationSites <debugger-api-debugger-memory-tracking-allocation-sites>` is set to ``true``, then the JavaScript engine logs each object allocated by *dbg*’s debuggee code. You can retrieve the current log by calling *dbg.memory.drainAllocationsLog*. You can control the limit on the log’s size by setting :ref:`dbg.memory.maxAllocationsLogLength <debugger-api-debugger-memory-max-alloc-log>`. + + +Censuses +******** + +A *census* is a complete traversal of the graph of all reachable memory items belonging to a particular ``Debugger``‘s debuggees. It produces a count of those items, broken down by various criteria. If *dbg* is a :doc:`Debugger <../debugger/index>` instance, you can call *dbg.memory.takeCensus* to conduct a census of its debuggees’ possessions. + + +Accessor Properties of the ``Debugger.Memory.prototype`` Object +*************************************************************** + +If *dbg* is a :doc:`Debugger <../debugger/index>` instance, then ``dbg.memory`` is a ``Debugger.Memory`` instance, which inherits the following accessor properties from its prototype: + + +.. _debugger-api-debugger-memory-tracking-allocation-sites: + +``trackingAllocationSites`` + + A boolean value indicating whether this ``Debugger.Memory`` instance is capturing the JavaScript execution stack when each Object is allocated. This accessor property has both a getter and setter: assigning to it enables or disables the allocation site tracking. Reading the accessor produces ``true`` if the Debugger is capturing stacks for Object allocations, and ``false`` otherwise. Allocation site tracking is initially disabled in a new Debugger. + + Assignment is fallible: if the Debugger cannot track allocation sites, it throws an ``Error`` instance. + + You can retrieve the allocation site for a given object with the :ref:`Debugger.Object.prototype.allocationSite <debugger-api-debugger-object-allocation-site>` accessor property. + + +.. _debugger-api-debugger-memory-alloc-sampling-probability: + +``allocationSamplingProbability`` + + A number between 0 and 1 that indicates the probability with which each new allocation should be entered into the allocations log. 0 is equivalent to “never”, 1 is “always”, and .05 would be “one out of twenty”. + + The default is 1, or logging every allocation. + + Note that in the presence of multiple ``Debugger`` instances observing the same allocations within a global’s scope, the maximum ``allocationSamplingProbability`` of all the ``Debugger`` is used. + + +.. _debugger-api-debugger-memory-max-alloc-log: + +``maxAllocationsLogLength`` + + The maximum number of allocation sites to accumulate in the allocations log at a time. This accessor can be both fetched and stored to. Its default value is ``5000``. + + +.. _debugger-api-debugger-memory-alloc-log-overflowed: + +``allocationsLogOverflowed`` + + Returns ``true`` if there have been more than [``maxAllocationsLogLength``][#max-alloc-log] allocations since the last time [``drainAllocationsLog``][#drain-alloc-log] was called and some data has been lost. Returns ``false`` otherwise. + + +Debugger.Memory Handler Functions +********************************* + +Similar to :doc:`Debugger's handler functions <../index>`, ``Debugger.Memory`` inherits accessor properties that store handler functions for SpiderMonkey to call when given events occur in debuggee code. + +Unlike ``Debugger``‘s hooks, ``Debugger.Memory``’s handlers’ return values are not significant, and are ignored. The handler functions receive the ``Debugger.Memory``’s owning ``Debugger`` instance as their ``this`` value. The owning ``Debugger``’s ``uncaughtExceptionHandler`` is still fired for errors thrown in ``Debugger.Memory`` hooks. + +On a new ``Debugger.Memory`` instance, each of these properties is initially ``undefined``. Any value assigned to a debugging handler must be either a function or ``undefined``; otherwise a ``TypeError`` is thrown. + +Handler functions run in the same thread in which the event occurred. They run in the compartment to which they belong, not in a debuggee compartment. + + +``onGarbageCollection(statistics)`` + + A garbage collection cycle spanning one or more debuggees has just been completed. + + The *statistics* parameter is an object containing information about the GC cycle. It has the following properties: + + +``collections`` + + The ``collections`` property’s value is an array. Because SpiderMonkey’s collector is incremental, a full collection cycle may consist of multiple discrete collection slices with the JS mutator running interleaved. For each collection slice that occurred, there is an entry in the ``collections`` array with the following form: + + .. code-block:: javascript + + { + "startTimestamp": timestamp, + "endTimestamp": timestamp, + } + + Here the *timestamp* values are timestamps of the GC slice’s start and end events. + +``reason`` + + A very short string describing the reason why the collection was triggered. Known values include the following: + + - “API” + - “EAGER_ALLOC_TRIGGER” + - “DESTROY_RUNTIME” + - “LAST_DITCH” + - “TOO_MUCH_MALLOC” + - “ALLOC_TRIGGER” + - “DEBUG_GC” + - “COMPARTMENT_REVIVED” + - “RESET” + - “OUT_OF_NURSERY” + - “EVICT_NURSERY” + - “FULL_STORE_BUFFER” + - “SHARED_MEMORY_LIMIT” + - “PERIODIC_FULL_GC” + - “INCREMENTAL_TOO_SLOW” + - “DOM_WINDOW_UTILS” + - “COMPONENT_UTILS” + - “MEM_PRESSURE” + - “CC_WAITING” + - “CC_FORCED” + - “LOAD_END” + - “PAGE_HIDE” + - “NSJSCONTEXT_DESTROY” + - “SET_NEW_DOCUMENT” + - “SET_DOC_SHELL” + - “DOM_UTILS” + - “DOM_IPC” + - “DOM_WORKER” + - “INTER_SLICE_GC” + - “REFRESH_FRAME” + - “FULL_GC_TIMER” + - “SHUTDOWN_CC” + - “USER_INACTIVE” + + +``nonincrementalReason`` + + If SpiderMonkey’s collector determined it could not incrementally collect garbage, and had to do a full GC all at once, this is a short string describing the reason it determined the full GC was necessary. Otherwise, ``null`` is returned. Known values include the following: + + - “GC mode” + - “malloc bytes trigger” + - “allocation trigger” + - “requested” + + +``gcCycleNumber`` + + The GC cycle’s “number”. Does not correspond to the number of GC cycles that have run, but is guaranteed to be monotonically increasing. + + + +Function Properties of the ``Debugger.Memory.prototype`` Object +*************************************************************** + +Memory Use Analysis Exposes Implementation Details + +Memory analysis may yield surprising results, because browser implementation details that are transparent to content JavaScript often have visible effects on memory consumption. Web developers need to know their pages’ actual memory consumption on real browsers, so it is correct for the tool to expose these behaviors, as long as it is done in a way that helps developers make decisions about their own code. + +This section covers some areas where Firefox’s actual behavior deviates from what one might expect from the specified behavior of the web platform. + +Objects +------- + +SpiderMonkey objects usually use less memory than the naïve “table of properties with attributes” model would suggest. For example, it is typical for many objects to have identical sets of properties, with only the properties’ values varying from one object to the next. To take advantage of this regularity, SpiderMonkey objects with identical sets of properties may share their property metadata; only property values are stored directly in the object. + +Array objects may also be optimized, if the set of live indices is dense. + + +Strings +------- + +SpiderMonkey has three representations of strings: + + +- Normal: the string’s text is counted in its size. + +- Substring: the string is a substring of some other string, and points to that string for its storage. This representation may result in a small string retaining a very large string. However, the memory consumed by the string itself is a small constant independent of its size, since it is a reference to the larger string, a start position, and a length. + +- Concatenations: When asked to concatenate two strings, SpiderMonkey may elect to delay copying the strings’ data, and represent the result as a pointer to the two original strings. Again, such a string retains other strings, but the memory consumed by the string itself is a small constant independent of its size, since it is a pair of pointers. + + +SpiderMonkey converts strings from the more complex representations to the simpler ones when it pleases. Such conversions usually increase memory consumption. + +SpiderMonkey shares some strings amongst all web pages and browser JS. These shared strings, called *atoms*, are not included in censuses’ string counts. + + +Scripts +------- + +SpiderMonkey has a complex, hybrid representation of JavaScript code. There are four representations kept in memory: + + +- *Source code*. SpiderMonkey retains a copy of most JavaScript source code. + +- *Compressed source code*. SpiderMonkey compresses JavaScript source code, and de-compresses it on demand. Heuristics determine how long to retain the uncompressed code. + +- *Bytecode*. This is SpiderMonkey’s parsed representation of JavaScript. Bytecode can be interpreted directly, or used as input to a just-in-time compiler. Source is parsed into bytecode on demand; functions that are never called are never parsed. + +- *Machine code*. SpiderMonkey includes several just-in-time compilers, each of which translates JavaScript source or bytecode to machine code. Heuristics determine which code to compile, and which compiler to use. Machine code may be dropped in response to memory pressure, and regenerated as needed. + + +Furthermore, SpiderMonkey tracks which types of values have appeared in variables and object properties. This type information can be large. + +In a census, all the various forms of JavaScript code are placed in the ``"script"`` category. Type information is accounted to the ``"types"`` category. + + +Source Metadata +--------------- + +Generated from file: + js/src/doc/Debugger/Debugger.Memory.md + +Watermark: + sha256:2c1529d6932efec8c624a6f1f366b09cb7fce625a6468657fab81788240bc7ae + +Changeset: + `e91b2c85aacd <https://hg.mozilla.org/mozilla-central/rev/e91b2c85aacd>`_ diff --git a/devtools/docs/user/debugger-api/debugger.object/index.rst b/devtools/docs/user/debugger-api/debugger.object/index.rst new file mode 100644 index 0000000000..e989195b25 --- /dev/null +++ b/devtools/docs/user/debugger-api/debugger.object/index.rst @@ -0,0 +1,310 @@ +=============== +Debugger.Object +=============== + +A ``Debugger.Object`` instance represents an object in the debuggee, providing reflection-oriented methods to inspect and modify its referent. The referent’s properties do not appear directly as properties of the ``Debugger.Object`` instance; the debugger can access them only through methods like ``Debugger.Object.prototype.getOwnPropertyDescriptor`` and ``Debugger.Object.prototype.defineProperty``, ensuring that the debugger will not inadvertently invoke the referent’s getters and setters. + +SpiderMonkey creates exactly one ``Debugger.Object`` instance for each debuggee object it presents to a given :doc:`Debugger <../debugger/index>` instance: if the debugger encounters the same object through two different routes (perhaps two functions are called on the same object), SpiderMonkey presents the same ``Debugger.Object`` instance to the debugger each time. This means that the debugger can use the ``==`` operator to recognize when two ``Debugger.Object`` instances refer to the same debuggee object, and place its own properties on a ``Debugger.Object`` instance to store metadata about particular debuggee objects. + +JavaScript code in different compartments can have different views of the same object. For example, in Firefox, code in privileged compartments sees content DOM element objects without redefinitions or extensions made to that object’s properties by content code. (In Firefox terminology, privileged code sees the element through an “xray wrapper”.) To ensure that debugger code sees each object just as the debuggee would, each ``Debugger.Object`` instance presents its referent as it would be seen from a particular compartment. This “viewing compartment” is chosen to match the way the debugger came across the referent. As a consequence, a single :doc:`Debugger <../debugger/index>` instance may actually have several ``Debugger.Object`` instances: one for each compartment from which the referent is viewed. + +If more than one :doc:`Debugger <../debugger/index>` instance is debugging the same code, each :doc:`Debugger <../debugger/index>` gets a separate ``Debugger.Object`` instance for a given object. This allows the code using each :doc:`Debugger <../debugger/index>` instance to place whatever properties it likes on its own ``Debugger.Object`` instances, without worrying about interfering with other debuggers. + +While most ``Debugger.Object`` instances are created by SpiderMonkey in the process of exposing debuggee’s behavior and state to the debugger, the debugger can use ``Debugger.Object.prototype.makeDebuggeeValue`` to create ``Debugger.Object`` instances for given debuggee objects, or use ``Debugger.Object.prototype.copy`` and ``Debugger.Object.prototype.create`` to create new objects in debuggee compartments, allocated as if by particular debuggee globals. + +``Debugger.Object`` instances protect their referents from the garbage collector; as long as the ``Debugger.Object`` instance is live, the referent remains live. This means that garbage collection has no visible effect on ``Debugger.Object`` instances. + + +Accessor Properties of the Debugger.Object prototype +**************************************************** + +A ``Debugger.Object`` instance inherits the following accessor properties from its prototype: + + +``proto`` + The referent’s prototype (as a new ``Debugger.Object`` instance), or ``null`` if it has no prototype. This accessor may throw if the referent is a scripted proxy or some other sort of exotic object (an opaque wrapper, for example). + +``class`` + A string naming the ECMAScript ``[[Class]]`` of the referent. + +``callable`` + ``true`` if the referent is a callable object (such as a function or a function proxy); false otherwise. + +``name`` + The name of the referent, if it is a named function. If the referent is an anonymous function, or not a function at all, this is ``undefined``. + + This accessor returns whatever name appeared after the ``function`` keyword in the source code, regardless of whether the function is the result of instantiating a function declaration (which binds the function to its name in the enclosing scope) or evaluating a function expression (which binds the function to its name only within the function’s body). + +``displayName`` + + The referent’s display name, if the referent is a function with a display name. If the referent is not a function, or if it has no display name, this is ``undefined``. + + If a function has a given name, its display name is the same as its given name. In this case, the ``displayName`` and ``name`` properties are equal. + + If a function has no name, SpiderMonkey attempts to infer an appropriate name for it given its context. For example: + + .. code-block:: javascript + + function f() {} // display name: f (the given name) + var g = function () {}; // display name: g + o.p = function () {}; // display name: o.p + var q = { + r: function () {} // display name: q.r + }; + + Note that the display name may not be a proper JavaScript identifier, or even a proper expression: we attempt to find helpful names even when the function is not immediately assigned as the value of some variable or property. Thus, we use ``a/b`` to refer to the *b* defined within *a*, and ``a<`` to refer to a function that occurs somewhere within an expression that is assigned to *a*. For example: + + .. code-block:: javascript + + function h() { + var i = function() {}; // display name: h/i + f(function () {}); // display name: h/< + } + var s = f(function () {}); // display name: s<``</pre> + +``parameterNames`` + If the referent is a debuggee function, the names of the its parameters, as an array of strings. If the referent is not a debuggee function, or not a function at all, this is ``undefined``. + + If the referent is a host function for which parameter names are not available, return an array with one element per parameter, each of which is ``undefined``. + + If the referent is a function proxy, return an empty array. + + If the referent uses destructuring parameters, then the array’s elements reflect the structure of the parameters. For example, if the referent is a function declared in this way: + + .. code-block:: javascript + + function f(a, [b, c], {d, e:f}) { ... } + + then this ``Debugger.Object`` instance’s ``parameterNames`` property would have the value: + + .. code-block:: javascript + + ["a", ["b", "c"], {d:"d", e:"f"}] + +``script`` + If the referent is a function that is debuggee code, this is that function’s script, as a :doc:`Debugger.Script <../debugger.script/index>` instance. If the referent is a function proxy or not debuggee code, this is ``undefined``. + +``environment`` + If the referent is a function that is debuggee code, a :doc:`Debugger.Environment <../debugger.environment/index>` instance representing the lexical environment enclosing the function when it was created. If the referent is a function proxy or not debuggee code, this is ``undefined``. + +``errorMessageName`` + If the referent is an error created with an engine internal message template this is a string which is the name of the template; ``undefined`` otherwise. + +``errorLineNumber`` + If the referent is an Error object, this is the line number at which the referent was created; ``undefined`` otherwise. + +``errorColumnNumber`` + If the referent is an Error object, this is the column number at which the referent was created; ``undefined`` otherwise. + +``isBoundFunction`` + If the referent is a debuggee function, returns ``true`` if the referent is a bound function; ``false`` otherwise. If the referent is not a debuggee function, or not a function at all, returns ``undefined`` instead. + +``isArrowFunction`` + If the referent is a debuggee function, returns ``true`` if the referent is an arrow function; ``false`` otherwise. If the referent is not a debuggee function, or not a function at all, returns ``undefined`` instead. + +``isGeneratorFunction`` + If the referent is a debuggee function, returns ``true`` if the referent was created with a ``function*`` expression or statement, or false if it is some other sort of function. If the referent is not a debuggee function, or not a function at all, this is ``undefined``. (This is always equal to ``obj.script.isGeneratorFunction``, assuming ``obj.script`` is a ``Debugger.Script``.) + +``isAsyncFunction`` + If the referent is a debuggee function, returns ``true`` if the referent is an async function, defined with an ``async function`` expression or statement, or false if it is some other sort of function. If the referent is not a debuggee function, or not a function at all, this is ``undefined``. (This is always equal to ``obj.script.isAsyncFunction``, assuming ``obj.script`` is a ``Debugger.Script``.) + +``isPromise`` + ``true`` if the referent is a Promise; ``false`` otherwise. + +``boundTargetFunction`` + If the referent is a bound debuggee function, this is its target function— the function that was bound to a particular ``this`` object. If the referent is either not a bound function, not a debuggee function, or not a function at all, this is ``undefined``. + +``boundThis`` + If the referent is a bound debuggee function, this is the ``this`` value it was bound to. If the referent is either not a bound function, not a debuggee function, or not a function at all, this is ``undefined``. + +``boundArguments`` + If the referent is a bound debuggee function, this is an array (in the Debugger object’s compartment) that contains the debuggee values of the ``arguments`` object it was bound to. If the referent is either not a bound function, not a debuggee function, or not a function at all, this is ``undefined``. + +``isProxy`` + If the referent is a (scripted) proxy, either revoked or not, return ``true``. If the referent is not a (scripted) proxy, return ``false``. + +``proxyTarget`` + If the referent is a non-revoked (scripted) proxy, return a ``Debugger.Object`` instance referring to the ECMAScript ``[[ProxyTarget]]`` of the referent. If the referent is a revoked (scripted) proxy, return ``null``. If the referent is not a (scripted) proxy, return ``undefined``. + +``proxyHandler`` + If the referent is a non-revoked (scripted) proxy, return a ``Debugger.Object`` instance referring to the ECMAScript ``[[ProxyHandler]]`` of the referent. If the referent is a revoked (scripted) proxy, return ``null``. If the referent is not a (scripted) proxy, return ``undefined``. + +``promiseState`` + If the referent is a `Promise <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise>`_, return a string indicating whether the `Promise <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise>`_ is pending, or has been fulfilled or rejected. This string takes one of the following values: + + - ``"pending"``, if the `Promise <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise>`_ is pending. + - ``"fulfilled"``, if the `Promise <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise>`_ has been fulfilled. + - ``"rejected"``, if the `Promise <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise>`_ has been rejected. + + + If the referent is not a `Promise <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise>`_, throw a ``TypeError``. + +``promiseValue`` + Return a debuggee value representing the value the `Promise <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise>`_ has been fulfilled with. + + If the referent is not a `Promise <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise>`_, or the `Promise <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise>`_ has not been fulfilled, throw a ``TypeError``. + +``promiseReason`` + Return a debuggee value representing the value the `Promise <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise>`_ has been rejected with. + + If the referent is not a `Promise <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise>`_, or the `Promise <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise>`_ has not been rejected, throw a ``TypeError``. + +``promiseAllocationSite`` + If the referent is a `Promise <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise>`_, this is the JavaScript execution stack captured at the time of the promise’s allocation. This can return null if the promise was not created from script. If the referent is not a `Promise <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise>`_, throw a ``TypeError`` exception. + +``promiseResolutionSite`` + If the referent is a `Promise <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise>`_, this is the JavaScript execution stack captured at the time of the promise’s resolution. This can return null if the promise was not resolved by calling its ``resolve`` or ``reject`` resolving functions from script. If the referent is not a `Promise <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise>`_, throw a ``TypeError`` exception. + +``promiseID`` + If the referent is a `Promise <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise>`_, this is a process-unique identifier for the `Promise <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise>`_. With e10s, the same id can potentially be assigned to multiple `Promise <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise>`_ instances, if those instances were created in different processes. If the referent is not a `Promise <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise>`_, throw a ``TypeError`` exception. + +``promiseDependentPromises`` + If the referent is a `Promise <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise>`_, this is an ``Array`` of ``Debugger.Objects`` referring to the promises directly depending on the referent `Promise <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise>`_. These are: + + + 1. Return values of ``then()`` calls on the promise. + 2. Return values of ``Promise.all()`` if the referent `Promise <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise>`_ was passed in as one of the arguments. + 3. Return values of ``Promise.race()`` if the referent `Promise <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise>`_ was passed in as one of the arguments. + + + Once a `Promise <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise>`_ is settled, it will generally notify its dependent promises and forget about them, so this is most useful on *pending* promises. + + Note that the ``Array`` only contains the promises that directly depend on the referent `Promise <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise>`_. It does not contain promises that depend on promises that depend on the referent `Promise <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise>`_. + + If the referent is not a `Promise <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise>`_, throw a ``TypeError`` exception. + + +``promiseLifetime`` + If the referent is a `Promise <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise>`_, this is the number of milliseconds elapsed since the `Promise <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise>`_ was created. If the referent is not a `Promise <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise>`_, throw a ``TypeError`` exception. + +``promiseTimeToResolution`` + If the referent is a `Promise <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise>`_, this is the number of milliseconds elapsed between when the `Promise <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise>`_ was created and when it was resolved. If the referent hasn’t been resolved or is not a `Promise <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise>`_, throw a ``TypeError`` exception. + +``global`` + A ``Debugger.Object`` instance referring to the global object in whose scope the referent was allocated. This does not unwrap cross-compartment wrappers: if the referent is a wrapper, the result refers to the wrapper’s global, not the wrapped object’s global. The result refers to the global directly, not via a wrapper. + +.. _debugger-api-debugger-object-allocation-site: + +``allocationSite`` + If :ref:`object allocation site tracking <debugger-api-debugger-memory-tracking-allocation-sites>` was enabled when this ``Debugger.Object``’s referent was allocated, return the JavaScript execution stack captured at the time of the allocation. Otherwise, return ``null``. + + +Function Properties of the Debugger.Object prototype +**************************************************** + +The functions described below may only be called with a ``this`` value referring to a ``Debugger.Object`` instance; they may not be used as methods of other kinds of objects. The descriptions use “referent” to mean “the referent of this ``Debugger.Object`` instance”. + +Unless otherwise specified, these methods are not :ref:`invocation functions <debugger-api-debugger-frame-invf>`; if a call would cause debuggee code to run (say, because it gets or sets an accessor property whose handler is debuggee code, or because the referent is a proxy whose traps are debuggee code), the call throws a ``Debugger.DebuggeeWouldRun`` exception. + +These methods may throw if the referent is not a native object. Even simple accessors like ``isExtensible`` may throw if the referent is a proxy or some sort of exotic object like an opaque wrapper. + + +``getProperty(key, [receiver])`` + Return a completion value with "return" being the value of the referent's property named *key*, or ``undefined`` if it has no such property. *key* must be a string or symbol; *receiver* must be a debuggee value. If the property is a getter, it will be evaluated with *receiver* as the receiver, defaulting to the ``Debugger.Object`` if omitted. + +``setProperty(key, value, [receiver])`` + Store *value* as the value of the referent’s property named *key*, creating the property if it does not exist. *key* must be a string or symbol; *value* and *receiver* must be debuggee values. If the property is a setter, it will be evaluated with *receiver* as the receiver, defaulting to the ``Debugger.Object`` if omitted. + +``getOwnPropertyDescriptor(name)`` + Return a property descriptor for the property named *name* of the referent. If the referent has no such property, return ``undefined``. (This function behaves like the standard ``Object.getOwnPropertyDescriptor`` function, except that the object being inspected is implicit; the property descriptor returned is allocated as if by code scoped to the debugger’s global object (and is thus in the debugger’s compartment); and its ``value``, ``get``, and ``set`` properties, if present, are debuggee values.) + +``getOwnPropertyNames()`` + Return an array of strings naming all the referent’s own properties, as if ``Object.getOwnPropertyNames(referent)`` had been called in the debuggee, and the result copied in the scope of the debugger’s global object. + +``getOwnPropertySymbols()`` + Return an array of strings naming all the referent’s own symbols, as if ``Object.getOwnPropertySymbols(referent)`` had been called in the debuggee, and the result copied in the scope of the debugger’s global object. + +``defineProperty(name, attributes)`` + Define a property on the referent named *name*, as described by the property descriptor *descriptor*. Any ``value``, ``get``, and ``set`` properties of *attributes* must be debuggee values. (This function behaves like ``Object.defineProperty``, except that the target object is implicit, and in a different compartment from the function and descriptor.) + +``defineProperties(properties)`` + Add the properties given by *properties* to the referent. (This function behaves like ``Object.defineProperties``, except that the target object is implicit, and in a different compartment from the *properties* argument.) + +``deleteProperty(name)`` + Remove the referent’s property named *name*. Return true if the property was successfully removed, or if the referent has no such property. Return false if the property is non-configurable. + +``seal()`` + Prevent properties from being added to or deleted from the referent. Return this ``Debugger.Object`` instance. (This function behaves like the standard ``Object.seal`` function, except that the object to be sealed is implicit and in a different compartment from the caller.) + +``freeze()`` + Prevent properties from being added to or deleted from the referent, and mark each property as non-writable. Return this ``Debugger.Object`` instance. (This function behaves like the standard ``Object.freeze`` function, except that the object to be sealed is implicit and in a different compartment from the caller.) + +``preventExtensions()`` + Prevent properties from being added to the referent. (This function behaves like the standard ``Object.preventExtensions`` function, except that the object to operate on is implicit and in a different compartment from the caller.) + +``isSealed()`` + Return true if the referent is sealed—that is, if it is not extensible, and all its properties have been marked as non-configurable. (This function behaves like the standard ``Object.isSealed`` function, except that the object inspected is implicit and in a different compartment from the caller.) + +``isFrozen()`` + Return true if the referent is frozen—that is, if it is not extensible, and all its properties have been marked as non-configurable and read-only. (This function behaves like the standard ``Object.isFrozen`` function, except that the object inspected is implicit and in a different compartment from the caller.) + +``isExtensible()`` + Return true if the referent is extensible—that is, if it can have new properties defined on it. (This function behaves like the standard ``Object.isExtensible`` function, except that the object inspected is implicit and in a different compartment from the caller.) + +``copy(value)`` + Apply the HTML5 “structured cloning” algorithm to create a copy of *value* in the referent’s global object (and thus in the referent’s compartment), and return a ``Debugger.Object`` instance referring to the copy. + + Note that this returns primitive values unchanged. This means you can use ``Debugger.Object.prototype.copy`` as a generic “debugger value to debuggee value” conversion function—within the limitations of the “structured cloning” algorithm. + +``create(prototype, [properties])`` + Create a new object in the referent’s global (and thus in the referent’s compartment), and return a ``Debugger.Object`` referring to it. The new object’s prototype is *prototype*, which must be an ``Debugger.Object`` instance. The new object’s properties are as given by *properties*, as if *properties* were passed to ``Debugger.Object.prototype.defineProperties``, with the new ``Debugger.Object`` instance as the ``this`` value. + +``makeDebuggeeValue(value)`` + Return the debuggee value that represents *value* in the debuggee. If *value* is a primitive, we return it unchanged; if *value* is an object, we return the ``Debugger.Object`` instance representing that object, wrapped appropriately for use in this ``Debugger.Object``’s referent’s compartment. + + Note that, if *value* is an object, it need not be one allocated in a debuggee global, nor even a debuggee compartment; it can be any object the debugger wishes to use as a debuggee value. + + As described above, each ``Debugger.Object`` instance presents its referent as viewed from a particular compartment. Given a ``Debugger.Object`` instance *d* and an object *o*, the call ``d.makeDebuggeeValue(o)`` returns a ``Debugger.Object`` instance that presents *o* as it would be seen by code in *d*’s compartment. + +``call(this, argument, …)`` + If the referent is callable, call it with the given *this* value and *argument* values, and return a completion value describing how the call completed. *This* should be a debuggee value, or ``{ asConstructor: true }`` to invoke the referent as a constructor, in which case SpiderMonkey provides an appropriate ``this`` value itself. Each *argument* must be a debuggee value. All extant handler methods, breakpoints, and so on remain active during the call. If the referent is not callable, throw a ``TypeError``. This function follows the invocation function conventions. + +``apply(this, arguments)`` + If the referent is callable, call it with the given *this* value and the argument values in *arguments*, and return a completion value describing how the call completed. *This* should be a debuggee value, or ``{ asConstructor: true }`` to invoke *function* as a constructor, in which case SpiderMonkey provides an appropriate ``this`` value itself. *Arguments* must either be an array (in the debugger) of debuggee values, or ``null`` or ``undefined``, which are treated as an empty array. All extant handler methods, breakpoints, and so on remain active during the call. If the referent is not callable, throw a ``TypeError``. This function follows the :ref:`invocation function conventions <debugger-api-debugger-frame-invf>`. + +``executeInGlobal(code, [options])`` + If the referent is a global object, evaluate *code* in that global environment, and return a completion value describing how it completed. *Code* is a string. All extant handler methods, breakpoints, and so on remain active during the call. This function follows the :ref:`invocation function conventions <debugger-api-debugger-frame-invf>`. If the referent is not a global object, throw a ``TypeError`` exception. + + *Code* is interpreted as strict mode code when it contains a Use Strict Directive. + + This evaluation is semantically equivalent to executing statements at the global level, not an indirect eval. Regardless of *code* being strict mode code, variable declarations in *code* affect the referent global object. + + The *options* argument is as for :ref:`Debugger.Frame.eval <debugger-api-debugger-frame-eval>`. + +``executeInGlobalWithBindings(code, bindings, [options])`` + + Like ``executeInGlobal``, but evaluate *code* using the referent as the variable object, but with a lexical environment extended with bindings from the object *bindings*. For each own enumerable property of *bindings* named *name* whose value is value, include a variable in the lexical environment in which *code* is evaluated named *name*, whose value is *value*. Each *value* must be a debuggee value. (This is not like a ``with`` statement: *code* may access, assign to, and delete the introduced bindings without having any effect on the *bindings* object.) + + This method allows debugger code to introduce temporary bindings that are visible to the given debuggee code and which refer to debugger-held debuggee values, and do so without mutating any existing debuggee environment. + + Note that, like ``executeInGlobal``, any declarations it contains affect the referent global object, even as *code* is evaluated in an environment extended according to *bindings*. (In the terms used by the ECMAScript specification, the ``VariableEnvironment`` of the execution context for *code* is the referent, and the *bindings* appear in a new declarative environment, which is the eval code’s ``LexicalEnvironment``.) + + The *options* argument is as for :ref:`Debugger.Frame.eval <debugger-api-debugger-frame-eval>`. + +``asEnvironment()`` + If the referent is a global object, return the :doc:`Debugger.Environment <../debugger.environment/index>` instance representing the referent’s global lexical scope. The global lexical scope’s enclosing scope is the global object. If the referent is not a global object, throw a ``TypeError``. + +``unwrap()`` + If the referent is a wrapper that this ``Debugger.Object``’s compartment is permitted to unwrap, return a ``Debugger.Object`` instance referring to the wrapped object. If we are not permitted to unwrap the referent, return ``null``. If the referent is not a wrapper, return this ``Debugger.Object`` instance unchanged. + +``unsafeDereference()`` + Return the referent of this ``Debugger.Object`` instance. + + If the referent is an inner object (say, an HTML5 ``Window`` object), return the corresponding outer object (say, the HTML5 ``WindowProxy`` object). This makes ``unsafeDereference`` more useful in producing values appropriate for direct use by debuggee code, without using :ref:`invocation functions <debugger-api-debugger-frame-invf>`. + + This method pierces the membrane of ``Debugger.Object`` instances meant to protect debugger code from debuggee code, and allows debugger code to access debuggee objects through the standard cross-compartment wrappers, rather than via ``Debugger.Object``’s reflection-oriented interfaces. This method makes it easier to gradually adapt large code bases to this Debugger API: adapted portions of the code can use ``Debugger.Object`` instances, but use this method to pass direct object references to code that has not yet been updated. + +``forceLexicalInitializationByName(binding)`` + If *binding* is in an uninitialized state initialize it to undefined and return true, otherwise do nothing and return false. + + +Source Metadata +*************** + +Generated from file: + js/src/doc/Debugger/Debugger.Object.md + +Watermark: + sha256:7ae16a834e0883a95b4e0d227193293f6b6e4e4dd812c2570372a39c4c04897b +Changeset: + `5572465c08a9+ <https://hg.mozilla.org/mozilla-central/rev/5572465c08a9>`_ diff --git a/devtools/docs/user/debugger-api/debugger.script/index.rst b/devtools/docs/user/debugger-api/debugger.script/index.rst new file mode 100644 index 0000000000..5652868696 --- /dev/null +++ b/devtools/docs/user/debugger-api/debugger.script/index.rst @@ -0,0 +1,272 @@ +=============== +Debugger.Script +=============== + +A ``Debugger.Script`` instance may refer to a sequence of bytecode in the debuggee or to a block of WebAssembly code. For the former, it is the :doc:`Debugger <../debugger/index>` API’s presentation of a JSAPI ``JSScript`` object. The two cases are distinguished by their ``format`` property being ``"js"`` or ``"wasm"``. + + +Debugger.Script for JSScripts +***************************** + +For ``Debugger.Script`` instances referring to a ``JSScript``, they are distinguished by their ``format`` property being ``"js"``. + +Each of the following is represented by a single ``JSScript`` object: + + +- The body of a function—that is, all the code in the function that is not contained within some nested function. + +- The code passed to a single call to ``eval``, excluding the bodies of any functions that code defines. + +- The contents of a ``<script>`` element. + +- A DOM event handler, whether embedded in HTML or attached to the element by other JavaScript code. + +- Code appearing in a ``javascript:`` URL. + + +The :doc:`Debugger <../debugger/index>` interface constructs ``Debugger.Script`` objects as scripts of debuggee code are uncovered by the debugger: via the ``onNewScript`` handler method; via :doc:`Debugger.Frame <../debugger.frame/index>`’s ``script`` properties; via the ``functionScript`` method of :doc:`Debugger.Object <../debugger.object/index>` instances; and so on. For a given :doc:`Debugger <../debugger/index>` instance, SpiderMonkey constructs exactly one ``Debugger.Script`` instance for each underlying script object; debugger code can add its own properties to a script object and expect to find them later, use ``==`` to decide whether two expressions refer to the same script, and so on. + +(If more than one :doc:`Debugger <../debugger/index>` instance is debugging the same code, each :doc:`Debugger <../debugger/index>` gets a separate ``Debugger.Script`` instance for a given script. This allows the code using each :doc:`Debugger <../debugger/index>` instance to place whatever properties it likes on its ``Debugger.Script`` instances, without worrying about interfering with other debuggers.) + +A ``Debugger.Script`` instance is a strong reference to a JSScript object; it protects the script it refers to from being garbage collected. + +Note that SpiderMonkey may use the same ``Debugger.Script`` instances for equivalent functions or evaluated code—that is, scripts representing the same source code, at the same position in the same source file, evaluated in the same lexical environment. + + +Debugger.Script for WebAssembly +******************************* + +For ``Debugger.Script`` instances referring to a block of WebAssembly code, they are distinguished by their ``format`` property being ``"wasm"``. + +Currently only entire modules evaluated via ``new WebAssembly.Module`` are represented. + +``Debugger.Script`` objects for WebAssembly are uncovered via ``onNewScript`` when a new WebAssembly module is instantiated and via the ``findScripts`` method on :doc:`Debugger <../debugger/index>` instances. SpiderMonkey constructs exactly one ``Debugger.Script`` for each underlying WebAssembly module per :doc:`Debugger <../debugger/index>` instance. + +A ``Debugger.Script`` instance is a strong reference to the underlying WebAssembly module; it protects the module it refers to from being garbage collected. + +Please note at the time of this writing, support for WebAssembly is very preliminary. Many properties and methods below throw. + + +Convention +********** + +For descriptions of properties and methods below, if the behavior of the property or method differs between the instance referring to a ``JSScript`` or to a block of WebAssembly code, the text will be split into two sections, headed by “**if the instance refers to a JSScript**” and “**if the instance refers to WebAssembly code**”, respectively. If the behavior does not differ, no such emphasized headings will appear. + + +Accessor Properties of the Debugger.Script Prototype Object +*********************************************************** + +A ``Debugger.Script`` instance inherits the following accessor properties from its prototype: + + +``isGeneratorFunction`` + True if this instance refers to a ``JSScript`` for a function defined with a ``function*`` expression or statement. False otherwise. + +``isAsyncFunction`` + True if this instance refers to a ``JSScript`` for an async function, defined with an ``async function`` expression or statement. False otherwise. + +``displayName`` + **If the instance refers to a JSScript**, this is the script’s display name, if it has one. If the script has no display name — for example, if it is a top-level ``eval`` script — this is ``undefined``. + + If the script’s function has a given name, its display name is the same as its function’s given name. + + If the script’s function has no name, SpiderMonkey attempts to infer an appropriate name for it given its context. For example: + + .. code-block:: javascript + + function f() {} // display name: f (the given name) + var g = function () {}; // display name: g + o.p = function () {}; // display name: o.p + var q = { + r: function () {} // display name: q.r + }; + + + Note that the display name may not be a proper JavaScript identifier, or even a proper expression: we attempt to find helpful names even when the function is not immediately assigned as the value of some variable or property. Thus, we use ``a/b`` to refer to the *b* defined within *a*, and ``a<`` to refer to a function that occurs somewhere within an expression that is assigned to *a*. For example: + + .. code-block:: javascript + + function h() { + var i = function() {}; // display name: h/i + f(function () {}); // display name: h/< + } + var s = f(function () {}); // display name: s<``</pre> + + **If the instance refers to WebAssembly code**, throw a ``TypeError``. + +``url`` + + **If the instance refers to a JSScript**, the filename or URL from which this script’s code was loaded. For scripts created by ``eval`` or the ``Function`` constructor, this may be a synthesized filename, starting with a valid URL and followed by information tracking how the code was introduced into the system; the entire string is not a valid URL. For ``Function.prototype``’s script, this is ``null``. If this ``Debugger.Script``’s ``source`` property is non-``null``, then this is equal to ``source.url``. + + **If the instance refers to WebAssembly code**, throw a ``TypeError``. + +``startLine`` + **If the instance refers to a JSScript**, the number of the line at which this script’s code starts, within the file or document named by ``url``. + +``lineCount`` + **If the instance refers to a JSScript**, the number of lines this script’s code occupies, within the file or document named by ``url``. + +``source`` + **If the instance refers to a JSScript**, the :doc:`Debugger.Source <../debugger.source/index>` instance representing the source code from which this script was produced. This is ``null`` if the source code was not retained. + + **If the instance refers to WebAssembly code**, the :doc:`Debugger.Source <../debugger.source/index>` instance representing the serialized text format of the WebAssembly code. + +``sourceStart`` + **If the instance refers to a JSScript**, the character within the :doc:`Debugger.Source <../debugger.source/index>` instance given by ``source`` at which this script’s code starts; zero-based. If this is a function’s script, this is the index of the start of the ``function`` token in the source code. + + **If the instance refers to WebAssembly code**, throw a ``TypeError``. + +``sourceLength`` + **If the instance refers to a JSScript**, the length, in characters, of this script’s code within the :doc:`Debugger.Source <../debugger.source/index>` instance given by ``source``. + + **If the instance refers to WebAssembly code**, throw a ``TypeError``. + +``global`` + + **If the instance refers to a JSScript**, a :doc:`Debugger.Object <../debugger.object/index>` instance referring to the global object in whose scope this script runs. The result refers to the global directly, not via a wrapper or a ``WindowProxy`` (“outer window”, in Firefox). + + **If the instance refers to WebAssembly code**, throw a ``TypeError``. + +``format`` + **If the instance refers to a JSScript**, ``"js"``. + + **If the instance refers to WebAssembly code**, ``"wasm"``. + + + +Function Properties of the Debugger.Script Prototype Object +*********************************************************** + +The functions described below may only be called with a ``this`` value referring to a ``Debugger.Script`` instance; they may not be used as methods of other kinds of objects. + + +``getAllOffsets()`` + **If the instance refers to a JSScript**, return an array *L* describing the relationship between bytecode instruction offsets and source code positions in this script. *L* is sparse, and indexed by source line number. If a source line number *line* has no code, then *L* has no *line* property. If there is code for *line*, then ``L[line]`` is an array of offsets of byte code instructions that are entry points to that line. + + For example, suppose we have a script for the following source code: + + .. code-block:: javascript + + a=[] + for (i=1; i < 10; i++) + // It's hip to be square. + a[i] = i*i; + + Calling ``getAllOffsets()`` on that code might yield an array like this: + + .. code-block:: javascript + + [[0], [5, 20], , [10]] + + This array indicates that: + + - the first line’s code starts at offset 0 in the script; + - the ``for`` statement head has two entry points at offsets 5 and 20 (for the initialization, which is performed only once, and the loop test, which is performed at the start of each iteration); + - the third line has no code; + - and the fourth line begins at offset 10. + + **If the instance refers to WebAssembly code**, throw a ``TypeError``. + + +``getAllColumnOffsets()``: + **If the instance refers to a JSScript**, return an array describing the relationship between bytecode instruction offsets and source code positions in this script. Unlike getAllOffsets(), which returns all offsets that are entry points for each line, getAllColumnOffsets() returns all offsets that are entry points for each (line, column) pair. + + The elements of the array are objects, each of which describes a single entry point, and contains the following properties: + + - lineNumber: the line number for which offset is an entry point + - columnNumber: the 1-based column number for which offset is an entry point + - offset: the bytecode instruction offset of the entry point + + + For example, suppose we have a script for the following source code: + + .. code-block:: javascript + + a=[] + for (i=1; i < 10; i++) + // It's hip to be square. + a[i] = i*i; + + Calling ``getAllColumnOffsets()`` on that code might yield an array like this: + + .. code-block:: javascript + + [{ lineNumber: 0, columnNumber: 1, offset: 0 }, + { lineNumber: 1, columnNumber: 6, offset: 5 }, + { lineNumber: 1, columnNumber: 11, offset: 20 }, + { lineNumber: 3, columnNumber: 5, offset: 10 }] + + **If the instance refers to WebAssembly code**, throw a ``TypeError``. + +``getLineOffsets(line)`` + **If the instance refers to a JSScript**, return an array of bytecode instruction offsets representing the entry points to source line *line*. If the script contains no executable code at that line, the array returned is empty. + +``getOffsetLocation(offset)`` + **If the instance refers to a JSScript**, return an object describing the source code location responsible for the bytecode at *offset* in this script. The object has the following properties: + + - lineNumber: the line number for which offset is an entry point + - columnNumber: the 1-based column number for which offset is an entry point + - isEntryPoint: true if the offset is a column entry point, as would be reported by getAllColumnOffsets(); otherwise false. + + +``getOffsetsCoverage()``: + **If the instance refers to a JSScript**, return ``null`` or an array which contains information about the coverage of all opcodes. The elements of the array are objects, each of which describes a single opcode, and contains the following properties: + + - lineNumber: the line number of the current opcode. + - columnNumber: the 1-based column number of the current opcode. + - offset: the bytecode instruction offset of the current opcode. + - count: the number of times the current opcode got executed. + + + If this script has no coverage, or if it is not instrumented, then this function will return ``null``. To ensure that the debuggee is instrumented, the flag ``Debugger.collectCoverageInfo`` should be set to ``true``. + + **If the instance refers to WebAssembly code**, throw a ``TypeError``. + +``getChildScripts()`` + **If the instance refers to a JSScript**, return a new array whose elements are Debugger.Script objects for each function in this script. Only direct children are included; nested children can be reached by walking the tree. + + **If the instance refers to WebAssembly code**, throw a ``TypeError``. + +``setBreakpoint(offset, handler)`` + **If the instance refers to a JSScript**, set a breakpoint at the bytecode instruction at *offset* in this script, reporting hits to the ``hit`` method of *handler*. If *offset* is not a valid offset in this script, throw an error. + + When execution reaches the given instruction, SpiderMonkey calls the ``hit`` method of *handler*, passing a :doc:`Debugger.Frame <../debugger.frame/index>` instance representing the currently executing stack frame. The ``hit`` method’s return value should be a resumption value, determining how execution should continue. + + Any number of breakpoints may be set at a single location; when control reaches that point, SpiderMonkey calls their handlers in an unspecified order. + + Any number of breakpoints may use the same *handler* object. + + Breakpoint handler method calls are cross-compartment, intra-thread calls: the call takes place in the same thread that hit the breakpoint, and in the compartment containing the handler function (typically the debugger’s compartment). + + The new breakpoint belongs to the :doc:`Debugger <../debugger/index>` instance to which this script belongs. Disabling the :doc:`Debugger <../debugger/index>` instance disables this breakpoint; and removing a global from the :doc:`Debugger <../debugger/index>` instance’s set of debuggees clears all the breakpoints belonging to that :doc:`Debugger <../debugger/index>` instance in that global’s scripts. + +``getBreakpoints([offset])`` + **If the instance refers to a JSScript**, return an array containing the handler objects for all the breakpoints set at *offset* in this script. If *offset* is omitted, return the handlers of all breakpoints set anywhere in this script. If *offset* is present, but not a valid offset in this script, throw an error. + + **If the instance refers to WebAssembly code**, throw a ``TypeError``. + +``clearBreakpoint(handler, [offset])`` + **If the instance refers to a JSScript**, remove all breakpoints set in this :doc:`Debugger <../debugger/index>` instance that use *handler* as their handler. If *offset* is given, remove only those breakpoints set at *offset* that use *handler*; if *offset* is not a valid offset in this script, throw an error. + + Note that, if breakpoints using other handler objects are set at the same location(s) as *handler*, they remain in place. + +``clearAllBreakpoints([offset])`` + **If the instance refers to a JSScript**, remove all breakpoints set in this script. If *offset* is present, remove all breakpoints set at that offset in this script; if *offset* is not a valid bytecode offset in this script, throw an error. + +``isInCatchScope([offset])`` + **If the instance refers to a JSScript**, this is ``true`` if this offset falls within the scope of a try block, and ``false`` otherwise. + + **If the instance refers to WebAssembly code**, throw a ``TypeError``. + + +Source Metadata +*************** + +Generated from file: + js/src/doc/Debugger/Debugger.Script.md + +Watermark: + sha256:8816a4e8617be32c4ce7f3ae54970fe9c8a7d248175d215a8990ccff23e6efa9 + +Changeset: + `5572465c08a9+ <https://hg.mozilla.org/mozilla-central/rev/5572465c08a9>`_ diff --git a/devtools/docs/user/debugger-api/debugger.source/index.rst b/devtools/docs/user/debugger-api/debugger.source/index.rst new file mode 100644 index 0000000000..3e4e73c1ee --- /dev/null +++ b/devtools/docs/user/debugger-api/debugger.source/index.rst @@ -0,0 +1,130 @@ +=============== +Debugger.Source +=============== + +A ``Debugger.Source`` instance represents either a piece of JavaScript source code or the serialized text of a block of WebAssembly code. The two cases are distinguished by the latter having its ``introductionType`` property always being ``"wasm"`` and the former having its ``introductionType`` property never being ``"wasm"``. + +Each :doc:`Debugger <../debugger/index>` instance has a separate collection of ``Debugger.Source`` instances representing the source code that has been presented to the system. + +A debugger may place its own properties on ``Debugger.Source`` instances, to store metadata about particular pieces of source code. + + +Debugger.Source for JavaScript +****************************** + +For a ``Debugger.Source`` instance representing a piece of JavaScript source code, its properties provide the source code itself as a string, and describe where it came from. Each :doc:`Debugger.Script <../debugger.script/index>` instance refers to the ``Debugger.Source`` instance holding the source code from which it was produced. + +If a single piece of source code contains both top-level code and function definitions, perhaps with nested functions, then the :doc:`Debugger.Script <../debugger.script/index>` instances for those all refer to the same ``Debugger.Source`` instance. Each script indicates the substring of the overall source to which it corresponds. + +A ``Debugger.Source`` instance may represent only a portion of a larger source document. For example, an HTML document can contain JavaScript in multiple ``<script>`` elements and event handler content attributes. In this case, there may be either a single ``Debugger.Source`` instance for the entire HTML document, with each :doc:`Debugger.Script <../debugger.script/index>` referring to its substring of the document; or there may be a separate ``Debugger.Source`` instance for each ``<script>`` element and attribute. The choice is left up to the implementation. + +If a given piece of source code is presented to the JavaScript implementation more than once, with the same origin metadata, the JavaScript implementation may generate a fresh ``Debugger.Source`` instance to represent each presentation, or it may use a single ``Debugger.Source`` instance to represent them all. + + +Debugger.Source for WebAssembly +******************************* + +For a ``Debugger.Source`` instance representing the serialized text of a block of WebAssembly code, its properties provide the serialized text as a string. + +Currently only entire modules evaluated via ``new WebAssembly.Module`` are represented. SpiderMonkey constructs exactly one ``Debugger.Source`` for each underlying WebAssembly module per :doc:`Debugger <../debugger/index>` instance. + +Please note at the time of this writing, support for WebAssembly is very preliminary. Many properties below return placeholder values. + + +Convention +********** + +For descriptions of properties and methods below, if the behavior of the property or method differs between the instance referring to JavaScript source or to a block of WebAssembly code, the text will be split into two sections, headed by “**if the instance refers to JavaScript source**” and “**if the instance refers to WebAssembly code**”, respectively. If the behavior does not differ, no such emphasized headings will appear. + + +Accessor Properties of the Debugger.Source Prototype Object +*********************************************************** + +A ``Debugger.Source`` instance inherits the following accessor properties from its prototype: + + +``text`` + **If the instance refers to JavaScript source**, the JavaScript source code, as a string. The value satisfies the ``Program``, ``FunctionDeclaration``, or ``FunctionExpression`` productions in the ECMAScript standard. + + **If the instance refers to WebAssembly code**, the serialized text representation. The format is yet to be specified in the WebAssembly standard. Currently, the text is an s-expression based syntax. The text generation is disabled if the Debugger has the ``allowWasmBinarySource`` property set, the ``"[wasm]"`` value will be returned in this case. + +``binary`` + **If the instance refers to WebAssembly code** and the Debugger has the ``allowWasmBinarySource`` property set, a Uint8Array that contains the WebAssembly bytecode. + +``url`` + **If the instance refers to JavaScript source**, the filename or URL from which this script’s code was loaded. For scripts created by ``eval`` or the ``Function`` constructor, this may be a synthesized filename, starting with a valid URL and followed by information tracking how the code was introduced into the system; the entire string is not a valid URL. For ``Function.prototype``’s script, this is ``null``. Source may be loaded from a URL in the following ways: + + - The URL may appear as the ``src`` attribute of a ``<script>`` element in markup text. + - The URL may be passed to the ``Worker`` web worker constructor, or the web worker ``importScripts`` function. + - The URL may be the name of a XPCOM JavaScript module or subscript. + + + (Note that code passed to ``eval``, the ``Function`` constructor, or a similar function is*not* considered to be loaded from a URL; the ``url`` accessor on ``Debugger.Source`` instances for such sources should return ``undefined``.) + + **If the instance refers to WebAssembly code**, the URL of the script that called ``new WebAssembly.Module`` with the string ``"> wasm"`` appended. + +``sourceMapURL`` + **If the instance refers to JavaScript source**, if this source was produced by a minimizer or translated from some other language, and we know the URL of a **source map** document relating the source positions in this source to the corresponding source positions in the original source, then this property’s value is that URL. Otherwise, this is ``null``. + + (On the web, the translator may provide the source map URL in a specially formatted comment in the JavaScript source code, or via a header in the HTTP reply that carried the generated JavaScript.) + + This property is writable, so you can change the source map URL by setting it. All Debugger.Source objects referencing the same source will see the change. Setting an empty string has no effect and will not change existing value. + + **If the instance refers to WebAssembly code**, ``null``. Attempts to write to this property throw a ``TypeError``. + +``displayURL`` + If the script had a special ``//# sourceURL`` comment, as described in the source maps specification, then this property’s value holds the string that was given. Otherwise, this is ``null``. + +``element`` + The <a href="Debugger.Object">``Debugger.Object``</a> instance referring to the DOM element to which this source code belongs, if any, or ``undefined`` if it belongs to no DOM element. Source belongs to a DOM element in the following cases: + + - Source belongs to a ``<script>`` element if it is the element’s text content (that is, it is written out as the body of the ``<script>`` element in the markup text), or is the source document referenced by its ``src`` attribute. + - Source belongs to a DOM element if it is an event handler content attribute (that is, if it is written out in the markup text as an attribute value). + - Source belongs to a DOM element if it was assigned to one of the element’s event handler IDL attributes as a string. (Note that one may assign both strings and functions to DOM elements’ event handler IDL attributes. If one assigns a function, that function’s script’s source does*not* belong to the DOM element; the function’s definition must appear elsewhere.) + + (If the sources attached to a DOM element change, the ``Debugger.Source`` instances representing superseded code still refer to the DOM element; this accessor only reflects origins, not current relationships.) + +``elementAttributeName`` + If this source belongs to a DOM element because it is an event handler content attribute or an event handler IDL attribute, this is the name of that attribute, a string. Otherwise, this is ``undefined``. + +``introductionType`` + **If the instance refers to JavaScript source**, a string indicating how this source code was introduced into the system. This accessor returns one of the following values: + + - ``"eval"``, for code passed to ``eval``. + - ``"Function"``, for code passed to the ``Function`` constructor. + - ``"Function.prototype"``, for ``Function.prototype`` internally generated code. + - ``"Worker"``, for code loaded by calling the Web worker constructor—the worker’s main script. + - ``"importScripts"``, for code by calling ``importScripts`` in a web worker. + - ``"eventHandler"``, for code assigned to DOM elements’ event handler IDL attributes as a string. + - ``"scriptElement"``, for code belonging to ``<script>`` elements. + - ``"javascriptURL"``, for code presented in ``javascript:`` URLs. + - ``"setTimeout"``, for code passed to ``setTimeout`` as a string. + - ``"setInterval"``, for code passed to ``setInterval`` as a string. + - ``undefined``, if the implementation doesn’t know how the code was introduced. + + + **If the instance refers to WebAssembly code**, ``"wasm"``. + +``introductionScript``, ``introductionOffset`` + **If the instance refers to JavaScript source**, and if this source was introduced by calling a function from debuggee code, then ``introductionScript`` is the <a href="Debugger.Script">``Debugger.Script``</a> instance referring to the script containing that call, and ``introductionOffset`` is the call’s bytecode offset within that script. Otherwise, these are both ``undefined``. Taken together, these properties indicate the location of the introducing call. + + For the purposes of these accessors, assignments to accessor properties are treated as function calls. Thus, setting a DOM element’s event handler IDL attribute by assigning to the corresponding JavaScript property creates a source whose ``introductionScript`` and ``introductionOffset`` refer to the property assignment. + + Since a ``<script>`` element parsed from a web page’s original HTML was not introduced by any scripted call, its source’s ``introductionScript`` and ``introductionOffset`` accessors both return ``undefined``. + + If a ``<script>`` element was dynamically inserted into a document, then these accessors refer to the call that actually caused the script to run—usually the call that made the element part of the document. Thus, they do*not* refer to the call that created the element; stored the source as the element’s text child; made the element a child of some uninserted parent node that was later inserted; or the like. + + Although the main script of a worker thread is introduced by a call to ``Worker`` or ``SharedWorker``, these accessors always return ``undefined`` on such script’s sources. A worker’s main script source and the call that created the worker are always in separate threads, but <a href="Debugger" title="The Debugger object">``Debugger``</a> is an inherently single-threaded facility: its debuggees must all run in the same thread. Since the global that created the worker is in a different thread, it is guaranteed not to be a debuggee of the <a href="Debugger" title="The Debugger object">``Debugger``</a> instance that owns this source; and thus the creating call is never “in debuggee code”. Relating a worker to its creator, and other multi-threaded debugging concerns, are out of scope for <a href="Debugger" title="The Debugger object">``Debugger``</a>. + + **If the instance refers to WebAssembly code**, ``introductionScript`` is the <a href="Debugger.Script">``Debugger.Script``</a> instance referring to the same underlying WebAssembly module. ``introductionOffset`` is ``undefined``. + + +Source Metadata +--------------- + +Generated from file: + js/src/doc/Debugger/Debugger.Source.md +Watermark: + sha256:5ca245813db96628aab1c78b803355eb2aa8c575839c67eb7d7bde177898df88 +Changeset: + `e91b2c85aacd <https://hg.mozilla.org/mozilla-central/rev/e91b2c85aacd>`_ diff --git a/devtools/docs/user/debugger-api/debugger/index.rst b/devtools/docs/user/debugger-api/debugger/index.rst new file mode 100644 index 0000000000..87647602bd --- /dev/null +++ b/devtools/docs/user/debugger-api/debugger/index.rst @@ -0,0 +1,312 @@ +======== +Debugger +======== + +The Debugger Object +******************* + +When called as a constructor, the ``Debugger`` object creates a new ``Debugger`` instance. + + +``new Debugger([global, …])`` + Create a debugger object, and apply its :ref:`addDebuggee <debugger-api-debugger-add-debuggee>` method to each of the given *global* objects to add them as the initial debuggees. + + +Accessor Properties of the Debugger Prototype Object +---------------------------------------------------- + +A ``Debugger`` instance inherits the following accessor properties from its prototype: + + +``enabled`` + + A boolean value indicating whether this ``Debugger`` instance’s handlers, breakpoints, and the like are currently enabled. It is an accessor property with a getter and setter: assigning to it enables or disables this ``Debugger`` instance; reading it produces true if the instance is enabled, or false otherwise. This property is initially ``true`` in a freshly created ``Debugger`` instance. + + This property gives debugger code a single point of control for disentangling itself from the debuggee, regardless of what sort of events or handlers or “points” we add to the interface. + +``allowUnobservedAsmJS`` + + A boolean value indicating whether asm.js code running inside this ``Debugger`` instance’s debuggee globals is invisible to Debugger API handlers and breakpoints. Setting this to ``false`` inhibits the ahead-of-time asm.js compiler and forces asm.js code to run as normal JavaScript. This is an accessor property with a getter and setter. It is initially ``false`` in a freshly created ``Debugger`` instance. + + Setting this flag to ``true`` is intended for uses of subsystems of the Debugger API (e.g, :doc:`Debugger.Source <../debugger.source/index>`) for purposes other than step debugging a target JavaScript program. + +``allowWasmBinarySource`` + + A boolean value indicating whether WebAssembly sources will be available in binary form. The WebAssembly text generation will be disabled. + +``collectCoverageInfo`` + + A boolean value indicating whether code coverage should be enabled inside each debuggee of this ``Debugger`` instance. Changing this flag value will recompile all JIT code to add or remove code coverage instrumentation. Changing this flag when any frame of the debuggee is currently active on the stack will produce an exception. + + Setting this to ``true`` enables code coverage instrumentation, which can be accessed via the :doc:`Debugger.Script <../debugger.script/index>` ``getOffsetsCoverage`` function. In some cases, the code coverage might expose information which pre-date the modification of this flag. Code coverage reports are monotone, thus one can take a snapshot when the Debugger is enabled, and output the difference. + + Setting this to ``false`` prevents this ``Debugger`` instance from requiring any code coverage instrumentation, but it does not guarantee that the instrumentation is not present. + +``uncaughtExceptionHook`` + + Either ``null`` or a function that SpiderMonkey calls when a call to a debug event handler, breakpoint handler, or similar function throws some exception, which we refer to as *debugger-exception* here. Exceptions thrown in the debugger are not propagated to debuggee code; instead, SpiderMonkey calls this function, passing *debugger-exception* as its sole argument and the ``Debugger`` instance as the ``this`` value. This function should return a resumption value, which determines how the debuggee should continue. + + If the uncaught exception hook itself throws an exception, *uncaught-hook-exception*, SpiderMonkey throws a new error object, *confess-to-debuggee-exception*, to the debuggee whose message blames the debugger, and includes textual descriptions of *uncaught-hook-exception* and the original *debugger-exception*. + + If ``uncaughtExceptionHook``’s value is ``null``, SpiderMonkey throws an exception to the debuggee whose message blames the debugger, and includes a textual description of *debugger-exception*. + + Assigning anything other than a callable value or ``null`` to this property throws a ``TypeError`` exception. + + (This is not an ideal way to handle debugger bugs, but the hope here is that some sort of backstop, even if imperfect, will make life easier for debugger developers. For example, an uncaught exception hook may have access to browser-level features like the ``alert`` function, which this API’s implementation does not, making it possible to present debugger errors to the developer in a way suited to the context.) + + +Debugger Handler Functions +************************** + +Each ``Debugger`` instance inherits accessor properties with which you can store handler functions for SpiderMonkey to call when given events occur in debuggee code. + +When one of the events described below occurs in debuggee code, the engine pauses the debuggee and calls the corresponding debugging handler on each ``Debugger`` instance that is observing the debuggee. The handler functions receive the ``Debugger`` instance as their ``this`` value. Most handler functions can return a resumption value indicating how the debuggee’s execution should proceed. + +On a new ``Debugger`` instance, each of these properties is initially ``undefined``. Any value assigned to a debugging handler must be either a function or ``undefined``; otherwise a ``TypeError`` is thrown. + +Handler functions run in the same thread in which the event occurred. They run in the compartment to which they belong, not in a debuggee compartment. + + +``onNewScript(script, global)`` + + New code, represented by the :doc:`Debugger.Script <../debugger.script/index>` instance *script*, has been loaded in the scope of the debuggees. + + This method’s return value is ignored. + +``onNewPromise(promise)`` + + A new Promise object, referenced by the :doc:`Debugger.Object <../debugger.object/index>` instance *promise*, has been allocated in the scope of the debuggees. The Promise’s allocation stack can be obtained using the *promiseAllocationStack* accessor property of the :doc:`Debugger.Object <../debugger.object/index>` instance *promise*. + + This handler method should return a resumption value specifying how the debuggee’s execution should proceed. However, note that a ``{ return: value }`` resumption value is treated like ``undefined`` (“continue normally”); *value* is ignored. + +``onPromiseSettled(promise)`` + + A Promise object, referenced by the :doc:`Debugger.Object <../debugger.object/index>` instance *promise* that was allocated within a debuggee scope, has settled (either fulfilled or rejected). The Promise’s state, fulfillment or rejection value, and the allocation and resolution stacks can be obtained using the Promise-related accessor properties of the :doc:`Debugger.Object <../debugger.object/index>` instance *promise*. + + This handler method should return a resumption value specifying how the debuggee’s execution should proceed. However, note that a ``{ return: value }`` resumption value is treated like ``undefined`` (“continue normally”); *value* is ignored. + +``onDebuggerStatement(frame)`` + + Debuggee code has executed a *debugger* statement in *frame*. This method should return a resumption value specifying how the debuggee’s execution should proceed. + +``onEnterFrame(frame)`` + + The stack *frame* is about to begin executing code. (Naturally, *frame* is currently the youngest :doc:`visible frame <../debugger.frame/index>`.) This method should return a resumption value specifying how the debuggee’s execution should proceed. + + SpiderMonkey only calls ``onEnterFrame`` to report :ref:`visible <debugger-api-debugger-frame-visible-frames>`, non-``"debugger"`` frames. + +``onExceptionUnwind(frame, value)`` + + The exception *value* has been thrown, and has propagated to *frame*; *frame* is the youngest remaining stack frame, and is a debuggee frame. This method should return a resumption value specifying how the debuggee’s execution should proceed. If it returns ``undefined``, the exception continues to propagate as normal: if control in ``frame`` is in a ``try`` block, control jumps to the corresponding ``catch`` or ``finally`` block; otherwise, *frame* is popped, and the exception propagates to *frame* caller. + + When an exception’s propagation causes control to enter a ``finally`` block, the exception is temporarily set aside. If the ``finally`` block finishes normally, the exception resumes propagation, and the debugger’s ``onExceptionUnwind`` handler is called again, in the same frame. (The other possibility is for the ``finally`` block to exit due to a ``return``, ``continue``, or ``break`` statement, or a new exception. In those cases the old exception does not continue to propagate; it is discarded.) + + This handler is not called when unwinding a frame due to an over-recursion or out-of-memory exception. + +``sourceHandler(ASuffusionOfYellow)`` + + This method is never called. If it is ever called, a contradiction has been proven, and the debugger is free to assume that everything is true. + +``onError(frame, report)`` + + SpiderMonkey is about to report an error in *frame*. *Report* is an object describing the error, with the following properties: + + + ``message`` + The fully formatted error message. + ``file`` + If present, the source file name, URL, etc. (If this property is present, the *line* property will be too, and vice versa.) + ``line`` + If present, the source line number at which the error occurred. + ``lineText`` + If present, this is the source code of the offending line. + ``offset`` + The index of the character within lineText at which the error occurred. + ``warning`` + Present and true if this is a warning; absent otherwise. + ``strict`` + Present and true if this error or warning is due to the strict option (not to be confused with ES strict mode) + ``exception`` + Present and true if an exception will be thrown; absent otherwise. + ``arguments`` + An array of strings, representing the arguments substituted into the error message. + + + This method’s return value is ignored. + +``onNewGlobalObject(global)`` + + A new global object, *global*, has been created. + + This handler method should return a resumption value specifying how the debuggee’s execution should proceed. However, note that a ``{ return: value }`` resumption value is treated like ``undefined`` (“continue normally”); *value* is ignored. (Allowing the handler to substitute its own value for the new global object doesn’t seem useful.) + + This handler method is only available to debuggers running in privileged code (“chrome”, in Firefox). Most functions provided by this ``Debugger`` API observe activity in only those globals that are reachable by the API’s user, thus imposing capability-based restrictions on a ``Debugger``’s reach. However, the ``onNewGlobalObject`` method allows the API user to monitor all global object creation that occurs anywhere within the JavaScript system (the “JSRuntime”, in SpiderMonkey terms), thereby escaping the capability-based limits. For this reason, ``onNewGlobalObject`` is only available to privileged code. + + +Function Properties of the Debugger Prototype Object +**************************************************** + +The functions described below may only be called with a ``this`` value referring to a ``Debugger`` instance; they may not be used as methods of other kinds of objects. + +.. _debugger-api-debugger-add-debuggee: + +``addDebuggee(global)`` + + Add the global object designated by *global* to the set of global objects this ``Debugger`` instance is debugging. If the designated global is already a debuggee, this has no effect. Return this ``Debugger`` :doc:`Debugger.Object <../debugger.object/index>` instance referring to the designated global. + + The value *global* may be any of the following: + + - A global object. + + - An HTML5 ``WindowProxy`` object (an “outer window”, in Firefox terminology), which is treated as if the ``Window`` object of the browsing context’s active document (the “inner window”) were passed. + + - A cross-compartment wrapper of an object; we apply the prior rules to the wrapped object. + + - A :doc:`Debugger.Object <../debugger.object/index>` instance belonging to this ``Debugger`` instance; we apply the prior rules to the referent. + + - Any other sort of value is treated as a ``TypeError``. (Note that each rule is only applied once in the process of resolving a given *global* argument. Thus, for example, a :doc:`Debugger.Object <../debugger.object/index>` referring to a second :doc:`Debugger.Object <../debugger.object/index>` which refers to a global does not designate that global for the purposes of this function.) + + + The global designated by *global* must be in a different compartment than this ``Debugger`` instance itself. If adding the designated global’s compartment would create a cycle of debugger and debuggee compartments, this method throws an error. + + This method returns the :doc:`Debugger.Object <../debugger.object/index>` instance whose referent is the designated global object. + + The ``Debugger`` instance does not hold a strong reference to its debuggee globals: if a debuggee global is not otherwise reachable, then it is dropped from the ``Debugger`` set of debuggees. (Naturally, the :doc:`Debugger.Object <../debugger.object/index>` instance this method returns does hold a strong reference to the added global.) + + If this debugger is :ref:`tracking allocation sites <debugger-api-debugger-memory-tracking-allocation-sites>` and cannot track allocation sites for *global*, this method throws an ``Error``. + +``addAllGlobalsAsDebuggees()`` + + This method is like :ref:`addDebuggee <debugger-api-debugger-add-debuggee>`, but adds all the global objects from all compartments to this ``Debugger`` instance’s set of debuggees. Note that it skips this debugger’s compartment. + + If this debugger is :ref:`tracking allocation sites <debugger-api-debugger-memory-tracking-allocation-sites>` and cannot track allocation sites for some global, this method throws an ``Error``. Otherwise this method returns ``undefined``. + + This method is only available to debuggers running in privileged code (“chrome”, in Firefox). Most functions provided by this ``Debugger`` API observe activity in only those globals that are reachable by the API’s user, thus imposing capability-based restrictions on a ``Debugger``’s reach. However, the ``addAllGlobalsAsDebuggees`` method allows the API user to monitor all global object creation that occurs anywhere within the JavaScript system (the “JSRuntime”, in SpiderMonkey terms), thereby escaping the capability-based limits. For this reason, ``addAllGlobalsAsDebuggees`` is only available to privileged code. + +``removeDebuggee(global)`` + + Remove the global object designated by *global* from this ``Debugger`` instance’s set of debuggees. Return ``undefined``. + + This method interprets *global* using the same rules that :ref:`addDebuggee <debugger-api-debugger-add-debuggee>` does. + + Removing a global as a debuggee from this ``Debugger`` clears all breakpoints that belong to that ``Debugger`` in that global. + +``removeAllDebuggees()`` + + Remove all the global objects from this ``Debugger`` instance’s set of debuggees. Return ``undefined``. + +``hasDebuggee(global)`` + + Return ``true`` if the global object designated by *global* is a debuggee of this ``Debugger`` instance. + + This method interprets *global* using the same rules that :ref:`addDebuggee <debugger-api-debugger-add-debuggee>` does. + +``getDebuggees()`` + + Return an array of distinct :doc:`Debugger.Object <../debugger.object/index>` instances whose referents are all the global objects this ``Debugger`` instance is debugging. + + Since ``Debugger`` instances don’t hold strong references to their debuggee globals, if a debuggee global is otherwise unreachable, it may be dropped at any moment from the array this method returns. + +``getNewestFrame()`` + + Return a :doc:`Debugger.Frame <../debugger.frame/index>` instance referring to the youngest :doc:`visible frame <../debugger.frame/index>` currently on the calling thread’s stack, or ``null`` if there are no visible frames on the stack. + +``findSources([query]) (not yet implemented)`` + + Return an array of all :doc:`Debugger.Source <../debugger.source/index>` instances matching *query*. Each source appears only once in the array. *Query* is an object whose properties restrict which sources are returned; a source must meet all the criteria given by *query* to be returned. If *query* is omitted, we return all sources of all debuggee scripts. + + *Query* may have the following properties: + + ``url`` + The source’s ``url`` property must be equal to this value. + + ``global`` + The source must have been evaluated in the scope of the given global object. If this property’s value is a :doc:`Debugger.Object <../debugger.object/index>` instance belonging to this ``Debugger`` instance, then its referent is used. If the object is not a global object, then the global in whose scope it was allocated is used. + + Note that the result may include sources that can no longer ever be used by the debuggee: say, eval code that has finished running, or source for unreachable functions. Whether such sources appear can be affected by the garbage collector’s behavior, so this function’s result is not entirely deterministic. + +``findScripts([query])`` + + Return an array of :doc:`Debugger.Script <../debugger.script/index>` instances for all debuggee scripts matching *query*. Each instance appears only once in the array. *Query* is an object whose properties restrict which scripts are returned; a script must meet all the criteria given by *query* to be returned. If *query* is omitted, we return the :doc:`Debugger.Script <../debugger.script/index>` instances for all debuggee scripts. + + *Query* may have the following properties: + + + ``url`` + The script’s ``url`` property must be equal to this value. + ``source`` + The script’s ``source`` property must be equal to this value. + ``line`` + The script must at least partially cover the given source line. If this property is present, the ``url`` property must be present as well. + ``innermost`` + If this property is present and true, the script must be the innermost script covering the given source location; scripts of enclosing code are omitted. + ``global`` + The script must be in the scope of the given global object. If this property’s value is a :doc:`Debugger.Object <../debugger.object/index>` instance belonging to this ``Debugger`` instance, then its referent is used. If the object is not a global object, then the global in whose scope it was allocated is used. + + + All properties of *query* are optional. Passing an empty object returns all debuggee code scripts. + + Note that the result may include :doc:`Debugger.Script <../debugger.script/index>` instances for scripts that can no longer ever be used by the debuggee, say, those for eval code that has finished running, or unreachable functions. Whether such scripts appear can be affected by the garbage collector’s behavior, so this function’s behavior is not entirely deterministic. + +``findObjects([query])`` + + Return an array of :doc:`Debugger.Object <../debugger.object/index>` instances referring to each live object allocated in the scope of the debuggee globals that matches *query*. Each instance appears only once in the array. *Query* is an object whose properties restrict which objects are returned; an object must meet all the criteria given by *query* to be returned. If *query* is omitted, we return the :doc:`Debugger.Object <../debugger.object/index>` instances for all objects allocated in the scope of debuggee globals. + + The *query* object may have the following properties: + + + ``class`` + If present, only return objects whose internal ``[[Class]]``’s name matches the given string. Note that in some cases, the prototype object for a given constructor has the same ``[[Class]]`` as the instances that refer to it, but cannot itself be used as a valid instance of the class. Code gathering objects by class name may need to examine them further before trying to use them. + + + All properties of *query* are optional. Passing an empty object returns all objects in debuggee globals. + + Unlike ``findScripts``, this function is deterministic and will never return <a href="Debugger.Object">``Debugger.Object``s</a> referring to previously unreachable objects that had not been collected yet. + +``clearBreakpoint(handler)`` + + Remove all breakpoints set in this ``Debugger`` instance that use *handler* as their handler. Note that, if breakpoints using other handler objects are set at the same location(s) as *handler*, they remain in place. + +``clearAllBreakpoints()`` + + Remove all breakpoints set using this ``Debugger`` instance. + +``findAllGlobals()`` + + Return an array of :doc:`Debugger.Object <../debugger.object/index>` instances referring to all the global objects present in this JavaScript instance. + + The results of this call can be affected in non-deterministic ways by the details of the JavaScript implementation. The array may include :doc:`Debugger.Object <../debugger.object/index>` instances referring to global objects that are not actually reachable by the debuggee or any other code in the system. (Naturally, once the function has returned, the array’s :doc:`Debugger.Object <../debugger.object/index>` instances strongly reference the globals they refer to.) + + This handler method is only available to debuggers running in privileged code (“chrome”, in Firefox). Most functions provided by this ``Debugger`` API observe activity in only those globals that are reachable by the API’s user, thus imposing capability-based restrictions on a ``Debugger``’s reach. However, ``findAllGlobals`` allows the API user to find all global objects anywhere within the JavaScript system (the “JSRuntime”, in SpiderMonkey terms), thereby escaping the capability-based limits. For this reason, ``findAllGlobals`` is only available to privileged code. + +``makeGlobalObjectReference(global)`` + + Return the :doc:`Debugger.Object <../debugger.object/index>` whose referent is the global object designated by *global*, without adding the designated global as a debuggee. If *global* does not designate a global object, throw a ``TypeError``. Determine which global is designated by *global* using the same rules as <a href="Debugger#addDebuggee" title="The Debugger object: addDebuggee">``Debugger.prototype.addDebuggee``</a>. + +``adoptDebuggeeValue(value)`` + + Given a debuggee value ``value`` owned by an arbitrary ``Debugger``, return an equivalent debuggee value owned by this ``Debugger``. + + If ``value`` is a primitive value, return it unchanged. If ``value`` is a ``Debugger.Object`` owned by an arbitrary ``Debugger``, return an equivalent ``Debugger.Object`` owned by this ``Debugger``. Otherwise, if ``value`` is some other kind of object, and hence not a proper debuggee value, throw a TypeError instead. + + +Static methods of the Debugger Object +************************************* + +The functions described below are not called with a ``this`` value. + +``isCompilableUnit(source)`` + Given a string of source code, designated by *source*, return false if the string might become a valid JavaScript statement with the addition of more lines. Otherwise return true. The intent is to support interactive compilation - accumulate lines in a buffer until isCompilableUnit is true, then pass it to the compiler. + + +Source Metadata +--------------- + +Generated from file: + js/src/doc/Debugger/Debugger.md + +Watermark: + sha256:03b36132885e046a5f213130ba22b1139b473770f7324b842483c09ab7665f7c + +Changeset: + `e91b2c85aacd <https://hg.mozilla.org/mozilla-central/rev/e91b2c85aacd>`_ diff --git a/devtools/docs/user/debugger-api/index.rst b/devtools/docs/user/debugger-api/index.rst new file mode 100644 index 0000000000..158b70213a --- /dev/null +++ b/devtools/docs/user/debugger-api/index.rst @@ -0,0 +1,92 @@ +============ +Debugger-API +============ + +The ``Debugger`` Interface +************************** + +Mozilla’s JavaScript engine, SpiderMonkey, provides a debugging interface named ``Debugger`` which lets JavaScript code observe and manipulate the execution of other JavaScript code. Both Firefox’s built-in developer tools and the Firebug add-on use ``Debugger`` to implement their JavaScript debuggers. However, ``Debugger`` is quite general, and can be used to implement other kinds of tools like tracers, coverage analysis, patch-and-continue, and so on. + +``Debugger`` has three essential qualities: + + +- It is a *source level* interface: it operates in terms of the JavaScript language, not machine language. It operates on JavaScript objects, stack frames, environments, and code, and presents a consistent interface regardless of whether the debuggee is interpreted, compiled, or optimized. If you have a strong command of the JavaScript language, you should have all the background you need to use ``Debugger`` successfully, even if you have never looked into the language’s implementation. + +- It is for use *by JavaScript code*. JavaScript is both the debuggee language and the tool implementation language, so the qualities that make JavaScript effective on the web can be brought to bear in crafting tools for developers. As is expected of JavaScript APIs, ``Debugger`` is a *sound* interface: using (or even misusing) ``Debugger`` should never cause Gecko to crash. Errors throw proper JavaScript exceptions. + +- It is an *intra-thread* debugging API. Both the debuggee and the code using ``Debugger`` to observe it must run in the same thread. Cross-thread, cross-process, and cross-device tools must use ``Debugger`` to observe the debuggee from within the same thread, and then handle any needed communication themselves. (Firefox’s builtin tools have a `protocol <https://wiki.mozilla.org/Remote_Debugging_Protocol>`_ defined for this purpose.) + + +In Gecko, the ``Debugger`` API is available to chrome code only. By design, it ought not to introduce security holes, so in principle it could be made available to content as well; but it is hard to justify the security risks of the additional attack surface. + +The ``Debugger`` API cannot currently observe self-hosted JavaScript. This is not inherent in the API’s design, but that the self-hosting infrastructure isn’t prepared for the kind of invasions the ``Debugger`` API can perform. + + +Debugger Instances and Shadow Objects +************************************* + +``Debugger`` reflects every aspect of the debuggee’s state as a JavaScript value—not just actual JavaScript values like objects and primitives, but also stack frames, environments, scripts, and compilation units, which are not normally accessible as objects in their own right. + +Here is a JavaScript program in the process of running a timer callback function: + +.. image:: shadows.svg + :alt: A running JavaScript program and its Debugger shadows + :class: center + +A running JavaScript program and its Debugger shadows + +This diagram shows the various types of shadow objects that make up the Debugger API (which all follow some general conventions): + + +- A :doc:`Debugger.Object <debugger.object/index>` represents a debuggee object, offering a reflection-oriented API that protects the debugger from accidentally invoking getters, setters, proxy traps, and so on. + +- A :doc:`Debugger.Script <debugger.script/index>` represents a block of JavaScript code—either a function body or a top-level script. Given a ``Debugger.Script``, one can set breakpoints, translate between source positions and bytecode offsets (a deviation from the “source level” design principle), and find other static characteristics of the code. + +- A :doc:`Debugger.Frame <debugger.frame/index>` represents a running stack frame. You can use these to walk the stack and find each frame’s script and environment. You can also set ``onStep`` and ``onPop`` handlers on frames. + +- A :doc:`Debugger.Environment <debugger.environment/index>` represents an environment, associating variable names with storage locations. Environments may belong to a running stack frame, captured by a function closure, or reflect some global object’s properties as variables. + + +The :doc:`Debugger <debugger/index>` instance itself is not really a shadow of anything in the debuggee; rather, it maintains the set of global objects which are to be considered debuggees. A ``Debugger`` observes only execution taking place in the scope of these global objects. You can set functions to be called when new stack frames are pushed; when new code is loaded; and so on. + +Omitted from this picture are :doc:`Debugger.Source <debugger.source/index.>` instances, which represent JavaScript compilation units. A ``Debugger.Source`` can furnish a full copy of its source code, and explain how the code entered the system, whether via a call to ``eval``, a ``<script>`` element, or otherwise. A ``Debugger.Script`` points to the ``Debugger.Source`` from which it is derived. + +Also omitted is the ``Debugger``’s :doc:`Debugger.Memory <debugger.memory/index>` instance, which holds methods and accessors for observing the debuggee’s memory use. + +All these types follow some general conventions, which you should look through before drilling down into any particular type’s specification. + +All shadow objects are unique per ``Debugger`` and per referent. For a given ``Debugger``, there is exactly one ``Debugger.Object`` that refers to a particular debuggee object; exactly one ``Debugger.Frame`` for a particular stack frame; and so on. Thus, a tool can store metadata about a shadow’s referent as a property on the shadow itself, and count on finding that metadata again if it comes across the same referent. And since shadows are per-``Debugger``, tools can do so without worrying about interfering with other tools that use their own ``Debugger`` instances. + + +Examples +******** + +Here are some things you can try out yourself that show off some of ``Debugger``’s features: + + +- :doc:`Setting a breakpoint <tutorial-breakpoint/index>` in a page, running a handler function when it is hit that evaluates an expression in the page’s context. + +- :doc:`Showing how many objects different call paths allocate. <tutorial-allocation-log-tree/index>` + + +Gecko-specific features +*********************** + +While the ``Debugger`` core API deals only with concepts common to any JavaScript implementation, it also includes some Gecko-specific features: + + +- [Global tracking][global] supports debugging all the code running in a Gecko instance at once—the ‘chrome debugging’ model. +- [Object wrapper][wrapper] functions help manipulate object references that cross privilege boundaries. + + +Source Metadata +--------------- + +Generated from file: + js/src/doc/Debugger/Debugger-API.md + +Watermark: + sha256:6ee2381145a0d2e53d2f798f3f682e82dd7ab0caa0ac4dd5e56601c2e49913a7 + +Changeset: + `ffa775dd5bd4 <https://hg.mozilla.org/mozilla-central/rev/ffa775dd5bd4>`_ diff --git a/devtools/docs/user/debugger-api/shadows.svg b/devtools/docs/user/debugger-api/shadows.svg new file mode 100644 index 0000000000..03db057223 --- /dev/null +++ b/devtools/docs/user/debugger-api/shadows.svg @@ -0,0 +1,4 @@ +<!-- This Source Code Form is subject to the terms of the Mozilla Public + - License, v. 2.0. If a copy of the MPL was not distributed with this + - file, You can obtain one at http://mozilla.org/MPL/2.0/. --> +<svg xmlns="http://www.w3.org/2000/svg" width="650" height="400"><defs><marker orient="auto" refY="0" refX="0" id="c" overflow="visible"><path d="M.98 0a1 1 0 11-2 0 1 1 0 012 0z" fill-rule="evenodd" stroke="#000" stroke-width=".2pt"/></marker><marker orient="auto" refY="0" refX="0" id="d" overflow="visible"><path d="M-1.2 0l-1 1 3.5-1-3.5-1 1 1z" fill-rule="evenodd" stroke="#000" stroke-width=".2pt"/></marker><marker orient="auto" refY="0" refX="0" id="a" overflow="visible"><path d="M.98 0a1 1 0 11-2 0 1 1 0 012 0z" fill-rule="evenodd" stroke="#000" stroke-width=".2pt"/></marker><marker orient="auto" refY="0" refX="0" id="b" overflow="visible"><path d="M-1.2 0l-1 1 3.5-1-3.5-1 1 1z" fill-rule="evenodd" stroke="#000" stroke-width=".2pt"/></marker></defs><g class="flip"><rect width="171.317" height="150.685" x=".11" y="248.55" ry="4.814" rx="4.035" fill="#c8c0c0" stroke="#000" stroke-width="2.182" stroke-dasharray="4.36452564,4.36452564"/><text style="line-height:125%" x="9.875" y="268.844" font-size="14.12" font-weight="400" letter-spacing="0" word-spacing="0" font-family="Sans"><tspan x="9.875" y="268.844">Debugger</tspan></text></g><g class="flip"><rect width="119.421" height="42.398" x="25.236" y="160.02" ry="11.065" rx="11.065" fill="#969696"/><rect width="177.655" height="46.615" x="209.361" y="336.42" ry="4.039" rx="4.039" fill="#969696"/><rect width="149.122" height="46.615" x="237.894" y="287.164" ry="4.039" rx="4.039" fill="#969696"/><rect width="119.421" height="42.398" x="192.177" y="161.099" ry="11.065" rx="11.065" fill="#969696"/><rect width="136.405" height="46.615" x="26.006" y="336.42" ry="11.065" rx="11.065" fill="#969696"/><rect width="242.772" height="75.739" x="183.318" y="47.055" ry="6.125" rx="6.125" fill="#969696"/><rect width="186.276" height="18.675" x="285.598" y="66.984" ry="6.125" rx="6.125" fill="#969696" stroke="#fff" stroke-width="2.929"/><rect width="194.03" height="46.615" x="413.202" y="336.42" ry="4.039" rx="4.039" fill="#969696"/><rect width="90.035" height="46.615" x="296.98" y="237.91" ry="4.039" rx="4.039" fill="#969696"/><text style="line-height:125%" x="33.258" y="378.201" font-size="12.935" font-weight="400" letter-spacing="0" word-spacing="0" font-family="Sans"><tspan x="33.258" y="378.201">Debugger.Object</tspan></text><text style="line-height:125%" x="218.723" y="377.522" font-size="12.935" font-weight="400" letter-spacing="0" word-spacing="0" font-family="Sans"><tspan x="218.723" y="377.522">Debugger.Environment</tspan></text><text style="line-height:125%" x="421.849" y="377.522" font-size="12.935" font-weight="400" letter-spacing="0" word-spacing="0" font-family="Sans"><tspan x="421.849" y="377.522">Debugger.Frame</tspan></text><text style="line-height:125%" x="29.181" y="196.813" font-size="12.935" font-weight="400" letter-spacing="0" word-spacing="0" font-family="Sans"><tspan x="29.181" y="196.813">Debugger.Object</tspan></text><text style="line-height:125%" x="199.222" y="197.892" font-size="12.935" font-weight="400" letter-spacing="0" word-spacing="0" font-family="Sans"><tspan x="199.222" y="197.892">Debugger.Object</tspan></text><text style="line-height:125%" x="190.189" y="118.008" font-size="12.935" font-weight="400" letter-spacing="0" word-spacing="0" font-family="Sans"><tspan x="190.189" y="118.008">Debugger.Script</tspan></text><rect width="194.03" height="46.615" x="413.202" y="287.164" ry="4.039" rx="4.039" fill="#969696"/></g><g transform="translate(0 -344.094)" class="flip"><rect width="177.927" height="46.615" x="201.82" y="664.159" ry="4.039" rx="4.039" class="nonvalue" fill="#ffd257"/><text style="line-height:125%" x="210.634" y="691.887" transform="scale(1.00076 .99924)" font-size="14.122" font-weight="400" letter-spacing="0" word-spacing="0" font-family="Sans"><tspan x="210.634" y="691.887">global environment</tspan></text><rect width="136.614" height="46.615" x="18.811" y="664.159" ry="11.065" rx="11.065" fill="#83d4ff"/><path d="M204.053 687.466h-46.267" fill="none" stroke="#000" stroke-width="3" marker-start="url(#a)" marker-end="url(#b)"/><text style="line-height:125%" x="3.02" y="659.444" transform="scale(1.00076 .99924)" font-size="14.122" font-weight="400" letter-spacing="0" word-spacing="0" font-family="Sans"><tspan x="3.02" y="659.444">global object:</tspan></text><text style="text-align:center;line-height:125%" x="87.051" y="698.414" transform="scale(1.00076 .99924)" font-size="14.122" font-weight="400" letter-spacing="0" word-spacing="0" text-anchor="middle" font-family="Sans"><tspan x="87.051" y="698.414">Date; Math; ...</tspan></text></g><g class="flip"><rect transform="translate(0 -652.362)" width="243.144" height="75.74" x="176.363" y="683.061" ry="6.125" rx="6.125" class="nonvalue" fill="#83ff9a"/><rect transform="translate(0 -652.362)" width="186.561" height="18.675" x="278.799" y="702.99" ry="6.125" rx="6.125" class="nonvalue" fill="#83ff9a" stroke="#e6e4dd" stroke-width="2.929"/></g><text style="line-height:125%" x="183" y="699.527" transform="matrix(1.00076 0 0 .99924 0 -652.362)" font-size="14.122" font-weight="400" letter-spacing="0" word-spacing="0" font-family="Sans"><tspan x="183" y="699.527">function alertLater(msg, delay) {</tspan><tspan x="183" y="717.179"> setTimeout( function () { alert(msg); },</tspan><tspan x="183" y="734.832"> delay);</tspan><tspan x="183" y="752.485">}</tspan></text><g class="flip"><rect transform="translate(0 -652.362)" width="119.604" height="42.398" x="18.04" y="796.026" ry="11.065" rx="11.065" fill="#83d4ff"/><text style="text-align:end;line-height:125%" x="98.428" y="811.158" transform="matrix(1.00076 0 0 .99924 0 -652.362)" font-size="13.919" font-weight="400" letter-spacing="0" word-spacing="0" text-anchor="end" font-family="Sans"><tspan x="98.428" y="811.158">[[Code]]:</tspan></text><text style="text-align:end;line-height:125%" x="98.428" y="831.649" transform="matrix(1.00076 0 0 .99924 0 -652.362)" font-size="13.919" font-weight="400" letter-spacing="0" word-spacing="0" text-anchor="end" font-family="Sans"><tspan x="98.428" y="831.649">[[Scope]]:</tspan></text><path d="M18.04 165.532h119.602" fill="none" stroke="#e6e4dd" stroke-width="2.957"/><text style="line-height:125%" x="2.407" y="791.508" transform="matrix(1.00076 0 0 .99924 0 -652.362)" font-size="14.122" font-weight="400" letter-spacing="0" word-spacing="0" font-family="Sans"><tspan x="2.407" y="791.508">alertLater:</tspan></text><path transform="translate(0 -652.362)" d="M113.607 806.633c0-45.024 23.466-83.543 59.207-83.543m-59.207 104.131c51.733 0 90.506 99.848 90.506 141.325" fill="none" stroke="#000" stroke-width="3" marker-start="url(#c)" marker-end="url(#d)"/><text style="text-align:center;line-height:125%" x="87.051" y="991.618" transform="matrix(1.00076 0 0 .99924 0 -652.362)" font-size="14.122" font-weight="400" letter-spacing="0" word-spacing="0" text-anchor="middle" font-family="Sans"><tspan x="89.299" y="991.618">alertLater;</tspan></text></g><g class="flip"><rect width="149.35" height="46.615" x="229.789" y="270.808" ry="4.039" rx="4.039" class="nonvalue" fill="#ffd257"/><g font-size="22" font-weight="400" letter-spacing="0" word-spacing="0" font-family="Sans"><text transform="matrix(.58945 0 0 .58739 4.526 -176.544)" y="795.716" x="499.133" style="text-align:end;line-height:125%" text-anchor="end"><tspan y="795.716" x="499.133">msg:</tspan><tspan y="823.216" x="499.133">delay:</tspan></text><text y="794.926" x="507" style="line-height:125%" transform="matrix(.58887 0 0 .58797 4.526 -176.544)"><tspan y="794.926" x="507">'xlerb'</tspan><tspan y="822.426" x="507">1000</tspan></text></g></g><g class="flip"><rect width="119.604" height="42.398" x="185.843" y="143.664" ry="11.065" rx="11.065" fill="#83d4ff"/><text style="text-align:end;line-height:125%" x="266.103" y="158.298" transform="scale(1.00076 .99924)" font-size="13.919" font-weight="400" letter-spacing="0" word-spacing="0" text-anchor="end" font-family="Sans"><tspan x="266.103" y="158.298">[[Code]]:</tspan></text><text style="text-align:end;line-height:125%" x="266.103" y="178.789" transform="scale(1.00076 .99924)" font-size="13.919" font-weight="400" letter-spacing="0" word-spacing="0" text-anchor="end" font-family="Sans"><tspan x="266.103" y="178.789">[[Scope]]:</tspan></text><path d="M185.843 165.532h119.602" fill="none" stroke="#e6e4dd" stroke-width="2.957"/><path d="M285.445 176.59c0 31.26-38.089 59.767-38.089 91.053m38.594-113.165c165.685 0 170.772-32.93 158.206-82.184" fill="none" stroke="#000" stroke-width="3" marker-start="url(#c)" marker-end="url(#d)"/></g><g class="flip"><rect width="194.03" height="46.615" x="406.385" y="320.064" ry="4.039" rx="4.039" class="nonvalue" fill="#ff9457"/><text style="line-height:125%" x="434.11" y="346.934" font-size="12.935" font-weight="400" letter-spacing="0" word-spacing="0" font-family="Sans"><tspan x="434.11" y="346.934"><tspan style="-inkscape-font-specification:Sans Italic" font-style="italic">anonymous</tspan>()</tspan></text><rect width="90.035" height="46.615" x="289.103" y="221.555" ry="4.039" rx="4.039" class="nonvalue" fill="#ffd257"/><text style="line-height:125%;-inkscape-font-specification:Sans Italic" x="312.997" y="248.058" font-size="12.935" font-style="italic" font-weight="400" letter-spacing="0" word-spacing="0" font-family="Sans"><tspan x="312.997" y="248.058">empty</tspan></text><path d="M415.86 342.35c-51.097 0 11.106-95.595-39.03-95.595m211.854 96.578c66.197 0 27.6-283.142-117.224-283.142" fill="none" stroke="#000" stroke-width="3" marker-start="url(#a)" marker-end="url(#b)"/></g><g class="flip"><rect width="194.03" height="46.615" x="406.385" y="270.808" ry="4.039" rx="4.039" class="nonvalue" fill="#ff9457"/><text style="line-height:125%" x="433.863" y="298.871" font-size="12.935" font-weight="400" letter-spacing="0" word-spacing="0" font-family="Sans"><tspan x="433.863" y="298.871">alert('xlerb')</tspan></text></g></svg>
\ No newline at end of file diff --git a/devtools/docs/user/debugger-api/tutorial-allocation-log-tree/alloc-plot-console.png b/devtools/docs/user/debugger-api/tutorial-allocation-log-tree/alloc-plot-console.png Binary files differnew file mode 100644 index 0000000000..e41a5449b7 --- /dev/null +++ b/devtools/docs/user/debugger-api/tutorial-allocation-log-tree/alloc-plot-console.png diff --git a/devtools/docs/user/debugger-api/tutorial-allocation-log-tree/enable-chrome-devtools.png b/devtools/docs/user/debugger-api/tutorial-allocation-log-tree/enable-chrome-devtools.png Binary files differnew file mode 100644 index 0000000000..17e3b30aa6 --- /dev/null +++ b/devtools/docs/user/debugger-api/tutorial-allocation-log-tree/enable-chrome-devtools.png diff --git a/devtools/docs/user/debugger-api/tutorial-allocation-log-tree/index.rst b/devtools/docs/user/debugger-api/tutorial-allocation-log-tree/index.rst new file mode 100644 index 0000000000..711e6f245b --- /dev/null +++ b/devtools/docs/user/debugger-api/tutorial-allocation-log-tree/index.rst @@ -0,0 +1,235 @@ +======================================== +Tutorial: Show Allocations Per Call Path +======================================== + +.. |br| raw:: html + + <br/> + +This page shows how to use the :doc:`Debugger API <../index>` to show how many objects a web page allocates, sorted by the function call path that allocated them. + +1. Visit the URL ``about:config``, and set the ``devtools.chrome.enabled`` preference to ``true``: + + .. image:: enable-chrome-devtools.png + :alt: Setting the devtools.chrome.enabled preference + :class: center + + Setting the ``devtools.chrome.enabled`` preference + +|br| + +2. Open a developer Scratchpad (Menu button > Developer > Scratchpad), and select "Browser" from the "Environment" menu. (This menu will not be present unless you have changed the preference as explained above.) + + .. image:: scratchpad-browser-environment.png + :alt: Selecting the browser context in the Scratchpad + :class: center + + Selecting the 'browser' context in the Scratchpad + +|br| + +3. Enter the following code in the Scratchpad: + + .. code-block:: javascript + + // This defines the 'Debugger' constructor in this + // Scratchpad; it doesn't actually start debugging anything. + const { addDebuggerToGlobal } = ChromeUtils.importESModule( + 'resource://gre/modules/jsdebugger.sys.mjs' + ); + addDebuggerToGlobal(window); + + (function () { + // The debugger we'll use to observe a tab's allocation. + var dbg; + + // Start measuring the selected tab's main window's memory + // consumption. This function is available in the browser + // console. + window.demoTrackAllocations = function() { + dbg = new Debugger; + + // This makes hacking on the demo *much* more + // pleasant. + dbg.uncaughtExceptionHook = handleUncaughtException; + + // Find the current tab's main content window. + var w = gBrowser.selectedBrowser.contentWindow; + console.log("Tracking allocations in page: " + + w.location.href); + + // Make that window a debuggee of our Debugger. + dbg.addDebuggee(w.wrappedJSObject); + + // Enable allocation tracking in dbg's debuggees. + dbg.memory.trackingAllocationSites = true; + } + + window.demoPlotAllocations = function() { + // Grab the allocation log. + var log = dbg.memory.drainAllocationsLog(); + + // Neutralize the Debugger, and drop it on the floor + // for the GC to collect. + console.log("Stopping allocation tracking."); + dbg.removeAllDebuggees(); + dbg = undefined; + + // Analyze and display the allocation log. + plot(log); + } + + function handleUncaughtException(ex) { + console.log('Debugger hook threw:'); + console.log(ex.toString()); + console.log('Stack:'); + console.log(ex.stack); + }; + + function plot(log) { + // Given the log, compute a map from allocation sites to + // allocation counts. Note that stack entries are '===' if + // they represent the same site with the same callers. + var counts = new Map; + for (let site of log) { + // This is a kludge, necessary for now. The saved stacks + // are new, and Firefox doesn't yet understand that they + // are safe for chrome code to use, so we must tell it + // so explicitly. + site = Components.utils.waiveXrays(site.frame); + + if (!counts.has(site)) + counts.set(site, 0); + counts.set(site, counts.get(site) + 1); + } + + // Walk from each site that allocated something up to the + // root, computing allocation totals that include + // children. Remember that 'null' is a valid site, + // representing the root. + var totals = new Map; + for (let [site, count] of counts) { + for(;;) { + if (!totals.has(site)) + totals.set(site, 0); + totals.set(site, totals.get(site) + count); + if (!site) + break; + site = site.parent; + } + } + + // Compute parent-to-child links, since saved stack frames + // have only parent links. + var rootChildren = new Map; + function childMapFor(site) { + if (!site) + return rootChildren; + + let parentMap = childMapFor(site.parent); + if (parentMap.has(site)) + return parentMap.get(site); + + var m = new Map; + parentMap.set(site, m); + return m; + } + for (let [site, total] of totals) { + childMapFor(site); + } + + // Print the allocation count for |site|. Print + // |children|'s entries as |site|'s child nodes. Indent + // the whole thing by |indent|. + function walk(site, children, indent) { + var name, place; + if (site) { + name = site.functionDisplayName; + place = ' ' + site.source + ':' + site.line + ':' + site.column; + } else { + name = '(root)'; + place = ''; + } + console.log(indent + totals.get(site) + ': ' + name + place); + for (let [child, grandchildren] of children) + walk(child, grandchildren, indent + ' '); + } + walk(null, rootChildren, ''); + } + })(); + +|br| + +4. In the Scratchpad, ensure that no text is selected, and press the "Run" button. (If you get an error complaining that ``Components.utils`` is not defined, be sure you've selected ``Browser`` from the scratchpad's ``Environment`` menu, as described in step 2.) + +|br| + +5. Save the following HTML text to a file, and visit the file in your browser. Make sure the current browser tab is displaying this page. + +.. code-block:: html + + <div onclick="doDivsAndSpans()"> + Click here to make the page do some allocations. + </div> + + <script> + function makeFactory(type) { + return function factory(content) { + var elt = document.createElement(type); + elt.textContent = content; + return elt; + }; + } + + var divFactory = makeFactory('div'); + var spanFactory = makeFactory('span'); + + function divsAndSpans() { + for (i = 0; i < 10; i++) { + var div = divFactory('div #' + i); + div.appendChild(spanFactory('span #' + i)); + document.body.appendChild(div); + } + } + + function doDivsAndSpans() { divsAndSpans(); } + </script> + +|br| + +6. Open the browser console (Menu Button > Developer > Browser Console), and then evaluate the expression ``demoTrackAllocations()`` in the browser console. This begins logging allocations in the current browser tab. + +|br| + +7. In the browser tab, click on the text that says "Click here…". The event handler should add some text to the end of the page. + +|br| + +8. Back in the browser console, evaluate the expression ``demoPlotAllocations()``. This stops logging allocations, and displays a tree of allocations: + + .. image:: alloc-plot-console.png + :alt: An allocation plot, displayed in the console + :class: center + + An allocation plot, displayed in the console + + The numbers at the left edge of each line show the total number of objects allocated at that site or at sites called from there. After the count, we see the function name, and the source code location of the call site or allocation. + + The ``(root)`` node's count includes objects allocated in the content page by the web browser, like DOM events. Indeed, this display shows that ``popup.xml`` and ``content.js``, which are internal components of Firefox, allocated more objects in the page's compartment than the page itself. (We will probably revise the allocation log to present such allocations in a way that is more informative, and that exposes less of Firefox's internal structure.) + + As expected, the ``onclick`` handler is responsible for all allocation done by the page's own code. (The line number for the onclick handler is ``1``, indicating that the allocating call is located on line one of the handler text itself. We will probably change this to be the line number within ``page.html``, not the line number within the handler code.) + + The ``onclick`` handler calls ``doDivsAndSpans``, which calls ``divsAndSpans``, which invokes closures of ``factory`` to do all the actual allocation. (It is unclear why ``spanFactory`` allocated thirteen objects, despite being called only ten times.) + + + +Source Metadata +--------------- + +Generated from file: + js/src/doc/Debugger/Tutorial-Alloc-Log-Tree.md + +Watermark: + sha256:b56f6df61c39dbe19ca1f49752aea42207c804355513f4fea8249bdeb4cb056d +Changeset: + `251fccc1f62b <https://hg.mozilla.org/mozilla-central/rev/251fccc1f62b>`_ diff --git a/devtools/docs/user/debugger-api/tutorial-allocation-log-tree/scratchpad-browser-environment.png b/devtools/docs/user/debugger-api/tutorial-allocation-log-tree/scratchpad-browser-environment.png Binary files differnew file mode 100644 index 0000000000..1e2e6cc51e --- /dev/null +++ b/devtools/docs/user/debugger-api/tutorial-allocation-log-tree/scratchpad-browser-environment.png diff --git a/devtools/docs/user/debugger-api/tutorial-breakpoint/console.png b/devtools/docs/user/debugger-api/tutorial-breakpoint/console.png Binary files differnew file mode 100644 index 0000000000..5016838502 --- /dev/null +++ b/devtools/docs/user/debugger-api/tutorial-breakpoint/console.png diff --git a/devtools/docs/user/debugger-api/tutorial-breakpoint/index.rst b/devtools/docs/user/debugger-api/tutorial-breakpoint/index.rst new file mode 100644 index 0000000000..918fecb00a --- /dev/null +++ b/devtools/docs/user/debugger-api/tutorial-breakpoint/index.rst @@ -0,0 +1,112 @@ +========================== +Tutorial: Set a breakpoint +========================== + +.. |br| raw:: html + + <br/> + +This page shows how you can try out the :doc:`Debugger API <../index>` yourself using Firefox’s Scratchpad. We use ``Debugger`` to set a breakpoint in a function, and then evaluate an expression whenever it is hit. + +This tutorial was tested against Firefox 58 Beta and Nightly. It does not work in Firefox 57. + +1. Since the ``Debugger`` API is only available to privileged JavaScript code, you’ll need to use the Browser Content Toolbox to try it out. To do this, open the Firefox developer tools, click on the options gear at the upper right of the toolbox, and make sure that both “Enable browser chrome and add-on debugging toolboxes” and “Enable remote debugging” are checked. These are located at the bottom right of the options panel; you may need to scroll to see them. Once they’re checked, you can close the developer tools. + +|br| + +2. Save the following text to an HTML file: + + .. code-block:: html + + <div onclick="report('the best div');">Click me!</div> + <div onclick="report('another great div');">Or me!</div> + <script> + function report(what) { + console.log('clicked: ' + what); + } + </script> + +|br| + +3. Visit the HTML file in your browser, and open the Browser Content Toolbox by opening the Firefox menu, choosing “Browser Tools”, and then “Browser Content Toolbox”. If that item doesn’t appear in the “Web Developer” menu, make sure you checked both boxes to enable the Browser Content Toolbox as explained in Step 1. + +|br| + +4. Our example code is long enough that the best way to run it is to use the Scratchpad panel, which is not enabled by default. To enable it, click on the options gear at the upper right of the Browser Content Toolbox, and make sure the “Scratchpad” box in the “Default Developer Tools” section the left is checked. The Scratchpad panel should appear at the top of the Toolbox alongside the Console, Debugger, and Memory panels. + +|br| + +5. Click on the Scratchpad panel and enter the following code: + + .. code-block:: javascript + + const { addDebuggerToGlobal } = ChromeUtils.importESModule( + "resource://gre/modules/jsdebugger.sys.mjs" + ); + const { console } = ChromeUtils.importESModule( + "resource://gre/modules/Console.sys.mjs" + ); + + // This defines 'Debugger' in this Scratchpad; + // it doesn't actually start debugging anything. + addDebuggerToGlobal(globalThis); + + // Create a 'Debugger' instance. + var dbg = new Debugger; + + // Make the tab's top window a debuggee, and get a + // Debugger.Object referring to the window. + var windowDO = dbg.addDebuggee(tabs[0].content); + + // Get a Debugger.Object referring to the window's `report` + // function. + var reportDO = windowDO.getOwnPropertyDescriptor('report').value; + + // Set a breakpoint at the entry point of `report`. + reportDO.script.setBreakpoint(0, { + hit: function (frame) { + console.log('hit breakpoint in ' + frame.callee.name); + console.log('what = ' + frame.eval('what').return); + } + }); + + console.log('Finished setting breakpoint!'); + +|br| + +6. In the Scratchpad, ensure that no text is selected, and press the “Run” button. + + Now, click on the text that says “Click me!” in the web page. This runs the ``div`` element’s ``onclick`` handler. When control reaches the start of the ``report`` function, ``Debugger`` calls the breakpoint handler’s ``hit`` method, passing a ``Debugger.Frame`` instance. The ``hit`` method logs the breakpoint hit to the browser content toolbox’s console. Then it evaluates the expression ``what`` in the given stack frame, and logs its result. The toolbox’s console now looks like this: + + .. image:: console.png + :alt: The breakpoint handler’s console output + :class: center + + You can also click on the text that says “Or me!”, to see ``report`` called from a different handler. + + If ``Debugger`` is unable to find the ``report`` function, or the console output does not appear, evaluate the expression ``tabs[0].content.document.location`` in the console to make sure that ``tabs[0]`` indeed refers to the HTML file you visited. If you have more than one tab visiting a ``file:`` URL, they all share a single content process, so you may need to use a different element of the array as the debuggee. + +|br| + +7. Press “Run” in the Scratchpad again. Now, clicking on “Click me!” causes the breakpoint hit to be logged twice—one for each ``Debugger`` instance. + + Multiple ``Debugger`` instances can observe the same debuggee. Re-running the code in the Scratchpad creates a fresh ``Debugger`` instance, adds the same web page as its debuggee, and then sets a new breakpoint. When you click on the ``div`` element, both ``Debugger's`` breakpoints are hit, and both handlers run. + + This shows how any number of ``Debugger``-based tools can observe a single web page simultaneously. In fact, you can use the Browser Content Toolbox’s Debugger panel to set its own breakpoint in ``report``, and it will trigger along with the first two. Keep in mind, however, that when multiple Debuggers share a debuggee, the order in which their handlers run is not specified. If more than one tool tries to influence the debuggee’s behavior, their combined behavior could be unpredictable. + +|br| + +8. Close the web page and the Browser Content Toolbox. + + Since both the Scratchpad’s global object and the debuggee window are now gone, the ``Debugger`` instances will be garbage collected, since they can no longer have any visible effect on Firefox’s behavior. The ``Debugger`` API tries to interact with garbage collection as transparently as possible; for example, if both a ``Debugger.Object`` instance and its referent are not reachable, they will both be collected, even while the ``Debugger`` instance to which the shadow belonged continues to exist. + + +Source Metadata +--------------- + +Generated from file: + js/src/doc/Debugger/Tutorial-Breakpoint.md +Watermark: + sha256:c8dd4bb69972b58e59fcbe6870499206463a5e330fda25f1214893595a1c01d0 +Changeset: + `ffa775dd5bd4 <https://hg.mozilla.org/mozilla-central/rev/ffa775dd5bd4>`_ 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 diff --git a/devtools/docs/user/deprecated_tools/canvas_tool.png b/devtools/docs/user/deprecated_tools/canvas_tool.png Binary files differnew file mode 100644 index 0000000000..8a6f567f3e --- /dev/null +++ b/devtools/docs/user/deprecated_tools/canvas_tool.png diff --git a/devtools/docs/user/deprecated_tools/deprecated_tool_notice.png b/devtools/docs/user/deprecated_tools/deprecated_tool_notice.png Binary files differnew file mode 100644 index 0000000000..b137dc3086 --- /dev/null +++ b/devtools/docs/user/deprecated_tools/deprecated_tool_notice.png diff --git a/devtools/docs/user/deprecated_tools/devtool_settings_deprecated_notice.png b/devtools/docs/user/deprecated_tools/devtool_settings_deprecated_notice.png Binary files differnew file mode 100644 index 0000000000..dfa6dd4a74 --- /dev/null +++ b/devtools/docs/user/deprecated_tools/devtool_settings_deprecated_notice.png diff --git a/devtools/docs/user/deprecated_tools/editor_mode_toggle_icon.png b/devtools/docs/user/deprecated_tools/editor_mode_toggle_icon.png Binary files differnew file mode 100644 index 0000000000..d7be24cf05 --- /dev/null +++ b/devtools/docs/user/deprecated_tools/editor_mode_toggle_icon.png diff --git a/devtools/docs/user/deprecated_tools/index.rst b/devtools/docs/user/deprecated_tools/index.rst new file mode 100644 index 0000000000..87eff82004 --- /dev/null +++ b/devtools/docs/user/deprecated_tools/index.rst @@ -0,0 +1,155 @@ +================ +Deprecated tools +================ + +Over the course of DevTools development, we have added several experimental panels to try out new ideas. Not all of these have had wide adoption, and due to the cost of maintenance, seldom used panels are eventually removed. + +We have created this list of deprecated or removed panels. This page documents the deprecated panels and the bugs that track their removal. Although these panels have been removed, you still have access to the old code, and there are alternative webextensions that you can try to get similar functionality. + +When we deprecate a panel, we begin by getting feedback from the community to determine the impact of removing that panel. Once we have decided to remove the panel, we will provide a warning message, and finally, we will remove the panel from the codebase. + +You may see a warning message, as in the following image, when trying to activate a deprecated panel: + +.. image:: devtool_settings_deprecated_notice.png + :class: border + +In addition, if you open the panel for one of these tools, you will also see a warning message about its removal. + +.. image:: deprecated_tool_notice.png + :class: border + + +Scratchpad +********** + +Scratchpad is deprecated as of Firefox 70 (`bug 1565380 <https://bugzilla.mozilla.org/show_bug.cgi?id=1565380>`_), and will be removed as of Firefox 72 (`bug 1519103 <https://bugzilla.mozilla.org/show_bug.cgi?id=1519103>`_). + + +Description +----------- + +Scratchpad provided an environment for experimenting with JavaScript code. You can write, run, and examine the result of code that interacts with the web page. + +.. image:: screen_shot_2019-08-26_at_08.08.11.png + :alt: Screenshot of the Scratchpad window with a deprecation message + + +Alternatives +------------ + +In Firefox 71+, you can write multi-line JavaScript code in the Web Console Editor Mode, making it similar to the Scratchpad. The Editor Mode can be triggered clicking on the icon on the right of the console input, or with :kbd:`Ctrl` + :kbd:`B` (:kbd:`Cmd` + :kbd:`B` on macOS) + + +.. image:: editor_mode_toggle_icon.png + :alt: Screenshot of the Webconsole in inline mode, with the editor mode icon displayed on the right of the console input + +When in Editor Mode, the :kbd:`Enter` key adds a new line in the input, and you can evaluate the expression using :kbd:`Ctrl` + :kbd:`Enter` (:kbd:`Cmd` + :kbd:`Enter` on macOS). + +.. image:: screen_shot_2019-08-26_at_08.18.26.png + :alt: Screenshot of the Webconsole multiline input, showing an evaluation with a Syntax Error and another, correct one. + +When evaluating, the input isn't cleared, which makes it possible to quickly iterate over a snippet of code. + +The results are displayed in the console output, to the right of the input, providing immediate feedback. Unlike in Scratchpad, errors are properly displayed in the output with an expandable stacktrace, making it easier to debug the code you're currently writing. + +Starting Firefox 72, you can import a Javascript file content in the console input with :kbd:`Ctrl` + :kbd:`O` (:kbd:`Cmd` + :kbd:`O` on macOS), as well as saving the console input content to a file using :kbd:`Ctrl` + :kbd:`S` (:kbd:`Cmd` + :kbd:`S` on macOS). + + +WebIDE and Connect page +*********************** + +WebIDE was deprecated as of Firefox 69 + +Disabled as of Firefox 70 (`bug 1539451 <https://bugzilla.mozilla.org/show_bug.cgi?id=1539451>`_). + +Removed as of Firefox 71 (`bug 1539462 <https://bugzilla.mozilla.org/show_bug.cgi?id=1539462>`_). + + +Description +----------- + +WebIDE allowed you to connect the Firefox Developer Tools to remote browsers, such as Firefox for Android. It was also intended to support application development for Firefox OS. + +.. image:: webide_68.png + + +Alternatives +------------ + +Remote debugging is available in about:debugging as of Firefox 68. Features not ported to about:debugging are: WiFi debugging for Firefox for Android, application development. Features that are planned but not ported yet: remote browser screenshots and edit remote browser configuration. More details on the `mailing-list thread <https://groups.google.com/forum/#!topic/mozilla.dev.developer-tools/aWA7JJ-TpRw>`_. + +Wireless debugging over Wi-Fi is possible and documented at :ref:`about-colon-debugging-connecting-to-android-over-wi-fi`. + + +Canvas debugger +*************** + +Bugzilla issue: `bug 1403938 <https://bugzilla.mozilla.org/show_bug.cgi?id=1403938>`_ + +Removed as of Firefox 67 + + +Description +----------- + +Canvas Debugger allowed users to inspect the canvas element and see how frequently a given function is called. It was deprecated due to lack of use. + +We do not have dedicated documentation for the Canvas Debugger. + +.. image:: canvas_tool.png + + +Alternatives +------------ + +`Spector.js <https://addons.mozilla.org/en-US/firefox/addon/spector-js/#&gid=1&pid=2>`_ is a WebExtension that can provide these features with 3D contexts.</span> + + +Web Audio editor +**************** + +Bugzilla issue: `bug 1403944 <https://bugzilla.mozilla.org/show_bug.cgi?id=1403944>`_ + +Removed as of Firefox 67 + + +Description +----------- + +The Web Audio Editor allowed you to examine an audio context constructed in the page and provided a visualization of its graph. This gave a high-level view of its operation, and enabled you to ensure that all the nodes are connected in the way you expect. It was possible to edit the AudioParam properties for each node in the graph. Some non-AudioParam properties, like an OscillatorNode's type property, were displayed and editable as well. It was deprecated due to lack of use. + +More details about the :doc:`Web Audio Editor <../web_audio_editor/index>` + +.. image:: webaudio_tool.png + :class: border + + +Alternatives +------------ + +Alternatives include the `AudioN <https://github.com/google/audion>`_ and https://github.com/spite/WebAudioExtension WebExtensions. + + +Shader editor +************* + +Bugzilla issue: `bug 1342237 <https://bugzilla.mozilla.org/show_bug.cgi?id=1342237>`_ + +Removed as of Firefox 67 + + +Description +----------- + +The Shader Editor allowed users to examine and edit the source of the WebGL vertex and fragment shaders. It was deprecated due to low usage and maintenance costs. + +:doc:`Shader Editor <../shader_editor/index>` + +.. image:: shadereditor_tool.png + :class: border + + +Alternatives +------------ + +An alternative to this panel is this extension: https://github.com/spite/ShaderEditorExtension, or `Spector.js <https://addons.mozilla.org/en-US/firefox/addon/spector-js/#&gid=1&pid=2>`_ also supports a Shader Editor that requires a library to use a shader reloader hook. Currently only the Babylon library does. diff --git a/devtools/docs/user/deprecated_tools/screen_shot_2019-08-26_at_08.08.11.png b/devtools/docs/user/deprecated_tools/screen_shot_2019-08-26_at_08.08.11.png Binary files differnew file mode 100644 index 0000000000..4f9e6d4618 --- /dev/null +++ b/devtools/docs/user/deprecated_tools/screen_shot_2019-08-26_at_08.08.11.png diff --git a/devtools/docs/user/deprecated_tools/screen_shot_2019-08-26_at_08.18.26.png b/devtools/docs/user/deprecated_tools/screen_shot_2019-08-26_at_08.18.26.png Binary files differnew file mode 100644 index 0000000000..ebdce97f2a --- /dev/null +++ b/devtools/docs/user/deprecated_tools/screen_shot_2019-08-26_at_08.18.26.png diff --git a/devtools/docs/user/deprecated_tools/shadereditor_tool.png b/devtools/docs/user/deprecated_tools/shadereditor_tool.png Binary files differnew file mode 100644 index 0000000000..bdc24e2c57 --- /dev/null +++ b/devtools/docs/user/deprecated_tools/shadereditor_tool.png diff --git a/devtools/docs/user/deprecated_tools/webaudio_tool.png b/devtools/docs/user/deprecated_tools/webaudio_tool.png Binary files differnew file mode 100644 index 0000000000..95efede30e --- /dev/null +++ b/devtools/docs/user/deprecated_tools/webaudio_tool.png diff --git a/devtools/docs/user/deprecated_tools/webide_68.png b/devtools/docs/user/deprecated_tools/webide_68.png Binary files differnew file mode 100644 index 0000000000..798b4bffea --- /dev/null +++ b/devtools/docs/user/deprecated_tools/webide_68.png diff --git a/devtools/docs/user/devtools_layoutmenu.png b/devtools/docs/user/devtools_layoutmenu.png Binary files differnew file mode 100644 index 0000000000..bc235c7a15 --- /dev/null +++ b/devtools/docs/user/devtools_layoutmenu.png diff --git a/devtools/docs/user/devtoolsapi/index.rst b/devtools/docs/user/devtoolsapi/index.rst new file mode 100644 index 0000000000..31a44a022f --- /dev/null +++ b/devtools/docs/user/devtoolsapi/index.rst @@ -0,0 +1,796 @@ +============ +DevTools API +============ + +.. warning:: + Deprecated: This feature is no longer recommended. Though some browsers might still support it, it may have already been removed from the relevant web standards, may be in the process of being dropped, or may only be kept for compatibility purposes. Avoid using it, and update existing code if possible; see the compatibility table at the bottom of this page to guide your decision. Be aware that this feature may cease to work at any time. + +.. warning:: + The DevTools API is still WIP. If you notice any inconsistency, please let The Firefox Developer Tools Team know. + + +While this api is currently a work-in-progress, there are usable portions of :doc:`page inspector <../page_inspector/index>` and :doc:`debugger <../debugger/index>` that may be used currently. + + +Introduction +************ + +The DevTools API provides a way to register and access developer tools in Firefox. + +In terms of User Interface, each registered tool lives in its own tab (we call one tab a **panel**). These tabs are located in a box we call a **Toolbox**. A toolbox can be *hosted* within a browser tab (at the bottom or on the side), or in its own window (we say that the toolbox is *undocked*). A Toolbox (and all the tools it contains) is linked to a **Target**, which is the object the tools are debugging. A target is usually a web page (a tab), but can be other things (a chrome window, a remote tab,…). + +In terms of code, each tool has to provide a **ToolDefinition** object. A definition is a JS light object that exposes different information about the tool (like its name and its icon), and a *build* method that will be used later-on to start an instance of this tool. The **gDevTools** global object provides methods to register a tool definition and to access tool instances. An instance of a tool is called a **ToolPanel**. The ToolPanel is built only when the tool is selected (not when the toolbox is opened). There is no way to "close/destroy" a ToolPanel. The only way to close a toolPanel is to close its containing toolbox. All these objects implement the **EventEmitter** interface. + + +API +*** + +gDevTools +--------- + +The ``gDevTools`` API can be used to register new tools, themes and handle toolboxes for different tabs and windows. To use the ``gDevTools`` API from an add-on, it can be imported with following snippet + +.. code-block:: JavaScript + + const { gDevTools } = require("resource:///modules/devtools/gDevTools.jsm"); + + +Methods +~~~~~~~ + +``registerTool(toolDefinition)`` + Registers a new tool and adds a tab to each existing toolbox. + + **Parameters:** + + - ``toolDefinition {ToolDefinition}`` - An object that contains information about the tool. See :ref:`ToolDefinition <devtoolsapi-tool-definition>` for details. + +``unregisterTool(tool)`` + Unregisters the given tool and removes it from all toolboxes. + + **Parameters:** + + - ``tool {ToolDefinition|String}`` - The tool definition object or the id of the tool to unregister. + +``registerTheme(themeDefinition)`` + Registers a new theme. + + **Parameters:** + + - ``themeDefinition {ThemeDefinition}`` - An object that contains information about the theme. + +``unregisterTheme(theme)`` + Unregisters the given theme. + + **Parameters:** + + - ``theme {ThemeDefinition|String}`` - The theme definition object or the theme identifier. + +``showToolbox(commands[, toolId [, hostType [, hostOptions]]])`` + Opens a toolbox for given target either by creating a new one or activating an existing one. + + **Parameters:** + + - ``commands {Object}`` - The commands object designating which debugging context the toolbox will debug. + - ``toolId {String}`` - The tool that should be activated. If unspecified the previously active tool is shown. + - ``hostType {String}`` - The position the toolbox will be placed. One of ``bottom``, ``side``, ``window``, ``custom``. See :ref:`HostType <devtoolsapi-host-type>` for details. + - ``hostOptions {Object}`` - An options object passed to the selected host. See :ref:`HostType <devtoolsapi-host-type>` for details. + + **Return value:** + A `Promise <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise>`_ that is fulfilled with the :ref:`Toolbox <devtoolsapi-toolbox>` instance once it has been initialized and the selected tool is loaded. + +``getToolbox(target)`` + Fetch the :ref:`Toolbox <devtoolsapi-toolbox>` object for the given target. + + **Parameters:** + + - ``target {Target}`` - The target the toolbox is debugging. + + **Return value:** + :ref:`Toolbox <devtoolsapi-toolbox>` object or undefined if there's no toolbox for the given target.. + +``closeToolbox(target)`` + Closes the toolbox for given target. + + **Parameters:** + + - ``target {Target}`` - The target of the toolbox that should be closed. + + **Return value:** + A `Promise <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise>`_ that is fulfilled once the toolbox has been destroyed. + +``getDefaultTools()`` + Returns an `Array <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array>`_ of :ref:`ToolDefinition <devtoolsapi-tool-definition>` objects for the built-in tools. + +``getAdditionalTools()`` + Returns an `Array <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array>`_ of :ref:`ToolDefinition <devtoolsapi-tool-definition>` objects for tools added by addons. + +``getToolDefinition(toolId)`` + Fetch the :ref:`ToolDefinition <devtoolsapi-tool-definition>` object for a tool if it exists and is enabled. + + **Parameters:** + + - ``toolId {String}`` - The ID of the tool. + + **Return value:** + A :ref:`ToolDefinition <devtoolsapi-tool-definition>` if a tool with the given ID exists and is enabled, null otherwise. + +``getToolDefinitionMap()`` + Returns a toolId → :ref:`ToolDefinition <devtoolsapi-tool-definition>` map for tools that are enabled. + +``getToolDefinitionArray()`` + Returns an `Array <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array>`_ of :ref:`ToolDefinition <devtoolsapi-tool-definition>` objects for enabled tools sorted by the order they appear in the toolbox. + +``getThemeDefinition(themeId)`` + Fetch the ``ThemeDefinition`` object for the theme with the given id. + + **Parameters:** + + - ``themeId {String}`` - The ID of the theme. + + **Return value:** + A ``ThemeDefinition`` object if the theme exists, null otherwise. + +``getThemeDefinitionMap()`` + Returns a toolId → ``ThemeDefinition`` map for available themes. + +``getThemeDefinitionArray()`` + Returns an `Array <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array>`_ of ``ThemeDefinition`` objects for available themes. + + +Events +~~~~~~ + +Following events are emitted by the ``gDevTools`` object via the :ref:`EventEmitter <devtoolsapi-event-emitter>` interface. + + +``tool-registered (toolId)`` + A new tool has been registered. + +``tool-unregistered(tool)`` + A tool has been unregistered. The parameter is a :ref:`ToolDefinition <devtoolsapi-tool-definition>` object. + +``theme-registered(themeId)`` + A new theme has been registered. + +``theme-unregistered(theme)`` + A theme has been unregistered. The parameter is a ``ThemeDefinition`` object. + +``toolbox-ready(toolbox)`` + A new toolbox has been created and is ready to use. The parameter is a :ref:`Toolbox <devtoolsapi-toolbox>` object instance. + +``toolbox-destroy(target)`` + The toolbox for the specified target is about to be destroyed. + +``toolbox-destroyed(target)`` + The toolbox for the specified target has been destroyed. + +``{toolId}-init(toolbox, iframe)`` + A tool with the given ID has began to load in the given toolbox to the given frame. + +``{toolId}-build(toolbox, panel)`` + A tool with the given ID has began to initialize in the given toolbox. The panel is the object returned by the ``ToolDefinition.build()`` method. + +``{toolId}-ready(toolbox, panel)`` + A tool with the given ID has finished its initialization and is ready to be used. The panel is the object returned by the ``ToolDefinition.build()`` method. + +``{toolId}-destroy(toolbox, panel)`` + A tool with the given ID is about to be destroyed. The panel is the object returned by the ``ToolDefinition.build()`` method. + + +.. _devtoolsapi-toolbox: + +Toolbox +------- + +A Toolbox is a frame for the :ref:`ToolPanel <devtoolsapi-tool-panel>` that is debugging a specific target. + + +Properties +~~~~~~~~~~ + + +``target`` + **Target**. The Target this toolbox is debugging. + + +``hostType`` + **Toolbox.HostType**. The type of the host this Toolbox is docked to. The value is one of the ``Toolbox.HostType`` constants. + +``zoomValue`` + The current zoom level of the Toolbox. + + +Constants +~~~~~~~~~ + +The Toolbox constructor contains following constant properties. + + +``Toolbox.HostType.BOTTOM`` + Host type for the default toolbox host at the bottom of the browser window. + +``Toolbox.HostType.SIDE`` + Host type for the host at the side of the browser window. + +``Toolbox.HostType.WINDOW`` + Host type for the separate Toolbox window. + +``Toolbox.HostType.CUSTOM`` + Host type for a custom frame host. + + +Methods +~~~~~~~ + +``getCurrentPanel()`` + Get the currently active :ref:`ToolPanel <devtoolsapi-tool-panel>`. + + **Return value:** + The :ref:`ToolPanel <devtoolsapi-tool-panel>` object that was returned from ``ToolPanel.build()``. + +``getPanel(toolId)`` + Get the :ref:`ToolPanel <devtoolsapi-tool-panel>` for given tool. + + **Parameters:** + + - ``toolId {String}`` - The tool identifier. + + **Return value:** + The :ref:`ToolPanel <devtoolsapi-tool-panel>` object if the tool with the given ``toolId`` is active, otherwise ``undefined``. + +``getPanelWhenReady(toolId)`` + Similar to ``getPanel()`` but waits for the tool to load first. If the tool is not already loaded or currently loading the returned `Promise <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise>`_ won't be fulfilled until something triggers the tool to load. + + **Parameters:** + + - ``toolId {String}`` - The tool identifier. + + **Return value:** + A `Promise <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise>`_ that is fulfilled with the :ref:`ToolPanel <devtoolsapi-tool-panel>` object once the tool has finished loading. + +``getToolPanels()`` + Returns a ``toolId`` → :ref:`ToolPanel <devtoolsapi-tool-panel>` `Map <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map>`_ for currently loaded tools. + +``getNotificationBox()`` + Returns a ``XULElem("notificationbox")`` element for the Toolbox that can be used to display notifications to the user. + +``loadTool(toolId)`` + Loads the tool with the given ``toolId`` in the background but does not activate it. + + **Parameters:** + + - ``toolId {String}`` - The tool identifier. + + **Return value:** + A `Promise <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise>`_ that is fulfilled with the :ref:`ToolPanel <devtoolsapi-tool-panel>` object of the loaded panel once the tool has loaded. + +``selectTool(toolId)`` + Selects the tool with the given ``toolId``. + + **Parameters:** + + - ``toolId {String}`` - The tool identifier. + + **Return value:** + A `Promise <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise>`_ that is fulfilled with the :ref:`ToolPanel <devtoolsapi-tool-panel>` object of the selected panel once the tool has loaded and activated. + +``selectNextTool()`` + Selects the next tool in the ``Toolbox``. + + **Return value:** + A `Promise <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise>`_ that is fulfilled with the :ref:`ToolPanel <devtoolsapi-tool-panel>` object of the selected panel. + +``selectPreviousTool()`` + Selects the previous tool in the ``Toolbox``. + + **Return value:** + A `Promise <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise>`_ that is fulfilled with the :ref:`ToolPanel <devtoolsapi-tool-panel>` object of the selected panel. + +``highlightTool(toolId)`` + Highlights the tab for the given tool. + + **Parameters:** + + - ``toolId {String}`` - The tool to highlight. + +``unhighlightTool(toolId)`` + Unhighlights the tab for the given tool. + + **Parameters:** + + - ``toolId {String}`` - The tool to unhighlight. + +``openSplitConsole()`` + Opens the split Console to the bottom of the toolbox. + + **Return value:** + A `Promise <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise>`_ that is fulfilled once the Console has loaded. + +``closeSplitConsole()`` + Closes the split console. + +``toggleSplitConsole()`` + Toggles the state of the split console. + + **Return value:** + A `Promise <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise>`_ that is fulfilled once the operation has finished. + +``switchHost(hostType)`` + Switches the location of the toolbox + + **Parameters:** + + - ``hostType {Toolbox.HostType}`` - The type of the new host. + + **Return value:** + A `Promise <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise>`_ that is fulfilled once the new host is ready. + +``reloadTarget(force)`` + Reloads the current target of the toolbox. + + **Parameters:** + + - ``force {Boolean} -`` If true the target is shift-reloaded i.e. the cache is bypassed during the reload. + +``zoomIn()`` + Increases the zoom level of the ``Toolbox`` document. + +``zoomOut()`` + Decreases the zoom level of the ``Toolbox`` document. + +``zoomReset()`` + Resets the zoom level of the ``Toolbox`` document. + +``setZoom(value)`` + Set the zoom level to an arbitrary value. + + **Parameters:** + + - ``value {Number}`` - The zoom level such as ``1.2``. + +``destroy()`` + Closes the toolbox. + + **Return value:** + A `Promise <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise>`_ that is resolved once the ``Toolbox`` is destroyed. + + +Events +~~~~~~ + +The Toolbox object emits following events via the :ref:`EventEmitter <devtoolsapi-event-emitter>` interface. + + +``host-changed`` + The Host for this Toolbox has changed. + +``ready`` + The ``Toolbox`` is ready to use. + +``select(toolId)`` + A tool has been selected. This event is emitted before the corresponding ``{toolId}-selected`` event. + +``{toolId}-init(frame)`` + A tool is about to be loaded. The frame is the `iframe <https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe>`_ element that has been created for the tool. + +``{toolId}-build(panel)`` + The frame for a tool has loaded and the ``ToolPanel.build()`` method has been called but the asynchronous initialization has not started. The parameter is a :ref:`ToolPanel <devtoolsapi-tool-panel>` object. + +``{toolId}-ready(panel)`` + The asynchronous initialization for a tool has completed and it is ready to be used. The parameter is a :ref:`ToolPanel <devtoolsapi-tool-panel>` object. + +``{toolId}-selected(panel)`` + A tool has been selected. The parameter is a :ref:`ToolPanel <devtoolsapi-tool-panel>` object. + +``{toolId}-destroy(panel)`` + A tool is about to be destroyed. The parameter is a :ref:`ToolPanel <devtoolsapi-tool-panel>` object. + +``destroy`` + The ``Toolbox`` is about to be destroyed. + +``destroyed`` + The ``Toolbox`` has been destroyed. + + +.. _devtoolsapi-tool-definition: + +ToolDefinition +-------------- + +A ``ToolDefinition`` object contains all the required information for a tool to be shown in the toolbox. + + +Methods +~~~~~~~ + +``isToolSupported(toolbox)`` + A method that is called during toolbox construction to check if the tool supports debugging the given target of the given toolbox. + + **Parameters:** + + - ``toolbox {Toolbox}`` - The toolbox where the tool is going to be displayed, if supported. + + **Return value:** + A boolean indicating if the tool supports the given toolbox's target. + +``build(window, toolbox)`` + A method that builds the :ref:`ToolPanel <devtoolsapi-tool-panel>` for this tool. + + **Parameters:** + + - ``window {Window}`` - The `Window <https://developer.mozilla.org/en-US/docs/Web/API/Window>`_ object for frame the tool is being built into. + - ``toolbox {Toolbox}`` - The :ref:`Toolbox <devtoolsapi-toolbox>` the tool is being built for. + + **Return value:** + A :ref:`ToolPanel <devtoolsapi-tool-panel>` for the tool. + + +``onKey(panel, toolbox)`` + **Optional.** A method that is called when the keyboard shortcut for the tool is activated while the tool is the active tool. + + **Parameters:** + + - ``panel {ToolPanel}`` - The :ref:`ToolPanel <devtoolsapi-tool-panel>` for the tool. + - ``toolbox {Toolbox}`` - The toolbox for the shortcut was triggered for. + + **Return value:** + Undefined. + + +Properties +~~~~~~~~~~ + +The ToolDefinition object can contain following properties. Most of them are optional and can be used to customize the presence of the tool in the Browser and the Toolbox. + + +``id`` + **String, required.** An unique identifier for the tool. It must be a valid id for an HTML `Element <https://developer.mozilla.org/en-US/docs/Web/API/Element>`_. + +``url`` + **String, required.** An URL of the panel document. + +``label`` + **String, optional.** The tool's name. If undefined the ``icon`` should be specified. + +``tooltip`` + **String, optional.** The tooltip for the tool's tab. + +``panelLabel`` + **String, optional.** An accessibility label for the panel. + +``ordinal`` + **Integer, optional.** The position of the tool's tab within the toolbox. **Default:** 99 + +``visibilityswitch`` + **String, optional.** A preference name that controls the visibility of the tool. **Default:** ``devtools.{id}.enabled`` + +``icon`` + **String, optional.** An URL for the icon to show in the toolbox tab. If undefined the label should be defined. + +``highlightedicon`` + **String, optional.** An URL for an icon that is to be used when the tool is highlighted (see e.g. paused, inactive debugger). **Default:** ``{icon}`` + +``iconOnly`` + **Boolean, optional.** If true, the label won't be shown in the tool's tab. **Default:** false + +``invertIconForLightTheme`` + **Boolean, optional.** If true the colors of the icon will be inverted for the light theme. **Default:** false + +``key`` + **String, optional.** The key used for keyboard shortcut. Either ``key`` or ``keycode`` value. + +``modifiers`` + **String, optional.** ``modifiers`` for the keyboard shortcut. + +``preventClosingOnKey`` + **Boolean, optional.** If true the tool won't close if its keybinding is pressed while it is active. **Default:** false + +``inMenu`` + **Boolean, optional.** If true the tool will be shown in the Developer Menu. **Default:** false + +``menuLabel`` + **String, optional.** A label for the Developer Menu item. **Default:** ``{label}`` + +``accesskey`` + **String, optional.** ``accesskey`` for the Developer Menu ``xul:menuitem``. + + +Example +~~~~~~~ + +Here's a minimal definition for a tool. + +.. code-block:: JavaScript + + let def = { + id: "my-tool", + label: "My Tool", + icon: "chrome://browser/skin/devtools/tool-webconsole.svg", + url: "about:blank", + isToolSupported: toolbox => true, + build: (window, toolbox) => new MyToolPanel(window, toolbox) + }; + + // Register it. + gDevTools.registerTool(def); + + +.. _devtoolsapi-target-type: + +TargetType +---------- + +FIXME: + + +.. _devtoolsapi-host-type: + +HostType +-------- + +FIXME + + +.. _devtoolsapi-tool-panel: + +ToolPanel +--------- + +The ToolPanel is an interface the toolbox uses to manage the panel of a tool. The object that ``ToolDefinition.build()`` returns should implement the methods described below. + +Methods +~~~~~~~ + + +``open()`` + **Optional**. A method that can be used to perform asynchronous initialization. If the method returns a `Promise <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise>`_, many operations (e.g. ``gDevTools.showToolbox()`` or ``toolbox.selectTool()``) and events (e.g. ``toolbox-ready`` are delayed until the promise has been fulfilled. + + **Return value:** + The method should return a `Promise <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise>`_ that is resolved with the ``ToolPanel`` object once it's ready to be used. + +``destroy()`` + A method that is called when the toolbox is closed or the tool is unregistered. If the tool needs to perform asynchronous operations during destruction the method should return a `Promise <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise>`_ that is resolved once the process is complete. + + **Return value:** + A `Promise <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise>`_ if the function performs asynchronous operations, otherwise ``undefined``. + + +Example +~~~~~~~ + +Here's a basic template for a ToolPanel implementation. + +.. code-block:: JavaScript + + // In the ToolDefinition object, do + // build: (window, target) => new MyPanel(window, target), + + function MyPanel(window, target) { + // The window object that has loaded the URL defined in the ToolDefinition + this.window = window; + // The Target this toolbox is debugging. + this.target = target; + + // Do synchronous initialization here. + window.document.body.addEventListener("click", this.handleClick); + } + + MyPanel.prototype = { + open: function() { + // Any asynchronous operations should be done here. + return this.doSomethingAsynchronous() + .then(() => this); + }, + + destroy: function() { + // Synchronous destruction. + this.window.document.body.removeEventListener("click", this.handleClick); + + // Async destruction. + return this.destroySomethingAsynchronously() + .then(() => console.log("destroyed")); + }, + + handleClick: function(event) { + console.log("Clicked", event.originalTarget); + }, + }; + + +.. _devtoolsapi-event-emitter: + +EventEmitter +------------ + +``EventEmitter`` is an interface many Developer Tool classes and objects implement and use to notify others about changes in their internal state. + +When an event is emitted on the ``EventEmitter``, the listeners will be called with the event name as the first argument and the extra arguments are spread as the remaining parameters. + +.. note:: + Some components use Add-on SDK event module instead of the DevTools EventEmitter. Unfortunately, their API's are a bit different and it's not always evident which one a certain component is using. The main differences between the two modules are that the first parameter for Add-on SDK events is the first payload argument instead of the event name and the ``once`` method does not return a Promise. The work for unifying the event paradigms is ongoing in `bug 952653 <https://bugzilla.mozilla.org/show_bug.cgi?id=952653>`_. + + +Methods +~~~~~~~ + +The following methods are available on objects that have been decorated with the ``EventEmitter`` interface. + +``emit(eventName, ...extraArguments)`` + Emits an event with the given name to this object. + + **Parameters:** + + - ``eventName {String}`` - The name of the event. + - ``extraArguments {...Any}`` - Extra arguments that are passed to the listeners. + +``on(eventName, listener)`` + Adds a listener for the given event. + +``off(eventName, listener)`` + Removes the previously added listener from the event. + +``once(eventName, listener)`` + Adds a listener for the event that is removed after it has been emitted once. + + **Return value:** + A `Promise <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise>`_ that is fulfilled with the first extra argument for the event when then event is emitted. If the event contains multiple payload arguments, the rest are discarded and can only be received by providing the listener function to this method. + + +Examples +~~~~~~~~ + +Here's a few examples using the ``gDevTools`` object. + +.. code-block:: JavaScript + + let onInit = (eventName, toolbox, netmonitor) => console.log("Netmonitor initialized!"); + + // Attach a listener. + gDevTools.on("netmonitor-init", onInit); + + // Remove a listener. + gDevTools.off("netmonitor-init", onInit); + + // Attach a one time listener. + gDevTools.once("netmonitor-init", (eventName, toolbox, netmonitor) => { + console.log("Network Monitor initialized once!", toolbox, netmonitor); + }); + + // Use the Promise returned by the once method. + gDevTools.once("netmonitor-init").then(toolbox => { + // Note that the second argument is not available here. + console.log("Network Monitor initialized to toolbox", toolbox); + }); + + +ToolSidebar +----------- + +To build a sidebar in your tool, first, add a xul:tabbox where you want the sidebar to live: + +.. code-block:: xml + + <splitter class="devtools-side-splitter"/> + <tabbox id="mytool-sidebar" class="devtools-sidebar-tabs" hidden="true"> + <tabs/> + <tabpanels flex="1"/> + </tabbox> + +A sidebar is composed of tabs. Each tab will hold an iframe. For example, in the Inspector, there are 3 tabs (Computed View, Rule View, Layout View). The user can select the tab they want to see. + +If the availability of the tabs depends on some tool-related conditions, we might want to not let the user select a tab. This API provides methods to hide the tabstripe. For example, in the Web Console, there are 2 views (Network View and Object View). These views are only available in certain conditions controlled by the WebConsole code. So it's up the WebConsole the hide and show the sidebar, and select the correct tab. + +If the loaded document exposes a ``window.setPanel(ToolPanel)`` function, the sidebar will call it once the document is loaded. + +.. list-table:: Methods + :widths: 70 30 + :header-rows: 1 + + * - Method + - Description + + * - ``new ToolSidebar(xul:tabbox, ToolPanel, uid, showTabstripe=true)`` + - ToolSidebar constructor + + * - ``void addTab(tabId, url, selected=false)`` + - Add a tab in the sidebar + + * - ``void select(tabId)`` + - Select a tab + + * - ``void hide()`` + - Hide the sidebar + + * - ``void show()`` + - Show the sidebar + + * - ``void toggle()`` + - Toggle the sidebar + + * - ``void getWindowForTab(tabId)`` + - Get the iframe containing the tab content + + * - ``tabId getCurrentTabID()`` + - Return the id of tabId of the current tab + + * - ``tabbox getTab(tabId)`` + - Return a tab given its id + + * - ``destroy()`` + - Destroy the ToolSidebar object + +.. list-table:: Events + :widths: 70 30 + :header-rows: 1 + + * - Events + - Description + + * - ``new-tab-registered`` + - A new tab has been added + + * - ``{tabId}-ready`` + - Tab is loaded and can be used + + * - ``{tabId}-selected`` + - Tab has been selected and is visible + + * - ``{tabId}-unselected`` + - Tab has been unselected and is not visible + + * - ``show`` + - The sidebar has been opened. + + * - ``hide`` + - The sidebar has been closed. + + +Examples +-------- + +Register a tool + +.. code-block:: JavaScript + + gDevTools.registerTool({ + // FIXME: missing key related properties. + id: "inspector", + icon: "chrome://browser/skin/devtools/inspector-icon.png", + url: "chrome://browser/content/devtools/inspector/inspector.xul", + get label() { + let strings = Services.strings.createBundle("chrome://browser/locale/devtools/inspector.properties"); + return strings.GetStringFromName("inspector.label"); + }, + + isToolSupported: function(toolbox) { + return toolbox.commands.descriptorFront.isLocalTab; + }, + + build: function(iframeWindow, toolbox, node) { + return new InspectorPanel(iframeWindow, toolbox, node); + } + }); + + +Open a tool, or select it if the toolbox is already open: + +.. code-block:: JavaScript + + let target = TargetFactory.forTab(gBrowser.selectedTab); + let toolbox = gDevTools.openToolbox(target, null, "inspector"); + + toolbox.once("inspector-ready", function(event, panel) { + let inspector = toolbox.getToolPanels().get("inspector"); + inspector.selection.setNode(target, "browser-context-menu"); + }); + + +Add a sidebar to an existing tool: + +.. code-block:: JavaScript + + let sidebar = new ToolSidebar(xulTabbox, toolPanel, "toolId"); + sidebar.addTab("tab1", "chrome://browser/content/.../tab1.xhtml", true); + sidebar.addTab("tab2", "chrome://browser/content/.../tab2.xhtml", false); + sidebar.show(); diff --git a/devtools/docs/user/devtoolscolors/index.rst b/devtools/docs/user/devtoolscolors/index.rst new file mode 100644 index 0000000000..68a54a1d62 --- /dev/null +++ b/devtools/docs/user/devtoolscolors/index.rst @@ -0,0 +1,207 @@ +============== +DevToolsColors +============== + +.. warning:: + **Firefox developers**: Don't change any of these values without UX approval. If any of these values need to be changed, you will need to change some CSS code in ``/browser/themes/*/devtools/``. File a DevTools bug accordingly. + + +This chart lists colors and CSS variables as implemented in the dark theme and light theme for developer tools. + +.. |br| raw:: html + + <br/><br/> + +.. list-table:: + :widths: 25 22 22 31 + :header-rows: 1 + + * - + - Dark Theme + - Light Theme + - CSS Variables + + * - **Chrome Colors** + - + - + - + + * - **Tab Toolbar** + - #252c33 |br| + rgba(37, 44, 51, 1) + - #ebeced |br| + rgba(235, 236, 237, 1) + - ``--theme-tab-toolbar-background`` + + * - **Toolbars** + - #343c45 |br| + rgba(52, 60, 69, 1) + - #f0f1f2 |br| + rgba(240, 241, 242, 1) + - ``--theme-toolbar-background`` + + * - **Selection Background** + - #1d4f73 |br| + rgba(29, 79, 115, 1) + - #4c9ed9 |br| + rgba(76, 158, 217, 1) + - ``--theme-selection-background`` + + * - **Selection Text Color** + - #f5f7fa |br| + rgba(245, 247, 250, 1) + - #f5f7fa |br| + rgba(245, 247, 250, 1) + - ``--theme-selection-color`` + + * - **Splitters** + - #000000 |br| + rgba(0, 0, 0, 1) + - #aaaaaa |br| + rgba(170, 170, 170, 1) + - ``--theme-splitter-color`` + + * - **Comment** + - #5c6773 |br| + rgba(92, 103, 115, 1) + - #747573 |br| + rgba(116, 117, 115, 1) + - ``--theme-comment`` + + * - **Content Colors** + - + - + - + + * - **Background - Body** + - #14171a |br| + rgba(17, 19, 21, 1) + - #fcfcfc |br| + rgba(252, 252, 252, 1) + - ``--theme-body-background`` + + * - **Background - Sidebar** + - #181d20 |br| + rgba(24, 29, 32, 1) + - #f7f7f7 |br| + rgba(247, 247, 247, 1) + - ``--theme-sidebar-background`` + + * - **Background - Attention** + - #b28025 |br| + rgba(178, 128, 37, 1) + - #e6b064 |br| + rgba(230, 176, 100, 1) + - ``--theme-contrast-background`` + + * - **Text Colors** + - + - + - + + * - **Body Text** + - #8fa1b2 |br| + rgba(143, 161, 178, 1) + - #18191a |br| + rgba(24, 25, 26, 1) + - ``--theme-body-color`` + + * - **Foreground (Text) - Grey** + - #b6babf |br| + rgba(182, 186, 191, 1) + - #585959 |br| + rgba(88, 89, 89, 1) + - ``--theme-body-color-alt`` + + * - **Content (Text) - High Contrast** + - #a9bacb |br| + rgba(169, 186, 203, 1) + - #292e33 |br| + rgba(41, 46, 51, 1) + - ``--theme-content-color1`` + + * - **Content (Text) - Grey** + - #8fa1b2 |br| + rgba(143, 161, 178, 1) + - #8fa1b2 |br| + rgba(143, 161, 178, 1) + - ``--theme-content-color2`` + + * - **Content (Text) - Dark Grey** + - #667380 |br| + rgba(102, 115, 128, 1) + - #667380 |br| + rgba(102, 115, 128, 1) + - ``--theme-content-color3`` + + * - **Highlight Colors** + - + - + - + + * - **Blue** + - #46afe3 |br| + rgba(70, 175, 227, 1) + - #0088cc |br| + rgba(0, 136, 204, 1) + - ``--theme-highlight-blue`` + + * - **Purple** + - #6b7abb |br| + rgba(107, 122, 187, 1) + - #5b5fff |br| + rgba(91, 95, 255, 1) + - ``--theme-highlight-purple`` + + * - **Pink** + - #df80ff |br| + rgba(223, 128, 255, 1) + - #b82ee5 |br| + rgba(184, 46, 229, 1) + - ``--theme-highlight-pink`` + + * - **Red** + - #eb5368 |br| + rgba(235, 83, 104, 1) + - #ed2655 |br| + rgba(237, 38, 85, 1) + - ``--theme-highlight-red`` + + * - **Orange** + - #d96629 |br| + rgba(217, 102, 41, 1) + - #f13c00 |br| + rgba(241, 60, 0, 1) + - ``--theme-highlight-orange`` + + * - **Light Orange** + - #d99b28 |br| + rgba(217, 155, 40, 1) + - #d97e00 |br| + rgba(217, 126, 0, 1) + - ``--theme-highlight-lightorange`` + + * - **Green** + - #70bf53 |br| + rgba(112, 191, 83, 1) + - #2cbb0f |br| + rgba(44, 187, 15, 1) + - ``--theme-highlight-green`` + + * - **Blue-Grey** + - #5e88b0 |br| + rgba(94, 136, 176, 1) + - #0072ab |br| + rgba(0, 114, 171, 1) + - ``--theme-highlight-bluegrey`` + + * - **Yellow** + - #ffffb4 |br| + rgba(255, 255, 180, 1) + - #ffffb4 |br| + rgba(255, 255, 180, 1) + - ``--theme-highlight-yellow`` + + +.. warning:: + Not yet finalized. See `bug 916766 <https://bugzilla.mozilla.org/show_bug.cgi?id=916766>`_ for progress. diff --git a/devtools/docs/user/dom_property_viewer/dom_inspector.png b/devtools/docs/user/dom_property_viewer/dom_inspector.png Binary files differnew file mode 100644 index 0000000000..013af4b1c8 --- /dev/null +++ b/devtools/docs/user/dom_property_viewer/dom_inspector.png diff --git a/devtools/docs/user/dom_property_viewer/dom_inspector_refresh_button.png b/devtools/docs/user/dom_property_viewer/dom_inspector_refresh_button.png Binary files differnew file mode 100644 index 0000000000..ed93b9ebdb --- /dev/null +++ b/devtools/docs/user/dom_property_viewer/dom_inspector_refresh_button.png diff --git a/devtools/docs/user/dom_property_viewer/dom_inspector_search_box.png b/devtools/docs/user/dom_property_viewer/dom_inspector_search_box.png Binary files differnew file mode 100644 index 0000000000..f5f25c975e --- /dev/null +++ b/devtools/docs/user/dom_property_viewer/dom_inspector_search_box.png diff --git a/devtools/docs/user/dom_property_viewer/index.rst b/devtools/docs/user/dom_property_viewer/index.rst new file mode 100644 index 0000000000..c5893a82fa --- /dev/null +++ b/devtools/docs/user/dom_property_viewer/index.rst @@ -0,0 +1,53 @@ +=================== +DOM Property Viewer +=================== + +.. container:: block_quote + + The DOM Property Viewer is new in Firefox 48. It is disabled by default. Enable it in the :ref:`Developer Tools Settings <tool-toolbox-settings>` + +The DOM Property Viewer lets you inspect the properties of the `DOM <https://developer.mozilla.org/en-US/docs/Glossary/DOM>`_ as an expandable tree structure, starting from the `window <https://developer.mozilla.org/en-US/docs/Web/API/Window>`_ object of the current page or the :doc:`selected iframe <../working_with_iframes/index>`. + +.. image:: dom_inspector.png + :class: center + + +Enabling the DOM Property Viewer +******************************** + +The DOM Property Viewer is not enabled by default. To enable it, open the :ref:`developer tools settings <tool-toolbox-settings>` and check the "DOM" box under "Default Firefox Developer Tools". + + +Opening the DOM Property Viewer +******************************* + +Once enabled, you can select the *DOM* panel in the Web Developer Tools, accessible from the Browser Tools submenu + +The :doc:`Toolbox <../tools_toolbox/index>` will appear at the bottom of the browser window, with the DOM Property Viewer activated. It's just called "DOM" in the Toolbox. + +DOM Property Viewer user interface +********************************** + +DOM tree +-------- + +The different properties of the DOM are displayed as an expandable tree. The left-hand side shows the property's name, and the right-hand side shows its value. Up to three properties of an object and items of an array are displayed. If a property has more elements than this, you'll see a "more..." annotation, and will need to click the property to see all elements. A lock icon indicates that a property is not writable. + +Refreshing the display +---------------------- + +If the DOM changes you can hit the *Refresh* button to update the display: + +.. image:: dom_inspector_refresh_button.png + :alt: Button to update the DOM Inspector display + :class: center + +Filtering +--------- + +There is a search box within the toolbar: + +.. image:: dom_inspector_search_box.png + :class: center + +This filters the list to show only items which match the search term. Items match the search term if their name contains the search term. Matching is case-sensitive. diff --git a/devtools/docs/user/eyedropper/eyedropper.png b/devtools/docs/user/eyedropper/eyedropper.png Binary files differnew file mode 100644 index 0000000000..cad092141b --- /dev/null +++ b/devtools/docs/user/eyedropper/eyedropper.png diff --git a/devtools/docs/user/eyedropper/index.rst b/devtools/docs/user/eyedropper/index.rst new file mode 100644 index 0000000000..672c81ad23 --- /dev/null +++ b/devtools/docs/user/eyedropper/index.rst @@ -0,0 +1,47 @@ +========== +Eyedropper +========== + +The Eyedropper tool enables you to select colors in the current page. It works like a magnifying glass over the page, enabling you to select with pixel precision. Underneath the magnifying glass it shows the color value for the current pixel using whichever scheme you've selected in :ref:`Settings > Inspector <settings-inspector>` > Default color unit: + +.. image:: eyedropper.png + +You can use it in one of two ways: + +- to select a color from the page and copy it to the clipboard +- to change a color value in the Inspector's Rules view to a color you've selected from the page + +Copying a color to the clipboard +******************************** + +Open the Eyedropper in one of these two ways: + +- select "Eyedropper" under the "Browser Tools" menu +- open the :doc:`Page Inspector <../page_inspector/index>` tab and click the eyedropper button in its toolbar + +As you move the mouse around the page you'll see the current color value in the Eyedropper change. Clicking copies the current color value to the clipboard. + +.. raw:: html + + <iframe width="560" height="315" src="https://www.youtube.com/embed/xf2uk6UyRB8" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe> + <br/> + <br/> + +Changing a color value in the Rules view +**************************************** + +Color values appearing in the Inspector's Rules view have color samples next to them: clicking the sample shows a :doc:`color picker popup <../page_inspector/how_to/inspect_and_select_colors/index>`. From Firefox 31, the popup contains an eyedropper icon: click this icon to activate the Eyedropper. + +Now, when you click the Eyedropper, the color in the Rules view is set to the color you selected. + +.. raw:: html + + <iframe width="560" height="315" src="https://www.youtube.com/embed/0Zx1TN21QOo" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe> + <br/> + <br/> + + +Keyboard shortcuts +****************** + +See :ref:`All keyboard shortcuts > Eyedropper <keyboard-shortcuts-eyedropper>`. diff --git a/devtools/docs/user/iframe_button.png b/devtools/docs/user/iframe_button.png Binary files differnew file mode 100644 index 0000000000..43f497e136 --- /dev/null +++ b/devtools/docs/user/iframe_button.png diff --git a/devtools/docs/user/index.rst b/devtools/docs/user/index.rst new file mode 100644 index 0000000000..67c9189bc7 --- /dev/null +++ b/devtools/docs/user/index.rst @@ -0,0 +1,270 @@ +.. toctree:: + :name: devtools-user-doc + +========================== +Firefox DevTools User Docs +========================== + +Firefox Developer Tools is a set of web developer tools built into Firefox. You can use them to examine, edit, and debug HTML, CSS, and JavaScript. + +This section contains detailed guides to all of the tools as well as information on how to debug Firefox for Android, how to extend DevTools, and how to debug the browser as a whole. + +If you have any feedback on DevTools or want to contribute to the project, you can `join the DevTools community <https://firefox-dev.tools/>`_. + +.. note:: + + If you are just getting started with web development and using developer tools, our `learning <https://developer.mozilla.org/en-US/docs/Learn>`_ docs will help you — see `Getting started with the Web <https://developer.mozilla.org/en-US/docs/Learn/Getting_started_with_the_web>`_ and `What are browser developer tools? <https://developer.mozilla.org/en-US/docs/Learn/Common_questions/What_are_browser_developer_tools>`_ for good starting points. + + +The Core Tools +************** + +You can open the Firefox Developer Tools from the menu by selecting **Tools > Web Developer > Web Developer Tools** or use the keyboard shortcut :kbd:`Ctrl` + :kbd:`Shift` + :kbd:`I` or :kbd:`F12` on Windows and Linux, or :kbd:`Cmd` + :kbd:`Opt` + :kbd:`I` on macOS. + +The ellipsis menu on the right-hand side of Developer Tools contains several commands that let you perform actions or change tool settings. + +.. figure:: devtools_layoutmenu.png + :align: center + + +========== ================================================================ + |image1| This button only appears when there are multiple iframes on a + page. Click it to display a list of the iframes on the current + page and select the one with which you want to work. + + |image2| Click this button to take a screenshot of the current page. + (*Note:* This feature is not turned on by + default and must be enabled in settings before the icon will + appear.) + + |image3| Toggles Responsive Design Mode + + |image4| Opens the menu that includes docking options, the ability to show + or hide the split console, and Developer Tools settings. + The menu also includes links to the documentation for Firefox + Web Tools and the Mozilla Community. + + |image5| Closes the Developer Tools + +========== ================================================================ + +.. |image1| image:: iframe_button.png + :class: center +.. |image2| image:: camera_button.png + :class: center +.. |image3| image:: responsive_button.png + :class: center +.. |image4| image:: menu_button.png + :class: center +.. |image5| image:: close_button.png + :class: center + + +Page Inspector +-------------- + +.. image:: landingpage_pageinspector.png + :class: border + :target: page_inspector + :alt: The all-new Inspector panel in Firefox 57. + +View and edit page content and layout. Visualize many aspects of the page including the box model, animations, and grid layouts + + +Web Console +----------- + +.. image:: landingpage_console.png + :class: border + :target: web_console + :alt: The all-new Console panel in Firefox 57. + +See messages logged by a web page and interact with the page using JavaScript. + + +JavaScript Debugger +------------------- + +.. image:: landingpage_debugger.png + :class: border + :target: debugger + :alt: The all-new Debugger panel in Firefox 57. + +Stop, step through, and examine the JavaScript running on a page. + + +Network Monitor +--------------- + +.. image:: landingpage_network.png + :class: border + :target: network_monitor + :alt: The Network panel in Firefox 57 DevTools. + + +See the network requests made when a page is loaded. + + +Performance Panel +----------------- + +.. image:: landingpage_performance_2022.png + :class: border + :target: https://profiler.firefox.com/docs/ + :alt: Performance Panel in Firefox 103 Developer Tools. + +Analyze your site's general responsiveness, JavaScript, and layout performance. + + +Responsive Design Mode +---------------------- + +.. image:: landingpage_responsivedesign.png + :class: border + :target: responsive_design_mode + :alt: Responsive Design mode in Firefox 57 Developer Tools. + +See how your website or app will look and behave on different devices and network types. + + +Accessibility inspector +----------------------- + +.. image:: landingpage_accessibility.png + :class: border + :target: accessibility_inspector + :alt: Performance Tools in Firefox 57 Developer Tools. + +Provides a means to access the page's accessibility tree, allowing you to check what's missing or otherwise needs attention. + + +Application panel +----------------- + +.. image:: just-application-panel.png + :class: border + :target: application + :alt: Performance Tools in Firefox 57 Developer Tools. + +Provides tools for inspecting and debugging modern web apps (also known as `Progressive Web Apps <https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps>`_). This includes inspection of `service workers <https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API>`_ and `web app manifests <https://developer.mozilla.org/en-US/docs/Web/Manifest>`_ + + +.. note:: + + The collective term for the UI inside which the DevTools all live is the :doc:`Toolbox <tools_toolbox/index>` + + +More Tools +********** + +These developer tools are also built into Firefox. Unlike the "Core Tools" above, you might not use them every day. + +.. list-table:: + :widths: 25 75 + :header-rows: 0 + + * - :doc:`Memory <memory/index>` + - Figure out which objects are keeping memory in use. + + * - :doc:`Storage Inspector <storage_inspector/index>` + - Inspect cookies, local storage, indexedDB, and session storage present in a page. + + * - :doc:`DOM Property Viewer <dom_property_viewer/index>` + - Inspect the page's DOM properties, functions, etc. + + * - :doc:`Eyedropper <eyedropper/index>` + - Select a color from the page. + + * - :doc:`Style Editor <style_editor/index>` + - View and edit CSS styles for the current page. + + * - :doc:`Taking screenshot <taking_screenshots/index>` + - Take a screenshot of the entire page or of a single element. + + * - :doc:`Measure a portion of the page <measure_a_portion_of_the_page/index>` + - Measure a specific area of a web page. + + * - :doc:`Rulers <rulers/index>` + - Overlay horizontal and vertical rulers on a web page + + * - :doc:`Custom formatters <custom_formatters/index>` + - Customize the way objects are displayed within the DevTools. + + +.. image:: logo-developer-quantum.png + :class: center + +.. rst-class:: center + + For the latest developer tools and features, try Firefox Developer Edition. + + `Download Firefox Developer Edition <https://www.mozilla.org/en-US/firefox/developer/>`_ + + + +Connecting the Developer Tools +****************************** + +If you open the developer tools using :ref:`keyboard shortcuts <keyboard-shortcuts-opening-and-closing-tools>` or the equivalent menu items, they'll target the document hosted by the currently active tab. But you can attach the tools to a variety of other targets, too, both within the current browser and in different browsers or even different devices. + +.. list-table:: + :widths: 30 70 + :header-rows: 0 + + * - :doc:`about:debugging <about_colon_debugging/index>` + - Debug add-ons, content tabs, and workers running in the browser. + + * - :ref:`Connecting to Firefox for Android <about-colon-debugging-connecting-to-a-remote-device>` + - Connect the developer tools to an instance of Firefox running on an Android device. + + * - :doc:`Connecting to iframes <working_with_iframes/index>` + - Connect the developer tools to a specific iframe in the current page. + + +Debugging the browser +********************* + +By default, the developer tools are attached to a web page or web app. But you can also connect them to the browser as a whole. This is useful for browser and add-on development. + +.. list-table:: + :widths: 30 70 + :header-rows: 0 + + * - :doc:`Browser Console <browser_console/index>` + - See messages logged by the browser itself and by add-ons, and run JavaScript code in the browser's scope. + + * - :doc:`Browser Toolbox <browser_toolbox/index>` + - Attach the Developer Tools to the browser itself. + + + +Extending DevTools +****************** + +For information on extending the Firefox DevTools, see `Extending the developer tools <https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Extending_the_developer_tools>`_ over in the `Browser Extensions <https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions>`_ section of MDN. + + +Migrating from Firebug +********************** + +Firebug has come to the end of its lifespan (see `Firebug lives on in Firefox DevTools <https://hacks.mozilla.org/2016/12/firebug-lives-on-in-firefox-devtools/>`_ for details of why), and we appreciate that some people will find migrating to another less familiar set of DevTools to be challenging. To ease a transition from Firebug to the Firefox developer tools, we have written a handy guide — :doc:`Migrating from Firebug <./migrating_from_firebug/index>` + + +Contribute +********** + +If you want to help improve the developer tools, these resources will get you started. + + +.. list-table:: + :widths: 30 70 + :header-rows: 0 + + * - `Get Involved <https://firefox-dev.tools/>`_ + - Our community website explains how to get involved. + + * - `bugs.firefox-dev.tools <https://bugs.firefox-dev.tools/>`_ + - A tool helping to find bugs to work on. + + * - :ref:`Read source docs <devtools-contributor-doc>` + - Firefox DevTools source code documentation. diff --git a/devtools/docs/user/index/index.rst b/devtools/docs/user/index/index.rst new file mode 100644 index 0000000000..1e0d540b8d --- /dev/null +++ b/devtools/docs/user/index/index.rst @@ -0,0 +1,7 @@ +===== +Index +===== + +.. note:: + + Draft: TODO: generate index of all pages. diff --git a/devtools/docs/user/json_viewer/index.rst b/devtools/docs/user/json_viewer/index.rst new file mode 100644 index 0000000000..f3e313dea1 --- /dev/null +++ b/devtools/docs/user/json_viewer/index.rst @@ -0,0 +1,18 @@ +=========== +JSON viewer +=========== + +The JSON viewer is new in Firefox 44. + +Before Firefox 53, the JSON viewer is enabled by default only in Firefox Developer Edition and Firefox Nightly. To enable this feature in other release channels, set the ```devtools.jsonview.enabled``` preference to ```true```. + +From Firefox 53 onwards, the JSON viewer is also enabled by default in Beta and the normal release version of Firefox. + + +Firefox includes a JSON viewer. If you open a JSON file in the browser, or view a remote URL with the Content-Type set to application/json, it is parsed and given syntax highlighting. Arrays and objects are shown collapsed, and you can expand them using the "+" icons. + +The JSON viewer provides a search box that you can use to filter the JSON. + +You can also view the raw JSON and pretty-print it. + +Finally, if the document was the result of a network request, the viewer displays the request and response headers. diff --git a/devtools/docs/user/just-application-panel.png b/devtools/docs/user/just-application-panel.png Binary files differnew file mode 100644 index 0000000000..12fadfb81f --- /dev/null +++ b/devtools/docs/user/just-application-panel.png diff --git a/devtools/docs/user/keyboard_shortcuts/index.rst b/devtools/docs/user/keyboard_shortcuts/index.rst new file mode 100644 index 0000000000..8b39220ecd --- /dev/null +++ b/devtools/docs/user/keyboard_shortcuts/index.rst @@ -0,0 +1,918 @@ +====================== +All keyboard shortcuts +====================== + +This page lists all keyboard shortcuts used by the developer tools built into Firefox. + +The first section lists the shortcut for opening each tool and the second section lists shortcuts that are applicable to the Toolbox itself. After that there's one section for each tool, which lists the shortcuts that you can use within that tool. + +Because access keys are locale-dependent, they're not documented in this page. + + +.. |br| raw:: html + + <br/> + + +.. _keyboard-shortcuts-opening-and-closing-tools: + +Opening and closing tools +************************* + +These shortcuts work in the main browser window to open the specified tool. The same shortcuts will work to close tools hosted in the Toolbox, if the tool is active. For tools like the Browser Console that open in a new window, you have to close the window to close the tool. + +.. list-table:: + :widths: 25 25 25 25 + :header-rows: 1 + + * - **Command** + - **Windows** + - **macOS** + - **Linux** + + * - Open Toolbox (with the most recent tool activated) + - :kbd:`Ctrl` + :kbd:`Shift` + :kbd:`I` + - :kbd:`Cmd` + :kbd:`Opt` + :kbd:`I` + - :kbd:`Ctrl` + :kbd:`Shift` + :kbd:`I` + + * - Bring Toolbox to foreground (if the Toolbox is in a separate window and not in foreground) + - :kbd:`Ctrl` + :kbd:`Shift` + :kbd:`I` or :kbd:`F12` + - :kbd:`Cmd` + :kbd:`Opt` + :kbd:`I` or :kbd:`F12` + - :kbd:`Ctrl` + :kbd:`Shift` + :kbd:`I` or :kbd:`F12` + + * - Close Toolbox (if the Toolbox is in a separate window and in foreground) + - :kbd:`Ctrl` + :kbd:`Shift` + :kbd:`I` or :kbd:`F12` + - :kbd:`Cmd` + :kbd:`Opt` + :kbd:`I` or :kbd:`F12` + - :kbd:`Ctrl` + :kbd:`Shift` + :kbd:`I` or :kbd:`F12` + + * - Open Web Console [#]_ + - :kbd:`Ctrl` + :kbd:`Shift` + :kbd:`K` + - :kbd:`Cmd` + :kbd:`Opt` + :kbd:`K` + - :kbd:`Ctrl` + :kbd:`Shift` + :kbd:`K` + + * - Toggle "Pick an element from the page" (opens the Toolbox and/or focus the Inspector tab) + - :kbd:`Ctrl` + :kbd:`Shift` + :kbd:`C` + - :kbd:`Cmd` + :kbd:`Opt` + :kbd:`C` + - :kbd:`Ctrl` + :kbd:`Shift` + :kbd:`C` + + * - Open Style Editor + - :kbd:`Shift` + :kbd:`F7` + - :kbd:`Shift` + :kbd:`F7` + - :kbd:`Shift` + :kbd:`F7` + + * - Open Profiler + - :kbd:`Shift` + :kbd:`F5` + - :kbd:`Shift` + :kbd:`F5` + - :kbd:`Shift` + :kbd:`F5` + + * - Open Network Monitor [#]_ + - :kbd:`Ctrl` + :kbd:`Shift` + :kbd:`E` + - :kbd:`Cmd` + :kbd:`Opt` + :kbd:`E` + - :kbd:`Ctrl` + :kbd:`Shift` + :kbd:`E` + + * - Toggle Responsive Design Mode + - :kbd:`Ctrl` + :kbd:`Shift` + :kbd:`M` + - :kbd:`Cmd` + :kbd:`Opt` + :kbd:`M` + - :kbd:`Ctrl` + :kbd:`Shift` + :kbd:`M` + + * - Open Browser Console + - :kbd:`Ctrl` + :kbd:`Shift` + :kbd:`J` + - :kbd:`Cmd` + :kbd:`Opt` + :kbd:`J` + - :kbd:`Ctrl` + :kbd:`Shift` + :kbd:`J` + + * - Open Browser Toolbox + - :kbd:`Ctrl` + :kbd:`Alt` + :kbd:`Shift` + :kbd:`I` + - :kbd:`Cmd` + :kbd:`Opt` + :kbd:`Shift` + :kbd:`I` + - :kbd:`Ctrl` + :kbd:`Alt` + :kbd:`Shift` + :kbd:`I` + + * - Storage Inspector + - :kbd:`Shift` + :kbd:`F9` + - :kbd:`Shift` + :kbd:`F9` + - :kbd:`Shift` + :kbd:`F9` + + * - Open Debugger [#]_ + - :kbd:`Ctrl` + :kbd:`Shift` + :kbd:`Z` + - :kbd:`Cmd` + :kbd:`Opt` + :kbd:`Z` + - :kbd:`Ctrl` + :kbd:`Shift` + :kbd:`Z` + + +.. [#] Unlike the other toolbox-hosted tools, this shortcut does not also close the Web Console. Instead, it focuses on the Web Console's command line. To close the Web Console, use the global toolbox shortcut of :kbd:`Ctrl` + :kbd:`Shift` + :kbd:`I` (:kbd:`Cmd` + :kbd:`Opt` + :kbd:`I` on a Mac). + +.. [#] Before Firefox 55, the keyboard shortcut was :kbd:`Ctrl` + :kbd:`Shift` + :kbd:`Q` (:kbd:`Cmd` + :kbd:`Opt` + :kbd:`Q` on a Mac) + +.. [#] Starting in Firefox 71. Before Firefox 66, the letter in this shortcut was :kbd:`S`. + + +.. _keyboard-shortcuts-toolbox: + +Toolbox +******* + +Keyboard shortcuts for the :doc:`Toolbox <../tools_toolbox/index>` + +These shortcuts work whenever the toolbox is open, no matter which tool is active. + + +.. list-table:: + :widths: 25 25 25 25 + :header-rows: 1 + + * - **Command** + - **Windows** + - **macOS** + - **Linux** + + * - Cycle through tools left to right + - :kbd:`Ctrl` + :kbd:`]` + - :kbd:`Cmd` + :kbd:`]` + - :kbd:`Ctrl` + :kbd:`]` + + * - Cycle through tools right to left + - :kbd:`Ctrl` + :kbd:`[` + - :kbd:`Cmd` + :kbd:`[` + - :kbd:`Ctrl` + :kbd:`[` + + * - Toggle between active tool and settings. + - :kbd:`F1` + - :kbd:`F1` + - :kbd:`F1` + + * - Toggle toolbox between the last 2 :ref:`docking modes <tools-toolbox-docking-mode>` + - :kbd:`Ctrl` + :kbd:`Shift` + :kbd:`D` + - :kbd:`Cmd` + :kbd:`Shift` + :kbd:`D` + - :kbd:`Ctrl` + :kbd:`Shift` + :kbd:`D` + + * - Toggle split console (except if console is the currently selected tool) + - :kbd:`Esc` + - :kbd:`Esc` + - :kbd:`Esc` + + +These shortcuts work in all tools that are hosted in the toolbox. + +.. list-table:: + :widths: 25 25 25 25 + :header-rows: 1 + + * - **Command** + - **Windows** + - **macOS** + - **Linux** + + * - Increase font size + - :kbd:`Ctrl` + :kbd:`+` + - :kbd:`Cmd` + :kbd:`+` + - :kbd:`Ctrl` + :kbd:`+` + + * - Decrease font size + - :kbd:`Ctrl` + :kbd:`-` + - :kbd:`Cmd` + :kbd:`-` + - :kbd:`Ctrl` + :kbd:`-` + + * - Reset font size + - :kbd:`Ctrl` + :kbd:`0` + - :kbd:`Cmd` + :kbd:`0` + - :kbd:`Ctrl` + :kbd:`0` + + +Source editor +************* + +This table lists the default shortcuts for the source editor. + +In the :ref:`Editor Preferences <settings-editor-preferences>` section of the developer tools settings, you can choose to use Vim, Emacs, or Sublime Text key bindings instead. + +To select these, visit ``about:config``, select the setting ``devtools.editor.keymap``, and assign "vim" or "emacs", or "sublime" to that setting. If you do this, the selected bindings will be used for all the developer tools that use the source editor. You need to reopen the editor for the change to take effect. + +From Firefox 33 onwards, the key binding preference is exposed in the :ref:`Editor Preferences <settings-editor-preferences>` section of the developer tools settings, and you can set it there instead of ``about:config``. + + +.. list-table:: + :widths: 25 25 25 25 + :header-rows: 1 + + * - **Command** + - **Windows** + - **macOS** + - **Linux** + + * - Go to line + - :kbd:`Ctrl` + :kbd:`J`, :kbd:`Ctrl` + :kbd:`G` + - :kbd:`Cmd` + :kbd:`J`, :kbd:`Cmd` + :kbd:`G` + - :kbd:`Ctrl` + :kbd:`J`, :kbd:`Ctrl` + :kbd:`G` + + * - Find in file + - :kbd:`Ctrl` + :kbd:`F` + - :kbd:`Cmd` + :kbd:`F` + - :kbd:`Ctrl` + :kbd:`F` + + * - Select all + - :kbd:`Ctrl` + :kbd:`A` + - :kbd:`Cmd` + :kbd:`A` + - :kbd:`Ctrl` + :kbd:`A` + + * - Cut + - :kbd:`Ctrl` + :kbd:`X` + - :kbd:`Cmd` + :kbd:`X` + - :kbd:`Ctrl` + :kbd:`X` + + * - Copy + - :kbd:`Ctrl` + :kbd:`C` + - :kbd:`Cmd` + :kbd:`C` + - :kbd:`Ctrl` + :kbd:`C` + + * - Paste + - :kbd:`Ctrl` + :kbd:`V` + - :kbd:`Cmd` + :kbd:`V` + - :kbd:`Ctrl` + :kbd:`V` + + * - Undo + - :kbd:`Ctrl` + :kbd:`Z` + - :kbd:`Cmd` + :kbd:`Z` + - :kbd:`Ctrl` + :kbd:`Z` + + * - Redo + - :kbd:`Ctrl` + :kbd:`Shift` + :kbd:`Z` / :kbd:`Ctrl` + :kbd:`Y` + - :kbd:`Cmd` + :kbd:`Shift` + :kbd:`Z` / :kbd:`Cmd` + :kbd:`Y` + - :kbd:`Ctrl` + :kbd:`Shift` + :kbd:`Z` / :kbd:`Ctrl` + :kbd:`Y` + + * - Indent + - :kbd:`Tab` + - :kbd:`Tab` + - :kbd:`Tab` + + * - Unindent + - :kbd:`Shift` + :kbd:`Tab` + - :kbd:`Shift` + :kbd:`Tab` + - :kbd:`Shift` + :kbd:`Tab` + + * - Move line(s) up + - :kbd:`Alt` + :kbd:`Up` + - :kbd:`Alt` + :kbd:`Up` + - :kbd:`Alt` + :kbd:`Up` + + * - Move line(s) down + - :kbd:`Alt` + :kbd:`Down` + - :kbd:`Alt` + :kbd:`Down` + - :kbd:`Alt` + :kbd:`Down` + + * - Comment/uncomment line(s) + - :kbd:`Ctrl` + :kbd:`/` + - :kbd:`Cmd` + :kbd:`/` + - :kbd:`Ctrl` + :kbd:`/` + + +.. _keyboard-shortcuts-page-inspector: + +Page Inspector +************** + +Keyboard shortcuts for the :doc:`Page inspector <../page_inspector/index>`. + +.. list-table:: + :widths: 25 25 25 25 + :header-rows: 1 + + * - **Command** + - **Windows** + - **macOS** + - **Linux** + + * - Inspect Element + - :kbd:`Ctrl` + :kbd:`Shift` + :kbd:`C` + - :kbd:`Cmd` + :kbd:`Shift` + :kbd:`C` + - :kbd:`Ctrl` + :kbd:`Shift` + :kbd:`C` + + +Node picker +*********** + +These shortcuts work while the :ref:`node picker <page-inspector-how-to-select-an-element-with-the-node-picker>` is active. + +.. list-table:: + :widths: 25 25 25 25 + :header-rows: 1 + + * - **Command** + - **Windows** + - **macOS** + - **Linux** + + * - Select the element under the mouse and cancel picker mode + - :kbd:`Click` + - :kbd:`Click` + - :kbd:`Click` + + * - Select the element under the mouse and stay in picker mode + - :kbd:`Shift` + :kbd:`Click` + - :kbd:`Shift` + :kbd:`Click` + - :kbd:`Shift` + :kbd:`Click` + + +.. _keyboard-shortcuts-html-pane: + +HTML pane +********* + +These shortcuts work while you're in the :doc:`Inspector's HTML pane <../page_inspector/how_to/examine_and_edit_html/index>`. + +.. list-table:: + :widths: 40 20 20 20 + :header-rows: 1 + + * - **Command** + - **Windows** + - **macOS** + - **Linux** + + * - Delete the selected node + - :kbd:`Delete` + - :kbd:`Delete` + - :kbd:`Delete` + + * - Undo delete of a node + - :kbd:`Ctrl` + :kbd:`Z` + - :kbd:`Cmd` + :kbd:`Z` + - :kbd:`Ctrl` + :kbd:`Z` + + * - Redo delete of a node + - :kbd:`Ctrl` + :kbd:`Shift` + :kbd:`Z` / :kbd:`Ctrl` + :kbd:`Y` + - :kbd:`Cmd` + :kbd:`Shift` + :kbd:`Z` / :kbd:`Cmd` + :kbd:`Y` + - :kbd:`Ctrl` + :kbd:`Shift` + :kbd:`Z` / :kbd:`Ctrl` + :kbd:`Y` + + * - Move to next node (expanded nodes only) + - :kbd:`↓` + - :kbd:`↓` + - :kbd:`↓` + + * - Move to previous node + - :kbd:`↑` + - :kbd:`↑` + - :kbd:`↑` + + * - Move to first node in the tree. + - :kbd:`Home` + - :kbd:`Home` + - :kbd:`Home` + + * - Move to last node in the tree. + - :kbd:`End` + - :kbd:`End` + - :kbd:`End` + + * - Expand currently selected node + - :kbd:`→` + - :kbd:`→` + - :kbd:`→` + + * - Collapse currently selected node + - :kbd:`←` + - :kbd:`←` + - :kbd:`←` + + * - (When a node is selected) move inside the node so you can start stepping through attributes. + - :kbd:`Enter` + - :kbd:`Return` + - :kbd:`Enter` + + * - Step forward through the attributes of a node + - :kbd:`Tab` + - :kbd:`Tab` + - :kbd:`Tab` + + * - Step backward through the attributes of a node + - :kbd:`Shift` + :kbd:`Tab` + - :kbd:`Shift` + :kbd:`Tab` + - :kbd:`Shift` + :kbd:`Tab` + + * - (When an attribute is selected) start editing the attribute + - :kbd:`Enter` + - :kbd:`Return` + - :kbd:`Enter` + + * - Hide/show the selected node + - :kbd:`H` + - :kbd:`H` + - :kbd:`H` + + * - Focus on the search box in the HTML pane + - :kbd:`Ctrl` + :kbd:`F` + - :kbd:`Cmd` + :kbd:`F` + - :kbd:`Ctrl` + :kbd:`F` + + * - Edit as HTML + - :kbd:`F2` + - :kbd:`F2` + - :kbd:`F2` + + * - Stop editing HTML + - :kbd:`F2` / :kbd:`Ctrl` +:kbd:`Enter` + - :kbd:`F2` / :kbd:`Cmd` + :kbd:`Return` + - :kbd:`F2` / :kbd:`Ctrl` + :kbd:`Enter` + + * - Copy the selected node's outer HTML + - :kbd:`Ctrl` + :kbd:`C` + - :kbd:`Cmd` + :kbd:`C` + - :kbd:`Ctrl` + :kbd:`C` + + * - Scroll the selected node into view + - :kbd:`S` + - :kbd:`S` + - :kbd:`S` + + * - Find the next match in the markup, when searching is active + - :kbd:`Enter` + - :kbd:`Return` + - :kbd:`Enter` + + * - Find the previous match in the markup, when searching is active + - :kbd:`Shift` + :kbd:`Enter` + - :kbd:`Shift` + :kbd:`Return` + - :kbd:`Shift` + :kbd:`Enter` + + +.. _keyboard-shortcuts-breadcrumbs-bar: + +Breadcrumbs bar +*************** + +These shortcuts work when the :ref:`breadcrumbs bar <page-inspector-how-to-examine-and-edit-html-breadcrumbs>` is focused. + +.. list-table:: + :widths: 40 20 20 20 + :header-rows: 1 + + * - **Command** + - **Windows** + - **macOS** + - **Linux** + + * - Move to the previous element in the breadcrumbs bar + - :kbd:`←` + - :kbd:`←` + - :kbd:`←` + + * - Move to the next element in the breadcrumbs bar + - :kbd:`→` + - :kbd:`→` + - :kbd:`→` + + * - Focus the :ref:`HTML pane <page_inspector_ui_tour_html_pane>` + - :kbd:`Shift` + :kbd:`Tab` + - :kbd:`Shift` + :kbd:`Tab` + - :kbd:`Shift` + :kbd:`Tab` + + * - Focus the :ref:`CSS pane <page_inspector_ui_tour_rules_view>` + - :kbd:`Tab` + - :kbd:`Tab` + - :kbd:`Tab` + + +CSS pane +******** + +These shortcuts work when you're in the :doc:`Inspector's CSS panel <../page_inspector/how_to/examine_and_edit_css/index>` + +.. list-table:: + :widths: 40 20 20 20 + :header-rows: 1 + + * - **Command** + - **Windows** + - **macOS** + - **Linux** + + * - Focus on the search box in the CSS pane + - :kbd:`Ctrl` + :kbd:`F` + - :kbd:`Cmd` + :kbd:`F` + - :kbd:`Ctrl` + :kbd:`F` + + * - Clear search box content (only when the search box is focused, and content has been entered) + - :kbd:`Esc` + - :kbd:`Esc` + - :kbd:`Esc` + + * - Step forward through properties and values + - :kbd:`Tab` + - :kbd:`Tab` + - :kbd:`Tab` + + * - Step backward through properties and values + - :kbd:`Shift` + :kbd:`Tab` + - :kbd:`Shift` + :kbd:`Tab` + - :kbd:`Shift` + :kbd:`Tab` + + * - Start editing property or value (Rules view only, when a property or value is selected, but not already being edited) + - :kbd:`Enter` or :kbd:`Space` + - :kbd:`Return` or :kbd:`Space` + - :kbd:`Enter` or :kbd:`Space` + + * - Cycle up and down through auto-complete suggestions (Rules view only, when a property or value is being edited) + - :kbd:`↑` , :kbd:`↓` + - :kbd:`↑` , :kbd:`↓` + - :kbd:`↑` , :kbd:`↓` + + * - Choose current auto-complete suggestion (Rules view only, when a property or value is being edited) + - :kbd:`Enter` or :kbd:`Tab` + - :kbd:`Return` or :kbd:`Tab` + - :kbd:`Enter` or :kbd:`Tab` + + * - Increment selected value by 1 + - :kbd:`↑` + - :kbd:`↑` + - :kbd:`↑` + + * - Decrement selected value by 1 + - :kbd:`↓` + - :kbd:`↓` + - :kbd:`↓` + + * - Increment selected value by 100 + - :kbd:`Shift` + :kbd:`PageUp` + - :kbd:`Shift` + :kbd:`PageUp` + - :kbd:`Shift` + :kbd:`PageUp` + + * - Decrement selected value by 100 + - :kbd:`Shift` + :kbd:`PageDown` + - :kbd:`Shift` + :kbd:`PageDown` + - :kbd:`Shift` + :kbd:`PageDown` + + * - Increment selected value by 10 + - :kbd:`Shift` + :kbd:`↑` + - :kbd:`Shift` + :kbd:`↑` + - :kbd:`Shift` + :kbd:`↑` + + * - Decrement selected value by 10 + - :kbd:`Shift` + :kbd:`↓` + - :kbd:`Shift` + :kbd:`↓` + - :kbd:`Shift` + :kbd:`↓` + + * - Increment selected value by 0.1 + - :kbd:`Alt` + :kbd:`↑` (:kbd:`Ctrl` + :kbd:`↑` from Firefox 60 onwards.) + - :kbd:`Alt` + :kbd:`↑` + - :kbd:`Alt` + :kbd:`↑` (:kbd:`Ctrl` + :kbd:`↑` from Firefox 60 onwards.) + + * - Decrement selected value by 0.1 + - :kbd:`Alt` + :kbd:`↓` (:kbd:`Ctrl` + :kbd:`↓` from Firefox 60 onwards). + - :kbd:`Alt` + :kbd:`↓` + - :kbd:`Alt` + :kbd:`↓` (:kbd:`Ctrl` + :kbd:`↓` from Firefox 60 onwards). + + * - Show/hide more information about current property (Computed view only, when a property is selected) + - :kbd:`Enter` or :kbd:`Space` + - :kbd:`Return` or :kbd:`Space` + - :kbd:`Enter` or :kbd:`Space` + + * - Open MDN reference page about current property (Computed view only, when a property is selected) + - :kbd:`F1` + - :kbd:`F1` + - :kbd:`F1` + + * - Open current CSS file in Style Editor (Computed view only, when more information is shown for a property and a CSS file reference is focused). + - :kbd:`Enter` + - :kbd:`Return` + - :kbd:`Enter` + + +.. _keyboard-shortcuts-debugger: + +Debugger +******** + +Keyboard shortcuts for the :doc:`Firefox JavaScript Debugger <../debugger/index>`. + +.. list-table:: + :widths: 25 25 25 25 + :header-rows: 1 + + * - **Command** + - **Windows** + - **macOS** + - **Linux** + + * - Close current file + - :kbd:`Ctrl` + :kbd:`W` + - :kbd:`Cmd` + :kbd:`W` + - :kbd:`Ctrl` + :kbd:`W` + + * - Search for a string in the current file + - :kbd:`Ctrl` + :kbd:`F` + - :kbd:`Cmd` + :kbd:`F` + - :kbd:`Ctrl` + :kbd:`F` + + * - Search for a string in all files + - :kbd:`Ctrl` + :kbd:`Shift` + :kbd:`F` + - :kbd:`Cmd` + :kbd:`Shift` + :kbd:`F` + - :kbd:`Ctrl` + :kbd:`Shift` + :kbd:`F` + + * - Find next in the current file + - :kbd:`Ctrl` + :kbd:`G` + - :kbd:`Cmd` + :kbd:`G` + - :kbd:`Ctrl` + :kbd:`G` + + * - Search for scripts by name + - :kbd:`Ctrl` + :kbd:`P` + - :kbd:`Cmd` + :kbd:`P` + - :kbd:`Ctrl` + :kbd:`P` + + * - Resume execution when at a breakpoint + - :kbd:`F8` + - :kbd:`F8` [4]_ + - :kbd:`F8` + + * - Step over + - :kbd:`F10` + - :kbd:`F10` [4]_ + - :kbd:`F10` + + * - Step into + - :kbd:`F11` + - :kbd:`F11` [4]_ + - :kbd:`F11` + + * - Step out + - :kbd:`Shift` + :kbd:`F11` + - :kbd:`Shift` + :kbd:`F11` [4]_ + - :kbd:`Shift` + :kbd:`F11` + + * - Toggle breakpoint on the currently selected line + - :kbd:`Ctrl` + :kbd:`B` + - :kbd:`Cmd` + :kbd:`B` + - :kbd:`Ctrl` + :kbd:`B` + + * - Toggle conditional breakpoint on the currently selected line + - :kbd:`Ctrl` + :kbd:`Shift` + :kbd:`B` + - :kbd:`Cmd` + :kbd:`Shift` + :kbd:`B` + - :kbd:`Ctrl` + :kbd:`Shift` + :kbd:`B` + + +.. [4] By default, on some Macs, the function key is remapped to use a special feature: for example, to change the screen brightness or the volume. See this `guide to using these keys as standard function keys <https://support.apple.com/kb/HT3399>`_. To use a remapped key as a standard function key, hold the Function key down as well (so to open the Profiler, use :kbd:`Shift` + :kbd:`Function` + :kbd:`F5`). + + +.. note:: + Before Firefox 66, the combination :kbd:`Ctrl` + :kbd:`Shift` + :kbd:`S` on Windows and Linux or :kbd:`Cmd` + :kbd:`Opt` + :kbd:`S` on macOS would open/close the Debugger. From Firefox 66 and later, this is no longer the case. + + +.. _keyboard-shortcuts-web-console: + +Web Console +*********** + +Keyboard shortcuts for the :doc:`Web Console <../web_console/index>`. + +.. list-table:: + :widths: 25 25 25 25 + :header-rows: 1 + + * - **Command** + - **Windows** + - **macOS** + - **Linux** + + * - Open the Web Console + - :kbd:`Ctrl` + :kbd:`Shift` + :kbd:`K` + - :kbd:`Cmd` + :kbd:`Opt` + :kbd:`K` + - :kbd:`Ctrl` + :kbd:`Shift` + :kbd:`K` + + * - Search in the message display pane + - :kbd:`Ctrl` + :kbd:`F` + - :kbd:`Cmd` + :kbd:`F` + - :kbd:`Ctrl` + :kbd:`F` + + * - Open the :ref:`object inspector pane <web_console_rich_output_examining_object_properties>` + - :kbd:`Ctrl` + :kbd:`Click` + - :kbd:`Ctrl` + :kbd:`Click` + - :kbd:`Ctrl` + :kbd:`Click` + + * - Clear the :ref:`object inspector pane <web_console_rich_output_examining_object_properties>` + - :kbd:`Esc` + - :kbd:`Esc` + - :kbd:`Esc` + + * - Focus on the command line + - :kbd:`Ctrl` + :kbd:`Shift` + :kbd:`K` + - :kbd:`Cmd` + :kbd:`Opt` + :kbd:`K` + - :kbd:`Ctrl` + :kbd:`Shift` + :kbd:`K` + + * - Clear output + - :kbd:`Ctrl` + :kbd:`Shift` + :kbd:`L` + - :kbd:`Ctrl` + :kbd:`L` |br| |br| From Firefox 67: |br| |br| :kbd:`Cmd` + :kbd:`K` + - :kbd:`Ctrl` + :kbd:`Shift` + :kbd:`L` + + + +Command line interpreter +************************ + +These shortcuts apply when you're in the :doc:`command line interpreter <../web_console/the_command_line_interpreter/index>`. + +.. list-table:: + :widths: 25 25 25 25 + :header-rows: 1 + + * - **Command** + - **Windows** + - **macOS** + - **Linux** + + * - Scroll to start of console output (only if the command line is empty) + - :kbd:`Home` + - :kbd:`Home` + - :kbd:`Home` + + * - Scroll to end of console output (only if the command line is empty) + - :kbd:`End` + - :kbd:`End` + - :kbd:`End` + + * - Page up through console output + - :kbd:`PageUp` + - :kbd:`PageUp` + - :kbd:`PageUp` + + * - Page down through console output + - :kbd:`PageDown` + - :kbd:`PageDown` + - :kbd:`PageDown` + + * - Go backward through :ref:`command history <command_line_interpreter_execution_history>` + - :kbd:`↑` + - :kbd:`↑` + - :kbd:`↑` + + * - Go forward through command history + - :kbd:`↓` + - :kbd:`↓` + - :kbd:`↓` + + * - Initiate reverse search through command history/step backwards through matching commands + - :kbd:`F9` + - :kbd:`Ctrl` + :kbd:`R` + - :kbd:`F9` + + * - Step forward through matching command history (after initiating reverse search) + - :kbd:`Shift` + :kbd:`F9` + - :kbd:`Ctrl` + :kbd:`S` + - :kbd:`Shift` + :kbd:`F9` + + * - Move to the beginning of the line + - :kbd:`Home` + - :kbd:`Ctrl` + :kbd:`A` + - :kbd:`Ctrl` + :kbd:`A` + + * - Move to the end of the line + - :kbd:`End` + - :kbd:`Ctrl` + :kbd:`E` + - :kbd:`Ctrl` + :kbd:`E` + + * - Execute the current expression + - :kbd:`Enter` + - :kbd:`Return` + - :kbd:`Enter` + + * - Add a new line, for entering multiline expressions + - :kbd:`Shift` + :kbd:`Enter` + - :kbd:`Shift` + :kbd:`Return` + - :kbd:`Shift` + :kbd:`Enter` + + +Autocomplete popup +****************** + +These shortcuts apply while the :ref:`autocomplete popup <command_line_interpreter_autocomplete>` is open: + +.. list-table:: + :widths: 40 20 20 20 + :header-rows: 1 + + * - **Command** + - **Windows** + - **macOS** + - **Linux** + + * - Choose the current autocomplete suggestion + - :kbd:`Tab` + - :kbd:`Tab` + - :kbd:`Tab` + + * - Cancel the autocomplete popup + - :kbd:`Esc` + - :kbd:`Esc` + - :kbd:`Esc` + + * - Move to the previous autocomplete suggestion + - :kbd:`↑` + - :kbd:`↑` + - :kbd:`↑` + + * - Move to the next autocomplete suggestion + - :kbd:`↓` + - :kbd:`↓` + - :kbd:`↓` + + * - Page up through autocomplete suggestions + - :kbd:`PageUp` + - :kbd:`PageUp` + - :kbd:`PageUp` + + * - Page down through autocomplete suggestions + - :kbd:`PageDown` + - :kbd:`PageDown` + - :kbd:`PageDown` + + * - Scroll to start of autocomplete suggestions + - :kbd:`Home` + - :kbd:`Home` + - :kbd:`Home` + + * - Scroll to end of autocomplete suggestions + - :kbd:`End` + - :kbd:`End` + - :kbd:`End` + + +.. _keyboard-shortcuts-style-editor: + +Style Editor +************ + +Keyboard shortcuts for the :doc:`Style editor <../style_editor/index>`. + +.. list-table:: + :widths: 25 25 25 25 + :header-rows: 1 + + * - **Command** + - **Windows** + - **macOS** + - **Linux** + + * - Open the Style Editor + - :kbd:`Shift` + :kbd:`F7` + - :kbd:`Shift` + :kbd:`F7` + - :kbd:`Shift` + :kbd:`F7` + + * - Open autocomplete popup + - :kbd:`Ctrl` + :kbd:`Space` + - :kbd:`Cmd` + :kbd:`Space` + - :kbd:`Ctrl` + :kbd:`Space` + + * - Find Next + - :kbd:`Ctrl` + :kbd:`G` + - :kbd:`Cmd` + :kbd:`G` + - :kbd:`Ctrl` + :kbd:`G` + + * - Find Previous + - :kbd:`Shift` + :kbd:`Ctrl` + :kbd:`G` + - :kbd:`Shift` + :kbd:`Cmd` + :kbd:`G` + - :kbd:`Shift` + :kbd:`Ctrl` + :kbd:`G` + + * - Replace + - :kbd:`Shift` + :kbd:`Ctrl` + :kbd:`F` + - :kbd:`Cmd` + :kbd:`Option` + :kbd:`F` + - :kbd:`Shift` + :kbd:`Ctrl` + :kbd:`F` + + * - Focus the filter input + - :kbd:`Ctrl` + :kbd:`P` + - :kbd:`Cmd` + :kbd:`P` + - :kbd:`Ctrl` + :kbd:`P` + + * - Save file to disk + - :kbd:`Ctrl` + :kbd:`S` + - :kbd:`Cmd` + :kbd:`S` + - :kbd:`Ctrl` + :kbd:`S` + +.. _keyboard-shortcuts-eyedropper: + +Eyedropper +********** + +Keyboard shortcuts for the :doc:`Eyedropper <../eyedropper/index>`. + +.. list-table:: + :widths: 25 25 25 25 + :header-rows: 1 + + * - **Command** + - **Windows** + - **macOS** + - **Linux** + + * - Select the current color + - :kbd:`Enter` + - :kbd:`Return` + - :kbd:`Enter` + + * - Dismiss the Eyedropper + - :kbd:`Esc` + - :kbd:`Esc` + - :kbd:`Esc` + + * - Move by 1 pixel + - :kbd:`ArrowKeys` + - :kbd:`ArrowKeys` + - :kbd:`ArrowKeys` + + * - Move by 10 pixels + - :kbd:`Shift` + :kbd:`ArrowKeys` + - :kbd:`Shift` + :kbd:`ArrowKeys` + - :kbd:`Shift` + :kbd:`ArrowKeys` diff --git a/devtools/docs/user/landingpage_accessibility.png b/devtools/docs/user/landingpage_accessibility.png Binary files differnew file mode 100644 index 0000000000..37dab30279 --- /dev/null +++ b/devtools/docs/user/landingpage_accessibility.png diff --git a/devtools/docs/user/landingpage_console.png b/devtools/docs/user/landingpage_console.png Binary files differnew file mode 100644 index 0000000000..ed5fdd0495 --- /dev/null +++ b/devtools/docs/user/landingpage_console.png diff --git a/devtools/docs/user/landingpage_debugger.png b/devtools/docs/user/landingpage_debugger.png Binary files differnew file mode 100644 index 0000000000..5ab71c2d1d --- /dev/null +++ b/devtools/docs/user/landingpage_debugger.png diff --git a/devtools/docs/user/landingpage_network.png b/devtools/docs/user/landingpage_network.png Binary files differnew file mode 100644 index 0000000000..9c3216bee0 --- /dev/null +++ b/devtools/docs/user/landingpage_network.png diff --git a/devtools/docs/user/landingpage_pageinspector.png b/devtools/docs/user/landingpage_pageinspector.png Binary files differnew file mode 100644 index 0000000000..4f5ada19c2 --- /dev/null +++ b/devtools/docs/user/landingpage_pageinspector.png diff --git a/devtools/docs/user/landingpage_performance_2022.png b/devtools/docs/user/landingpage_performance_2022.png Binary files differnew file mode 100644 index 0000000000..cf1e82fdfe --- /dev/null +++ b/devtools/docs/user/landingpage_performance_2022.png diff --git a/devtools/docs/user/landingpage_responsivedesign.png b/devtools/docs/user/landingpage_responsivedesign.png Binary files differnew file mode 100644 index 0000000000..a48803b40e --- /dev/null +++ b/devtools/docs/user/landingpage_responsivedesign.png diff --git a/devtools/docs/user/logo-developer-quantum.png b/devtools/docs/user/logo-developer-quantum.png Binary files differnew file mode 100644 index 0000000000..778bc9e2d3 --- /dev/null +++ b/devtools/docs/user/logo-developer-quantum.png diff --git a/devtools/docs/user/measure_a_portion_of_the_page/cursor-shown.png b/devtools/docs/user/measure_a_portion_of_the_page/cursor-shown.png Binary files differnew file mode 100644 index 0000000000..dc0f9cde2a --- /dev/null +++ b/devtools/docs/user/measure_a_portion_of_the_page/cursor-shown.png diff --git a/devtools/docs/user/measure_a_portion_of_the_page/index.rst b/devtools/docs/user/measure_a_portion_of_the_page/index.rst new file mode 100644 index 0000000000..35a1ae1962 --- /dev/null +++ b/devtools/docs/user/measure_a_portion_of_the_page/index.rst @@ -0,0 +1,34 @@ +============================= +Measure a portion of the page +============================= + +Using the **Measuring Tool** you can measure a specific area of a web page. + +This tool is hidden by default. To enable its button: + + +- Go to the DevTools :doc:`Settings <../settings/index>`. +- From the *Available Toolbox Buttons* check the *Measure a portion of the page* checkbox. + + +You will now see the *Measure a portion of the page* button at the top right of the Toolbox, in the same place as the Settings/Options button. + +.. image:: measure-button.png + :class: center + +When you want to use the tool, click this button. Now when you mouse over the viewport, you'll see the mouse has a crosshair cursor with its current coordinates displayed beside it. + +.. image:: cursor-shown.png + :class: border + + +When you hold the mouse button down and then drag, you'll start to draw a rectangle, with its x, y, and diagonal dimensions displayed. The units are in pixels. + +When you stop holding the mouse down, the rectangle that was displayed on screen when you released the button will stay there until you click again, allowing you time to take screenshots, note the information down, etc. The rectangle can also be resized later on by clicking one of the handles around it. + +.. image:: resizable_measuring_area.png + :class: border + +.. note:: + + **Tip**: Use the arrow keys to move the tool around and :kbd:`Ctrl` + arrow keys (:kbd:`Cmd` + arrow keys on a Mac) to resize it. Hold :kbd:`Shift` to make it move faster. diff --git a/devtools/docs/user/measure_a_portion_of_the_page/measure-button.png b/devtools/docs/user/measure_a_portion_of_the_page/measure-button.png Binary files differnew file mode 100644 index 0000000000..83895dcda9 --- /dev/null +++ b/devtools/docs/user/measure_a_portion_of_the_page/measure-button.png diff --git a/devtools/docs/user/measure_a_portion_of_the_page/resizable_measuring_area.png b/devtools/docs/user/measure_a_portion_of_the_page/resizable_measuring_area.png Binary files differnew file mode 100644 index 0000000000..cbb3ecb668 --- /dev/null +++ b/devtools/docs/user/measure_a_portion_of_the_page/resizable_measuring_area.png diff --git a/devtools/docs/user/memory/aggregate_view/index.rst b/devtools/docs/user/memory/aggregate_view/index.rst new file mode 100644 index 0000000000..94118e8c5b --- /dev/null +++ b/devtools/docs/user/memory/aggregate_view/index.rst @@ -0,0 +1,183 @@ +============== +Aggregate view +============== + +Before Firefox 48, this was the default view of a heap snapshot. After Firefox 48, the default view is the :doc:`Tree map view <../tree_map_view/index>`, and you can switch to the Aggregate view using the dropdown labeled "View:": + +.. image:: memory-tool-switch-view.png + :class: center + + +The Aggregate view looks something like this: + +.. image:: memory-tool-aggregate-view.png + :class: center + + +It presents a breakdown of the heap's contents, as a table. There are three main ways to group the data: + + +- :ref:`Type <memory-aggregate-view-type>` +- :ref:`Call Stack <memory-aggregate-view-call-stack>` +- :ref:`Inverted Call Stack <memory-aggregate-view-inverted-call-stack>` + +You can switch between them using the dropdown menu labeled "Group by:" located at the top of the panel: + +There's also a box labeled "Filter" at the top-right of the pane. You can use this to filter the contents of the snapshot that are displayed, so you can quickly see, for example, how many objects of a specific class were allocated. + + +.. _memory-aggregate-view-type: + +Type +**** + +This is the default view, which looks something like this: + +.. image:: memory-tool-aggregate-view.png + :class: center + +It groups the things on the heap into types, including: + + +- **JavaScript objects:** such as `Function <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function>`_ or `Array <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array>`_ +- **DOM elements:** such as `HTMLSpanElement <https://developer.mozilla.org/en-US/docs/Web/API/HTMLSpanElement>`_ or `Window <https://developer.mozilla.org/en-US/docs/Web/API/Window>`_ +- **Strings:** listed as ``"strings"`` +- **JavaScript sources:** listed as "``JSScript"`` +- **Internal objects:** such as "``js::Shape``". These are prefixed with ``"js::"``. + + +Each type gets a row in the table, and rows are ordered by the amount of memory occupied by objects of that type. For example, in the screenshot above you can see that JavaScript ``Object`` account for most memory, followed by strings. + + +- The "Total Count" column shows you the number of objects of each category that are currently allocated. +- The "Total Bytes" column shows you the number of bytes occupied by objects in each category, and that number as a percentage of the whole heap size for that tab. + + +The screenshots in this section are taken from a snapshot of the :doc:`monster example page <../monster_example/index>`. + + +For example, in the screenshot above, you can see that: + +- there are four ``Array`` objects +- that account for 15% of the total heap. + + +Next to the type's name, there's an icon that contains three stars arranged in a triangle: + +.. image:: memory-tool-in-group-icon.png + :class: center + + +Click this to see every instance of that type. For example, the entry for ``Array`` tells us that there are four ``Array`` objects in the snapshot. If we click the star-triangle, we'll see all four ``Array`` instances: + +.. image:: memory-tool-in-group.png + :class: center + + +For each instance, you can see the :ref:`retained size and shallow size <shallow-and-retained-size>` of that instance. In this case, you can see that the first three arrays have a fairly large shallow size (5% of the total heap usage) and a much larger retained size (26% of the total). + +On the right-hand side is a pane that just says "Select an item to view its retaining paths". If you select an item, you'll see the :ref:`Retaining paths panel <memory-dominators-view-retaining-paths-panel>` for that item: + +.. image:: memory-tool-in-group-retaining-paths.png + :class: center + + +.. _memory-aggregate-view-call-stack: + +Call Stack +********** + +The Call Stack shows you exactly where in your code you are making heap allocations. + +Because tracing allocations has a runtime cost, it must be explicitly enabled by checking "Record call stacks" *before* you allocate the memory in the snapshot. + +You'll then see a list of all the functions that allocated objects, ordered by the size of the allocations they made: + +.. image:: memory-tool-call-stack.png + :class: center + + +The structure of this view is very much like the structure of the :doc:`Call Tree <../../performance/call_tree/index>`, only it shows allocations rather than processor samples. So, for example, the first entry says that: + + +- 4,832,592 bytes, comprising 93% of the total heap usage, were allocated in a function at line 35 of "alloc.js", **or in functions called by that function** + + +We can use the disclosure triangle to drill down the call tree, to find the exact place your code made those allocations. + +It's easier to explain this with reference to a simple example. For :doc:`DOM allocation example <../dom_allocation_example/index>`. This page runs a script that creates a large number of DOM nodes (200 `HTMLDivElement <https://developer.mozilla.org/en-US/docs/Web/API/HTMLDivElement>`_ objects and 4000 `HTMLSpanElement <https://developer.mozilla.org/en-US/docs/Web/API/HTMLSpanElement>`_ objects). + +Let's get an allocation trace: + + +1. open the Memory tool +2. check "Record call stacks" +3. load https://firefox-devtools.github.io/performance-scenarios/dom-allocs/alloc.html +4. take a snapshot +5. select "View/Aggregate" +6. select "Group by/Call Stack" + +.. raw:: html + + <iframe width="560" height="315" src="https://www.youtube.com/embed/DyLulu9eoKY" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe> + <br/> + <br/> + +You should see something like this: + +.. image:: memory-tool-call-stack.png + :class: center + + +This is telling us that 93% of the total heap snapshot was allocated in functions called from "alloc.js", line 35 (our initial ``createToolbars()`` call). + +We can use the disclosure arrow to expand the tree to find out exactly where we're allocating memory: + +.. image:: memory-tool-call-stack-expanded.png + :class: center + + +This is where the "Bytes" and "Count" columns are useful: they show allocation size and number of allocations at that exact point. + +So in the example above, we can see that we made 4002 allocations, accounting for 89% of the total heap, in ``createToolbarButton()``, at `alloc.js line 9, position 23 <https://github.com/mdn/performance-scenarios/blob/gh-pages/dom-allocs/scripts/alloc.js#L9>`_: that is, the exact point where we create the `<span> <https://developer.mozilla.org/en-US/docs/Web/HTML/Element/span>`_ elements. + +The file name and line number is a link: if we click it, we go directly to that line in the debugger: + +.. raw:: html + + <iframe width="560" height="315" src="https://www.youtube.com/embed/zlnJcr1IFyY" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe> + <br/> + <br/> + + +.. _memory-aggregate-view-inverted-call-stack: + +Inverted Call Stack +******************* + +The Call Stack view is top-down: it shows allocations that happen at that point **or points deeper in the call tree**. So it's good for getting an overview of where your program is memory-hungry. However, this view means you have to drill a long way down to find the exact place where the allocations are happening. + +The "Inverted Call Stack" view helps with that. It gives you the bottom-up view of the program showing the exact places where allocations are happening, ranked by the size of allocation at each place. The disclosure arrow then walks you back up the call tree towards the top level. + +Let's see what the example looks like when we select "Inverted Call Stack": + +.. image:: memory-tool-inverted-call-stack.png + :class: center + + +Now at the top we can immediately see the ``createToolbarButton()`` call accounting for 89% of the heap usage in our page. + + +(no stack available) +******************** + +In the example above you'll note that 7% of the heap is marked "(no stack available)". This is because not all heap usage results from your JavaScript. + +For example: + + +- any scripts the page loads occupy heap space +- sometimes an object is allocated when there is no JavaScript on the stack. For example, DOM `Event <https://developer.mozilla.org/en-US/docs/Web/API/Event>`_ objects are allocated before the JavaScript is run and event handlers are called. + + +Many real-world pages will have a much higher "(no stack available)" share than 7%. diff --git a/devtools/docs/user/memory/aggregate_view/memory-tool-aggregate-view.png b/devtools/docs/user/memory/aggregate_view/memory-tool-aggregate-view.png Binary files differnew file mode 100644 index 0000000000..653710979f --- /dev/null +++ b/devtools/docs/user/memory/aggregate_view/memory-tool-aggregate-view.png diff --git a/devtools/docs/user/memory/aggregate_view/memory-tool-call-stack-expanded.png b/devtools/docs/user/memory/aggregate_view/memory-tool-call-stack-expanded.png Binary files differnew file mode 100644 index 0000000000..fe2364da58 --- /dev/null +++ b/devtools/docs/user/memory/aggregate_view/memory-tool-call-stack-expanded.png diff --git a/devtools/docs/user/memory/aggregate_view/memory-tool-call-stack.png b/devtools/docs/user/memory/aggregate_view/memory-tool-call-stack.png Binary files differnew file mode 100644 index 0000000000..52a96015da --- /dev/null +++ b/devtools/docs/user/memory/aggregate_view/memory-tool-call-stack.png diff --git a/devtools/docs/user/memory/aggregate_view/memory-tool-in-group-icon.png b/devtools/docs/user/memory/aggregate_view/memory-tool-in-group-icon.png Binary files differnew file mode 100644 index 0000000000..6354a3d377 --- /dev/null +++ b/devtools/docs/user/memory/aggregate_view/memory-tool-in-group-icon.png diff --git a/devtools/docs/user/memory/aggregate_view/memory-tool-in-group-retaining-paths.png b/devtools/docs/user/memory/aggregate_view/memory-tool-in-group-retaining-paths.png Binary files differnew file mode 100644 index 0000000000..191115f041 --- /dev/null +++ b/devtools/docs/user/memory/aggregate_view/memory-tool-in-group-retaining-paths.png diff --git a/devtools/docs/user/memory/aggregate_view/memory-tool-in-group.png b/devtools/docs/user/memory/aggregate_view/memory-tool-in-group.png Binary files differnew file mode 100644 index 0000000000..88aac55e9e --- /dev/null +++ b/devtools/docs/user/memory/aggregate_view/memory-tool-in-group.png diff --git a/devtools/docs/user/memory/aggregate_view/memory-tool-inverted-call-stack.png b/devtools/docs/user/memory/aggregate_view/memory-tool-inverted-call-stack.png Binary files differnew file mode 100644 index 0000000000..5a951c2e8c --- /dev/null +++ b/devtools/docs/user/memory/aggregate_view/memory-tool-inverted-call-stack.png diff --git a/devtools/docs/user/memory/aggregate_view/memory-tool-switch-view.png b/devtools/docs/user/memory/aggregate_view/memory-tool-switch-view.png Binary files differnew file mode 100644 index 0000000000..bb3cb0cdb3 --- /dev/null +++ b/devtools/docs/user/memory/aggregate_view/memory-tool-switch-view.png diff --git a/devtools/docs/user/memory/basic_operations/index.rst b/devtools/docs/user/memory/basic_operations/index.rst new file mode 100644 index 0000000000..c8149ef344 --- /dev/null +++ b/devtools/docs/user/memory/basic_operations/index.rst @@ -0,0 +1,95 @@ +================ +Basic operations +================ + + +.. _memory-basic-operations-opening-the-memory-tool: + +Opening the Memory tool +*********************** + +Before Firefox 50, the Memory tool is not enabled by default. To enable it, open the developer tool settings, and check the "Memory" box under "Default Firefox Developer Tools". + +From Firefox 50 onwards, the Memory tool is enabled by default. + + +.. _memory-basic-operations-taking-a-heap-snapshot: + +Taking a heap snapshot +********************** + +To take a snapshot of the heap, click the "Take snapshot" button, or the camera icon on the left: + +.. image:: memory-1-small.png + :class: center + +The snapshot will occupy the large pane on the right-hand side. On the left, you'll see an entry for the new snapshot, including its timestamp, size, and controls to save or clear this snapshot: + +.. image:: memory-2-small.png + :class: center + + +.. _memory-basic-operations-clearing-a-snapshot: + +Clearing a snapshot +******************* + +To remove a snapshot, click the "X" icon: + +.. image:: memory-3-small.png + :class: center + + +.. _memory-basic-operations-saving-and-loading-snapshots: + +Saving and loading snapshots +**************************** + +If you close the Memory tool, all unsaved snapshots will be discarded. To save a snapshot click "Save": + +.. image:: memory-4-small.png + :class: center + +You'll be prompted for a name and location, and the file will be saved with an ``.fxsnapshot`` extension. + +To load a snapshot from an existing ``.fxsnapshot`` file, click the import button, which looks like a rectangle with an arrow rising from it (before Firefox 49, this button was labeled with the text "Import..."): + +.. image:: memory-5-small.png + :class: center + +You'll be prompted to find a snapshot file on disk. + + +.. _memory-basic-operations-comparing-snapshots: + +Comparing snapshots +******************* + +Starting in Firefox 45, you can diff two heap snapshots. The diff shows you where memory was allocated or freed between the two snapshots. + +To create a diff, click the button that looks like a Venn diagram next to the camera icon (before Firefox 47, this looked like a "+/-" icon): + +.. image:: memory-6-small.png + :class: center + +You'll be prompted to select the snapshot to use as a baseline, then the snapshot to compare. The tool then shows you the differences between the two snapshots: + +.. raw:: html + + <iframe width="560" height="315" src="https://www.youtube.com/embed/3Ow-mdK6b2M" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe> + <br/> + <br/> + +.. note:: + When you're looking at a comparison, you can't use the Dominators view or the Tree Map view. + + +.. _memory-basic-operations-recording-call-stacks: + +Recording call stacks +********************* + +The Memory tool can tell you exactly where in your code you are allocating memory. However, recording this information has a run-time cost, so you must ask the tool to record memory calls *before* the memory is allocated, if you want to see memory call sites in the snapshot. To do this, check "Record call stacks" (before Firefox 49 this was labeled "Record allocation stacks"): + +.. image:: memory-7-small.png + :class: center diff --git a/devtools/docs/user/memory/basic_operations/memory-1-small.png b/devtools/docs/user/memory/basic_operations/memory-1-small.png Binary files differnew file mode 100644 index 0000000000..a2076330b8 --- /dev/null +++ b/devtools/docs/user/memory/basic_operations/memory-1-small.png diff --git a/devtools/docs/user/memory/basic_operations/memory-2-small.png b/devtools/docs/user/memory/basic_operations/memory-2-small.png Binary files differnew file mode 100644 index 0000000000..569b0d9d66 --- /dev/null +++ b/devtools/docs/user/memory/basic_operations/memory-2-small.png diff --git a/devtools/docs/user/memory/basic_operations/memory-3-small.png b/devtools/docs/user/memory/basic_operations/memory-3-small.png Binary files differnew file mode 100644 index 0000000000..5d77bd7f60 --- /dev/null +++ b/devtools/docs/user/memory/basic_operations/memory-3-small.png diff --git a/devtools/docs/user/memory/basic_operations/memory-4-small.png b/devtools/docs/user/memory/basic_operations/memory-4-small.png Binary files differnew file mode 100644 index 0000000000..9a1e18da6f --- /dev/null +++ b/devtools/docs/user/memory/basic_operations/memory-4-small.png diff --git a/devtools/docs/user/memory/basic_operations/memory-5-small.png b/devtools/docs/user/memory/basic_operations/memory-5-small.png Binary files differnew file mode 100644 index 0000000000..e3277186dc --- /dev/null +++ b/devtools/docs/user/memory/basic_operations/memory-5-small.png diff --git a/devtools/docs/user/memory/basic_operations/memory-6-small.png b/devtools/docs/user/memory/basic_operations/memory-6-small.png Binary files differnew file mode 100644 index 0000000000..da69b93e51 --- /dev/null +++ b/devtools/docs/user/memory/basic_operations/memory-6-small.png diff --git a/devtools/docs/user/memory/basic_operations/memory-7-small.png b/devtools/docs/user/memory/basic_operations/memory-7-small.png Binary files differnew file mode 100644 index 0000000000..844565a8b4 --- /dev/null +++ b/devtools/docs/user/memory/basic_operations/memory-7-small.png diff --git a/devtools/docs/user/memory/dom_allocation_example/index.rst b/devtools/docs/user/memory/dom_allocation_example/index.rst new file mode 100644 index 0000000000..85a9ab9036 --- /dev/null +++ b/devtools/docs/user/memory/dom_allocation_example/index.rst @@ -0,0 +1,57 @@ +====================== +DOM allocation example +====================== + +This article describes a very simple web page that we'll use to illustrate some features of the Memory tool. + +You can try out the site at https://firefox-devtools.github.io/performance-scenarios/dom-allocs/alloc.html. + +It just contains a script that creates a large number of DOM nodes: + +.. code-block:: javascript + + var toolbarButtonCount = 20; + var toolbarCount = 200; + + function getRandomInt(min, max) { + return Math.floor(Math.random() * (max - min + 1)) + min; + } + + function createToolbarButton() { + var toolbarButton = document.createElement("span"); + toolbarButton.classList.add("toolbarbutton"); + // stop Spidermonkey from sharing instances + toolbarButton[getRandomInt(0,5000)] = "foo"; + return toolbarButton; + } + + function createToolbar() { + var toolbar = document.createElement("div"); + // stop Spidermonkey from sharing instances + toolbar[getRandomInt(0,5000)] = "foo"; + for (var i = 0; i < toolbarButtonCount; i++) { + var toolbarButton = createToolbarButton(); + toolbar.appendChild(toolbarButton); + } + return toolbar; + } + + function createToolbars() { + var container = document.getElementById("container"); + for (var i = 0; i < toolbarCount; i++) { + var toolbar = createToolbar(); + container.appendChild(toolbar); + } + } + + createToolbars(); + +A simple pseudocode representation of how this code operates looks like this: + +.. code-block:: JavaScript + + createToolbars() + -> createToolbar() // called 200 times, creates 1 DIV element each time + -> createToolbarButton() // called 20 times per toolbar, creates 1 SPAN element each time</pre> + +In total, then, it creates 200 `HTMLDivElement <https://developer.mozilla.org/en-US/docs/Web/API/HTMLDivElement>`_ objects, and 4000 `HTMLSpanElement <https://developer.mozilla.org/en-US/docs/Web/API/HTMLSpanElement>`_ objects. diff --git a/devtools/docs/user/memory/dominators/index.rst b/devtools/docs/user/memory/dominators/index.rst new file mode 100644 index 0000000000..443b4c6e7b --- /dev/null +++ b/devtools/docs/user/memory/dominators/index.rst @@ -0,0 +1,85 @@ +========== +Dominators +========== + +This article provides an introduction to the concepts of *Reachability*, *Shallow* versus *Retained* size, and *Dominators*, as they apply in garbage-collected languages like JavaScript. + +These concepts matter in memory analysis, because often an object may itself be small, but may hold references to other much larger objects, and by doing this will prevent the garbage collector from freeing that extra memory. + +You can see the dominators in a page using the :doc:`Dominators view <../dominators_view/index>` in the Memory tool. + + +With a garbage-collected language, like JavaScript, the programmer doesn't generally have to worry about deallocating memory. They can just create and use objects, and when the objects are no longer needed, the runtime takes care of cleaning up, and frees the memory the objects occupied. + + +.. _memory-dominators-reachability: + +Reachability +************ + +In modern JavaScript implementations, the runtime decides whether an object is no longer needed based on *reachability*. In this system the heap is represented as one or more graphs. Each node in the graph represents an object, and each connection between nodes (edge) represents a reference from one object to another. The graph starts at a root node, indicated in these diagrams with "R". + +.. image:: memory-graph.svg + :class: center + + +During garbage collection, the runtime traverses the graph, starting at the root, and marks every object it finds. Any objects it doesn't find are unreachable, and can be deallocated. + +So when an object becomes unreachable (for example, because it is only referenced by a single local variable which goes out of scope) then any objects it references also become unreachable, as long as no other objects reference them: + +.. image:: memory-graph-unreachable.svg + :class: center + + +Conversely, this means that objects are kept alive as long as some other reachable object is holding a reference to them. + + +.. _shallow-and-retained-size: + +Shallow and retained size +************************* + +This gives rise to a distinction between two ways to look at the size of an object: + + +- *shallow size*: the size of the object itself +- *retained size*: the size of the object itself, plus the size of other objects that are kept alive by this object + + +Often, objects will have a small shallow size but a much larger retained size, through the references they contain to other objects. Retained size is an important concept in analyzing memory usage, because it answers the question "if this object ceases to exist, what's the total amount of memory freed?". + + +Dominators +********** + +A related concept is that of the *dominator*. Node B is said to dominate node A if every path from the root to A passes through B: + +.. image:: memory-graph-dominators.svg + :class: center + + +If any of node A's dominators are freed, then node A itself becomes eligible for garbage collection. + + +.. _memory-dominators-immediate-dominator: + +If node B dominates node A, but does not dominate any of A's other dominators, then B is the *immediate dominator* of A: + +.. image:: memory-graph-immediate-dominator.svg + :class: center + + +.. _memory-dominators-multiple-paths: + +One slight subtlety here is that if an object A is referenced by two other unrelated objects B and C, then neither object is its dominator, because you could remove either B or C from the graph, and A would still be retained by its other referrer. Instead, the immediate dominator of A would be its first common ancestor: + +.. image:: memory-graph-dominator-multiple-references.svg + :class: center + + +See also +******** + + +- `Dominators in graph theory <https://en.wikipedia.org/wiki/Dominator_%28graph_theory%29>`_. +- `Tracing garbage collection <https://en.wikipedia.org/wiki/Tracing_garbage_collection>`_. diff --git a/devtools/docs/user/memory/dominators/memory-graph-dominator-multiple-references.svg b/devtools/docs/user/memory/dominators/memory-graph-dominator-multiple-references.svg new file mode 100644 index 0000000000..4ac6b45812 --- /dev/null +++ b/devtools/docs/user/memory/dominators/memory-graph-dominator-multiple-references.svg @@ -0,0 +1,4 @@ +<!-- This Source Code Form is subject to the terms of the Mozilla Public + - License, v. 2.0. If a copy of the MPL was not distributed with this + - file, You can obtain one at http://mozilla.org/MPL/2.0/. --> +<svg xmlns="http://www.w3.org/2000/svg" xmlns:xl="http://www.w3.org/1999/xlink" viewBox="114 20 158 212" width="158pt" height="212pt"><defs><linearGradient x1="0" x2="1" id="a" gradientUnits="userSpaceOnUse"><stop offset="0" stop-color="#e5f2f2"/><stop offset="1" stop-color="#cff2f2"/></linearGradient><linearGradient id="b" xl:href="#a" gradientTransform="matrix(0 38 -38 0 183 90.5)"/><linearGradient id="c" xl:href="#a" gradientTransform="matrix(0 38 -38 0 135 141.5)"/><linearGradient id="d" xl:href="#a" gradientTransform="rotate(90 44.5 186) scale(38)"/><linearGradient id="f" xl:href="#a" gradientTransform="matrix(0 38 -38 0 183 191.5)"/><marker orient="auto" overflow="visible" markerUnits="strokeWidth" id="e" viewBox="-1 -4 10 8" markerWidth="10" markerHeight="8" color="#000"><path d="M8 0L0-3v6z" fill="currentColor" stroke="currentColor"/></marker><marker orient="auto" overflow="visible" markerUnits="strokeWidth" id="g" viewBox="-1 -4 10 8" markerWidth="10" markerHeight="8" color="#000"><path d="M8 0H0m0-3l8 3-8 3" fill="none" stroke="currentColor"/></marker></defs><g fill="none"><circle cx="183" cy="109.5" r="19" fill="url(#b)"/><circle cx="183" cy="109.5" r="19" stroke="#000" stroke-linecap="round" stroke-linejoin="round"/><circle cx="135" cy="160.5" r="19" fill="url(#c)"/><circle cx="135" cy="160.5" r="19" stroke="#000" stroke-linecap="round" stroke-linejoin="round"/><circle cx="230.5" cy="160.5" r="19" fill="url(#d)"/><circle cx="230.5" cy="160.5" r="19" stroke="#000" stroke-linecap="round" stroke-linejoin="round"/><path marker-end="url(#e)" stroke="#000" stroke-linecap="round" stroke-linejoin="round" d="M169.978 123.336l-15.171 16.119m41.143-16.051l14.853 15.948"/><circle cx="183" cy="210.5" r="19" fill="url(#f)"/><circle cx="183" cy="210.5" r="19" stroke="#000" stroke-linecap="round" stroke-linejoin="round"/><text transform="translate(172.8 201.5)" fill="#000"><tspan font-family="Helvetica Neue" font-size="16" font-weight="500" x="5.016" y="15" textLength="10.368">A</tspan></text><path marker-end="url(#e)" stroke="#000" stroke-linecap="round" stroke-linejoin="round" d="M148.158 174.206l14.828 15.446"/><text transform="translate(169 26.5)" fill="#000"><tspan font-family="Helvetica Neue" font-size="16" font-weight="500" x=".096" y="15" textLength="10.368">A</tspan><tspan font-family="Helvetica Neue" font-size="16" font-weight="500" x="9.28" y="15" textLength="4.448">’</tspan><tspan font-family="Helvetica Neue" font-size="16" font-weight="500" x="12.544" y="15" textLength="85.36">s dominator</tspan></text><path marker-end="url(#g)" stroke="#000" stroke-linecap="round" stroke-linejoin="round" stroke-dasharray="4,4" d="M210.905 50.5l-15.546 32.87"/><path marker-end="url(#e)" stroke="#000" stroke-linecap="round" stroke-linejoin="round" d="M217.414 174.275l-14.509 15.272"/></g></svg>
\ No newline at end of file diff --git a/devtools/docs/user/memory/dominators/memory-graph-dominators.svg b/devtools/docs/user/memory/dominators/memory-graph-dominators.svg new file mode 100644 index 0000000000..e3a63c96df --- /dev/null +++ b/devtools/docs/user/memory/dominators/memory-graph-dominators.svg @@ -0,0 +1,4 @@ +<!-- This Source Code Form is subject to the terms of the Mozilla Public + - License, v. 2.0. If a copy of the MPL was not distributed with this + - file, You can obtain one at http://mozilla.org/MPL/2.0/. --> +<svg xmlns="http://www.w3.org/2000/svg" xmlns:xl="http://www.w3.org/1999/xlink" viewBox="60 57 353 232" width="353pt" height="232pt"><defs><linearGradient x1="0" x2="1" id="a" gradientUnits="userSpaceOnUse"><stop offset="0" stop-color="#e5f2f2"/><stop offset="1" stop-color="#cff2f2"/></linearGradient><linearGradient id="b" xl:href="#a" gradientTransform="matrix(0 38 -38 0 183 90.5)"/><linearGradient id="c" xl:href="#a" gradientTransform="matrix(0 38 -38 0 135 141.5)"/><linearGradient id="d" xl:href="#a" gradientTransform="rotate(90 44.5 186) scale(38)"/><linearGradient id="f" xl:href="#a" gradientTransform="matrix(0 38 -38 0 81.5 196.5)"/><linearGradient id="g" xl:href="#a" gradientTransform="rotate(90 41 238.5) scale(38)"/><linearGradient id="h" xl:href="#a" gradientTransform="rotate(90 -8.5 240) scale(38)"/><linearGradient id="i" xl:href="#a" gradientTransform="matrix(0 38 -38 0 327 248.5)"/><marker orient="auto" overflow="visible" markerUnits="strokeWidth" id="e" viewBox="-1 -4 10 8" markerWidth="10" markerHeight="8" color="#000"><path d="M8 0L0-3v6z" fill="currentColor" stroke="currentColor"/></marker><marker orient="auto" overflow="visible" markerUnits="strokeWidth" id="j" viewBox="-1 -4 10 8" markerWidth="10" markerHeight="8" color="#000"><path d="M8 0H0m0-3l8 3-8 3" fill="none" stroke="currentColor"/></marker></defs><g fill="none"><circle cx="183" cy="109.5" r="19" fill="url(#b)"/><circle cx="183" cy="109.5" r="19" stroke="#000" stroke-linecap="round" stroke-linejoin="round"/><text transform="translate(172.8 100.5)" fill="#000"><tspan font-family="Helvetica Neue" font-size="16" font-weight="500" x="4.72" y="15" textLength="10.96">R</tspan></text><circle cx="135" cy="160.5" r="19" fill="url(#c)"/><circle cx="135" cy="160.5" r="19" stroke="#000" stroke-linecap="round" stroke-linejoin="round"/><circle cx="230.5" cy="160.5" r="19" fill="url(#d)"/><circle cx="230.5" cy="160.5" r="19" stroke="#000" stroke-linecap="round" stroke-linejoin="round"/><path marker-end="url(#e)" stroke="#000" stroke-linecap="round" stroke-linejoin="round" d="M169.978 123.336l-15.171 16.119m41.143-16.051l14.853 15.948"/><circle cx="81.5" cy="215.5" r="19" fill="url(#f)"/><circle cx="81.5" cy="215.5" r="19" stroke="#000" stroke-linecap="round" stroke-linejoin="round"/><path marker-end="url(#e)" stroke="#000" stroke-linecap="round" stroke-linejoin="round" d="M121.752 174.119l-20.101 20.665"/><circle cx="279.5" cy="216.5" r="19" fill="url(#g)"/><circle cx="279.5" cy="216.5" r="19" stroke="#000" stroke-linecap="round" stroke-linejoin="round"/><circle cx="231.5" cy="267.5" r="19" fill="url(#h)"/><circle cx="231.5" cy="267.5" r="19" stroke="#000" stroke-linecap="round" stroke-linejoin="round"/><circle cx="327" cy="267.5" r="19" fill="url(#i)"/><circle cx="327" cy="267.5" r="19" stroke="#000" stroke-linecap="round" stroke-linejoin="round"/><text transform="translate(316.8 258.5)" fill="#000"><tspan font-family="Helvetica Neue" font-size="16" font-weight="500" x="5.016" y="15" textLength="10.368">A</tspan></text><path marker-end="url(#e)" stroke="#000" stroke-linecap="round" stroke-linejoin="round" d="M243.012 174.799l17.457 19.951m31.981 35.654l14.853 15.948m-40.825-16.016l-15.171 16.119"/><text transform="translate(301.5 63)" fill="#000"><tspan font-family="Helvetica Neue" font-size="16" font-weight="500" x=".096" y="15" textLength="10.368">A</tspan><tspan font-family="Helvetica Neue" font-size="16" font-weight="500" x="9.28" y="15" textLength="4.448">’</tspan><tspan font-family="Helvetica Neue" font-size="16" font-weight="500" x="12.544" y="15" textLength="93.36">s dominators</tspan></text><path marker-end="url(#j)" stroke="#000" stroke-linecap="round" stroke-linejoin="round" stroke-dasharray="4,4" d="M296.5 84.682l-85.265 18.644M333.483 87l-79.457 56.709M346.715 87l-53.899 103.845"/></g></svg>
\ No newline at end of file diff --git a/devtools/docs/user/memory/dominators/memory-graph-immediate-dominator.svg b/devtools/docs/user/memory/dominators/memory-graph-immediate-dominator.svg new file mode 100644 index 0000000000..8288524884 --- /dev/null +++ b/devtools/docs/user/memory/dominators/memory-graph-immediate-dominator.svg @@ -0,0 +1,4 @@ +<!-- This Source Code Form is subject to the terms of the Mozilla Public + - License, v. 2.0. If a copy of the MPL was not distributed with this + - file, You can obtain one at http://mozilla.org/MPL/2.0/. --> +<svg xmlns="http://www.w3.org/2000/svg" xmlns:xl="http://www.w3.org/1999/xlink" viewBox="60 57 350 232" width="350pt" height="232pt"><defs><linearGradient x1="0" x2="1" id="a" gradientUnits="userSpaceOnUse"><stop offset="0" stop-color="#e5f2f2"/><stop offset="1" stop-color="#cff2f2"/></linearGradient><linearGradient id="b" xl:href="#a" gradientTransform="matrix(0 38 -38 0 183 90.5)"/><linearGradient id="c" xl:href="#a" gradientTransform="matrix(0 38 -38 0 135 141.5)"/><linearGradient id="d" xl:href="#a" gradientTransform="rotate(90 44.5 186) scale(38)"/><linearGradient id="f" xl:href="#a" gradientTransform="matrix(0 38 -38 0 81.5 196.5)"/><linearGradient id="g" xl:href="#a" gradientTransform="rotate(90 41 238.5) scale(38)"/><linearGradient id="h" xl:href="#a" gradientTransform="rotate(90 -8.5 240) scale(38)"/><linearGradient id="i" xl:href="#a" gradientTransform="matrix(0 38 -38 0 327 248.5)"/><marker orient="auto" overflow="visible" markerUnits="strokeWidth" id="e" viewBox="-1 -4 10 8" markerWidth="10" markerHeight="8" color="#000"><path d="M8 0L0-3v6z" fill="currentColor" stroke="currentColor"/></marker><marker orient="auto" overflow="visible" markerUnits="strokeWidth" id="j" viewBox="-1 -4 10 8" markerWidth="10" markerHeight="8" color="#000"><path d="M8 0H0m0-3l8 3-8 3" fill="none" stroke="currentColor"/></marker></defs><g fill="none"><circle cx="183" cy="109.5" r="19" fill="url(#b)"/><circle cx="183" cy="109.5" r="19" stroke="#000" stroke-linecap="round" stroke-linejoin="round"/><text transform="translate(172.8 100.5)" fill="#000"><tspan font-family="Helvetica Neue" font-size="16" font-weight="500" x="4.72" y="15" textLength="10.96">R</tspan></text><circle cx="135" cy="160.5" r="19" fill="url(#c)"/><circle cx="135" cy="160.5" r="19" stroke="#000" stroke-linecap="round" stroke-linejoin="round"/><circle cx="230.5" cy="160.5" r="19" fill="url(#d)"/><circle cx="230.5" cy="160.5" r="19" stroke="#000" stroke-linecap="round" stroke-linejoin="round"/><path marker-end="url(#e)" stroke="#000" stroke-linecap="round" stroke-linejoin="round" d="M169.978 123.336l-15.171 16.119m41.143-16.051l14.853 15.948"/><circle cx="81.5" cy="215.5" r="19" fill="url(#f)"/><circle cx="81.5" cy="215.5" r="19" stroke="#000" stroke-linecap="round" stroke-linejoin="round"/><path marker-end="url(#e)" stroke="#000" stroke-linecap="round" stroke-linejoin="round" d="M121.752 174.119l-20.101 20.665"/><circle cx="279.5" cy="216.5" r="19" fill="url(#g)"/><circle cx="279.5" cy="216.5" r="19" stroke="#000" stroke-linecap="round" stroke-linejoin="round"/><circle cx="231.5" cy="267.5" r="19" fill="url(#h)"/><circle cx="231.5" cy="267.5" r="19" stroke="#000" stroke-linecap="round" stroke-linejoin="round"/><circle cx="327" cy="267.5" r="19" fill="url(#i)"/><circle cx="327" cy="267.5" r="19" stroke="#000" stroke-linecap="round" stroke-linejoin="round"/><text transform="translate(316.8 258.5)" fill="#000"><tspan font-family="Helvetica Neue" font-size="16" font-weight="500" x="5.016" y="15" textLength="10.368">A</tspan></text><path marker-end="url(#e)" stroke="#000" stroke-linecap="round" stroke-linejoin="round" d="M243.012 174.799l17.457 19.951m31.981 35.654l14.853 15.948m-40.825-16.016l-15.171 16.119"/><text transform="translate(304.5 62)" fill="#000"><tspan font-family="Helvetica Neue" font-size="16" font-weight="500" x=".2" y="15" textLength="10.368">A</tspan><tspan font-family="Helvetica Neue" font-size="16" font-weight="500" x="9.384" y="15" textLength="4.448">’</tspan><tspan font-family="Helvetica Neue" font-size="16" font-weight="500" x="12.648" y="15" textLength="87.152">s immediate</tspan><tspan font-family="Helvetica Neue" font-size="16" font-weight="500" x="13.544" y="33" textLength="72.912">dominator</tspan></text><path marker-end="url(#j)" stroke="#000" stroke-linecap="round" stroke-linejoin="round" stroke-dasharray="4,4" d="M341.863 103l-48.444 88.167"/></g></svg>
\ No newline at end of file diff --git a/devtools/docs/user/memory/dominators/memory-graph-unreachable.svg b/devtools/docs/user/memory/dominators/memory-graph-unreachable.svg new file mode 100644 index 0000000000..62abb0e016 --- /dev/null +++ b/devtools/docs/user/memory/dominators/memory-graph-unreachable.svg @@ -0,0 +1,4 @@ +<!-- This Source Code Form is subject to the terms of the Mozilla Public + - License, v. 2.0. If a copy of the MPL was not distributed with this + - file, You can obtain one at http://mozilla.org/MPL/2.0/. --> +<svg xmlns="http://www.w3.org/2000/svg" xmlns:xl="http://www.w3.org/1999/xlink" viewBox="60 88 287 200" width="287pt" height="200pt"><defs><linearGradient x1="0" x2="1" id="a" gradientUnits="userSpaceOnUse"><stop offset="0" stop-color="#e5f2f2"/><stop offset="1" stop-color="#cff2f2"/></linearGradient><linearGradient id="c" xl:href="#a" gradientTransform="matrix(0 38 -38 0 183 90.5)"/><linearGradient id="d" xl:href="#a" gradientTransform="matrix(0 38 -38 0 135 141.5)"/><linearGradient id="e" xl:href="#a" gradientTransform="rotate(90 44.5 186) scale(38)"/><linearGradient x1="0" x2="1" id="b" gradientUnits="userSpaceOnUse"><stop offset="0" stop-color="#f29a8b"/><stop offset="1" stop-color="#f23d1c"/></linearGradient><linearGradient id="f" xl:href="#b" gradientTransform="rotate(90 41 237.5) scale(38)"/><linearGradient id="g" xl:href="#b" gradientTransform="rotate(90 -8.5 239) scale(38)"/><linearGradient id="h" xl:href="#b" gradientTransform="matrix(0 38 -38 0 326 247.5)"/><linearGradient id="j" xl:href="#a" gradientTransform="matrix(0 38 -38 0 81.5 196.5)"/><marker orient="auto" overflow="visible" markerUnits="strokeWidth" id="i" viewBox="-1 -4 10 8" markerWidth="10" markerHeight="8" color="#000"><path d="M8 0L0-3v6z" fill="currentColor" stroke="currentColor"/></marker></defs><g fill="none"><circle cx="183" cy="109.5" r="19" fill="url(#c)"/><circle cx="183" cy="109.5" r="19" stroke="#000" stroke-linecap="round" stroke-linejoin="round"/><text transform="translate(172.8 100.5)" fill="#000"><tspan font-family="Helvetica Neue" font-size="16" font-weight="500" x="4.72" y="15" textLength="10.96">R</tspan></text><circle cx="135" cy="160.5" r="19" fill="url(#d)"/><circle cx="135" cy="160.5" r="19" stroke="#000" stroke-linecap="round" stroke-linejoin="round"/><circle cx="230.5" cy="160.5" r="19" fill="url(#e)"/><circle cx="230.5" cy="160.5" r="19" stroke="#000" stroke-linecap="round" stroke-linejoin="round"/><circle cx="278.5" cy="215.5" r="19" fill="url(#f)"/><circle cx="278.5" cy="215.5" r="19" stroke="#000" stroke-linecap="round" stroke-linejoin="round"/><circle cx="230.5" cy="266.5" r="19" fill="url(#g)"/><circle cx="230.5" cy="266.5" r="19" stroke="#000" stroke-linecap="round" stroke-linejoin="round"/><circle cx="326" cy="266.5" r="19" fill="url(#h)"/><circle cx="326" cy="266.5" r="19" stroke="#000" stroke-linecap="round" stroke-linejoin="round"/><path marker-end="url(#i)" stroke="#000" stroke-linecap="round" stroke-linejoin="round" d="M169.978 123.336l-15.171 16.119m41.143-16.051l14.853 15.948m54.675 89.984l-15.171 16.119m41.143-16.051l14.853 15.948"/><circle cx="81.5" cy="215.5" r="19" fill="url(#j)"/><circle cx="81.5" cy="215.5" r="19" stroke="#000" stroke-linecap="round" stroke-linejoin="round"/><path marker-end="url(#i)" stroke="#000" stroke-linecap="round" stroke-linejoin="round" d="M121.752 174.119l-20.101 20.665"/></g></svg>
\ No newline at end of file diff --git a/devtools/docs/user/memory/dominators/memory-graph.svg b/devtools/docs/user/memory/dominators/memory-graph.svg new file mode 100644 index 0000000000..0b4ee2d64c --- /dev/null +++ b/devtools/docs/user/memory/dominators/memory-graph.svg @@ -0,0 +1,4 @@ +<!-- This Source Code Form is subject to the terms of the Mozilla Public + - License, v. 2.0. If a copy of the MPL was not distributed with this + - file, You can obtain one at http://mozilla.org/MPL/2.0/. --> +<svg xmlns="http://www.w3.org/2000/svg" xmlns:xl="http://www.w3.org/1999/xlink" viewBox="60 88 288 201" width="384" height="268"><defs><linearGradient x1="0" x2="1" id="a" gradientUnits="userSpaceOnUse"><stop offset="0" stop-color="#e5f2f2"/><stop offset="1" stop-color="#cff2f2"/></linearGradient><linearGradient id="b" xl:href="#a" gradientTransform="matrix(0 38 -38 0 183 90.5)"/><linearGradient id="c" xl:href="#a" gradientTransform="matrix(0 38 -38 0 135 141.5)"/><linearGradient id="d" xl:href="#a" gradientTransform="rotate(90 44.5 186) scale(38)"/><linearGradient id="f" xl:href="#a" gradientTransform="matrix(0 38 -38 0 81.5 196.5)"/><linearGradient id="g" xl:href="#a" gradientTransform="rotate(90 41 238.5) scale(38)"/><linearGradient id="h" xl:href="#a" gradientTransform="rotate(90 -8.5 240) scale(38)"/><linearGradient id="i" xl:href="#a" gradientTransform="matrix(0 38 -38 0 327 248.5)"/><marker orient="auto" overflow="visible" markerUnits="strokeWidth" id="e" viewBox="-1 -4 10 8" markerWidth="10" markerHeight="8" color="#000"><path d="M8 0L0-3v6z" fill="currentColor" stroke="currentColor"/></marker></defs><g fill="none"><circle cx="183" cy="109.5" r="19" fill="url(#b)"/><circle cx="183" cy="109.5" r="19" stroke="#000" stroke-linecap="round" stroke-linejoin="round"/><text transform="translate(172.8 100.5)" fill="#000"><tspan font-family="Helvetica Neue" font-size="16" font-weight="500" x="4.72" y="15" textLength="10.96">R</tspan></text><circle cx="135" cy="160.5" r="19" fill="url(#c)"/><circle cx="135" cy="160.5" r="19" stroke="#000" stroke-linecap="round" stroke-linejoin="round"/><circle cx="230.5" cy="160.5" r="19" fill="url(#d)"/><circle cx="230.5" cy="160.5" r="19" stroke="#000" stroke-linecap="round" stroke-linejoin="round"/><path marker-end="url(#e)" stroke="#000" stroke-linecap="round" stroke-linejoin="round" d="M169.978 123.336l-15.171 16.119m41.143-16.051l14.853 15.948"/><circle cx="81.5" cy="215.5" r="19" fill="url(#f)"/><circle cx="81.5" cy="215.5" r="19" stroke="#000" stroke-linecap="round" stroke-linejoin="round"/><path marker-end="url(#e)" stroke="#000" stroke-linecap="round" stroke-linejoin="round" d="M121.752 174.119l-20.101 20.665"/><circle cx="279.5" cy="216.5" r="19" fill="url(#g)"/><circle cx="279.5" cy="216.5" r="19" stroke="#000" stroke-linecap="round" stroke-linejoin="round"/><circle cx="231.5" cy="267.5" r="19" fill="url(#h)"/><circle cx="231.5" cy="267.5" r="19" stroke="#000" stroke-linecap="round" stroke-linejoin="round"/><circle cx="327" cy="267.5" r="19" fill="url(#i)"/><circle cx="327" cy="267.5" r="19" stroke="#000" stroke-linecap="round" stroke-linejoin="round"/><path marker-end="url(#e)" stroke="#000" stroke-linecap="round" stroke-linejoin="round" d="M243.012 174.799l17.457 19.951m31.981 35.654l14.853 15.948m-40.825-16.016l-15.171 16.119"/></g></svg>
\ No newline at end of file diff --git a/devtools/docs/user/memory/dominators_view/dominators-1.png b/devtools/docs/user/memory/dominators_view/dominators-1.png Binary files differnew file mode 100644 index 0000000000..163a80016c --- /dev/null +++ b/devtools/docs/user/memory/dominators_view/dominators-1.png diff --git a/devtools/docs/user/memory/dominators_view/dominators-10.png b/devtools/docs/user/memory/dominators_view/dominators-10.png Binary files differnew file mode 100644 index 0000000000..e6688060af --- /dev/null +++ b/devtools/docs/user/memory/dominators_view/dominators-10.png diff --git a/devtools/docs/user/memory/dominators_view/dominators-2.png b/devtools/docs/user/memory/dominators_view/dominators-2.png Binary files differnew file mode 100644 index 0000000000..99b7db7b09 --- /dev/null +++ b/devtools/docs/user/memory/dominators_view/dominators-2.png diff --git a/devtools/docs/user/memory/dominators_view/dominators-3.png b/devtools/docs/user/memory/dominators_view/dominators-3.png Binary files differnew file mode 100644 index 0000000000..2d380f6e21 --- /dev/null +++ b/devtools/docs/user/memory/dominators_view/dominators-3.png diff --git a/devtools/docs/user/memory/dominators_view/dominators-4.png b/devtools/docs/user/memory/dominators_view/dominators-4.png Binary files differnew file mode 100644 index 0000000000..d3d5eef59c --- /dev/null +++ b/devtools/docs/user/memory/dominators_view/dominators-4.png diff --git a/devtools/docs/user/memory/dominators_view/dominators-5.png b/devtools/docs/user/memory/dominators_view/dominators-5.png Binary files differnew file mode 100644 index 0000000000..41a03488e9 --- /dev/null +++ b/devtools/docs/user/memory/dominators_view/dominators-5.png diff --git a/devtools/docs/user/memory/dominators_view/dominators-6.png b/devtools/docs/user/memory/dominators_view/dominators-6.png Binary files differnew file mode 100644 index 0000000000..a3d3026eb2 --- /dev/null +++ b/devtools/docs/user/memory/dominators_view/dominators-6.png diff --git a/devtools/docs/user/memory/dominators_view/dominators-7.png b/devtools/docs/user/memory/dominators_view/dominators-7.png Binary files differnew file mode 100644 index 0000000000..160f205391 --- /dev/null +++ b/devtools/docs/user/memory/dominators_view/dominators-7.png diff --git a/devtools/docs/user/memory/dominators_view/dominators-8.png b/devtools/docs/user/memory/dominators_view/dominators-8.png Binary files differnew file mode 100644 index 0000000000..e9512b9b05 --- /dev/null +++ b/devtools/docs/user/memory/dominators_view/dominators-8.png diff --git a/devtools/docs/user/memory/dominators_view/dominators-9.png b/devtools/docs/user/memory/dominators_view/dominators-9.png Binary files differnew file mode 100644 index 0000000000..af396abc21 --- /dev/null +++ b/devtools/docs/user/memory/dominators_view/dominators-9.png diff --git a/devtools/docs/user/memory/dominators_view/index.rst b/devtools/docs/user/memory/dominators_view/index.rst new file mode 100644 index 0000000000..a0e2c9db87 --- /dev/null +++ b/devtools/docs/user/memory/dominators_view/index.rst @@ -0,0 +1,174 @@ +=============== +Dominators view +=============== + +The Dominators view is new in Firefox 46. + +Starting in Firefox 46, the Memory tool includes a new view called the Dominators view. This is useful for understanding the "retained size" of objects allocated by your site: that is, the size of the objects themselves plus the size of the objects that they keep alive through references. + +If you already know what shallow size, retained size, and dominators are, skip to the Dominators UI section. Otherwise, you might want to review the article on :doc:`Dominators concepts <../dominators/index>`. + + +Dominators UI +************* + +To see the Dominators view for a snapshot, select "Dominators" in the "View" drop-down list. It looks something like this: + +.. image:: dominators-1.png + :class: center + +The Dominators view consists of two panels: + +- the :ref:`Dominators Tree panel <memory-dominators-view-dominators-tree-panel>` shows you which nodes in the snapshot are retaining the most memory +- the :ref:`Retaining Paths panel <memory-dominators-view-retaining-paths-panel>` (new in Firefox 47) shows the 5 shortest retaining paths for a single node. + +.. image:: dominators-2.png + :class: center + + +.. _memory-dominators-view-dominators-tree-panel: + +Dominators Tree panel +********************* + +The Dominators Tree tells you which objects in the snapshot are retaining the most memory. + +In the main part of the UI, the first row is labeled "GC Roots". Immediately underneath that is an entry for: + + +- Every GC root node. In Gecko, there is more than one memory graph, and therefore more than one root. There may be many (often temporary) roots. For example: variables allocated on the stack need to be rooted, or internal caches may need to root their elements. +- Any other node that's referenced from two different roots (since in this case, neither root dominates it). + + +Each entry displays: + + +- the retained size of the node, as bytes and as a percentage of the total +- the shallow size of the node, as bytes and as a percentage of the total +- the nodes's name and address in memory. + + +Entries are ordered by the amount of memory that they retain. For example: + +.. image:: dominators-3.png + :class: center + +In this screenshot we can see five entries under "GC Roots". The first two are Call and Window objects, and retain about 21% and 8% of the total size of the memory snapshot, respectively. You can also see that these objects have a relatively tiny "Shallow Size", so almost all of the retained size is in the objects that they dominate. + +Immediately under each GC root, you'll see all the nodes for which this root is the :ref:`immediate dominator <memory-dominators-immediate-dominator>`. These nodes are also ordered by their retained size. + +For example, if we click on the first Window object: + +.. image:: dominators-4.png + :class: center + +We can see that this Window dominates a CSS2Properties object, whose retained size is 2% of the total snapshot size. Again the shallow size is very small: almost all of its retained size is in the nodes that it dominates. By clicking on the disclosure arrow next to the Function, we can see those nodes. + +In this way you can quickly get a sense of which objects retain the most memory in the snapshot. + +You can use :kbd:`Alt` + :kbd:`click` to expand the whole graph under a node. + +Call Stack +********** + +In the toolbar at the top of the tool is a dropdown called "Label by": + +.. image:: dominators-5.png + :class: center + +By default, this is set to "Type". However, you can set it instead to "Call Stack" to see exactly where in your code the objects are being allocated. + +.. note:: + + This option is called "Allocation Stack" in Firefox 46. + + +To enable this, you must check the box labeled "Record call stacks" *before* you run the code that allocates the objects. Then take a snapshot, then select "Call Stack" in the "Label by" drop-down. + +Now the node's name will contain the name of the function that allocated it, and the file, line number and character position of the exact spot where the function allocated it. Clicking the file name will take you to that spot in the Debugger. + + +.. note:: + + Sometimes you'll see "(no stack available)" here. In particular, allocation stacks are currently only recorded for objects, not for arrays, strings, or internal structures. + + +.. _memory-dominators-view-retaining-paths-panel: + +Retaining Paths panel +********************* + +The Retaining Paths panel is new in Firefox 47. + +The Retaining Paths panel shows you, for a given node, the 5 shortest paths back from this node to a GC root. This enables you to see all the nodes that are keeping the given node from being garbage-collected. If you suspect that an object is being leaked, this will show you exactly which objects are holding a reference to it. + +To see the retaining paths for a node, you have to select the node in the Dominators Tree panel: + +.. image:: dominators-6.png + :class: center + + +Here, we've selected an object, and can see a single path back to a GC root. + +The ``Window`` GC root holds a reference to an ``HTMLDivElement`` object, and that holds a reference to an ``Object``, and so on. If you look in the Dominators Tree panel, you can trace the same path there. If either of these references were removed, the items below them could be garbage-collected. + +Each connection in the graph is labeled with the variable name for the referenced object. + +Sometimes there's more than one retaining path back from a node: + +.. image:: dominators-7.png + :class: center + + +Here there are three paths back from the ``DocumentPrototype`` node to a GC root. If one were removed, then the ``DocumentPrototype`` would still not be garbage-collected, because it's still retained by the other two path. + + +Example +******* + +Let's see how some simple code is reflected in the Dominators view. + +We'll use the :doc:`monster allocation example <../monster_example/index>`, which creates three arrays, each containing 5000 monsters, each monster having a randomly-generated name. + +Taking a snapshot +***************** + +To see what it looks like in the Dominators view: + +- load the page +- enable the Memory tool in the :ref:`Settings <tool-toolbox-settings>`, if you haven't already +- open the Memory tool +- check "Record call stacks" +- press the button labeled "Make monsters!" +- take a snapshot +- switch to the "Dominators" view + + +Analyzing the Dominators Tree +***************************** + +You'll see the three arrays as the top three GC roots, each retaining about 23% of the total memory usage: + +.. image:: dominators-8.png + :class: center + + +If you expand an array, you'll see the objects (monsters) it contains. Each monster has a relatively small shallow size of 160 bytes. This includes the integer eye- and tentacle-counts. Each monster has a bigger retained size, which is accounted for by the string used for the monster's name: + +.. image:: dominators-9.png + :class: center + +All this maps closely to the :ref:`memory graph we were expecting to see <memory-dominators-immediate-dominator>`. One thing you might be wondering, though, is: where's the top-level object that retains all three arrays? If we look at the Retaining Paths panel for one of the arrays, we'll see it: + +.. image:: dominators-10.png + :class: center + +Here we can see the retaining object, and even that this particular array is the array of ``fierce`` monsters. But the array is also rooted directly, so if the object were to stop referencing the array, it would still not be eligible for garbage collection. + +This means that the object does not dominate the array, and is therefore not shown in the Dominators Tree view. :ref:`See the relevant section of the Dominators concepts article <memory-dominators-multiple-paths>`. + + +Using the Call Stack view +************************* + +Finally, you can switch to the Call Stack view, see where the objects are being allocated, and jump to that point in the Debugger. diff --git a/devtools/docs/user/memory/index.rst b/devtools/docs/user/memory/index.rst new file mode 100644 index 0000000000..7a508015a1 --- /dev/null +++ b/devtools/docs/user/memory/index.rst @@ -0,0 +1,52 @@ +====== +Memory +====== + +The Memory tool lets you take a snapshot of the current tab's memory `heap <https://en.wikipedia.org/wiki/Memory_management#HEAP>`_. It then provides a number of views of the heap that can show you which objects account for memory usage and exactly where in your code you are allocating memory. + +.. raw:: html + + <iframe width="560" height="315" src="https://www.youtube.com/embed/DJLoq5E5ww0" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe> + <br/> + <br/> + + +The basics +********** + +- :ref:`Opening the memory tool <memory-basic-operations-opening-the-memory-tool>` +- :ref:`Taking a heap snapshot <memory-basic-operations-taking-a-heap-snapshot>` +- :ref:`Comparing two snapshots <memory-basic-operations-comparing-snapshots>` +- :ref:`Deleting snapshots <memory-basic-operations-clearing-a-snapshot>` +- :ref:`Saving and loading snapshots <memory-basic-operations-saving-and-loading-snapshots>` +- :ref:`Recording call stacks <memory-basic-operations-recording-call-stacks>` + + +Analyzing snapshots +******************* + +The Tree map view is new in Firefox 48, and the Dominators view is new in Firefox 46. + +Once you've taken a snapshot, there are three main views the Memory tool provides: + + +- :doc:`the Tree map view <tree_map_view/index>` shows memory usage as a `treemap <https://en.wikipedia.org/wiki/Treemapping>`_. +- :doc:`the Aggregate view <aggregate_view/index>` shows memory usage as a table of allocated types. +- :doc:`the Dominators view <dominators_view/index>` shows the "retained size" of objects: that is, the size of objects plus the size of other objects that they keep alive through references. + + +If you've opted to record allocation stacks for the snapshot, the Aggregate and Dominators views can show you exactly where in your code allocations are happening. + +Concepts +******** + +- :doc:`Dominators <dominators_view/index>` + + +Example pages +************* + +Examples used in the Memory tool documentation. + +- :doc:`Monster example <monster_example/index>` +- :doc:`DOM allocation example <dom_allocation_example/index>` diff --git a/devtools/docs/user/memory/monster_example/index.rst b/devtools/docs/user/memory/monster_example/index.rst new file mode 100644 index 0000000000..93042541a1 --- /dev/null +++ b/devtools/docs/user/memory/monster_example/index.rst @@ -0,0 +1,80 @@ +=============== +Monster example +=============== + +This article describes a very simple web page that we'll use to illustrate some features of the Memory tool. + +You can try the site at https://firefox-devtools.github.io/performance-scenarios/js-allocs/alloc.html. Here's the code: + +.. code-block:: javascript + + var MONSTER_COUNT = 5000; + var MIN_NAME_LENGTH = 2; + var MAX_NAME_LENGTH = 48; + + function Monster() { + + function randomInt(min, max) { + return Math.floor(Math.random() * (max - min + 1)) + min; + } + + function randomName() { + var chars = "abcdefghijklmnopqrstuvwxyz"; + var nameLength = randomInt(MIN_NAME_LENGTH, MAX_NAME_LENGTH); + var name = ""; + for (var j = 0; j &lt; nameLength; j++) { + name += chars[randomInt(0, chars.length-1)]; + } + return name; + } + + this.name = randomName(); + this.eyeCount = randomInt(0, 25); + this.tentacleCount = randomInt(0, 250); + } + + function makeMonsters() { + var monsters = { + "friendly": [], + "fierce": [], + "undecided": [] + }; + + for (var i = 0; i < MONSTER_COUNT; i++) { + monsters.friendly.push(new Monster()); + } + + for (var i = 0; i < MONSTER_COUNT; i++) { + monsters.fierce.push(new Monster()); + } + + for (var i = 0; i < MONSTER_COUNT; i++) { + monsters.undecided.push(new Monster()); + } + + console.log(monsters); + } + + var makeMonstersButton = document.getElementById("make-monsters"); + makeMonstersButton.addEventListener("click", makeMonsters); + +The page contains a button: when you push the button, the code creates some monsters. Specifically: + + +- the code creates an object with three properties, each an array: + + - one for fierce monsters + - one for friendly monsters + - one for monsters who haven't decided yet. + + +- for each array, the code creates and appends 5000 randomly-initialized monsters. Each monster has: + + - a string, for the monster's name + - a number representing the number of eyes it has + - a number representing the number of tentacles it has. + +So the structure of the memory allocated on the JavaScript heap is an object containing three arrays, each containing 5000 objects (monsters), each object containing a string and two integers: + +.. image:: monsters.svg + :class: center diff --git a/devtools/docs/user/memory/monster_example/monsters.svg b/devtools/docs/user/memory/monster_example/monsters.svg new file mode 100644 index 0000000000..1ecb9b1f77 --- /dev/null +++ b/devtools/docs/user/memory/monster_example/monsters.svg @@ -0,0 +1,4 @@ +<!-- This Source Code Form is subject to the terms of the Mozilla Public + - License, v. 2.0. If a copy of the MPL was not distributed with this + - file, You can obtain one at http://mozilla.org/MPL/2.0/. --> +<svg xmlns="http://www.w3.org/2000/svg" xmlns:xl="http://www.w3.org/1999/xlink" viewBox="62 78 464 484" width="464pt" height="484pt"><defs><linearGradient x1="0" x2="1" id="a" gradientUnits="userSpaceOnUse"><stop offset="0" stop-color="#e5f2f2"/><stop offset="1" stop-color="#cff2f2"/></linearGradient><linearGradient id="b" xl:href="#a" gradientTransform="matrix(0 31.5 -31.5 0 103.25 304)"/><linearGradient id="c" xl:href="#a" gradientTransform="matrix(0 31.5 -31.5 0 231.25 136)"/><linearGradient id="d" xl:href="#a" gradientTransform="matrix(0 31.5 -31.5 0 359.25 136)"/><linearGradient id="e" xl:href="#a" gradientTransform="matrix(0 31.5 -31.5 0 359.25 80)"/><linearGradient id="f" xl:href="#a" gradientTransform="matrix(0 31.5 -31.5 0 359.25 192)"/><linearGradient id="g" xl:href="#a" gradientTransform="matrix(0 31.5 -31.5 0 484.75 81)"/><linearGradient id="h" xl:href="#a" gradientTransform="matrix(0 31.5 -31.5 0 484.75 136)"/><linearGradient id="j" xl:href="#a" gradientTransform="matrix(0 31.5 -31.5 0 231.25 304)"/><linearGradient id="k" xl:href="#a" gradientTransform="matrix(0 31.5 -31.5 0 359.25 304)"/><linearGradient id="l" xl:href="#a" gradientTransform="matrix(0 31.5 -31.5 0 359.25 248)"/><linearGradient id="m" xl:href="#a" gradientTransform="matrix(0 31.5 -31.5 0 359.25 360)"/><linearGradient id="n" xl:href="#a" gradientTransform="matrix(0 31.5 -31.5 0 484.75 249)"/><linearGradient id="o" xl:href="#a" gradientTransform="matrix(0 31.5 -31.5 0 484.75 304)"/><linearGradient id="p" xl:href="#a" gradientTransform="matrix(0 31.5 -31.5 0 231.25 472)"/><linearGradient id="q" xl:href="#a" gradientTransform="matrix(0 31.5 -31.5 0 359.25 472)"/><linearGradient id="r" xl:href="#a" gradientTransform="matrix(0 31.5 -31.5 0 359.25 416)"/><linearGradient id="s" xl:href="#a" gradientTransform="matrix(0 31.5 -31.5 0 359.25 528)"/><linearGradient id="t" xl:href="#a" gradientTransform="matrix(0 31.5 -31.5 0 484.75 417)"/><linearGradient id="u" xl:href="#a" gradientTransform="matrix(0 31.5 -31.5 0 484.75 472)"/><marker orient="auto" overflow="visible" markerUnits="strokeWidth" id="i" viewBox="-1 -4 10 8" markerWidth="10" markerHeight="8" color="#000"><path d="M8 0L0-3v6z" fill="currentColor" stroke="currentColor"/></marker></defs><g fill="none"><path fill="url(#b)" d="M64.5 304H142v31.5H64.5z"/><path stroke="#000" stroke-linecap="round" stroke-linejoin="round" d="M64.5 304H142v31.5H64.5z"/><text transform="translate(69.5 310.75)" fill="#000"><tspan font-family="Helvetica Neue" font-size="16" font-weight="500" x="10.038" y="15" textLength="47.424">Object</tspan></text><path fill="url(#c)" d="M192.5 136H270v31.5h-77.5z"/><path stroke="#000" stroke-linecap="round" stroke-linejoin="round" d="M192.5 136H270v31.5h-77.5z"/><text transform="translate(197.5 142.75)" fill="#000"><tspan font-family="Helvetica Neue" font-size="16" font-weight="500" x="14.942" y="15" textLength="37.616">Array</tspan></text><path fill="url(#d)" d="M320.5 136H398v31.5h-77.5z"/><path stroke="#000" stroke-linecap="round" stroke-linejoin="round" d="M320.5 136H398v31.5h-77.5z"/><text transform="translate(325.5 142.75)" fill="#000"><tspan font-family="Helvetica Neue" font-size="16" font-weight="500" x="4.262" y="15" textLength="58.976">Monster</tspan></text><path fill="url(#e)" d="M320.5 80H398v31.5h-77.5z"/><path stroke="#000" stroke-linecap="round" stroke-linejoin="round" d="M320.5 80H398v31.5h-77.5z"/><text transform="translate(325.5 86.75)" fill="#000"><tspan font-family="Helvetica Neue" font-size="16" font-weight="500" x="4.262" y="15" textLength="58.976">Monster</tspan></text><path fill="url(#f)" d="M320.5 192H398v31.5h-77.5z"/><path stroke="#000" stroke-linecap="round" stroke-linejoin="round" d="M320.5 192H398v31.5h-77.5z"/><text transform="translate(325.5 198.75)" fill="#000"><tspan font-family="Helvetica Neue" font-size="16" font-weight="500" x="25.75" y="15" textLength="16">…</tspan></text><path fill="url(#g)" d="M446 81h77.5v31.5H446z"/><path stroke="#000" stroke-linecap="round" stroke-linejoin="round" d="M446 81h77.5v31.5H446z"/><text transform="translate(451 87.75)" fill="#000"><tspan font-family="Helvetica Neue" font-size="16" font-weight="500" x="12.566" y="15" textLength="42.368">String</tspan></text><path fill="url(#h)" d="M446 136h77.5v31.5H446z"/><path stroke="#000" stroke-linecap="round" stroke-linejoin="round" d="M446 136h77.5v31.5H446z"/><text transform="translate(451 142.75)" fill="#000"><tspan font-family="Helvetica Neue" font-size="16" font-weight="500" x="12.566" y="15" textLength="42.368">String</tspan></text><path d="M103.25 304V151.75h79.35m112.65 0h15.35m-15.35 0v-56h15.35m-40.6 56h25.25v56h15.35m87.4-112l38.101.439M398 151.75h38.1" marker-end="url(#i)" stroke="#000" stroke-linecap="round" stroke-linejoin="round"/><path fill="url(#j)" d="M192.5 304H270v31.5h-77.5z"/><path stroke="#000" stroke-linecap="round" stroke-linejoin="round" d="M192.5 304H270v31.5h-77.5z"/><text transform="translate(197.5 310.75)" fill="#000"><tspan font-family="Helvetica Neue" font-size="16" font-weight="500" x="14.942" y="15" textLength="37.616">Array</tspan></text><path fill="url(#k)" d="M320.5 304H398v31.5h-77.5z"/><path stroke="#000" stroke-linecap="round" stroke-linejoin="round" d="M320.5 304H398v31.5h-77.5z"/><text transform="translate(325.5 310.75)" fill="#000"><tspan font-family="Helvetica Neue" font-size="16" font-weight="500" x="4.262" y="15" textLength="58.976">Monster</tspan></text><path fill="url(#l)" d="M320.5 248H398v31.5h-77.5z"/><path stroke="#000" stroke-linecap="round" stroke-linejoin="round" d="M320.5 248H398v31.5h-77.5z"/><text transform="translate(325.5 254.75)" fill="#000"><tspan font-family="Helvetica Neue" font-size="16" font-weight="500" x="4.262" y="15" textLength="58.976">Monster</tspan></text><path fill="url(#m)" d="M320.5 360H398v31.5h-77.5z"/><path stroke="#000" stroke-linecap="round" stroke-linejoin="round" d="M320.5 360H398v31.5h-77.5z"/><text transform="translate(325.5 366.75)" fill="#000"><tspan font-family="Helvetica Neue" font-size="16" font-weight="500" x="25.75" y="15" textLength="16">…</tspan></text><path fill="url(#n)" d="M446 249h77.5v31.5H446z"/><path stroke="#000" stroke-linecap="round" stroke-linejoin="round" d="M446 249h77.5v31.5H446z"/><text transform="translate(451 255.75)" fill="#000"><tspan font-family="Helvetica Neue" font-size="16" font-weight="500" x="12.566" y="15" textLength="42.368">String</tspan></text><path fill="url(#o)" d="M446 304h77.5v31.5H446z"/><path stroke="#000" stroke-linecap="round" stroke-linejoin="round" d="M446 304h77.5v31.5H446z"/><text transform="translate(451 310.75)" fill="#000"><tspan font-family="Helvetica Neue" font-size="16" font-weight="500" x="12.566" y="15" textLength="42.368">String</tspan></text><path d="M142 319.75h40.6m112.65 0h15.35m-15.35 0v-56h15.35m-40.6 56h25.25v56h15.35m87.4-112l38.101.439M398 319.75h38.1" marker-end="url(#i)" stroke="#000" stroke-linecap="round" stroke-linejoin="round"/><path fill="url(#p)" d="M192.5 472H270v31.5h-77.5z"/><path stroke="#000" stroke-linecap="round" stroke-linejoin="round" d="M192.5 472H270v31.5h-77.5z"/><text transform="translate(197.5 478.75)" fill="#000"><tspan font-family="Helvetica Neue" font-size="16" font-weight="500" x="14.942" y="15" textLength="37.616">Array</tspan></text><path fill="url(#q)" d="M320.5 472H398v31.5h-77.5z"/><path stroke="#000" stroke-linecap="round" stroke-linejoin="round" d="M320.5 472H398v31.5h-77.5z"/><text transform="translate(325.5 478.75)" fill="#000"><tspan font-family="Helvetica Neue" font-size="16" font-weight="500" x="4.262" y="15" textLength="58.976">Monster</tspan></text><path fill="url(#r)" d="M320.5 416H398v31.5h-77.5z"/><path stroke="#000" stroke-linecap="round" stroke-linejoin="round" d="M320.5 416H398v31.5h-77.5z"/><text transform="translate(325.5 422.75)" fill="#000"><tspan font-family="Helvetica Neue" font-size="16" font-weight="500" x="4.262" y="15" textLength="58.976">Monster</tspan></text><path fill="url(#s)" d="M320.5 528H398v31.5h-77.5z"/><path stroke="#000" stroke-linecap="round" stroke-linejoin="round" d="M320.5 528H398v31.5h-77.5z"/><text transform="translate(325.5 534.75)" fill="#000"><tspan font-family="Helvetica Neue" font-size="16" font-weight="500" x="25.75" y="15" textLength="16">…</tspan></text><path fill="url(#t)" d="M446 417h77.5v31.5H446z"/><path stroke="#000" stroke-linecap="round" stroke-linejoin="round" d="M446 417h77.5v31.5H446z"/><text transform="translate(451 423.75)" fill="#000"><tspan font-family="Helvetica Neue" font-size="16" font-weight="500" x="12.566" y="15" textLength="42.368">String</tspan></text><path fill="url(#u)" d="M446 472h77.5v31.5H446z"/><path stroke="#000" stroke-linecap="round" stroke-linejoin="round" d="M446 472h77.5v31.5H446z"/><text transform="translate(451 478.75)" fill="#000"><tspan font-family="Helvetica Neue" font-size="16" font-weight="500" x="12.566" y="15" textLength="42.368">String</tspan></text><path d="M103.25 335.5v152.25h79.35m112.65 0h15.35m-15.35 0v-56h15.35m-40.6 56h25.25v56h15.35m87.4-112l38.101.439M398 487.75h38.1" marker-end="url(#i)" stroke="#000" stroke-linecap="round" stroke-linejoin="round"/></g></svg>
\ No newline at end of file diff --git a/devtools/docs/user/memory/tree_map_view/index.rst b/devtools/docs/user/memory/tree_map_view/index.rst new file mode 100644 index 0000000000..3ab11d733b --- /dev/null +++ b/devtools/docs/user/memory/tree_map_view/index.rst @@ -0,0 +1,47 @@ +============= +Tree map view +============= + +The Tree map view is new in Firefox 48. + +The Tree map view provides a visual representation of the snapshot, that helps you quickly get an idea of which objects are using the most memory. + +A treemap displays `"hierarchical (tree-structured) data as a set of nested rectangles" <https://en.wikipedia.org/wiki/Treemapping>`_. The size of the rectangles corresponds to some quantitative aspect of the data. + +For the treemaps shown in the Memory tool, things on the heap are divided at the top level into four categories: + + +- **objects**: JavaScript and DOM objects, such as `Function <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function>`_, `Object <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object>`_, or `Array <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array>`_, and DOM types like `Window <https://developer.mozilla.org/en-US/docs/Web/API/Window>`_ and `HTMLDivElement <https://developer.mozilla.org/en-US/docs/Web/API/HTMLDivElement>`_. +- **scripts**: JavaScript sources loaded by the page. +- **strings** +- **other**: this includes internal `SpiderMonkey <https://spidermonkey.dev/>`_ objects. + + +Each category is represented with a rectangle, and the size of the rectangle corresponds to the proportion of the heap occupied by items in that category. This means you can quickly get an idea of roughly what sorts of things allocated by your site are using the most memory. + +Within top-level categories: + + +- **objects** is further divided by the object's type. +- **scripts** is further subdivided by the script's origin. It also includes a separate rectangle for code that can't be correlated with a file, such as JIT-optimized code. +- **other** is further subdivided by the object's type. + + +Here are some example snapshots, as they appear in the Tree map view: + +.. image:: treemap-domnodes.png + :class: center + + +This treemap is from the :doc:`DOM allocation example <../dom_allocation_example/index>`, which runs a script that creates a large number of DOM nodes (200 `HTMLDivElement <https://developer.mozilla.org/en-US/docs/Web/API/HTMLDivElement>`_ objects and 4000 `HTMLSpanElement <https://developer.mozilla.org/en-US/docs/Web/API/HTMLSpanElement>`_ objects). You can see how almost all the heap usage is from the ``HTMLSpanElement`` objects that it creates. + +.. image:: treemap-monsters.png + :class: center + + +This treemap is from the :doc:`monster allocation example <../monster_example/index>`, which creates three arrays, each containing 5000 monsters, each monster having a randomly-generated name. You can see that most of the heap is occupied by the strings used for the monsters' names, and the objects used to contain the monsters' other attributes. + +.. image:: treemap-bbc.png + :class: center + +This treemap is from http://www.bbc.com/, and is probably more representative of real life than the examples. You can see the much larger proportion of the heap occupied by scripts, that are loaded from a large number of origins. diff --git a/devtools/docs/user/memory/tree_map_view/treemap-bbc.png b/devtools/docs/user/memory/tree_map_view/treemap-bbc.png Binary files differnew file mode 100644 index 0000000000..55552b8382 --- /dev/null +++ b/devtools/docs/user/memory/tree_map_view/treemap-bbc.png diff --git a/devtools/docs/user/memory/tree_map_view/treemap-domnodes.png b/devtools/docs/user/memory/tree_map_view/treemap-domnodes.png Binary files differnew file mode 100644 index 0000000000..1192e390da --- /dev/null +++ b/devtools/docs/user/memory/tree_map_view/treemap-domnodes.png diff --git a/devtools/docs/user/memory/tree_map_view/treemap-monsters.png b/devtools/docs/user/memory/tree_map_view/treemap-monsters.png Binary files differnew file mode 100644 index 0000000000..513adab923 --- /dev/null +++ b/devtools/docs/user/memory/tree_map_view/treemap-monsters.png diff --git a/devtools/docs/user/menu_button.png b/devtools/docs/user/menu_button.png Binary files differnew file mode 100644 index 0000000000..d8a58075dc --- /dev/null +++ b/devtools/docs/user/menu_button.png diff --git a/devtools/docs/user/migrating_from_firebug/index.rst b/devtools/docs/user/migrating_from_firebug/index.rst new file mode 100644 index 0000000000..7bb8b1083e --- /dev/null +++ b/devtools/docs/user/migrating_from_firebug/index.rst @@ -0,0 +1,351 @@ +====================== +Migrating from Firebug +====================== + +When migrating from Firebug to the Firefox Developer Tools, you may wonder where the features you loved in Firebug are available in the Developer Tools. The following list aims to help Firebug users to find their way into the Developer Tools. + +.. image:: logo-developer-quantum.png + :class: center + +.. rst-class:: center + + For the latest developer tools and features, try Firefox Developer Edition. + +.. raw:: html + + <a href="https://www.mozilla.org/en-US/firefox/developer/" style="width: 280px; display: block; margin-left: auto; margin-right: auto; padding: 10px; text-align: center; border-radius: 4px; background-color: #81BC2E; white-space: nowrap; color: white; text-shadow: 0px 1px 0px rgba(0, 0, 0, 0.25); box-shadow: 0px 1px 0px 0px rgba(0, 0, 0, 0.2), 0px -1px 0px 0px rgba(0, 0, 0, 0.3) inset;">Download Firefox Developer Edition</a> + + +General +******* + +Activation +---------- + +Firebug's activation is URL based respecting the `same origin policy <https://en.wikipedia.org/wiki/Same_origin_policy>`_. That means that when you open a page on the same origin in a different tab, Firebug gets opened automatically. And when you open a page of a different origin in the same tab, it closes automatically. The DevTools' activation on the other hand is tab based. That means, that when you open the DevTools in a tab, they stay open even when you switch between different websites. When you switch to another tab, though, they're closed. + + +Open the tools +-------------- + +Firebug can be opened by pressing F12. To open it to inspect an element it is possible to press :kbd:`Ctrl` + :kbd:`Shift` + :kbd:`C` / :kbd:`Cmd` + :kbd:`Opt` + :kbd:`C`. The DevTools share the same shortcuts, but also provide :ref:`shortcuts for the different panels <keyboard-shortcuts-opening-and-closing-tools>`. E.g. the :doc:`Network Monitor <../network_monitor/index>` can be opened via :kbd:`Ctrl` + :kbd:`Shift` + :kbd:`Q` / :kbd:`Cmd` + :kbd:`Opt` + :kbd:`Q`, the :doc:`Web Console <../web_console/index>` via :kbd:`Ctrl` + :kbd:`Shift` + :kbd:`K` / :kbd:`Cmd` + :kbd:`Opt` + :kbd:`K` and the :doc:`Debugger <../debugger/index>` via :kbd:`Ctrl` + :kbd:`Shift` + :kbd:`S` / :kbd:`Cmd` + :kbd:`Opt` + :kbd:`S`. + + +Web Console +*********** + +The :doc:`Web Console <../web_console/index>` is the equivalent of Firebug's Console panel. It shows log information associated with a web page and allows you to execute JavaScript expressions via its :doc:`command line <../web_console/the_command_line_interpreter/index>`. The display between both is somewhat different. This may be changed in `bug 1269730 <https://bugzilla.mozilla.org/show_bug.cgi?id=1269730>`_. + + +Filter log messages +------------------- + +Firebug offers two ways to filter log messages, via the options menu and via the filter buttons within the toolbar. The Developer Tools console offers similar functionality via the :ref:`filter buttons inside its toolbar <web_console_ui_tour_filtering_by_category>` — centralized at one place. + + +Command Line API +---------------- + +The Command Line API in Firebug provides some special functions for your convenience. The Developer Tools command line has :ref:`some functions in common <command_line_interpreter_helper_commands>`, but also has some other functions and misses others. + + +Console API +----------- + +To log things to the console from within the web page Firebug makes a Console API available within the page. The Developer Tools share the `same API <https://developer.mozilla.org/en-US/docs/Web/API/console>`_, so your ``console.*`` statements will continue to work. + + +Persist logs +------------ + +In Firebug you can click the *Persist* button within the toolbar to keep the logged messages between page navigations and reloads. In the DevTools this option is called :ref:`Enable persistent logs <settings-common-preferences>` and is available within the Toolbox Options panel. + + +Server logs +----------- + +Firebug extensions like FirePHP allow to log server-side messages to the Firebug console. This functionality is already :ref:`integrated into the DevTools <web_console_server>` using the `ChromeLogger <https://craig.is/writing/chrome-logger>`_ protocol and doesn't require any extensions to be installed. + + +Command history +--------------- + +The :ref:`command history <command_line_interpreter_execution_history>` available through a button in Firebug's command line, is available by pressing :kbd:`↑`/:kbd:`↓` within the DevTools command line. + + +Inspect object properties +------------------------- + +By clicking on an object logged within the console you can inspect the object's properties and methods within the DOM panel. In the Firefox DevTools you can also inspect the objects. The difference is that they :ref:`show the properties and methods within a side panel inside the Web Console <web_console_rich_output_examining_object_properties>`. + + +Show network requests +--------------------- + +The Console panel in Firebug allows to log `AJAX <https://developer.mozilla.org/en-US/docs/Glossary/AJAX>`_ requests (aka `XMLHttpRequest <https://developer.mozilla.org/en-US/docs/Glossary/XHR_(XMLHttpRequest)>`_). This option is also available within the DevTools Web Console via the *Net* > *XHR*. Furthermore, the Web Console even allows to display all other network requests via *Net* > *Log*. + + +View JSON and XML structures +---------------------------- + +To view JSON and XML responses of `AJAX <https://developer.mozilla.org/en-US/docs/Glossary/AJAX>`_ requests, Firebug has special tabs when expanding the request within the Console panel. The DevTools Web Console shows those structures directly under the "Response" tab. + + +Multi-line command line +----------------------- + +Firebug's console has a multi-line command line called Command Editor. The DevTools have a :ref:`side panel <command_line_interpreter_multi_line_mode>` like the Command Editor. + + +Response preview +---------------- + +There is a *Preview* tab when a network request logged to the console is expanded in Firebug. The Web Console displays a preview within the *Response* tab. It is currently missing the preview for HTML, XML and SVG, though, which is tracked in `bug 1247392 <https://bugzilla.mozilla.org/show_bug.cgi?id=1247392>`_ and `bug 1262796 <https://bugzilla.mozilla.org/show_bug.cgi?id=1262796>`_, but when you click on the URL of the request you switch to the :doc:`Network Monitor <../network_monitor/index>`, which has a *Preview* tab. + + +Inspector +********* + +Firebug has an HTML panel, which allows to edit HTML/XML/SVG and the CSS related to it. Within the DevTools this functionality is served by the :doc:`Page Inspector <../page_inspector/index>`. + + +Edit HTML +--------- + +Within the Page Inspector the tag attributes and the contents can be edited inline just like in Firebug. Beyond that it allows to edit the tag names inline. + +You can also edit the HTML directly. In Firebug you do this by right-clicking a node and clicking Edit HTML... in the context menu. In the DevTools this option is also available via the context menu. There the option is called :ref:`Edit As HTML <page-inspector-how-to-examine-and-edit-html-editing_html>`. Only the live preview of changes is currently missing, which is tracked in `bug 1067318 <https://bugzilla.mozilla.org/show_bug.cgi?id=1067318>`_ and `bug 815464 <https://bugzilla.mozilla.org/show_bug.cgi?id=815464>`_. + + +Copy HTML and related information +--------------------------------- + +Firebug's HTML panel allows to copy the inner and outer HTML of an element as well as the CSS and XPath to it via the context menu of an element. The Page Inspector provides the same functionality except copying XPaths. This is covered by `bug 987877 <https://bugzilla.mozilla.org/show_bug.cgi?id=987877>`_. + + +Edit CSS +-------- + +Both tools allow to view and edit the CSS rules related to the element selected within the node view in a similar way. Firebug has a Style side panel for this, the DevTools have a :doc:`Rules side panel <../page_inspector/how_to/examine_and_edit_css/index>`. + +In Firebug you add new rules by right-clicking and choosing *Add Rule...* from the context menu. The DevTools also have a context menu option for that named :ref:`Add New Rule and additionally have a + button <page_inspector_how_to_examine_and_edit_css_add_rules>` within the Rules panel's toolbar to create new rules. + +To edit element styles, i.e. the CSS properties of the `style <https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes#attr-style>`_ attribute of an element, in Firebug you have to right-click into the Style side panel and choose Edit Element Style... from the context menu. The DevTools display an :ref:`element {} rule <page_inspector_how_to_examine_and_edit_css_element_rule>` for this purpose, which requires a single click into it to start editing the properties. + + +Auto-completion of CSS +---------------------- + +As in Firebug, the Rules view provides an auto-completion for the CSS property names and their values. A few property values are not auto-completed yet, which is tracked in `bug 1337918 <https://bugzilla.mozilla.org/show_bug.cgi?id=1337918>`_. + + +Copy & paste CSS +---------------- + +Firebug's Style side panel as well as the DevTools' Rules side panel provide options within their context menus to copy the CSS rule or the style declarations. The DevTools additionally provide an option to copy the selector of a rule and copy disabled property declarations as commented out. They are missing the option to copy the whole style declaration, though this can be achieved by selecting them within the panel and copying the selection by pressing :kbd:`Ctrl` + :kbd:`C` or via the context menu. + +The Rules side panel of the DevTools is smarter when it comes to pasting CSS into it. You can paste whole style declarations into an existing rule property declarations which are commented out are automatically disabled. + + +Toggle pseudo-classes +--------------------- + +Firebug lets you toggle the CSS `pseudo-classes <https://developer.mozilla.org/en-US/docs/Web/CSS/Pseudo-classes>`_ `:hover <https://developer.mozilla.org/en-US/docs/Web/CSS/:hover>`_, `:active <https://developer.mozilla.org/en-US/docs/Web/CSS/:active>`_ and `:focus <https://developer.mozilla.org/en-US/docs/Web/CSS/:focus>`_ for an element via the options menu of the Style side panel. In the DevTools there are two ways to do the same. The first one is to toggle them via the pseudo-class panel within the Rules side panel. The second one is to right-click and element within the node view and toggle the pseudo-classes via the :ref:`context menu <page_inspector_how_to_examine_and_edit_html_context_menu_reference>`. + + +Examine CSS shorthand properties +-------------------------------- + +CSS `shorthand properties <https://developer.mozilla.org/en-US/docs/Web/CSS/Shorthand_properties>`_ can be split into their related longhand properties by setting the option *Expand Shorthand Properties* within the Style side panel. The DevTools' Rules panel is a bit smarter and allows you to expand individual shorthand properties by clicking the twisty besides them. + + +Only show applied styles +------------------------ + +The Style side panel in Firebug has an option to display only the properties of a CSS rule that are applied to the selected element and hide all overwritten styles. There is no such feature in the :doc:`Rules side panel <../page_inspector/how_to/examine_and_edit_css/index>` of the DevTools, but it is requested in `bug 1335327 <https://bugzilla.mozilla.org/show_bug.cgi?id=1335327>`_. + + +Inspect box model +----------------- + +In Firebug the `box model <https://developer.mozilla.org/en-US/docs/Learn/CSS/Building_blocks/The_box_model>`_ can be inspected via the Layout side panel. In the DevTools the :doc:`box model is part of the Computed side panel <../page_inspector/how_to/examine_and_edit_the_box_model/index>`. Both tools highlight the different parts of the box model within the page when hovering them in the box model view. Also, both tools allow you to edit the different values inline via a click on them. + + +Inspect computed styles +----------------------- + +The computed values of CSS properties are displayed within the DevTools' :ref:`Computed side panel <page_inspector_how_to_examine_and_edit_css_examine_computed_css>` like within Firebug's Computed side panel. The difference is that in the DevTools the properties are always listed alphabetically and not grouped (see `bug 977128 <https://bugzilla.mozilla.org/show_bug.cgi?id=977128>`_) and there is no option to hide the Mozilla specific styles, therefore there is an input field allowing to filter the properties. + + +Inspect events +-------------- + +Events assigned to an element are displayed in the Events side panel in Firebug. In the DevTools they are shown when clicking the small 'ev' icon besides an element within the node view. Both tools allow to display wrapped event listeners (e.g. listeners wrapped in jQuery functions). To improve the UI of the DevTools, there is also a request to add an Events side panel to them like the one in Firebug (see `bug 1226640 <https://bugzilla.mozilla.org/show_bug.cgi?id=1226640>`_). + + +Stop script execution on DOM mutation +------------------------------------- + +In Firebug you can break on DOM mutations, that means that when an element is changed, the script execution is stopped at the related line within the JavaScript file, which caused the change. This feature can globally be enabled via the *Break On Mutate* button, or individually for each element and for different types of changes like attribute changes, content changes or element removal. Unfortunately, the DevTools do not have this feature yet (see `bug 1004678 <https://bugzilla.mozilla.org/show_bug.cgi?id=1004678>`_). To stop the script execution there, you need to set a breakpoint on the line with the modification within the :doc:`Debugger panel <../debugger/index>`. + + +Search for elements via CSS selectors or XPaths +----------------------------------------------- + +Firebug allows to search for elements within the HTML panel via CSS selectors or XPaths. Also the :ref:`DevTools' Inspector panel allows to search for CSS selectors <page_inspector_how_to_examine_and_edit_html_searching>`. It even displays a list with matching IDs or classes. Searching by XPaths is not supported though (see `bug 963933 <https://bugzilla.mozilla.org/show_bug.cgi?id=963933>`_). + + +Debugger +******** + +What's the Script panel in Firebug, is the :doc:`Debugger panel <../debugger/index>` in the DevTools. Both allow you to debug JavaScript code executed on a website. + + +Switch between sources +---------------------- + +Firebug has a Script Location Menu listing all JavaScript sources related to the website. Those sources can be static, i.e. files, or they can be dynamically generated (i.e. scripts executed via event handlers, ``eval()``, ``new Function()``, etc.). In the DevTools' Debugger panel the scripts are listed at the left side within the :ref:`Sources side panel <debugger-ui-tour-source-list-pane>`. Dynamically generated scripts are only listed there when they are :doc:`named via a //# sourceURL comment <../debugger/how_to/debug_eval_sources/index>`. + + +Managing breakpoints +-------------------- + +In Firebug you can set different types of breakpoints, which are all listed within the Breakpoints side panel. In the DevTools the breakpoints are shown below each script source within the :ref:`Sources side panel <debugger-ui-tour-source-list-pane>`. Those panels allow you to enable and disable single or all breakpoints and to remove single breakpoints or all of them at once. They do currently only allow to set script breakpoints. XHR, DOM, Cookie and Error breakpoints are not supported yet (see `bug 821610 <https://bugzilla.mozilla.org/show_bug.cgi?id=821610>`_, `bug 1004678 <https://bugzilla.mozilla.org/show_bug.cgi?id=1004678>`_, `bug 895893 <https://bugzilla.mozilla.org/show_bug.cgi?id=895893>`_ and `bug 1165010 <https://bugzilla.mozilla.org/show_bug.cgi?id=1165010>`_). While there are no breakpoints for single JavaScript errors, there is a setting *Pause on Exceptions* within the :ref:`Debugger panel options <settings-debugger>`. + + +Step through code +----------------- + +Once the script execution is stopped, you can step through the code using the Continue (:kbd:`F8`), Step Over (:kbd:`F10`), Step Into (:kbd:`F11`) and Step Out (:kbd:`Shift` + :kbd:`F11`) options. They work the same in both tools. + + +Examine call stack +------------------ + +When the script execution is paused, Firebug displays the function call stack within its Stack side panel. In there the functions are listed together with their call parameters. In the DevTools the function call stack is shown within the :ref:`Call Stack side panel <debugger-ui-tour-call-stack>`. To see the call parameters in the DevTools, you need to have a look at the :doc:`Variables side panel <../debugger/how_to/set_watch_expressions/index>`. + + +Examine variables +----------------- + +The Watch side panel in Firebug displays the `window <https://developer.mozilla.org/en-US/docs/Web/API/Window>`_ object (the global scope) by default. With the script execution halted it shows the different variable scopes available within the current call stack frame. Furthermore, it allows you to add and manipulate watch expressions. The DevTools have a :doc:`Variables side panel <../debugger/how_to/set_watch_expressions/index>`, which works basically the same. The main difference is that it is empty when the script execution is not stopped, i.e. it doesn't display the ``window`` object. Though you can inspect that object either via the :doc:`DOM property viewer <../dom_property_viewer/index>` or via the :doc:`Web Console <../web_console/index>`. + + +Style Editor +************ + +The :doc:`Style Editor <../style_editor/index>` in the Firefox DevTools allows you to examine and edit the different CSS style sheets of a page like Firebug's CSS panel does it. In addition to that it allows to create new style sheets and to import existing style sheets and apply them to the page. It also allows you to toggle individual style sheets. + + +Switch between sources +---------------------- + +The CSS panel of Firebug allows to switch between different CSS sources using the CSS Location Menu. The Style Editor has a :ref:`sidebar <style-editor-the-style-sheet-pane>` for this purpose. + + +Edit a style sheet +------------------ + +Firebug's CSS panel offers three different ways for editing style sheets. The default one is to edit them inline like within the Style side panel. Furthermore it has a Source and a Live Edit mode, which allow to edit the selected style sheet like within a text editor. The Style Editor of the DevTools only has one way to edit style sheets, which corresponds to Firebug's Live Edit mode. + + +Try out CSS selectors +--------------------- + +Firebug's Selectors side panel provides a way to validate a CSS selector. It lists all elements matching the entered selector. The DevTools don't have this feature yet, but it's requested in `bug 1323746 <https://bugzilla.mozilla.org/show_bug.cgi?id=1323746>`_. + + +Searching within the style sheets +--------------------------------- + +Firebug allows to search within the style sheets via the search field. The Style Editor in the DevTools also provides a way to search within a style sheet, though there is currently no option to search within multiple sheets (see `bug 889571 <https://bugzilla.mozilla.org/show_bug.cgi?id=889571>`_ and also not via a regular expression (see `bug 1362030 <https://bugzilla.mozilla.org/show_bug.cgi?id=1362030>`_). + + +Performance Tool +**************** + +Firebug allows to profile JavaScript performance via the "Profile" button within the Console panel or the ``console.profile()`` and ``console.profileEnd()`` commands. The DevTools provide advanced tooling regarding performance profiling. A profile can be created via `console.profile() <https://developer.mozilla.org/en-US/docs/Web/API/console/profile>`_ and `console.profileEnd() <https://developer.mozilla.org/en-US/docs/Web/API/console/profileEnd>`_ like in Firebug or via the "Start Recording Performance" button in the :doc:`Performance Tool <../performance/index>`. The output of the :doc:`Call Tree <../performance/call_tree/index>` is the one that comes nearest to the output in Firebug, but the Performance panel provides much more information than just the JavaScript performance. E.g. it also provides information about HTML parsing or layout. + +This is the part where Firebug and the DevTools differ the most, because the outputs are completely different. While Firebug focuses on JavaScript performance and provides detailed information about JavaScript function calls during the profiling session, the Performance Tool in the DevTools offers a broad spectrum of information regarding a website's performance but doesn't go into detail regarding JavaScript function calls. + + +View JavaScript call performance +-------------------------------- + +What comes nearest to Firebug's profiler output is the :doc:`Call Tree view <../performance/index>` in the Performance panel. Like in Firebug it lists the total execution time of each function call under *Total Time* as well as the number of calls under *Samples*, the time spent within the function under *Self Time* and the related percentages in reference to the total execution time. + + +.. note:: + + The times and percentages listed in the DevTools' Call Tree view is not equivalent to the ones shown in Firebug, because it uses different APIs sampling the execution of the JavaScript code. + + +Jump to function declaration +---------------------------- + +Like in Firebug's profiler output the :doc:`Call Tree view <../performance/call_tree/index>` of the DevTools' Performance Tool allows to jump to the line of code where the called JavaScript function is defined. In Firebug the source link to the function is located at the right side of the Console panel output while within the DevTools the link is placed on the right side within the Call Tree View. + + +Network Monitor +*************** + +To monitor network requests Firebug provides a Net panel. The Firefox DevTools allow to inspect the network traffic using the :doc:`Network Monitor <../network_monitor/index>`. Both tools provide similar information including a timeline showing the request and response times of the network requests. + + +Inspect request information +--------------------------- + +Both Firebug and the Firefox DevTools' Network Monitor allow you to inspect the information about a request by clicking on it. The only difference is that Firebug shows the information below the request while the Network Monitor displays it within a side panel. + +In both tools there are different tabs containing different kinds of information for the selected request. They contain a *Headers*, *Params*, *Response* and *Cookies* panel. A preview of the response is shown within specifically named panels like *HTML*. The Network Monitor has a *Preview* panel for this purpose. It doesn't provide information about the cached data yet (see `bug 859051 <https://bugzilla.mozilla.org/show_bug.cgi?id=859051>`_), but provides a *Security* tab in addition to Firebug's information and a *Timings* tab showing detailed information about the network timings. + + +View request timings +-------------------- + +Firebug offers detailed information about the network timings related to a request by hovering the Timeline column within its Net panel. The Network Monitor shows this information within a :ref:`Timings side panel <network-monitor-request-details-timings-tab>` when you select a request. + + +View remote address +------------------- + +The remote address of a request is shown within the Remote IP column within Firebug. In the Network Monitor the address is shown at *Remote Address* in the *Headers* tab when a request is selected. + + +Search within requests +---------------------- + +The search field within Firebug allows to search within the requests. The search field in the Firefox DevTools filters the requests by the entered string. + +Firebug allowed to search within the response body of the network requests by checking *Response Bodies* within its search field options. This feature is not available yet within the Network Monitor, but it's requested in `bug 1334408 <https://bugzilla.mozilla.org/show_bug.cgi?id=1334408>`_. While response bodies can't be searched yet, the Network Monitor allows to :ref:`filter by different request properties <request-list-filtering-by-properties>`. + + +Storage Inspector +***************** + +The Cookies panel in Firebug displays information related to the cookies created by a page and allows to manipulate the information they store. Within the DevTools this functionality is located within the :doc:`Storage Inspector <../storage_inspector/index>`. In contrast to Firebug the Storage Inspector not only allows to inspect cookies but also other kinds of storages like the local and session storage, the cache and `IndexedDB <https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API>`_ databases. + + +Inspect cookies +--------------- + +All cookies related to a website are listed inside the Cookies panel in Firebug. Inside the DevTools, the cookies are grouped by domain under the Cookies section within the :doc:`Storage Inspector <../storage_inspector/index>`. Both show pretty much the same information per cookie, i.e. the name, value, domain, path, expiration date and whether the cookie is HTTP-only. + +The DevTools don't show by default whether a cookie is secure, but this can be enabled by right-clicking the table header and checking *Secure* from the context menu. Additionally, the DevTools allow to display the creation date of a cookie as well as when it was last accessed and whether it is host-only. + + +Edit cookies +------------ + +To edit a cookie in Firebug you have to right-click the cookie and choose *Edit* from the context menu. Then a dialog pops up allowing you to edit the data of the cookie and save it. Inside the Storage Inspector you just have to double-click the data you want to edit. Then an inline editor allows you to edit the value. + +Delete cookies +-------------- + +Firebug's Cookies panel allows you to delete all cookies of a website via the menu option *Cookies* > *Remove Cookies* or by pressing :kbd:`Ctrl` + :kbd:`Shift` + :kbd:`O`. It also allows you to only remove session cookies via *Cookies* > *Remove Session Cookies* and to remove single cookies by right-clicking them and choosing *Delete*. The DevTools Storage Inspector allows to remove all cookies and a single one by right-clicking on a cookie and choosing *Delete All* resp. *Delete "<cookie name>"*. Additionally, it allows to delete all cookies from a specific domain via the context menu option *Delete All From "<domain name>"*. It currently does not allow to only delete session cookies (see `bug 1336934 <https://bugzilla.mozilla.org/show_bug.cgi?id=1336934>`_). + + +Feedback +******** + +We are always happy to respond to feedback and questions. If you have any queries or points of view, feel free to share them on our `DevTools Discourse Forum <https://discourse.mozilla.org/c/devtools>`_. diff --git a/devtools/docs/user/migrating_from_firebug/logo-developer-quantum.png b/devtools/docs/user/migrating_from_firebug/logo-developer-quantum.png Binary files differnew file mode 100644 index 0000000000..778bc9e2d3 --- /dev/null +++ b/devtools/docs/user/migrating_from_firebug/logo-developer-quantum.png diff --git a/devtools/docs/user/network_monitor/hamburger.png b/devtools/docs/user/network_monitor/hamburger.png Binary files differnew file mode 100644 index 0000000000..0a86806250 --- /dev/null +++ b/devtools/docs/user/network_monitor/hamburger.png diff --git a/devtools/docs/user/network_monitor/index.rst b/devtools/docs/user/network_monitor/index.rst new file mode 100644 index 0000000000..4de8266d67 --- /dev/null +++ b/devtools/docs/user/network_monitor/index.rst @@ -0,0 +1,62 @@ +=============== +Network Monitor +=============== + +The Network Monitor shows you all the HTTP requests Firefox makes (for example, when it loads a page, or due to `XMLHttpRequests <https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest>`_), how long each request takes, and details of each request. + +Opening the Network Monitor +*************************** + +There are a few different ways to open the Network Monitor: + +- Press :kbd:`Ctrl` + :kbd:`Shift` + :kbd:`E` (:kbd:`Cmd` + :kbd:`Opt` + :kbd:`E` on a Mac). + +- Select the *Network* panel in the Web Developer Tools, accessible from the Browser Tools submenu + +- Click the wrench icon |image1|, which is in the main toolbar or under the Hamburger menu |image2|, then select "Network". + +.. |image1| image:: wrench-icon.png + :width: 20 + +.. |image2| image:: hamburger.png + :width: 20 + +The Network Monitor will appear at the bottom of the browser window. When it first opens, the Network Monitor does not show request information. The just opened tool looks like this: + +.. image:: network_monitor_new.png + :class: border + +Either action causes the Network Monitor to begin monitoring network activity. Once the tool is monitoring network requests, the display looks like this: + +.. image:: network_monitor.png + :class: border + +When it is actively monitoring activity, the Network Monitor records network requests any time the Toolbox is open, even if the Network Monitor itself is not selected. This means you can start debugging a page in, for example, the Web Console, then switch to the Network Monitor to see network activity without having to reload the page. + +UI overview +*********** + +The UI is divided into four main pieces: + +- The main screen contains the :doc:`toolbar <toolbar/index>`, the :doc:`network request list <request_list/index>`, and the :doc:`network request details pane <request_details/index>`: + +.. image:: network_monitor_closeup.png + :class: border + +- The :doc:`performance analysis <peformance_analysis/index>` view is a separate screen: + +.. image:: network_performance.png + :class: border + +Working with the network monitor +******************************** + +The following articles cover different aspects of using the network monitor: + +- :doc:`Toolbar <toolbar/index>` +- :doc:`Network request list <request_list/index>` +- :doc:`Network request details <request_details/index>` +- :doc:`Network traffic recording <performance_analysis/index>` +- :doc:`Throttling <throttling/index>` +- :doc:`Inspecting web sockets <inspecting_web_sockets/index>` +- :doc:`Inspecting server-sent events <inspecting_server-sent_events/index>` diff --git a/devtools/docs/user/network_monitor/inspecting_server-sent_events/basic-sse-message-view.png b/devtools/docs/user/network_monitor/inspecting_server-sent_events/basic-sse-message-view.png Binary files differnew file mode 100644 index 0000000000..98b7d5c8e7 --- /dev/null +++ b/devtools/docs/user/network_monitor/inspecting_server-sent_events/basic-sse-message-view.png diff --git a/devtools/docs/user/network_monitor/inspecting_server-sent_events/customize-columns.png b/devtools/docs/user/network_monitor/inspecting_server-sent_events/customize-columns.png Binary files differnew file mode 100644 index 0000000000..e856d2a929 --- /dev/null +++ b/devtools/docs/user/network_monitor/inspecting_server-sent_events/customize-columns.png diff --git a/devtools/docs/user/network_monitor/inspecting_server-sent_events/index.rst b/devtools/docs/user/network_monitor/inspecting_server-sent_events/index.rst new file mode 100644 index 0000000000..a75666e618 --- /dev/null +++ b/devtools/docs/user/network_monitor/inspecting_server-sent_events/index.rst @@ -0,0 +1,63 @@ +============================= +Inspecting server-sent events +============================= + +`Server-sent events <https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events>`_ allow for an inversion of the traditional client-initiated web request model, with a server sending new data to a web page at any time by pushing messages. From Firefox 82 onwards, you can inspect server-sent events and their message contents using the :doc:`Network Monitor <../index>`. This article shows you how. + +Inspecting the SSE network activity +*********************************** + +When you are viewing a document that is receiving server-sent events, you can go to the Network Monitor, select the file that is sending the server-sent events, and view the received messages in the *Response* tab on the right-hand panel. + +.. image:: basic-sse-message-view.png + :class: border + + +At the top of the panel there is a trash can icon, which allows you to trash the messages sent so far, and a filter field in which you can enter a text string to filter the displayed messages by. + + +Viewing the message contents +**************************** + +Select one of the messages listed in the *Response* tab, and you'll see the message contents displayed at the bottom of that same tab. + +.. image:: see-message-detail-view.png + :class: border + +In the above example, you can see that JSON and raw data representations of the content are shown. For a plain text message, you'd just see a raw data section. + +The supported data formats are as follows: + +- Mercure protocol +- JSON + + +Customizing the displayed columns +********************************* + +For each message, you'll see *Data* and Time columns by default, but you can right-click on the table header to bring up a context menu in which you can toggle columns on and off, and reset it back to its original state. + +.. image:: customize-columns.png + :class: border + +The available columns are as follows: + +- *Data*: A summary of the contained message data. +- *Size*: The size of the message. +- *Time*: A timestamp representing when the message was sent. +- *Event Name*: The name of the event type that resulted in the message being sent (e.g. ```message``` or ```ping```). +- *Last Event ID*: The ID of the last event that was fired. +- *Retry*: The interval after which failed message will be resent. + + +Network Monitor features +************************ + +The following articles cover different aspects of using the network monitor: + +- :doc:`Toolbar <../toolbar/index>` +- :doc:`Network request list <../request_list/index>` +- :doc:`Network request details <../request_details/index>` +- :doc:`Network traffic recording <../performance_analysis/index>` +- :doc:`Throttling <../throttling/index>` +- :doc:`Inspecting web sockets <../inspecting_web_sockets/index>` diff --git a/devtools/docs/user/network_monitor/inspecting_server-sent_events/see-message-detail-view.png b/devtools/docs/user/network_monitor/inspecting_server-sent_events/see-message-detail-view.png Binary files differnew file mode 100644 index 0000000000..b6dcce5c15 --- /dev/null +++ b/devtools/docs/user/network_monitor/inspecting_server-sent_events/see-message-detail-view.png diff --git a/devtools/docs/user/network_monitor/inspecting_web_sockets/index.rst b/devtools/docs/user/network_monitor/inspecting_web_sockets/index.rst new file mode 100644 index 0000000000..f69edfa770 --- /dev/null +++ b/devtools/docs/user/network_monitor/inspecting_web_sockets/index.rst @@ -0,0 +1,121 @@ +====================== +Inspecting web sockets +====================== + +Since Firefox 71, the :doc:`Network Monitor <../index>` has had the ability to inspect `web socket <https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API>`_ connections. This article explores what functionality the Web Socket Inspector makes available. + +Accessing the inspector +*********************** + +When you are inspecting a web app that utilizes a web socket connection, the web socket requests are listed in the list of requests in the Network Monitor along with all other requests. + +.. image:: wsi-filiter.png + :alt: WS filter in the network inspector + +You can use the WS button to filter the list for just web socket connections. Only requests with the `101 status code <https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/101>`_ (WebSocket Protocol Handshake) are visible, which indicates that the server is switching to a web socket connection. + +Clicking on a web socket request opens the usual sidebar to reveal additional details. Choose the **Response** tab to inspect web socket frames sent and received through the selected connection. + +.. image:: new-web-sockets.png + :alt: Messages panel in the web socket inspector + :class: border + +The live-updated table shows data for sent (green arrow) and received (red arrow) frames. Each frame expands on click, so you can inspect the formatted data. + +Pausing web socket traffic +************************** + +You can use the pause/resume button in the Network Monitor toolbar to stop intercepting web socket traffic. This allows you to capture only the frames that you are interested in. + +.. image:: ws-pause.png + :alt: Pausing the web socket inspector + +Filtering web socket frames +*************************** + +To focus on specific messages, frames can be filtered using the filter at the top of the *Response* panel. + +.. image:: ws_response_text_filter.png + :class: border + :alt: web socket frame filter + +There are also predefined filters, available in the tool bar of the Response pane, grouped into a selection list. + +.. image:: ws_filter_menu.png + :alt: Screenshot showing the filter menu for WebSocket messages + +The following filters are available: + +.. list-table:: + :widths: 20 80 + :header-rows: 0 + + * - **All** + - Displays all messages (by default, except control messages). + + * - **Sent** + - Displays only messages sent by the browser (by default, except control messages). + + * - **Received`** + - Displays only messages received from the server (by default, except control messages). + + * - **Control** + - (Available starting in Firefox 76). Displays messages for control frames (Ping, Pong, or Close). This filter can be combined with the others, to display, for example, only messages for control frames sent by the browser. + +Columns in the Response pane +**************************** + +In the **Response** pane, you can choose to show the following information about each frame: + +- Data +- Size +- Time +- OpCode +- MaskBit +- FinBit + +The *Data* and *Time* columns are visible by default, but you can customize the interface to see more columns by choosing which ones to show from the context menu that is opened by right-clicking in the table header. + + +.. image:: ws_message_columns.png + :class: border + :alt: columns in the messages panel + + +Expanding each message +********************** + +Selecting a message in the list shows a preview of the data being sent in that message, at the bottom of the Response pane. + +.. image:: ws_expand_message.png + :class: border + :alt: web socket payload preview + + +Supported WS protocols +********************** + +The inspector currently supports the following web socket protocols: + +- Plain JSON +- Socket.IO +- SockJS +- SignalR +- WAMP +- STOMP +- STOMP inside SockJS + +The payload based on those protocols is parsed and displayed as an expandable tree for easy inspection, although you can of course still see the raw data (as sent over the wire) as well. + +Network Monitor features +************************ + +The following articles cover different aspects of using the network monitor: + +- :doc:`Toolbar <../toolbar/index>` +- :doc:`Network request list <../request_list/index>` +- :doc:`Network request details <../request_details/index>` +- :doc:`Network traffic recording <../performance_analysis/index>` +- :doc:`Throttling <../throttling/index>` +- :doc:`Inspecting web sockets <../inspecting_web_sockets/index>` +- :doc:`Inspecting server-sent events <../inspecting_server-sent_events/index>` diff --git a/devtools/docs/user/network_monitor/inspecting_web_sockets/new-web-sockets.png b/devtools/docs/user/network_monitor/inspecting_web_sockets/new-web-sockets.png Binary files differnew file mode 100644 index 0000000000..1d9c8f3450 --- /dev/null +++ b/devtools/docs/user/network_monitor/inspecting_web_sockets/new-web-sockets.png diff --git a/devtools/docs/user/network_monitor/inspecting_web_sockets/ws-pause.png b/devtools/docs/user/network_monitor/inspecting_web_sockets/ws-pause.png Binary files differnew file mode 100644 index 0000000000..606c40ebcd --- /dev/null +++ b/devtools/docs/user/network_monitor/inspecting_web_sockets/ws-pause.png diff --git a/devtools/docs/user/network_monitor/inspecting_web_sockets/ws_expand_message.png b/devtools/docs/user/network_monitor/inspecting_web_sockets/ws_expand_message.png Binary files differnew file mode 100644 index 0000000000..d7dbc3f0b3 --- /dev/null +++ b/devtools/docs/user/network_monitor/inspecting_web_sockets/ws_expand_message.png diff --git a/devtools/docs/user/network_monitor/inspecting_web_sockets/ws_filter_menu.png b/devtools/docs/user/network_monitor/inspecting_web_sockets/ws_filter_menu.png Binary files differnew file mode 100644 index 0000000000..8d284f29db --- /dev/null +++ b/devtools/docs/user/network_monitor/inspecting_web_sockets/ws_filter_menu.png diff --git a/devtools/docs/user/network_monitor/inspecting_web_sockets/ws_message_columns.png b/devtools/docs/user/network_monitor/inspecting_web_sockets/ws_message_columns.png Binary files differnew file mode 100644 index 0000000000..93972466a6 --- /dev/null +++ b/devtools/docs/user/network_monitor/inspecting_web_sockets/ws_message_columns.png diff --git a/devtools/docs/user/network_monitor/inspecting_web_sockets/ws_response_text_filter.png b/devtools/docs/user/network_monitor/inspecting_web_sockets/ws_response_text_filter.png Binary files differnew file mode 100644 index 0000000000..f82692f22c --- /dev/null +++ b/devtools/docs/user/network_monitor/inspecting_web_sockets/ws_response_text_filter.png diff --git a/devtools/docs/user/network_monitor/inspecting_web_sockets/wsi-filiter.png b/devtools/docs/user/network_monitor/inspecting_web_sockets/wsi-filiter.png Binary files differnew file mode 100644 index 0000000000..bef54d39ca --- /dev/null +++ b/devtools/docs/user/network_monitor/inspecting_web_sockets/wsi-filiter.png diff --git a/devtools/docs/user/network_monitor/network_monitor.png b/devtools/docs/user/network_monitor/network_monitor.png Binary files differnew file mode 100644 index 0000000000..000bd945f9 --- /dev/null +++ b/devtools/docs/user/network_monitor/network_monitor.png diff --git a/devtools/docs/user/network_monitor/network_monitor_closeup.png b/devtools/docs/user/network_monitor/network_monitor_closeup.png Binary files differnew file mode 100644 index 0000000000..7037eb090a --- /dev/null +++ b/devtools/docs/user/network_monitor/network_monitor_closeup.png diff --git a/devtools/docs/user/network_monitor/network_monitor_new.png b/devtools/docs/user/network_monitor/network_monitor_new.png Binary files differnew file mode 100644 index 0000000000..24fba42a12 --- /dev/null +++ b/devtools/docs/user/network_monitor/network_monitor_new.png diff --git a/devtools/docs/user/network_monitor/network_performance.png b/devtools/docs/user/network_monitor/network_performance.png Binary files differnew file mode 100644 index 0000000000..44453cac8c --- /dev/null +++ b/devtools/docs/user/network_monitor/network_performance.png diff --git a/devtools/docs/user/network_monitor/performance_analysis/index.rst b/devtools/docs/user/network_monitor/performance_analysis/index.rst new file mode 100644 index 0000000000..f6eeacfc24 --- /dev/null +++ b/devtools/docs/user/network_monitor/performance_analysis/index.rst @@ -0,0 +1,35 @@ +==================== +Performance Analysis +==================== + +The Network Monitor includes a performance analysis tool, to help show you how long the browser takes to download the different parts of your site. + +Using the Performance analysis tool +*********************************** + +To run the performance analysis tool click the stopwatch icon in the :doc:`Toolbar <../toolbar/index>` + +(Alternatively, if you have only just opened the Network Monitor, so it's not yet populated with the list of requests, you'll get a stopwatch icon in the main window.) + +The Network Monitor then loads the site twice: once with an empty browser cache, and once with a primed browser cache. This simulates the first time a user visits your site, and subsequent visits. It displays the results for each run side by side, or vertically if the browser window is narrow: + +.. image:: network_performance.png + :class: border + +The results for each run are summarized in a table and a pie chart. The tables group resources by type, and show the total size of each resource and the total time it took to load them. The accompanying pie chart shows the relative size of each resource type. + +To get back to the Network Monitor's list of network requests click the "Back" button on the left. + +Clicking on a slice of the pie takes you to the Network Monitor for that run, with a filter automatically applied to see :ref:`only that resource type <request-list-filtering-requests>`. + +Network Monitor Features +************************ + +The following articles cover different aspects of using the network monitor: + +- :doc:`Toolbar <../toolbar/index>` +- :doc:`Network request list <../request_list/index>` +- :doc:`Network request details <../request_details/index>` +- :doc:`Network traffic recording <../recording/index/>` +- :doc:`Network traffic recording <../recording/index/>` +- :doc:`Throttling <../throttling/index>` diff --git a/devtools/docs/user/network_monitor/performance_analysis/network_performance.png b/devtools/docs/user/network_monitor/performance_analysis/network_performance.png Binary files differnew file mode 100644 index 0000000000..44453cac8c --- /dev/null +++ b/devtools/docs/user/network_monitor/performance_analysis/network_performance.png diff --git a/devtools/docs/user/network_monitor/recording/index.rst b/devtools/docs/user/network_monitor/recording/index.rst new file mode 100644 index 0000000000..379ac43f42 --- /dev/null +++ b/devtools/docs/user/network_monitor/recording/index.rst @@ -0,0 +1,34 @@ +========================= +Network monitor recording +========================= + +You can pause and resume the monitoring of network traffic using the pause button. + +Pausing and resume network traffic recording +******************************************** + +The Network Monitor has a button that pauses and resumes recording of the current page's network traffic. This is useful in situations where, for example, you are trying to get a stable view of a page for debugging purposes, but under normal circumstances the view keeps evolving due to persistent network requests. The pause button allows you to look at a certain snapshot. + +The button can be found at the far left of the main Network Monitor toolbar, and looks like a typical pause button — |image1|. + +.. |image1| image:: pause-icon.png + :width: 20 + +You can see it here in context: + +.. image:: play-pause-network-traffic.png + :class: border + +Once pressed, the button changes to a play icon, and you can toggle network traffic recording back on by pressing it again. + +Network Monitor features +************************ + +The following articles cover different aspects of using the network monitor: + +- :doc:`Toolbar <../toolbar/index>` +- :doc:`Network request list <../request_list/index>` +- :doc:`Network request details <../request_details/index>` +- :doc:`Network traffic recording <../recording/index/>` +- :doc:`Performance analysis <../performance_analysis/index>` +- :doc:`Throttling <../throttling/index>` diff --git a/devtools/docs/user/network_monitor/recording/pause-icon.png b/devtools/docs/user/network_monitor/recording/pause-icon.png Binary files differnew file mode 100644 index 0000000000..d8aa4d5c77 --- /dev/null +++ b/devtools/docs/user/network_monitor/recording/pause-icon.png diff --git a/devtools/docs/user/network_monitor/recording/play-pause-network-traffic.png b/devtools/docs/user/network_monitor/recording/play-pause-network-traffic.png Binary files differnew file mode 100644 index 0000000000..fa36656e2f --- /dev/null +++ b/devtools/docs/user/network_monitor/recording/play-pause-network-traffic.png diff --git a/devtools/docs/user/network_monitor/request_details/copy-response-headers-fx78.png b/devtools/docs/user/network_monitor/request_details/copy-response-headers-fx78.png Binary files differnew file mode 100644 index 0000000000..8a43bce10a --- /dev/null +++ b/devtools/docs/user/network_monitor/request_details/copy-response-headers-fx78.png diff --git a/devtools/docs/user/network_monitor/request_details/highlight-samesite-attribute.png b/devtools/docs/user/network_monitor/request_details/highlight-samesite-attribute.png Binary files differnew file mode 100644 index 0000000000..244ffabfa0 --- /dev/null +++ b/devtools/docs/user/network_monitor/request_details/highlight-samesite-attribute.png diff --git a/devtools/docs/user/network_monitor/request_details/html_formatted_response.png b/devtools/docs/user/network_monitor/request_details/html_formatted_response.png Binary files differnew file mode 100644 index 0000000000..b40149f02b --- /dev/null +++ b/devtools/docs/user/network_monitor/request_details/html_formatted_response.png diff --git a/devtools/docs/user/network_monitor/request_details/html_raw_response.png b/devtools/docs/user/network_monitor/request_details/html_raw_response.png Binary files differnew file mode 100644 index 0000000000..7f9b399b31 --- /dev/null +++ b/devtools/docs/user/network_monitor/request_details/html_raw_response.png diff --git a/devtools/docs/user/network_monitor/request_details/index.rst b/devtools/docs/user/network_monitor/request_details/index.rst new file mode 100644 index 0000000000..8cda537466 --- /dev/null +++ b/devtools/docs/user/network_monitor/request_details/index.rst @@ -0,0 +1,526 @@ +======================= +Network request details +======================= + +The request details pane appears when you click on a network request in the request list. This pane provides more detailed information about the request. + +Network request details +*********************** + +Clicking on a row displays a new pane in the right-hand side of the network monitor, which provides more detailed information about the request. + +.. image:: network-details-fx78.png + :alt: Screenshot of the Network Request details pane, without callouts for the close-pane button and the detail tabs + :class: center + +.. note:: + + The screenshots and descriptions in this section reflect Firefox 78. Earlier versions appeared similarly, but might not include some functionality. + + +The tabs at the top of this pane enable you to switch between the following pages: + +- :ref:`Headers <network-monitor-request-details-headers-tab>` +- **Messages** (only for WebSocket items) +- :ref:`Request <network-monitor-request-details-request-tab>` +- :ref:`Response <network-monitor-request-details-response-tab>` +- :ref:`Cache <network-monitor-request-details-cache-tab>` +- :ref:`Timings <network-monitor-request-details-timings-tab>` +- :ref:`Security <network-monitor-request-details-security-tab>` +- :ref:`Stack trace <network-monitor-request-details-stack-trace-tab>` (only when the request has a stack trace, e.g. a script called by another script). + + +Clicking the icon at the right-hand end of the :doc:`toolbar <../toolbar/index>` closes the details pane and returns you to the list view. + + +.. _network-monitor-request-details-headers-tab: + +Headers tab +----------- + +The Headers tab has a toolbar, followed by three main sections. + +This includes: + + +- Information about the request + + - Status: The response status code for the request; click the "?" icon to go to the reference page for the status code. + - Version: The version of HTTP used. + - Transferred: The amount of data transferred for the request. + - Referrer policy: The value of the `Referrer-policy header <https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referrer-Policy>`_. + +- **HTTP Response headers** +- **HTTP Request headers** + +Each section has a disclosure triangle to expand the section to show more information. + + +Headers toolbar +~~~~~~~~~~~~~~~ + +Using the Headers toolbar, you can: + + +- Filter the headers in the Response Headers and Request Headers sections. +- **Block** the domain involved in this request. The domain is added to the :ref:`Blocking sidebar <network_monitor_blocking_specific_urls>`. +- Resend the request. The **Resend** button opens a menu with two items: + + - **Resend**: Resends the request. + - **Edit and Resend**: Enables an editing mode, where you can modify the method, URL, request headers, or request body of the request. Click **Send** to send the modified request, or **Cancel** to cancel editing. + + +Request Information +~~~~~~~~~~~~~~~~~~~ + +The following information is shown only when the section is expanded: + +- **Scheme**: The scheme used in the URL +- **Host**: The server involved in the request +- **Filename**: The full path to the file requested +- **Address**: The IP address of the host + +The following information is shown in both the collapsed and the expanded states: + + +- **Status:** The `HTTP response code <https://developer.mozilla.org/en-US/docs/Web/HTTP/Status>`_ for the request. +- **Version**: The HTTP version used +- **Transferred**: The amount of data transferred with the request +- The **Referrer Policy**, which governs which referrer information, sent in the `Referer <https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referer>`_ header, should be included with requests. (See `Referrer-Policy <https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referrer-Policy>`_ for a description of possible values) +- **Blocking**: If the request is to a site that is associated with a known tracker, an icon and a message are shown; otherwise, this field is not shown. + + +Response headers +~~~~~~~~~~~~~~~~ + +The response headers section shows details about the response. For each line in the response headers section, a question mark links to the documentation for that response header, if one is available. + +A **Raw** toggle button in the section heading controls whether the headers are shown with formatting, or as plain, unformatted text. + +.. note:: + Note that the keys in the response header are all in lowercase, while the request headers keys are not. `HTTP/2 requires that all headers be lowercase <https://datatracker.ietf.org/doc/html/rfc7540#section-8.1.2>`_; response headers are shown as they are received from the server. (There may be some exceptions, such as ``X-Firefox-Spdy``, which is added by Firefox.) + + +.. image:: response-headers-fx78.png + :alt: Screenshot showing the Request headers section of the Request details pane + :class: border + +You can copy some or all of the response header in JSON format by using the context menu: + +.. image:: copy-response-headers-fx78.png + :alt: Screenshot showing the Response headers pane, and its context menu with "Copy" and "Copy all" items + :class: border + +If you select **Copy**, a single key word, value pair is copied. If you select **Copy All**, the entire header is copied in JSON format, giving you something like this (after running the results through a JSON validator): + + +.. code-block:: json + + { + "Response headers (1.113 KB)": { + "headers": [ + { + "name": "accept-ranges", + "value": "bytes" + }, + { + "name": "age", + "value": "0" + }, + { + "name": "backend-timing", + "value": "D=74716 t=1560258099074460" + }, + { + "name": "cache-control", + "value": "private, must-revalidate, max-age=0" + }, + { + "name": "content-disposition", + "value": "inline; filename=api-result.js" + }, + { + "name": "content-encoding", + "value": "gzip" + }, + { + "name": "content-length", + "value": "673" + }, + { + "name": "content-type", + "value": "text/javascript; charset=utf-8" + }, + { + "name": "date", + "value": "Tue, 11 Jun 2019 13:01:39 GMT" + }, + { + "name": "mediawiki-login-suppressed", + "value": "true" + }, + { + "name": "p3p", + "value": "CP=\"This is not a P3P policy! See https://en.wikipedia.org/wiki/Special:CentralAutoLogin/P3P for more info.\"" + }, + { + "name": "server", + "value": "mw1316.eqiad.wmnet" + }, + { + "name": "server-timing", + "value": "cache;desc=\"pass\"" + }, + { + "name": "strict-transport-security", + "value": "max-age=106384710; includeSubDomains; preload" + }, + { + "name": "vary", + "value": "Accept-Encoding,Treat-as-Untrusted,X-Forwarded-Proto,Cookie,Authorization,X-Seven" + }, + { + "name": "via", + "value": "1.1 varnish (Varnish/5.1), 1.1 varnish (Varnish/5.1)" + }, + { + "name": "x-analytics", + "value": "ns=-1;special=Badtitle;WMF-Last-Access=11-Jun-2019;WMF-Last-Access-Global=11-Jun-2019;https=1" + }, + { + "name": "x-cache", + "value": "cp1075 pass, cp1075 pass" + }, + { + "name": "x-cache-status", + "value": "pass" + }, + { + "name": "x-client-ip", + "value": "204.210.158.136" + }, + { + "name": "x-content-type-options", + "value": "nosniff" + }, + { + "name": "X-Firefox-Spdy", + "value": "h2" + }, + { + "name": "x-frame-options", + "value": "SAMEORIGIN" + }, + { + "name": "x-powered-by", + "value": "HHVM/3.18.6-dev" + }, + { + "name": "x-search-id", + "value": "esvan0r5bnnwscyk2wq09i1im" + }, + { + "name": "x-varnish", + "value": "766019457, 417549316" + } + ] + }, + "Request headers (665 B)": { + "headers": [ + { + "name": "Accept", + "value": "*/*" + }, + { + "name": "Accept-Encoding", + "value": "gzip, deflate, br" + }, + { + "name": "Accept-Language", + "value": "en-US,en;q=0.5" + }, + { + "name": "Connection", + "value": "keep-alive" + }, + { + "name": "Cookie", + "value": "WMF-Last-Access=11-Jun-2019; WMF-Last-Access-Global=11-Jun-2019; mwPhp7Seed=5c9; GeoIP=US:NY:Port_Jervis:41.38:-74.67:v4" + }, + { + "name": "DNT", + "value": "1" + }, + { + "name": "Host", + "value": "en.wikipedia.org" + }, + { + "name": "Referer", + "value": "https://www.wikipedia.org/" + }, + { + "name": "TE", + "value": "Trailers" + }, + { + "name": "User-Agent", + "value": "Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:68.0) Gecko/20100101 Firefox/68.0" + } + ] + } + } + +Request headers +~~~~~~~~~~~~~~~ + +The Request headers section shows details about the request headers. For each line in the request headers section, a question mark links to the documentation for that request header, if one is available. + +A **Raw** toggle button in the section heading controls whether the headers are shown with formatting, or as plain, unformatted text. + +.. image:: request-headers-fx78.png + :alt: Screenshot showing the Request headers section of the Request details pane + :class: border + + +.. _network-monitor-request-details-cookies-tab: + +Cookies tab +----------- + +This tab lists full details of any cookies sent with the request or response: + +.. image:: network_cookies.png + :class: border + +As with headers, you can filter the list of cookies displayed. The full list of cookie attributes is shown—see the following screenshot showing Response cookies with further attributes shown. + +.. image:: highlight-samesite-attribute.png + :alt: cookies panel in firefox devtools network monitor, showing a number of cookie attributes including samesite + +The ``samesite`` attribute has been shown since Firefox 62 (`bug 1452715 <https://bugzilla.mozilla.org/show_bug.cgi?id=1452715>`_). + + +.. _network-monitor-request-details-request-tab: + +Request tab +----------- + +Request shows the complete request parameters, by default, in a formatted view: + +.. image:: json_formatted_request.png + :class: border + + +Switch the toggle button to have the raw view presented: + +.. image:: json_raw_request.png + :class: border + + +.. _network-monitor-request-details-response-tab: + +Response tab +------------ + +The complete content of the response. If the response is HTML, JS, or CSS, it will be shown as text: + +.. image:: html_formatted_response.png + :class: border + + +The toggle button for switching between raw and formatted response view has been implemented (`bug 1693147 <https://bugzilla.mozilla.org/show_bug.cgi?id=1693147>`_). The previous HTML example makes use of the formatted view. When the toggle button is turned on, the raw response view will be enabled: + +.. image:: html_raw_response.png + :class: border + + +If the response is JSON, it will be shown as an inspectable object: + +.. image:: json_formatted_response.png + :class: border + + +In the raw response view the response will be shown as a string: + +.. image:: json_raw_response.png + :class: border + + +If the response is an image, the tab displays a preview: + +.. image:: response_pane_image.png + :class: border + + +If the response is a web font, the tab also displays a preview: + +.. image:: response_font.png + :class: border + + +For network responses that are initiated by a `WebSocket <https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API>`_ connection, the details pane shows any associated messages. For more information, see :doc:`Inspecting web sockets <../inspecting_web_sockets/index>`. + + +.. _network-monitor-request-details-cache-tab: + +Cache tab +--------- + +If the response is cached (i.e. a 304), the Cache tab displays details about that cached resource. + +.. image:: response_cache.png + :class: border + +These details include: + +- **Last fetched:** The date the resource was last fetched +- **Fetched count:** The number of times in the current session that the resource has been fetched +- **Data size:** The size of the resource. +- **Last modified:** The date the resource was last modified. +- **Expires:** The date the resource expires. +- **Device:** The device the resource was fetched from (e.g. "disk"). + + +HTML preview +~~~~~~~~~~~~ + +If the response is HTML, a preview of the rendered HTML appears inside the Response tab, above the response payload. + + +.. _network-monitor-request-details-timings-tab: + +Timings tab +----------- + +The Timings tab provides information about how long each stage of a network request took, with a more detailed, annotated, view of the timeline bar, so it is easy to locate performance bottlenecks. + +.. image:: network-timings-tab.png + :class: border + + +This tab can include the following sections. + + +Queued, Started, Downloaded +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +New in Firefox 72, we now show the following timings at the top of the Timings tab, making dependency analysis a lot easier: + +- Queued: When the resource was queued for download. +- Started: When the resource started downloading. +- Downloaded: When the resource finished downloading. + + +.. note:: + Future versions will also show this information when entries in the network monitor timeline graph are moused over (see `bug 1580493 <https://bugzilla.mozilla.org/show_bug.cgi?id=1580493>`_). + + +Request Timing +~~~~~~~~~~~~~~ + +The *Request Timing* section breaks a network request down into the following subset of the stages defined in the `HTTP Archive <https://dvcs.w3.org/hg/webperf/raw-file/tip/specs/HAR/Overview.html>`_ specification: + + +.. list-table:: + :widths: 20 80 + :header-rows: 0 + + * - Name + - Description + + * - Blocked + - Time spent in a queue waiting for a network connection. + + The browser imposes a limit on the number of simultaneous connections that can be made to a single server. In Firefox this defaults to 6, but can be changed using the `network.http.max-persistent-connections-per-server <http://kb.mozillazine.org/Network.http.max-persistent-connections-per-server>`_ preference. If all connections are in use, the browser can't download more resources until a connection is released. + + * - DNS resolution + - Time taken to resolve a host name. + + * - Connecting + - Time taken to create a TCP connection. + + * - Sending + - Time taken to send the HTTP request to the server. + + * - Waiting + - Waiting for a response from the server. + + * - Receiving + - Time taken to read the entire response from the server (or cache). + + +Server Timing +~~~~~~~~~~~~~ + +New in Firefox 71, the *Server Timing* section lists any information provided in the `Server-Timing <https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Server-Timing>`_ header — this is used to surface any backend server timing metrics you've recorded (e.g. database read/write, CPU time, file system access, etc.). + +The header takes a series of descriptions and durations, which can be anything you like. In the above screenshot for example, the highlighted request's ``Server-Timing`` header contains 4 items — *data*, *markup*, *total*, and *miss*. + +Service Worker Timing +~~~~~~~~~~~~~~~~~~~~~ + +The *Service Worker Timing* section lists the information relating to the specific service worker request. The metrics include Startup, Dispatch fetch and Handle fetch. + +.. image:: network-service-worker-timings.png + :class: border + +.. list-table:: + :widths: 20 80 + :header-rows: 0 + + + * - Name + - Description + + * - Startup + - Time taken to launch the service worker, this is only indicated if the launch starts after the fetch event has already been dispatched. + + * - Dispatch fetch + - Time taken from when a fetch event is triggered to just before it starts getting handled by the service worker. + + * - Handle fetch + - Time taken to by the service worker to handle the fetch event. + + +.. _network-monitor-request-details-security-tab: + +Security tab +------------ + +If the site is being served over HTTPS, you get an extra tab labeled "Security". This contains details about the secure connection used including the protocol, the cipher suite, and certificate details: + +.. image:: network_security.png + :alt: border + +The Security tab shows a warning for security weaknesses. Currently it warns you about two weaknesses: + +1. Using SSLv3 instead of TLS +2. Using the RC4 cipher + +.. image:: security-warning.png + :class: center + + +.. _network-monitor-request-details-stack-trace-tab: + +Stack trace tab +--------------- + +Stack traces are shown in the *Stack Trace* tab, for responses that have a stack trace of course. + +.. image:: network_stack_trace.png + :class: border + + +Network Monitor Features +************************ + +The following articles cover different aspects of using the network monitor: + +- :doc:`Toolbar <../toolbar/index>` +- :doc:`Network request list <../request_list/index>` +- :doc:`Network request details <../request_details/index>` +- :doc:`Network traffic recording <../performance_analysis/index>` +- :doc:`Throttling <../throttling/index>` +- :doc:`Inspecting web sockets <../inspecting_web_sockets/index>` diff --git a/devtools/docs/user/network_monitor/request_details/json_formatted_request.png b/devtools/docs/user/network_monitor/request_details/json_formatted_request.png Binary files differnew file mode 100644 index 0000000000..88c544bd9a --- /dev/null +++ b/devtools/docs/user/network_monitor/request_details/json_formatted_request.png diff --git a/devtools/docs/user/network_monitor/request_details/json_formatted_response.png b/devtools/docs/user/network_monitor/request_details/json_formatted_response.png Binary files differnew file mode 100644 index 0000000000..500d3597f4 --- /dev/null +++ b/devtools/docs/user/network_monitor/request_details/json_formatted_response.png diff --git a/devtools/docs/user/network_monitor/request_details/json_raw_request.png b/devtools/docs/user/network_monitor/request_details/json_raw_request.png Binary files differnew file mode 100644 index 0000000000..de12a3d284 --- /dev/null +++ b/devtools/docs/user/network_monitor/request_details/json_raw_request.png diff --git a/devtools/docs/user/network_monitor/request_details/json_raw_response.png b/devtools/docs/user/network_monitor/request_details/json_raw_response.png Binary files differnew file mode 100644 index 0000000000..d02e896d03 --- /dev/null +++ b/devtools/docs/user/network_monitor/request_details/json_raw_response.png diff --git a/devtools/docs/user/network_monitor/request_details/network-details-fx78.png b/devtools/docs/user/network_monitor/request_details/network-details-fx78.png Binary files differnew file mode 100644 index 0000000000..c97f52c350 --- /dev/null +++ b/devtools/docs/user/network_monitor/request_details/network-details-fx78.png diff --git a/devtools/docs/user/network_monitor/request_details/network-service-worker-timings.png b/devtools/docs/user/network_monitor/request_details/network-service-worker-timings.png Binary files differnew file mode 100644 index 0000000000..f37adc81db --- /dev/null +++ b/devtools/docs/user/network_monitor/request_details/network-service-worker-timings.png diff --git a/devtools/docs/user/network_monitor/request_details/network-timings-tab.png b/devtools/docs/user/network_monitor/request_details/network-timings-tab.png Binary files differnew file mode 100644 index 0000000000..e5cbfa4432 --- /dev/null +++ b/devtools/docs/user/network_monitor/request_details/network-timings-tab.png diff --git a/devtools/docs/user/network_monitor/request_details/network_cookies.png b/devtools/docs/user/network_monitor/request_details/network_cookies.png Binary files differnew file mode 100644 index 0000000000..c20a83539f --- /dev/null +++ b/devtools/docs/user/network_monitor/request_details/network_cookies.png diff --git a/devtools/docs/user/network_monitor/request_details/network_response.png b/devtools/docs/user/network_monitor/request_details/network_response.png Binary files differnew file mode 100644 index 0000000000..080c8c5730 --- /dev/null +++ b/devtools/docs/user/network_monitor/request_details/network_response.png diff --git a/devtools/docs/user/network_monitor/request_details/network_security.png b/devtools/docs/user/network_monitor/request_details/network_security.png Binary files differnew file mode 100644 index 0000000000..5ca146c615 --- /dev/null +++ b/devtools/docs/user/network_monitor/request_details/network_security.png diff --git a/devtools/docs/user/network_monitor/request_details/network_stack_trace.png b/devtools/docs/user/network_monitor/request_details/network_stack_trace.png Binary files differnew file mode 100644 index 0000000000..29ee5f91b6 --- /dev/null +++ b/devtools/docs/user/network_monitor/request_details/network_stack_trace.png diff --git a/devtools/docs/user/network_monitor/request_details/params.png b/devtools/docs/user/network_monitor/request_details/params.png Binary files differnew file mode 100644 index 0000000000..9f5ceb0ccc --- /dev/null +++ b/devtools/docs/user/network_monitor/request_details/params.png diff --git a/devtools/docs/user/network_monitor/request_details/request-headers-fx78.png b/devtools/docs/user/network_monitor/request_details/request-headers-fx78.png Binary files differnew file mode 100644 index 0000000000..581c4e8200 --- /dev/null +++ b/devtools/docs/user/network_monitor/request_details/request-headers-fx78.png diff --git a/devtools/docs/user/network_monitor/request_details/response-headers-fx78.png b/devtools/docs/user/network_monitor/request_details/response-headers-fx78.png Binary files differnew file mode 100644 index 0000000000..9e9f4a114c --- /dev/null +++ b/devtools/docs/user/network_monitor/request_details/response-headers-fx78.png diff --git a/devtools/docs/user/network_monitor/request_details/response_cache.png b/devtools/docs/user/network_monitor/request_details/response_cache.png Binary files differnew file mode 100644 index 0000000000..6b69e7990c --- /dev/null +++ b/devtools/docs/user/network_monitor/request_details/response_cache.png diff --git a/devtools/docs/user/network_monitor/request_details/response_font.png b/devtools/docs/user/network_monitor/request_details/response_font.png Binary files differnew file mode 100644 index 0000000000..28aa850026 --- /dev/null +++ b/devtools/docs/user/network_monitor/request_details/response_font.png diff --git a/devtools/docs/user/network_monitor/request_details/response_json.png b/devtools/docs/user/network_monitor/request_details/response_json.png Binary files differnew file mode 100644 index 0000000000..a3e74c7472 --- /dev/null +++ b/devtools/docs/user/network_monitor/request_details/response_json.png diff --git a/devtools/docs/user/network_monitor/request_details/response_pane_image.png b/devtools/docs/user/network_monitor/request_details/response_pane_image.png Binary files differnew file mode 100644 index 0000000000..4dc1e7485f --- /dev/null +++ b/devtools/docs/user/network_monitor/request_details/response_pane_image.png diff --git a/devtools/docs/user/network_monitor/request_details/security-warning.png b/devtools/docs/user/network_monitor/request_details/security-warning.png Binary files differnew file mode 100644 index 0000000000..1685395c86 --- /dev/null +++ b/devtools/docs/user/network_monitor/request_details/security-warning.png diff --git a/devtools/docs/user/network_monitor/request_list/404_filter.png b/devtools/docs/user/network_monitor/request_list/404_filter.png Binary files differnew file mode 100644 index 0000000000..a70e1ce9fe --- /dev/null +++ b/devtools/docs/user/network_monitor/request_list/404_filter.png diff --git a/devtools/docs/user/network_monitor/request_list/afterblocking.png b/devtools/docs/user/network_monitor/request_list/afterblocking.png Binary files differnew file mode 100644 index 0000000000..71f62ecced --- /dev/null +++ b/devtools/docs/user/network_monitor/request_list/afterblocking.png diff --git a/devtools/docs/user/network_monitor/request_list/beforeblocking.png b/devtools/docs/user/network_monitor/request_list/beforeblocking.png Binary files differnew file mode 100644 index 0000000000..044d4b11bd --- /dev/null +++ b/devtools/docs/user/network_monitor/request_list/beforeblocking.png diff --git a/devtools/docs/user/network_monitor/request_list/blocked_nw_icon.png b/devtools/docs/user/network_monitor/request_list/blocked_nw_icon.png Binary files differnew file mode 100644 index 0000000000..c2ed85b941 --- /dev/null +++ b/devtools/docs/user/network_monitor/request_list/blocked_nw_icon.png diff --git a/devtools/docs/user/network_monitor/request_list/har-dropdown.png b/devtools/docs/user/network_monitor/request_list/har-dropdown.png Binary files differnew file mode 100644 index 0000000000..93e309e247 --- /dev/null +++ b/devtools/docs/user/network_monitor/request_list/har-dropdown.png diff --git a/devtools/docs/user/network_monitor/request_list/http.svg b/devtools/docs/user/network_monitor/request_list/http.svg new file mode 100644 index 0000000000..fc7062c9c1 --- /dev/null +++ b/devtools/docs/user/network_monitor/request_list/http.svg @@ -0,0 +1,4 @@ +<!-- This Source Code Form is subject to the terms of the Mozilla Public + - License, v. 2.0. If a copy of the MPL was not distributed with this + - file, You can obtain one at http://mozilla.org/MPL/2.0/. --> +<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="16" height="16"><style>.icon-default{fill:#999}</style><defs><rect id="shape-lock-clasp-outer" x="4" y="2" width="8" height="10" rx="4" ry="4"/><rect id="shape-lock-clasp-inner" x="6" y="4" width="4" height="6" rx="2" ry="2"/><rect id="shape-lock-base" x="3" y="7" width="10" height="7" rx="1" ry="1"/><mask id="mask-clasp-cutout"><path d="M0 0h16v16H0z"/><use xlink:href="#shape-lock-clasp-outer" fill="#fff"/><use xlink:href="#shape-lock-clasp-inner"/><path stroke="#000" stroke-width="2" d="M2 13L14 1.5M2 15L14 3.5"/><rect x="3" y="7" width="10" height="7" rx="1" ry="1"/></mask><mask id="mask-base-cutout"><path d="M0 0h16v16H0z"/><use xlink:href="#shape-lock-base" fill="#fff"/><path stroke="#000" stroke-width="1.8" d="M2 14.8L14 3.2"/></mask></defs><use xlink:href="#shape-lock-clasp-outer" mask="url(#mask-clasp-cutout)" class="icon-default"/><use xlink:href="#shape-lock-base" mask="url(#mask-base-cutout)" class="icon-default"/><path stroke="#d92d21" stroke-width="1.8" d="M2 14.1L14 2.5"/></svg>
\ No newline at end of file diff --git a/devtools/docs/user/network_monitor/request_list/https-failed.svg b/devtools/docs/user/network_monitor/request_list/https-failed.svg new file mode 100644 index 0000000000..bfc8eeee58 --- /dev/null +++ b/devtools/docs/user/network_monitor/request_list/https-failed.svg @@ -0,0 +1,4 @@ +<!-- This Source Code Form is subject to the terms of the Mozilla Public + - License, v. 2.0. If a copy of the MPL was not distributed with this + - file, You can obtain one at http://mozilla.org/MPL/2.0/. --> +<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16"><path fill="gray" d="M14.8 12.5L9.3 1.9C9 1.3 8.5 1 8 1s-1 .3-1.3.9L1.2 12.5c-.3.6-.3 1.2 0 1.7s.8.8 1.4.8h10.8c.6 0 1.1-.3 1.4-.8.3-.5.3-1.1 0-1.7z"/><path fill="#fff" d="M8 11c-.8 0-1.5.7-1.5 1.5S7.2 14 8 14s1.5-.7 1.5-1.5S8.8 11 8 11zm0-1c.6 0 1-.4 1-1l.2-4.2c0-.7-.5-1.2-1.2-1.2s-1.2.5-1.2 1.2L7 9c0 .6.4 1 1 1z"/></svg>
\ No newline at end of file diff --git a/devtools/docs/user/network_monitor/request_list/https-weak.svg b/devtools/docs/user/network_monitor/request_list/https-weak.svg new file mode 100644 index 0000000000..7206803009 --- /dev/null +++ b/devtools/docs/user/network_monitor/request_list/https-weak.svg @@ -0,0 +1,4 @@ +<!-- This Source Code Form is subject to the terms of the Mozilla Public + - License, v. 2.0. If a copy of the MPL was not distributed with this + - file, You can obtain one at http://mozilla.org/MPL/2.0/. --> +<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="16" height="16"><style>.icon-default{fill:gray}</style><defs><rect id="shape-lock-clasp-outer" x="2" y="1" width="8" height="10" rx="4" ry="4"/><rect id="shape-lock-clasp-inner" x="4" y="3" width="4" height="6" rx="2" ry="2"/><rect id="shape-lock-base" x="1" y="6" width="10" height="7" rx="1" ry="1"/><mask id="mask-clasp-cutout"><path d="M0 0h16v16H0z"/><use xlink:href="#shape-lock-clasp-outer" fill="#fff"/><use xlink:href="#shape-lock-clasp-inner"/></mask></defs><use xlink:href="#shape-lock-clasp-outer" mask="url(#mask-clasp-cutout)" class="icon-default"/><use xlink:href="#shape-lock-base" class="icon-default"/><path fill="#fff" d="M10.5 5c-.7 0-1.4.4-1.7 1.2L5.3 13c-.4.7-.4 1.4 0 2 .4.6 1 1 1.8 1H14c.8 0 1.4-.4 1.8-1 .3-.6.3-1.4 0-2l-3.5-6.8c-.4-.8-1.1-1.2-1.8-1.2z"/><path fill="#ffbf00" d="M14.8 13.4l-3.5-6.8c-.1-.4-.4-.6-.8-.6-.3 0-.7.2-.9.6l-3.5 6.8c-.2.4-.2.8 0 1.1.2.3.5.5.9.5h7c.4 0 .7-.2.9-.5.2-.3.1-.7-.1-1.1z"/><path fill="#fff" d="M10 8.5c0-.3.2-.5.5-.5s.5.2.5.5l-.2 2.5h-.6L10 8.5z"/><circle fill="#fff" cx="10.5" cy="12.5" r=".75"/></svg>
\ No newline at end of file diff --git a/devtools/docs/user/network_monitor/request_list/https.svg b/devtools/docs/user/network_monitor/request_list/https.svg new file mode 100644 index 0000000000..e5da9f4e38 --- /dev/null +++ b/devtools/docs/user/network_monitor/request_list/https.svg @@ -0,0 +1,4 @@ +<!-- This Source Code Form is subject to the terms of the Mozilla Public + - License, v. 2.0. If a copy of the MPL was not distributed with this + - file, You can obtain one at http://mozilla.org/MPL/2.0/. --> +<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="16" height="16"><style>.icon-default{fill:#4d9a26}</style><defs><rect id="shape-lock-clasp-outer" x="4" y="2" width="8" height="10" rx="4" ry="4"/><rect id="shape-lock-clasp-inner" x="6" y="4" width="4" height="6" rx="2" ry="2"/><rect id="shape-lock-base" x="3" y="7" width="10" height="7" rx="1" ry="1"/><mask id="mask-clasp-cutout"><path d="M0 0h16v16H0z"/><use xlink:href="#shape-lock-clasp-outer" fill="#fff"/><use xlink:href="#shape-lock-clasp-inner"/></mask></defs><use xlink:href="#shape-lock-clasp-outer" mask="url(#mask-clasp-cutout)" class="icon-default"/><use xlink:href="#shape-lock-base" class="icon-default"/></svg>
\ No newline at end of file diff --git a/devtools/docs/user/network_monitor/request_list/image_preview.png b/devtools/docs/user/network_monitor/request_list/image_preview.png Binary files differnew file mode 100644 index 0000000000..fda8e08cf2 --- /dev/null +++ b/devtools/docs/user/network_monitor/request_list/image_preview.png diff --git a/devtools/docs/user/network_monitor/request_list/index.rst b/devtools/docs/user/network_monitor/request_list/index.rst new file mode 100644 index 0000000000..c0345290c8 --- /dev/null +++ b/devtools/docs/user/network_monitor/request_list/index.rst @@ -0,0 +1,497 @@ +==================== +Network request list +==================== + +The request list of the Network Monitor shows a list of all the network requests made in the course of loading the page. + + +Network request list +-------------------- + +By default, the Network Monitor shows a list of all the network requests made in the course of loading the page. Each request is displayed in its own row: + +.. image:: network_request_list.png + :class: border + +By default, the Network Monitor is cleared each time you navigate to a new page or reload the current page. You can override this behavior by checking "Enable persistent logs" in the :ref:`Settings <settings-common-preferences>`. + + +Network request columns +----------------------- + +You can toggle columns on and off by right-clicking on the table header and choosing the specific column from the context menu. A **Reset Columns** command is available on the context menu to reset the columns to their initial configuration. + +You can also change the width of the columns to help make the information you are looking for easier to view. The mouse pointer changes to a resize icon when you move it over the border of a column. You can drag to manually set the size of column. Starting in Firefox 76 you can double-click a column divider to resize the column to the left of it to fit its contents. + +The **Reset Columns** command on the context menu also resets the width of the columns to the default values. + +.. raw:: html + + <iframe width="560" height="315" src="https://www.youtube.com/embed/5fbuDO2s9Pk" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe> + <br/> + <br/> + +Clicking the column header label sorts the request list by that column. You can reset the sort to the default by selecting "Reset Sorting" from the context menu. + +.. image:: network_monitor_columns_menu.png + :alt: Screenshot of the context menu for selecting columns to display in the Network monitor + :class: center + + +Here is a list of all available columns: + +.. |image1| image:: blocked_nw_icon.png + :alt: Red circle with a diagonal slash + :width: 20 + +.. |image2| image:: nwmon-turtle-tooltip.png + :alt: Screenshot of a network request with a turtle icon, and a tooltip explaining the problem + :class: border + + +- **Status**: The HTTP status code returned. The numeric code is displayed on a colored background, to help unusual ones stand out. If there was no response, this column is empty. Or you might see a |image1| red circle with a diagonal slash for responses that were blocked by the browser or the server. +- **Method**: The HTTP request method used. +- **Domain**: Domain of the path requested. + + - If the request used SSL/TLS and the connection had security weaknesses such as weak ciphers, you'll see a warning triangle next to the domain. Y + - Hover over the domain to see the IP address. + - There's an icon next to the domain that gives you extra information about the security status of that request. See :ref:`Security icons <network-monitor-request-list-security-icons>`. + +- **File**: The basename of the file requested. + + - (Starting in Firefox 80) On the right edge of the File column, a turtle icon appears if the server waiting time exceeds a threshold (default: 500 ms). A tooltip explains the problem. You can configure the threshold in the `Configuration Editor <https://support.mozilla.org/en-US/kb/about-config-editor-firefox>`_ (about:config) by modifying the ``devtools.netmonitor.audits.slow`` setting. + - |image2| + +- **URL**: The `URL <https://developer.mozilla.org/en-US/docs/Glossary/URL>`_ of the file requested. +- **Protocol:** The network protocol used to transfer the data, this column is hidden by default. +- **Scheme:** The scheme (https/http/ftp/...) of the path requested. This column is hidden by default. +- **Remote IP**: The IP address of the server answering the request. This column is hidden by default. +- **Type**: ``Content-type`` of the response. +- **Cookies:** The number of request cookies associated to the request. This column is hidden by default. This is new in Firefox 55. +- **Set-Cookies:** The number of response cookies associated to the request. This column is hidden by default. This is new in Firefox 55. +- **Transferred**: The number of bytes that were actually transferred to load the resource, or a message about why the resource was not transferred. A number value is less than **Size** if the resource was compressed. + + - If the resource was fetched from a `service worker <https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API>`_ cache, then this cell displays "service worker". + - Cached resources may be fetched from the cache and the network simultaneously, which may improve load time for slow caches. `Starting with Firefox 68 <https://bugzilla.mozilla.org/show_bug.cgi?id=1358038>`_, the transferred column lists either "cached (raced)" or "[size] (raced)" depending on the faster source. This feature is called `Race Cache With Network (RCWN) <https://slides.com/valentingosu/race-cache-with-network-2017#>`_. + - If the resource was blocked, the message indicates why it was blocked. For example, "CSP", "Malware", "CORS Missing Allow Origin", "Blocked by [Name of Extension]". + +- **Size**: The size of the transferred resource. + + +Image thumbnails +~~~~~~~~~~~~~~~~ + +If the request is for an Image, hovering over its filename shows a preview of the image in a tooltip: + +.. image:: image_preview.png + :class: border + + +.. _network-monitor-request-list-security-icons: + +Security icons +~~~~~~~~~~~~~~ + +The Network Monitor displays an icon in the Domain column: + +.. image:: network_message_list_63.png + :class: border + + +This gives you extra information about the security status of the request: + +.. |image3| image:: https.svg + :width: 20 + +.. |image4| image:: https-weak.svg + :width: 20 + +.. |image5| image:: https-failed.svg + :width: 20 + +.. |image6| image:: http.svg + :width: 20 + +.. |image7| image:: localhost.svg + :width: 20 + +.. |image8| image:: tracker_icon.png + :width: 20 + + +.. list-table:: + :widths: 25 75 + :header-rows: 1 + + * - Icon + - Meaning + + * - |image3| + - HTTPS + + * - |image4| + - Weak HTTPS (for example, a weak cipher was used) + + * - |image5| + - Failed HTTPS (for example, a certificate was invalid) + + * - |image6| + - HTTP + + * - |image7| + - Localhost + + * - |image8| + - Indicates that the URL belongs to a known tracker that would be blocked with content blocking enabled. + + +Timeline +-------- + +The request list also displays a timeline for the different parts of each request. + +.. image:: timeline.png + :class: border + + +Each timeline is given a horizontal position in its row relative to the other network requests, so you can see the total time taken to load the page. For more details on the color-coding used here, see the section on the :ref:`Timings <network-monitor-request-details-timings-tab>` page. + +Starting in Firefox 45, the timeline also contains two vertical lines: + + +- The blue line marks the point at which thepage's `DOMContentLoaded <https://developer.mozilla.org/en-US/docs/Web/API/Window/DOMContentLoaded_event>`_ event is triggered. +- The red line marks the point at which the page's `load <https://developer.mozilla.org/en-US/docs/Web/API/Window/load_event>`_ event is triggered. + + +.. _network_monitor_blocking_specific_urls: + +Blocking specific URLs +---------------------- + +If you want to view your page as it would look without a resource (e.g., if it were blocked by the browser or an extension), you can block requests matching patterns you specify. + + +1. Click the **Request Blocking** icon in the toolbar. This opens the **Blocking** sidebar. (Click the icon again when you want to close the sidebar.) + + .. image:: request_blocking_panel.png + :alt: Screen shot of the Blocking panel, with arrows indicating the panel and the Request Blocking toolbar icon + :class: center + +2. Enter a string in the field with the placeholder text *Block resource when URL contains*. +3. Reload the page to test it with the specified URL blocked. + + +Other actions you can take with Request Blocking: + + +- To turn all request blocking off or on: Toggle the checkbox next to Enable Request Blocking. +- To turn a specific block off or on: Toggle the checkbox next to that item. +- To delete a blocked item, click the X icon that appears when you focus the item. +- (Starting with Firefox 77) Right-click any item in the list and choose from the context menu: + + - **Enable all** enables blocking of all items in the list. + - **Disable all** disables blocking of all items in the list. + - **Remove all** deletes all items in the list. + + +Blocking a specific URL from the request list +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can also block a URL from the request list: + +.. image:: beforeblocking.png + :class: border + + +1. Hover over the item you want to block in the Request List. +2. Select Block URL from the context menu. +3. When you refresh the page, that specific URL will be blocked and a message will be added to the item in the list indicating that it has been blocked by the DevTools. + +.. image:: afterblocking.png + :class: border + + +Stop blocking a URL from the Request List +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. image:: unblockurl.png + :class: border + +1. Hover over the item. +2. Select **Unblock URL**. +3. Now when you refresh the page, the item will once enabled. + + +.. note:: + (Starting in Firefox 80) You can also block and unblock URLs from the :doc:`Web Console <../../web_console/index>`, using the ``:block`` and ``:unblock`` helper commands. These accept any string, and affect any URL containing the string. + + +.. _request-list-filtering-requests: + +Filtering requests +****************** + +You can filter requests by content type, by whether they are XMLHttpRequests or WebSocket requests, or by request properties. + +.. |br| raw:: html + + <br/> + + +.. list-table:: + :widths: 25 75 + :header-rows: 1 + + * - Filter type + - How to apply + + * - Content type + - Use the buttons in the :doc:`toolbar <../toolbar/index>` (**HTML**, **CSS**, **JS**). + + * - `XHR <https://developer.mozilla.org/en-US/docs/Glossary/XHR_(XMLHttpRequest)>`_ requests + - Use the **XHR** button in the :doc:`toolbar <../toolbar/index>`. + + * - `WebSocket <https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API>`_ connections + - Use the **WS** button in the :doc:`toolbar <../toolbar/index>`. You can filter by plain text (in which case the text is used to find partial matches; entering "for" will match any message that contains the word "for") or—as of `Firefox 75 <https://developer.mozilla.org/en-US/docs/Mozilla/Firefox/Releases/75>`_ — using `regular expressions <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions>`_ (by writing the regexp bracketed within slashes; "/.+Corp.*/" will look for any occurrence of "Corp" which has at least one character before it and may or may not have any characters after it, for example). |br| |br| The third-party add-on `WebSocket Sniffer <https://addons.mozilla.org/en-US/firefox/addon/websocketsniff>`_ may be helpful as well. + + * - URL + - Use the *Filter URLs* box in the :doc:`toolbar <../toolbar/index>`. You can focus it by clicking in the filter box, or by pressing :kbd:`Ctrl` + :kbd:`F` (or :kbd:`Cmd` + :kbd:`F` on a Mac); then start typing. The list of network requests is filtered to include only requests that contain your filter string, in either the Domain or the File portions. |br| |br| You can filter requests that *don't* contain your filter string by prefixing your query with the "-" operator. For example, the query "-google.com" will show all requests that don't have "google.com" in the URL. + + * - Request properties + - Use the search box in the :doc:`toolbar <../toolbar/index>`. See next section. + + +.. _request-list-filtering-by-properties: +.. _request-list-requst-list-cause-column: + +Filtering by properties +~~~~~~~~~~~~~~~~~~~~~~~ + +The search box recognizes specific keywords, which can be used to filter the requests by specific request properties. Those keywords are followed by a colon and a related filter value. The filter values are matched case insensitive. Prepending a minus (``-``) negates the filter. You can combine different filters together by separating them with a space. + + +.. list-table:: + :widths: 20 40 40 + :header-rows: 1 + + * - Keyword + - Meaning + - Examples + + * - ``status-code`` + - Shows resources that have the specific HTTP status code. + - ``status-code:304`` + + * - ``method`` + - Shows resources that have were requested via the specific HTTP request method. + - ``method:post`` + + * - ``domain`` + - Shows resources coming from a specific domain. + - ``domain:mozilla.org`` + + * - ``remote-ip`` + - Shows resources coming from a server with the specified IP. + - ``remote-ip:63.245.215.53`` |br| |br| ``remote-ip:[2400:cb00:2048:1::6810:2802]`` + + * - ``cause`` + - Shows resources matching a specific cause type. The types can be found in the description of the cause column. + - ``cause:js`` |br| |br| ``cause:stylesheet`` |br| |br| ``cause:img`` + + * - ``transferred`` + - Shows resources having a specific transferred size or a transferred size close to the one specified. ``k`` can be used as suffix for kilobytes and ``m`` for megabytes, e.g. the value ``1k`` is equivalent to ``1024``. + - ``transferred:1k`` + + * - ``size`` + - Shows resources having a specific size (after decompression) or a size close to the one specified. ``k`` can be used as suffix for kilobytes and ``m`` for megabytes, e.g. the value ``1k`` is equivalent to ``1024``. + - ``size:2m`` + + * - ``larger-than`` + - Shows resources that are larger than the specified size in bytes. ``k`` can be used as suffix for kilobytes and ``m`` for megabytes, e.g. the value ``1k`` is equivalent to ``1024``. + - ``larger-than:2000`` |br| |br| ``-larger-than:4k`` + + * - ``mime-type`` + - Shows resources that match the specified MIME type. + - ``mime-type:text/html`` |br| |br| ``mime-type:image/png`` |br| |br| ``mime-type:application/javascript`` + + * - ``is`` + - ``is:cached`` and ``is:from-cache`` shows only resources coming from cache. ``is:running`` shows only resources, which are currently being transferred. + - ``is:cached`` |br| |br| ``-is:running`` + + * - ``scheme`` + - Shows resources transferred via the given scheme. + - ``scheme:http`` + + * - ``has-response-header`` + - Shows resources that contain the specified HTTP response header. + - ``has-response-header:cache-control`` |br| |br| ``has-response-header:X-Firefox-Spdy`` + + * - ``set-cookie-domain`` + - Shows the resources that have a ``Set-Cookie`` header with a ``Domain`` attribute that matches the specified value. + - ``set-cookie-domain:.mozilla.org`` + + * - ``set-cookie-name`` + - Shows the resources that have a ``Set-Cookie`` header with a name that matches the specified value. + - ``set-cookie-name:_ga`` + + * - ``set-cookie-value`` + - Shows the resources that have a ``Set-Cookie`` header with a value that matches the specified value. + - ``set-cookie-value:true`` + + * - ``regexp`` + - Shows the resources having a URL that matches the given `regular expression <https://developer.mozilla.org/en-US/docs/Glossary/Regular_expression>`_. + - ``regexp:\d{5}`` |br| |br| ``regexp:mdn|mozilla`` + + +For example, to find all 404, not found, errors, you can type "404" into the search and auto-complete suggests "status-code:404" so you'll end up with something like this: + +.. image:: 404_filter.png + :class: border + + +Search in requests +------------------ + +Use the *Search* panel to run a full-text search on headers and content. + + +1. Click the **Search** icon in the toolbar. This opens the Search sidebar. + +.. image:: search_panel.png + :alt: Screenshot of the Network monitor, with the request search sidebar displayed, and arrows indicating the search toolbar icon and the search box. + :class: border + +2. Enter a string in the search field of the sidebar, and press :kbd:`Enter` or :kbd:`Return`. The search results area below the search field displays the requests that contain that string in the request or response headers or in the content of the response. You can expand each item to show the specific item that matches the string. Clicking an item in the search results highlights that item in the monitor list, and displays the corresponding information in the request details pane. + +.. image:: search_panel_matches.png + :alt: Screenshot of the search panel, with "newsletter" as the search string, and callouts for the expanded results, and corresponding items displayed in the request list and headers tab. + :class: border + + +Other ways to use the search panel: + + +- To clear the search string: click the **X** icon in the search field. +- To make the search case sensitive: click the **Case Sensitive** (**Aa**) icon next to the search field. +- To close the search panel, do one of the following: + + - Click the **X** icon next to the search field. + - Click the **Search** icon in the Network Monitor toolbar. + + +.. _network-monitor-request-list-edit-and-resend: + +Context menu +------------ + +Context-clicking on a row in the list displays a context menu with the following options: + +.. list-table:: + :widths: 25 75 + :header-rows: 1 + + * - Menuitem + - Description + + * - Copy > Copy URL + - Copies the URL. + + * - Copy > Copy as cURL + - Copies the network request to the clipboard as a `cURL <https://curl.haxx.se/>`_ command, so you can execute it from a command line. See :ref:`Copy as cURL <request-list-copy-as-curl>`, below. + + * - Copy > Copy as Fetch + - Copies the request as a call to the <a href="/en-US/docs/Web/API/fetch">fetch()</a> method, including the URL and any settings object. + + * - Copy > Copy Request Headers + - Copies the request's header to the clipboard. + + * - Copy > Copy Response Headers + - Copies the headers of the response for this request, to the clipboard. + + * - Copy > Copy Response + - Copies the entire response that was sent for this request. + + * - Copy > Copy All As HAR + - Creates an `HTTP Archive <https://w3c.github.io/web-performance/specs/HAR/Overview.html>`_ (HAR) for all requests listed, and copies it to the clipboard. + + * - Save All As HAR + - Creates an `HTTP Archive <https://w3c.github.io/web-performance/specs/HAR/Overview.html>`_ (HAR) for all requests listed, and opens a file dialog, so you can save it to a file. + + * - Resend + - Resends the request as it was originally sent with no changes made. + + * - Edit and Resend + - Opens an editor enabling you to edit the request's method, URL, parameters, and headers, and resend the request. + + * - Block URL + - Blocks the selected URL for future requests. See :ref:`Blocking a specific URL from the Request List <network_monitor_blocking_specific_urls>`. + + * - Open in New Tab + - Resends the request in a new tab — very useful for debugging asynchronous requests. + + * - Open in Style Editor + - For a CSS resource, opens it in the :doc:`Style Editor <../../style_editor/index>`. + + * - Start :doc:`Performance Analysis <../performance_analysis/index>` + - + + * - Use as Fetch in Console + - Submits the request as a call to the `fetch() <https://developer.mozilla.org/en-US/docs/Web/API/fetch>` method in the console. + + +.. _request-list-copy-as-curl: + +Copy as cURL +~~~~~~~~~~~~ + +The command may include the following options: + +.. list-table:: + :widths: 25 75 + :header-rows: 0 + + * - ``-X [METHOD]`` + - If the method is not GET or POST + + * - ``--data`` + - For URL encoded request parameters + + * - ``--data-binary`` + - For multipart request parameters + + * - ``--http/VERSION`` + - If the HTTP version is not 1.1 + + * - ``-I`` + - If the method is HEAD + + * - ``-H`` + - One for each request header. |br| |br| If the "Accept-Encoding" header is present, the cURL command includes ``--compressed`` instead of ``-H "Accept-Encoding: gzip, deflate"``. This means that the response will be automatically decompressed. + + + * - ``--globoff`` + - Suppresses cURL's globbing (wildcard matching) feature if the copied URL includes square bracket characters (``[`` or ``]``). (Starting in Firefox 76) + + + +Managing HAR data +~~~~~~~~~~~~~~~~~ + +The HAR format enables you to export detailed information about network requests. In addition to the **Copy** and **Save** menu items for HAR in the context menu, similar menu items are available in the **HAR** dropdown menu in the toolbar, as well as an **Import** menuitem. + +.. image:: har-dropdown.png + :class: border + + +Network Monitor features +************************ + +The following articles cover different aspects of using the network monitor: + +- :doc:`Toolbar <../toolbar/index>` +- :doc:`Network request list <../request_list/index>` +- :doc:`Network request details <../request_details/index>` +- :doc:`Network traffic recording <../performance_analysis/index>` +- :doc:`Throttling <../throttling/index>` +- :doc:`Inspecting web sockets <../inspecting_web_sockets/index>` +- :doc:`Inspecting server-sent events <../inspecting_server-sent_events/index>` diff --git a/devtools/docs/user/network_monitor/request_list/localhost.svg b/devtools/docs/user/network_monitor/request_list/localhost.svg new file mode 100644 index 0000000000..4e321aadcd --- /dev/null +++ b/devtools/docs/user/network_monitor/request_list/localhost.svg @@ -0,0 +1,4 @@ +<!-- This Source Code Form is subject to the terms of the Mozilla Public + - License, v. 2.0. If a copy of the MPL was not distributed with this + - file, You can obtain one at http://mozilla.org/MPL/2.0/. --> +<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16"><circle fill="#a6a6a6" cx="8" cy="8" r="7"/><path fill="#fff" d="M6.316 2.741a.125.125 0 00-.054.007.042.042 0 00-.013.011l.018-.001c.018-.004.031-.016.05-.017zm.023.859c.023-.029-.032-.053-.062-.051.008-.035.052-.053.04-.097-.01-.046-.066-.037-.096-.012-.026.023-.04.063-.063.09-.013.015-.036.02-.045.038-.008.017.002.046 0 .065a.122.122 0 00.103-.032l.017-.008c-.004.003-.006.01-.008.014.018.022.097.016.114-.007zm.037-1.227c-.002.054.05.06.09.081-.013.031-.055.03-.075.055-.024.031.02.058.042.072.042.026.018.056.01.093-.011.052.1.038.125.037.042-.002.11.005.15-.015.043-.024.066-.077.111-.103.038-.022.091-.034.132-.019.044.015.039.071.074.095.042.029.087.038.123-.005.022-.027.073-.061.075-.09.004-.051.019-.091.075-.102.045-.009.035.035.067.043.07.018.103-.196.18-.133.017.015.022.073.053.068.031-.005.032-.051.066-.052.01.031-.058.069-.067.103.042-.035.063-.03.111-.035.013.033-.082.087-.106.092-.035.009-.056-.011-.082.008-.021.014-.05.013-.074.015-.035.004-.1.05-.099.088 0 .015.012.049 0 .061-.013.013-.041.001-.044-.012-.03.044-.068-.033-.093.029.04.01.076.048.12.059l.13.034c.072.022.18-.065.234-.107a.403.403 0 00.133-.19c.015-.069.09-.148.075-.216-.014-.064-.024-.094.048-.117.03-.01.105-.026.115-.061.016-.052-.147-.038-.171-.05-.082-.037-.118-.078-.212-.041-.05.019-.098.035-.15.049-.026.007-.053.009-.067.032a.06.06 0 01-.024.021c-.043.017.01-.064.015-.069.013-.016.036-.065-.008-.054-.065.015-.113.115-.183.12-.053.004-.036-.043-.022-.07.026-.049-.05-.055-.083-.055-.048 0-.083.027-.129.032-.042.004-.091.012-.134.011-.085-.003-.14.047-.225.019-.089-.029-.184.045-.27.055-.029.004-.07-.002-.082.032-.01.028 0 .071.022.092l.007-.006c-.02.019-.021.046-.049.056-.026.009-.053.044-.067.068-.01.018-.041.093.012.054.038-.029.06-.083.121-.072zM3.184 7.108c-.091-.066-.297-.082-.272-.236.016-.094.113-.167.19-.213a.544.544 0 01.333-.052c.028.003.08-.002.095.02a.075.075 0 00.036.022c.031.009.063.01.094.016.047.009.081.05.128.016.055-.038.064-.046.13-.038.059.007.094-.038.144-.034.015.001.03.004.041.009.005-.017.012-.032.023-.035.024-.007.079.053.104.058.066.014.062-.032.066-.079.033-.006.049.039.078.011 0 .009.005.023.005.032a.015.015 0 00.02-.001.018.018 0 00.001-.016c.016.005.024-.006.026-.025.012.001.03-.006.042-.004.01-.034.029-.079.004-.11l.02-.004c0-.034.023-.049.024-.076-.036-.005-.075-.003-.112-.002.022-.02.074-.064.079-.091.01-.048-.052-.077-.047-.134.006.03.04.099.07.109.072.024.051-.047.056-.084.018-.117.122-.02.124.041.03-.07.107.008.072.068-.017.029-.04.018-.018.056.014.027.036.028.068.021a.122.122 0 00.014-.053c.055-.017.09.048.059.087a.553.553 0 01.125-.054c-.026-.09-.052-.178-.036-.274.004-.021.007-.045.023-.061.02-.021-.005-.013-.007-.027-.006-.042.039-.085.055-.123-.046-.01-.004-.102.027-.118.034-.017.132.011.14-.016.019.011.038.027.061.027.055.001.091.002.129.046.018.023.046.074.08.078-.001.038.042.066-.003.098-.036.025-.085.019-.1.067-.01.03-.039.044.005.065.019.01.042.012.063.012.005.029.02.068.057.063.073-.009.089-.101.147-.132.095-.05.08.166.162.112.02-.013.02-.068.03-.089a.703.703 0 01.07-.128c.037-.05.083-.102.067-.167-.01-.036-.078-.051-.11-.076a.368.368 0 01-.096-.107c-.014-.026-.022-.035 0-.048.012-.007.008-.021.004-.031-.024-.05-.088-.139.001-.17.02-.007.062-.071.065-.096.005-.042-.059-.08-.03-.122.02-.031.073-.051.1-.082a.086.086 0 01.047-.032c.001-.017.005-.036.02-.047.023-.018.06-.009.089-.018.045-.014.065-.061.1-.087.03-.022.063-.014.095-.03.017-.008.024-.026.04-.034.042-.02.09.012.108.047.044.084.1.214.226.18a.158.158 0 00.105-.104c.015-.046-.003-.084 0-.129.004-.08.082-.131.091-.21-.059.001-.028-.036-.048-.07-.022-.038-.071-.01-.104-.016.034-.081.034-.109-.045-.148-.035-.017-.092-.097-.119-.094.022-.03.073.02.09.034a.168.168 0 00.113.052.107.107 0 01-.012-.083c.009-.022-.013-.045-.011-.073.055.071.046.152.078.23.013.033.045.055.06.089.017.043.005.042.043.068.022.016.03.044.034.069.007.044.023.025.047.05.013.015.049.017.042.048-.005.022-.02.04-.023.063-.009.066.12-.024.133-.033.028-.021.073-.025.095-.05.023-.026.018-.064.042-.088.03-.031.058-.01.093-.016.042-.006.077-.039.108-.064.065-.055.106-.115.16-.178-.023.006-.104.065-.109.01-.03 0-.101-.005-.112-.039-.01-.025-.006-.053-.006-.078-.001-.027-.034-.018-.055-.032-.044-.028-.066-.08-.112-.104a.458.458 0 01-.163-.169c-.025-.039-.116-.118-.11-.165.005-.031.03-.064.028-.095 0-.028-.022-.043-.02-.074.004-.036-.083-.099-.007-.106.023-.002.027-.031.054-.047.03-.018.023-.034.055-.025.053.016.089-.042.125-.073.06-.054-.037-.055-.042-.096-.005-.041-.028-.071-.035-.119-.004-.035-.037-.021-.056-.012-.025.012-.051-.006-.076-.011-.022-.005-.041-.043-.069-.031-.02.01-.02.035-.049.032-.022-.002-.036-.023-.057-.027-.034-.004-.004.028-.042.031-.026.002-.112-.034-.114 0-.027-.046-.038.032-.066.04-.032.009-.065.001-.097.013-.069.028-.046.097.02.108.053.008-.016.045.002.081.016.032.02.054.055.067.057.021.118.038.099.112a.348.348 0 01-.18.221c-.086.04-.11-.069-.175-.097-.04-.017-.085-.011-.128-.006-.007.011.06.032.07.051.02.039-.034.034-.038.064-.004.025-.037.043-.019.068-.019-.023-.055.008-.068.022-.019.02-.015.033-.007.058.016.051-.061.104-.107.098-.038-.006-.074-.003-.111-.021-.043-.021-.029-.008-.037-.057-.01-.046-.073-.066-.035-.123.027-.042.014-.038.009-.078-.006-.042.013-.048.046-.054.037-.007.053-.072.074-.103.005-.007.028-.065-.008-.05-.02.009-.005.034-.035.038-.022.004-.044-.011-.066-.011-.026 0-.053.013-.076-.003.012-.014.096-.084.03-.098-.027-.006-.006.038-.041.032-.007.035-.05.032-.07.054.009-.037.087-.065.061-.095.056-.049.068-.058-.008-.085-.12-.042-.11-.165-.028-.239.074-.068.198-.154.27-.041.079.121.128.033.192-.045-.021-.009-.002-.015-.009-.042-.07.029-.134-.063-.085-.118.03-.033.075-.024.114-.034.035-.009.066-.043.08-.075-.029.008-.025-.01-.014-.023-.018-.002-.037-.01-.052-.015-.043-.015-.04-.048-.085-.054-.108-.016.112-.14.005-.14-.035-.001-.065-.053-.09-.043-.019.007-.024.021-.045.012-.015-.006-.033-.019-.05-.009-.04.024-.047-.005-.084.006-.031.01-.048.04-.083.032.035-.048.079-.088.11-.138a.249.249 0 01.081-.086c.019-.011.072-.022.075-.048.005-.043-.022-.039-.051-.022a6.919 6.919 0 00-.232.144c-.046.029-.081.054-.137.046-.044-.007-.061.041-.096.037-.017-.067-.387.176-.432.197-.072.032-.153.087-.23.106-.032.008-.098.082-.094 0-.04-.005-.069.035-.095.055-.038.029-.082.047-.123.072-.087.056-.169.123-.25.186-.076.06-.153.13-.234.184-.028.019-.13.071-.127.11.072.014.318-.294.387-.211.018.021-.104.083-.124.095-.017.009-.037.008-.053.017-.022.013-.036.035-.057.049a.591.591 0 00-.142.13c-.028.037-.049.085-.08.119.004-.036-.003-.062-.002-.097-.04.026-.057.07-.113.058-.051-.012-.092.04-.128.068-.085.065-.142.137-.213.213-.04.043-.082.073-.107.126-.027.057-.064.108-.099.161-.066.097-.142.186-.207.283-.133.199-.22.427-.33.639-.057.11-.11.218-.134.341-.02.106-.02.214-.018.322.06-.047.057.051.041.08a.463.463 0 00-.038.146c-.01.065-.022.13-.022.196 0 .056-.018.108-.019.162-.02-.016.024-.084-.016-.074-.02.005-.02.034-.025.049-.016.052-.086.047-.097.106-.006.036-.01.057-.034.086-.018.022 0 .032.003.054.01.052-.058.124-.04.166.017.041.005.087.024.126.01.02.032.046.023.071-.042.008.012.106.016.136.006.049.05.203.097.225.059.091.14.218.245.264.074.032.1-.064.142-.104a.494.494 0 01.189-.109c.058-.021.302-.092.185-.176zm.102 3.285c.012-.02.003-.071-.019-.088-.052-.044-.073.06-.039.091.013.033.043.022.058-.003zM3.5 7.369c-.015-.013-.025-.005-.026-.032 0-.024.003-.07-.029-.041-.009.003.003.008-.01.013-.009.003-.016-.004-.022-.007-.016-.007-.026-.008-.039.01-.009.012-.009.026-.024.036l-.025.009c-.01.003-.035.021-.036.031-.004.015.019.026.035.03.012.009.03.017.042.026.013.009.034.025.05.029.035.02.09.042.118 0 .008-.016.014-.028.003-.042-.01-.015-.026-.019-.03-.031-.005-.013.006-.021-.007-.031zm4.745.755a.14.14 0 00-.067.026c-.03.026.034.041.058.048.028.016.067.024.094.04.023.017.038.04.064.051.032.015.075.022.11.031.014.005.037.004.057.008.022.013.031.033.05.047.03.028.073.035.114.033.038.004.067.011.101.002.04-.01.067.01.104.01.015 0 .03-.012.043-.011.019 0 .021.008.03.024.016.023.056.058.085.059.017 0 .031-.003.046.002.017.01.024.01.036.02.02.009.038.015.047.031.016.028.015.059.04.081l.052.04c.012.011.002.009.02.009.01.002.028.002.04-.002.05-.003.024-.073.008-.096-.01-.02-.019-.036-.015-.055.003-.023.014-.039-.001-.058a.075.075 0 00-.03-.024c-.006-.008-.008-.016-.015-.028-.015-.019-.044-.025-.063-.043-.031-.032-.048-.078-.088-.108-.022-.013-.042-.003-.068-.014-.011-.007-.017-.014-.033-.019-.015-.005-.028-.002-.041-.003-.029-.002-.054-.027-.081-.025-.03.004-.037.037-.055.055-.015.013-.033.013-.04-.008-.001-.027.009-.043.023-.06.021-.023 0-.036-.029-.038-.036 0-.043.029-.058.06-.024.033-.039.01-.072.005-.023.001-.039.01-.06.001-.015-.005-.018-.017-.029-.024a.036.036 0 00-.041.002c-.017.004-.017.004-.034-.005-.015-.006-.019-.018-.037-.022-.03-.006-.06.019-.085.012-.011-.006-.02-.022-.035-.027-.017-.01-.014-.001-.025.011-.018.018-.044.024-.062.01-.022-.016-.024-.043-.058-.048zm1.127 1.182c.016-.002.024-.018.037-.016.016-.003.008.013.02.023.009.009.019.009.029.009.017.003.052.005.059-.011.008-.025-.034-.03-.045-.05-.01-.029.013-.057.021-.082.012-.034-.03-.049-.026-.076-.001-.029.018-.039.012-.067a.162.162 0 00-.035-.059c-.012-.016-.035-.031-.033-.054.002-.024.046-.023.025-.052-.012-.025-.043-.02-.072-.024-.01 0-.02.001-.03-.009-.009-.014-.005-.021-.005-.031-.006-.027-.026-.037-.05-.048-.008-.004-.02-.009-.025-.021-.004-.012.008-.016.004-.027-.012-.026-.06.01-.08.001-.013-.002-.011-.015-.02-.029l-.024-.011c-.033-.015-.045.012-.04.039.015.061.06.101.055.162a.207.207 0 00.016.06c.008.033.016.049.002.081-.024.018-.002.04.006.063.004.031.012.055.011.088-.006.06-.024.119-.02.18.004.025.002.048.01.072.004.031.03.042.055.059.024.021.139.09.105.006-.01-.019-.025-.046-.03-.068-.008-.023.02-.039.02-.063.004-.027-.016-.036.022-.043.008-.006.02 0 .026-.002zM8.182 2.1c.03-.007.061.002.09-.009.015-.006.063-.023.06-.043-.005-.037-.162-.013-.188-.002-.007.023.016.041.037.047V2.1zm.754 6.688c-.006-.013 0-.025 0-.038-.003-.021-.01-.027-.006-.049.007-.012.007-.031.004-.046a.126.126 0 00-.025-.031.032.032 0 00-.01-.022c-.012-.012-.024.006-.037.012-.01.009-.029.015-.032.025-.01.015-.004.027-.004.04l.003.015c-.022.022 0 .08-.004.102 0 .025-.035.095.012.074.013-.006.023-.015.035-.021.015-.009.035-.009.054-.015.006 0 .04-.003.04-.009.001-.013-.027-.022-.03-.037zm-.891 1.264c.04.019.108-.019.146-.031.047-.015.122-.065.17-.037.02.011.03.034.05.043.026.011.057.001.083-.005.026-.006.057-.01.082-.022.021-.011.035-.029.054-.043.048-.037.09-.002.143-.01.03-.004.06-.019.089-.027.021-.005.06-.005.077-.021.018-.018.01-.057.01-.08-.001-.031 0-.063-.01-.092-.022-.057-.1-.124-.019-.169.016-.1-.1-.083-.134-.155-.022-.047-.029-.083-.091-.088-.052-.005-.084.023-.13.041-.05.019-.09.002-.134-.023-.027-.015-.083-.05-.094-.004-.01.04.028.079-.003.115-.028.032-.076.046-.116.055-.085.018-.153.084-.216.141l.007.006c-.024-.001-.06.065-.062.085l.03.009c-.001.034.037.011.04-.013.008.002.016.007.024.008.007.002.022.001.027.004.017.007.02.023.04.025-.01.052 0 .107-.025.156-.016.03-.095.104-.038.132zm.407-7.692c.03.032.066.041.06.091.037.005.06.019.082-.013a.12.12 0 01.058-.044c.027-.011.14-.01.136.037-.003.023-.017.043-.021.066-.005.032.03.009.044.017a.167.167 0 01-.058.024.033.033 0 01.016.024c-.026.006-.038.078-.084.092-.027.009-.068-.01-.096-.013-.032-.004-.057-.014-.09-.016-.03-.002-.005-.044-.045-.036-.007.028.007.099.012.127.005.035.035.055.07.061.048.008.07.024.112.048.032.018.069.007.104.01a.106.106 0 01.061.026c-.004.011-.012.029-.007.041.007.016.058-.002.07-.003.035-.004.069-.043.102-.038.013.002.072.02.07.035-.032-.013-.053.026-.078.005-.021-.019-.08-.003-.042.024a.687.687 0 01.013.086c-.003.028-.054.058-.05.076.007.001.053.004.062.013.003-.012-.005-.017.022-.025a.094.094 0 01.066.002c.008.035-.017.071.03.062.046-.009.066.021.113-.01a.066.066 0 01.087.011c.035.034-.035.081.005.114.016.013.029.053.045.06.01.005.07-.016.08-.021.02.034.036-.018.05-.021a.078.078 0 01.06-.05c.04-.004.041.003.068.022.078.054.067-.078.108-.112.073-.06.11-.117.16-.194.039-.062.094-.077.164-.088.055-.009.14-.022.163-.082.027-.07-.038-.108-.094-.129-.063-.022-.134-.046-.106-.126.032-.093.004-.147-.095-.177-.208-.065-.396-.174-.608-.234a2.557 2.557 0 00-.57-.082c-.085-.03-.266-.033-.319.04-.033.047.01.088.005.137a.22.22 0 00.065.163zm3.275 9.271l-.001-.001c.003.005.001.014.002.021.038 0 .055.035.097.022.042-.012.067-.053.033-.087-.03-.029-.055-.054-.098-.046-.052.01-.04.051-.033.091zm1.34-1.337l-.005-.026c-.04-.012-.066.03-.104-.001-.072.049.005.146-.113.14.02.025.019.053.009.082-.015.045-.027.041-.057.047-.065.01-.095-.03-.115-.084-.063.002-.15.1-.2.131-.012.007-.035.028-.049.037l-.05.027c-.034.017-.106.04-.11.078-.017-.003-.043.007-.06.005-.006.008-.006.017 0 .026.077.013.118-.013.183-.041.068-.031.141-.024.205-.048.03-.011.032-.045.082-.025.022.01.047.042.052.064.01.05-.042.124-.094.127-.013-.031.006-.063.011-.088-.069-.023-.182.075-.2.133.07.015.1.119.061.176-.012.014-.027.032-.052.04-.04.012-.06-.025-.099.004-.05.039.005.146-.024.206-.023.046-.061.063-.094.095-.022.023-.035.048-.064.068-.039.026-.132.082-.124.136.084.029.26-.119.333-.168.046-.031.075-.079.122-.11.054-.033.124-.05.158-.109.02-.034.004-.064.016-.098.01-.03.032-.04.051-.063.037-.044.07-.058.112-.094.051-.046.04-.118.063-.179.02-.053.061-.094.09-.144.044-.079.16-.267.111-.356-.012.01-.033.007-.044.012zm1.008-2.559c-.025-.048.013-.186.013-.243 0-.105-.033-.184-.047-.282-.01-.092-.022-.336.012-.419.047-.117-.184-.315-.197-.442a.396.396 0 00-.164-.277c-.036-.027-.115-.39-.161-.373-.023.011.024.091.021.116-.013.088-.057 0-.103.02-.086.035-.177.118-.188.203-.04.315-.263-.011-.245-.024.049-.038.067-.026.125-.034.064-.023-.036-.069.065-.079-.024-.065.03-.086.004-.137-.039-.075-.066-.066-.028-.147.017-.044-.084-.183-.091-.236-.008-.052-.01-.12-.016-.178-.004-.037.056-.072.045-.101-.002-.103.02-.214-.016-.314-.025-.068-.055-.158-.098-.216a.727.727 0 01-.066-.152c-.012-.064-.04-.04-.076-.065a.794.794 0 00-.135-.12 1.639 1.639 0 01-.199-.181c-.015-.045-.111-.08-.1-.129.015-.074-.242-.266-.314-.279-.047-.008.142.218.14.213.004.013.122.164.122.164.027.009.092.194.09.218-.007.07-.188-.115-.201-.14-.09-.109-.25-.197-.352-.27-.072-.067-.036-.105-.16-.162-.045-.021-.168-.122-.207-.125-.046-.002.007.096.008.107.007.07.083.075.129.121.036.038.069.085.037.127 0 0-.057.104-.06.095.016.044.147.141.18.177-.006-.009.171.224.186.1.006-.045-.044-.099-.038-.138.005-.024.204.227.215.249.048.133.044-.02.094-.004.042.013.153.152.06.158-.14.009.026.132.066.151.081.04.138.133.223.168.133.054.105.15.172.248.022.031-.383 0-.414.018-.053.042.203.329.204.372.002.09.053.156.067.246.008.083-.002.192.052.259.045.041.086-.068.156-.003.026.012.062.041.07.063.024.062.158.441-.003.413-.07-.013-.03.298-.025.343.021.098.06.09.035.214.003.103-.08.155-.139.229a.333.333 0 00-.058.117c-.033-.032-.048-.083-.094-.1-.05-.019-.158.041-.201.062-.105.053-.028.149-.07.232-.029.061-.118.091-.176.121-.07.036-.164.074-.233.016-.059-.048-.033-.145-.095-.187-.07-.047-.077.058-.093.1-.03.079-.122.106-.099.205.01.041.03.078.039.119.01.051-.016.097-.019.148-.006.087.085.107.109.178.02.064-.001.163-.072.187-.076.027-.16-.042-.235-.05-.075-.008-.171.013-.185.099-.013.076.064.138.027.216-.016.033-.044.059-.063.089-.035.05-.055.108-.087.159.038.001.034-.023.069-.016.036.008.069-.029.1-.041.006.024.003.049.006.073.025.008.05-.002.074-.011.002.021-.007.045.001.066.007.018.028.024.04.038.03.037-.007.098-.029.13-.062.092-.168.143-.237.229-.066.08-.071.177-.12.264-.017.03-.033.071.011.085.01-.016.025-.029.045-.029.031-.001.02.022.035.04.064.082.132-.053.16-.092.027-.042.142-.105.173-.035.025.053-.004.128-.028.176.041.019.03.049.04.085.012.05.057.082.057.137 0 .066-.144.197-.087.247.07.062.153-.11.18-.147.053-.071.172-.081.202-.168.032-.099.021-.158.152-.161.056-.001.096-.036.148-.047.058-.011.083-.017.12-.061.052-.063.1.012.101.062.002.051-.02.115.011.161.039.056.081-.018.12-.054-.003.038.047.06.077.072.045-.031.074-.082.122-.11a.212.212 0 01.074-.022c.007.041.014.085.05.105.053.03-.012.059.058.091.085.033.114.12.155.19.02.032.2-.163.269-.17.229-.026.348-.325.433-.502.122-.253.178-.534.21-.795.077-.161.109-.456.077-.643-.019-.114.046-.272-.012-.38zm-2.072 3.797c.006-.028.065-.132.01-.147-.02-.005-.036.025-.054.03-.024.008-.05-.007-.071.004-.02.011-.039.043-.05.061-.015.022-.01.031.014.043.024.013.055.019.068.045.012.023.006.054.003.078 0-.001.004-.005.005-.009a.038.038 0 01.015-.001l-.005.01c.063.01.058-.073.065-.114zm.74-1.251c.001.03.034.027.055.019.02-.006.033-.023.046-.038.018-.023.028-.046.013-.073a.28.28 0 01-.034-.081c-.013.007-.028.019-.042.023-.014.005-.016.001-.032 0-.036-.001-.028.027-.044.05-.013.02-.042.028-.03.054.007.02.04.037.058.046l.005-.006c0 .002-.002.003-.003.005a.017.017 0 00.007.001zM9.18 12.428c.037-.065.102-.106.16-.151a1.14 1.14 0 00.188-.185c-.033-.008-.035-.039-.056-.059-.031-.031-.08-.011-.086-.058-.007-.042-.042-.051-.075-.068-.077-.039-.109-.115-.171-.168-.068-.06-.16-.04-.244-.056-.073-.014-.147-.131-.225-.081-.049.031-.072.11-.038.159.026.038.072.057.09.102-.027.025-.033.041 0 .064.038.027.112.055.093.114-.01.032-.036.063-.07.069-.025.005-.086-.009-.073.036-.027-.074-.105.042-.148-.019-.034-.049-.056-.093-.11-.126-.07-.043.028-.085.017-.15-.018-.095-.134-.069-.175-.139-.025-.04.009-.072.025-.107.015-.036.058-.007.08.003a.25.25 0 00.245-.029c.029-.024.092-.135.012-.135-.055.001-.098.049-.15.052-.008-.063-.037-.17.03-.212.06-.038.19-.082.135-.18-.02-.034-.054.022-.083-.003-.012-.01-.003-.033 0-.044a.179.179 0 01-.045-.062c-.044-.106.084-.189.03-.301a.274.274 0 00-.103-.104c-.043-.03-.045-.068-.06-.113-.009-.025-.05-.084-.085-.069-.031.012-.04.065-.064.087-.053.052-.165.072-.236.055-.058-.013-.055-.035-.082-.073-.01-.014-.029-.015-.044-.021-.025-.01-.028-.033-.034-.056-.024-.087-.196.021-.222-.101-.006-.028.004-.075-.037-.081-.045-.008-.047-.052-.047-.089 0-.03.002-.072-.03-.089-.04-.022-.05-.012-.063-.058-.015-.059-.055.002-.089-.01-.07-.028-.058.007-.115.037-.098.052-.109-.189-.142-.236-.065-.09-.049.111-.093.136-.04.023-.083-.03-.098-.061-.008-.018-.013-.038-.024-.056-.017-.026-.047-.037-.063-.063-.014-.023-.035-.05-.045-.075-.009-.022-.007-.05-.024-.068-.02-.023.005-.061.02-.09.026-.01.064.01.083.027.046.039.117.21.197.178-.016-.022-.005-.049-.017-.073-.013-.025-.038-.04-.057-.06-.041-.048-.086-.096-.114-.154-.024-.05-.036-.103-.084-.138-.04-.029-.117-.057-.1-.119v-.002c.033.007.056.031.08.052.034.03.078.045.119.065.074.036.16.061.223.116.04.033.019.107.068.148.036.03.09.131.158.091.024-.015.035-.044.06-.061.027-.019.07-.036.102-.05.018-.009.05-.006.065-.021.023-.023-.033-.089-.046-.106-.05-.065-.096-.136-.164-.185-.034-.025-.068-.052-.108-.069-.022-.009-.06-.008-.064-.038.01.007.017.005.019-.006-.001-.02-.03-.021-.044-.025-.033-.009-.056-.009-.069-.037-.017-.034-.076-.033-.107-.041-.048-.012-.085-.048-.13-.066-.054-.02-.094.001-.147.013-.009.002-.026.033-.043.059a.128.128 0 00-.11.02c-.048.037-.076.093-.113.139-.016.019-.039.038-.061.031-.004-.002-.002-.007-.005-.009.028-.205.044-.412.025-.371-.037.08-.065.136-.093.194-.042-.018-.09-.019-.108.025-.019.047.006.108-.024.149-.006.011-.017.01-.027.015-.002-.005-.012-.018-.011-.019l-.018.033a.33.33 0 01-.102-.023l-.001-.003-.002.002c-.044-.015-.09-.029-.129-.015-.079.028-.082.141-.132.21-.075.105-.268.06-.302-.065l.082-.102a.29.29 0 00-.27-.18c-.033.001-.067.007-.097-.007-.03-.015-.047-.047-.074-.067-.083-.062-.193.02-.262.097a.489.489 0 00-.302.183l-.141-.012c.027.076-.064.138-.106.208-.051.085-.025.184.026.275-.006.014-.01.029-.023.035-.06.032-.044.051-.027.116a.554.554 0 01-.003.217c-.01.044-.053.15-.106.125-.028-.014-.057-.025-.083.001a.083.083 0 00-.024.04.3.3 0 00-.052.007c-.034.007-.069.015-.102.001-.032-.014-.076-.041-.112-.029-.03.01-.09.037-.104.069-.006.014.013.051.013.07 0 .034.026.085.015.116-.025-.012-.061-.016-.078-.041-.016-.021-.04-.016-.057-.038-.004.038-.018.091-.063.101-.044.01-.086-.025-.13-.013-.117.03.07.176.094.204.042.047.055.109.086.162.034.058.103.077.143.128.034.043.04.101.089.133.053.037.101.07.123.133.023-.022.07.082.119-.001.025-.045.07-.084.1-.011.024.063 0 .103.053.158.042.043.04.094-.031.089.012.032.03.064 0 .093-.014.014-.053.043-.025.063.033-.015.067-.024.1-.039.035-.015.07-.051.111-.05.002.013-.055.051-.02.054.03.003.073-.028.096-.002.027.028-.007.071.01.102.015.032.068.008.094.013-.01.028-.052.023-.075.034.052.064-.016.158-.092.16-.036 0-.166-.149-.171-.053a.285.285 0 00.016.09c.012.035.097.02.128.033a.22.22 0 01.113.106c.017.046.055.076.07.12.029.082.107.093.188.117.107.032.055.199.049.279-.005.079.105.098.156.143.056.049.065.144-.028.152-.047.004-.126-.018-.144.043-.026.086.105.077.162.096.027.009.134.02.144.045.015.039.003.092.017.133.033.105.13.175.224.227.201.113.44.184.66.247a2.6 2.6 0 00.376.081c.122.016.23.006.334.074.072.047.118.012.192.025.031.006.045.035.069.052.026.021.057-.006.085.005a.076.076 0 00-.005-.055c.056.021.125.081.184.033.03-.024.05-.057.08-.08.036.003.072.005.109.005.152 0 .273-.07.395-.152.131-.088.29-.09.441-.104a1.45 1.45 0 00.479-.107c.128-.062.16-.175.197-.3.04-.136.158-.191.236-.301.092-.128.031-.295.106-.428zm-5.885-1.804a.1.1 0 00-.041-.071l-.002.009c-.034-.017-.038-.081-.083-.076-.038-.06-.132-.033-.162.022-.02.037.004.054.026.081.027.034.022.06.032.099.025.101.109.032.168.071.023.015.031.058.065.051.037-.009.036-.065.026-.09-.014-.036-.024-.057-.029-.096zm.788 1.191c.006-.017-.02-.036-.038-.035-.016.001-.03.023-.037.035a.054.054 0 00.048.082c.01-.019.007-.056.035-.059-.002-.009-.008-.012-.016-.015l.008-.008zm-.838-1.269a.054.054 0 01.009.007c.003-.005.006-.009.007-.015l-.016.008zm9.245 1.403c-.017.016-.012.034-.02.053-.009.023-.043.032-.062.044-.03.019-.04.064-.072.075-.014-.021-.035-.08-.063-.029-.017.033-.006.066-.033.096-.027.028-.025.062-.043.093a.273.273 0 01-.106.107c-.038.023-.046.066-.074.098-.03.035-.075.048-.115.066-.029.012-.076.046-.109.027-.043-.027.016-.075.037-.092.02-.016.113-.073.091-.105-.014-.021-.068-.018-.09-.016-.044.005-.077.05-.115.071a.723.723 0 01-.125.06c-.053.019-.057.069-.1.099a.204.204 0 01-.12.046c-.057 0-.054-.048-.071-.088-.022.003-.04.031-.061.04-.034.014-.056.03-.04.067.013.038-.14.073-.167.092-.006-.019.024-.039.036-.05-.047-.004-.1.037-.15.044-.045.006-.103.038-.11.086-.005.038-.055.037-.086.05-.053.022-.031.053-.04.095-.02.079-.185.019-.102-.086.03-.037.074-.061.101-.099.03-.044.036-.099.06-.146-.053.015-.092.045-.137.074-.05.033-.093.025-.149.014-.065-.014-.11.019-.17.034-.039.009-.125.006-.13.062-.003.036.06.043.08.064.03.032.064.079.09.115.02.028.098.067.093.103-.008.07-.096.058-.143.07-.048.012-.055.055-.09.081-.039.029-.092-.005-.135.013-.045.017-.076.057-.115.083-.065.045-.107-.004-.174-.007-.055-.002-.104.023-.155.034-.047.01-.103.018-.138.051-.078.07.172.051.196.049-.011.04-.022.087-.058.113-.046.033-.11.025-.162.037-.04.01-.097.055-.038.087.054.027.122.013.175-.006.061-.021.118-.054.183-.068.067-.015.137-.008.204-.02.072-.014.135-.053.202-.08a.569.569 0 01.2-.038c-.014.025-.082.023-.107.029-.05.01-.085.054-.137.051-.06-.002-.053.04-.095.05-.028.007-.093.071-.114.031-.015-.031-.046-.025-.056.013-.008.028.008.038-.03.039-.03 0-.044-.012-.07-.019-.054-.014-.077.041-.115.055-.055.021-.114.014-.168.049-.03.02-.064.026-.1.037-.066.021-.129.046-.195.068-.05.018-.102.04-.157.041-.023 0-.114-.016-.129.011-.027.05.057.031.075.021.05-.027.112-.011.168-.011a.39.39 0 00.188-.046c.017-.009.129-.033.135-.02.01.006.083-.021.096-.024l.18-.042c.182-.047.362-.118.54-.179.354-.12.68-.323.987-.529.14-.093.253-.215.404-.291.152-.076.288-.177.427-.272.136-.093.24-.221.353-.338.115-.119.211-.231.262-.389-.029-.007-.059.052-.082.063-.04.019-.109.009-.14.039zm-.85-.161c.034-.047.004-.111-.057-.074-.023.013-.02.039-.038.055-.018.017-.02-.003-.039-.008-.027-.006-.07.03-.079.054-.036-.001-.069.04-.052.072.048-.018.078-.063.13-.049.041.011.108-.015.134-.05z"/></svg>
\ No newline at end of file diff --git a/devtools/docs/user/network_monitor/request_list/network_message_list_63.png b/devtools/docs/user/network_monitor/request_list/network_message_list_63.png Binary files differnew file mode 100644 index 0000000000..255dab1f9c --- /dev/null +++ b/devtools/docs/user/network_monitor/request_list/network_message_list_63.png diff --git a/devtools/docs/user/network_monitor/request_list/network_monitor_columns_menu.png b/devtools/docs/user/network_monitor/request_list/network_monitor_columns_menu.png Binary files differnew file mode 100644 index 0000000000..5a347a9886 --- /dev/null +++ b/devtools/docs/user/network_monitor/request_list/network_monitor_columns_menu.png diff --git a/devtools/docs/user/network_monitor/request_list/network_request_list.png b/devtools/docs/user/network_monitor/request_list/network_request_list.png Binary files differnew file mode 100644 index 0000000000..2f570377df --- /dev/null +++ b/devtools/docs/user/network_monitor/request_list/network_request_list.png diff --git a/devtools/docs/user/network_monitor/request_list/nwmon-turtle-tooltip.png b/devtools/docs/user/network_monitor/request_list/nwmon-turtle-tooltip.png Binary files differnew file mode 100644 index 0000000000..8f17571f74 --- /dev/null +++ b/devtools/docs/user/network_monitor/request_list/nwmon-turtle-tooltip.png diff --git a/devtools/docs/user/network_monitor/request_list/request_blocking_panel.png b/devtools/docs/user/network_monitor/request_list/request_blocking_panel.png Binary files differnew file mode 100644 index 0000000000..a5d0024c11 --- /dev/null +++ b/devtools/docs/user/network_monitor/request_list/request_blocking_panel.png diff --git a/devtools/docs/user/network_monitor/request_list/search_panel.png b/devtools/docs/user/network_monitor/request_list/search_panel.png Binary files differnew file mode 100644 index 0000000000..4f9b1aae1f --- /dev/null +++ b/devtools/docs/user/network_monitor/request_list/search_panel.png diff --git a/devtools/docs/user/network_monitor/request_list/search_panel_matches.png b/devtools/docs/user/network_monitor/request_list/search_panel_matches.png Binary files differnew file mode 100644 index 0000000000..59fd659ccb --- /dev/null +++ b/devtools/docs/user/network_monitor/request_list/search_panel_matches.png diff --git a/devtools/docs/user/network_monitor/request_list/timeline.png b/devtools/docs/user/network_monitor/request_list/timeline.png Binary files differnew file mode 100644 index 0000000000..f479ff3439 --- /dev/null +++ b/devtools/docs/user/network_monitor/request_list/timeline.png diff --git a/devtools/docs/user/network_monitor/request_list/tracker_icon.png b/devtools/docs/user/network_monitor/request_list/tracker_icon.png Binary files differnew file mode 100644 index 0000000000..fa91611f34 --- /dev/null +++ b/devtools/docs/user/network_monitor/request_list/tracker_icon.png diff --git a/devtools/docs/user/network_monitor/request_list/unblockurl.png b/devtools/docs/user/network_monitor/request_list/unblockurl.png Binary files differnew file mode 100644 index 0000000000..b59042c413 --- /dev/null +++ b/devtools/docs/user/network_monitor/request_list/unblockurl.png diff --git a/devtools/docs/user/network_monitor/throttling/index.rst b/devtools/docs/user/network_monitor/throttling/index.rst new file mode 100644 index 0000000000..66dabf45b4 --- /dev/null +++ b/devtools/docs/user/network_monitor/throttling/index.rst @@ -0,0 +1,46 @@ +========== +Throttling +========== + +The network monitor allows you to throttle your network speed to emulate various connection speeds so you can see how your app will behave under different connection types. + +Throttling +********** + +The toolbar includes a Throttling dropdown, which allows you to throttle your network speed to emulate various different network speed conditions. Choose an option from the menu, and it will persist across reloads. + +.. image:: throttling.png + :class: border + +The characteristics emulated are: + +- Download speed +- Upload speed +- Minimum latency + +The table below lists the numbers associated with each network type, but please do not rely on this feature for exact performance measurements; it's intended to give an approximate idea of the user experience in different conditions. The speeds are expressed in multiples of bits per second. + +.. csv-table:: + :header: "Selection", "Download speed", "Upload speed", "Minimum latency" + :widths: auto + + GPRS, 50 Kbps, 20 Kbps, 500 + Regular 2G, 250 Kbps, 50 Kbps, 300 + Good 2G, 450 Kbps, 150 Kbps, 150 + Regular 3G, 750 Kbps, 250 Kbps, 100 + Good 3G, 1.5 Mbps, 750 Kbps, 40 + Regular 4G/LTE, 4 Mbps, 3 Mbps, 20 + DSL, 2 Mbps, 1 Mbps, 5 + Wi-Fi, 30 Mbps, 15 Mbps, 2 + Offline, 0 Mbps, 0 Mbps, 5 + +Network Monitor Features +************************ + +The following articles cover different aspects of using the network monitor: + +- :doc:`Toolbar <../toolbar/index>` +- :doc:`Network request list <../request_list/index>` +- :doc:`Network request details <../request_details/index>` +- :doc:`Network traffic recording <../recording/index/>` +- :doc:`Performance analysis <../performance_analysis/index>` diff --git a/devtools/docs/user/network_monitor/throttling/throttling.png b/devtools/docs/user/network_monitor/throttling/throttling.png Binary files differnew file mode 100644 index 0000000000..094eb33290 --- /dev/null +++ b/devtools/docs/user/network_monitor/throttling/throttling.png diff --git a/devtools/docs/user/network_monitor/toolbar/index.rst b/devtools/docs/user/network_monitor/toolbar/index.rst new file mode 100644 index 0000000000..9407c4fba0 --- /dev/null +++ b/devtools/docs/user/network_monitor/toolbar/index.rst @@ -0,0 +1,59 @@ +======================= +Network monitor toolbar +======================= + +The network monitor provides two toolbar areas, one above the main section, and another below. + +Toolbar +******* + +The toolbar is at the top of the main network monitor window. (Prior to Firefox 77, this toolbar was arranged somewhat differently.) + +.. image:: network_toolbar_callouts.png + :alt: Screenshot of the Network toolbar, without callouts for the parts + :class: border + +It provides: + +- An icon to clear the :doc:`network request list <../request_list/index>` +- A box enabling you to :ref:`filter requests <request-list-filtering-requests>` by URL and by properties. +- A set of tool icons: + + - Pause (or **resume**) recording network log + - **Search** the log + - **Request Blocking** + +- An array of buttons to filter the network request list by type: + + - by the content type of the response + - XHR requests + - WebSocket upgrades and messages (labeled **WS**) + - Other requests + +- A checkbox that allows you to disable caching. +- **Throttling** menu, to simulate various connection types +- A menu of other actions: + + - **Persist Logs**: By default, the Network Monitor is cleared each time you navigate to a new page or reload the current page. When you select **Persist Logs**, the log is not cleared on page load. + - **Import HAR** imports a HAR (HTTP Archive) file. + - **Save All as HAR** opens a file dialog box so you can save the current contents of the Network log as a HAR file with the extension ```.har```. + - **Copy All as HAR** copies the current contents of the Network log to the clipboard in HAR format. + +A second toolbar area at the bottom of the network monitor provides: + +.. image:: network_monitor_bottom_toolbar.png + +- An icon to launch :doc:`performance analysis <../performance_analysis/index>`. +- A summary of this page, including the number of requests, total size, and total time. + + +Network Monitor features +************************ + +The following articles cover different aspects of using the network monitor: + +- :doc:`Network request list <../request_list/index>` +- :doc:`Network request details <../request_details/index>` +- :doc:`Network traffic recording <../recording/index/>` +- :doc:`Performance analysis <../performance_analysis/index>` +- :doc:`Throttling <../throttling/index>` diff --git a/devtools/docs/user/network_monitor/toolbar/network_monitor_bottom_toolbar.png b/devtools/docs/user/network_monitor/toolbar/network_monitor_bottom_toolbar.png Binary files differnew file mode 100644 index 0000000000..fe89e59f00 --- /dev/null +++ b/devtools/docs/user/network_monitor/toolbar/network_monitor_bottom_toolbar.png diff --git a/devtools/docs/user/network_monitor/toolbar/network_toolbar_callouts.png b/devtools/docs/user/network_monitor/toolbar/network_toolbar_callouts.png Binary files differnew file mode 100644 index 0000000000..71189a9840 --- /dev/null +++ b/devtools/docs/user/network_monitor/toolbar/network_toolbar_callouts.png diff --git a/devtools/docs/user/network_monitor/wrench-icon.png b/devtools/docs/user/network_monitor/wrench-icon.png Binary files differnew file mode 100644 index 0000000000..b0d7a57776 --- /dev/null +++ b/devtools/docs/user/network_monitor/wrench-icon.png diff --git a/devtools/docs/user/page_inspector/3-pane_mode/2-pane-view-final.png b/devtools/docs/user/page_inspector/3-pane_mode/2-pane-view-final.png Binary files differnew file mode 100644 index 0000000000..0598aed36d --- /dev/null +++ b/devtools/docs/user/page_inspector/3-pane_mode/2-pane-view-final.png diff --git a/devtools/docs/user/page_inspector/3-pane_mode/3-pane-view-final.png b/devtools/docs/user/page_inspector/3-pane_mode/3-pane-view-final.png Binary files differnew file mode 100644 index 0000000000..df8b007dcf --- /dev/null +++ b/devtools/docs/user/page_inspector/3-pane_mode/3-pane-view-final.png diff --git a/devtools/docs/user/page_inspector/3-pane_mode/index.rst b/devtools/docs/user/page_inspector/3-pane_mode/index.rst new file mode 100644 index 0000000000..8cd0b09440 --- /dev/null +++ b/devtools/docs/user/page_inspector/3-pane_mode/index.rst @@ -0,0 +1,78 @@ +========================== +Page inspector 3-pane mode +========================== + +This article explains how to use the Page Inspector's 3-pane mode. + +Feature summary +*************** + +From Firefox 62 onwards, the :doc:`Page Inspector <../index>` has a new mode available — **3-Pane mode**. When activated, this allows you to see the following simultaneously: + + +- The :doc:`HTML pane <../how_to/examine_and_edit_html/index>` on the left hand side, as usual. + +- The :ref:`CSS Rules <page-inspector-how-to-examine-and-edit-css-examine-css-rules>` in the middle in their own separate pane, rather than as a tab. + +- The other CSS related features — such as :ref:`Computed styles view <page_inspector_how_to_examine_and_edit_css_examine_computed_css>`, :doc:`Animations view <../how_to/work_with_animations/index>`, and :doc:`Fonts view <../how_to/edit_fonts/index>` — in tabs on the right hand side, as usual. + +.. image:: 3-pane-view-final.png + :alt: The firefox page inspector in 3 pane mode, with HTML pane on left, CSS rules pane in center, and CSS tool tabs on right + :class: border + +.. note:: + + At narrower browser window widths, the tabs appear below the CSS Rules pane. + + +Having the CSS Rules in their own pane is very useful because it allows you to not only inspect your HTML and edit the CSS applied to it, but also see the effect this has on CSS features such as computed styles and grids in real time. You just need to have the relevant tab open to see the effect. + +A brief walkthrough +******************* + +The 3-pane inspector is disabled by default. It is enabled via a toggle control found in the tabs pane on the left hand side. + +.. image:: toggle-icon-final.png + :alt: a view of the tabs panel, showing the 2 to 3 pane toggle icon + :class: center + +Press the toggle control to toggle between the 2- and 3-pane views. + +.. image:: 2-pane-view-final.png + :alt: The firefox page inspector in 2 pane mode, with HTML pane on left and CSS tool tabs on right + :class: border + + +.. image:: 3-pane-view-final.png + :alt: The firefox page inspector in 3 pane mode, with HTML pane on left, CSS rules pane in center, and CSS tool tabs on right + :class: border + + +With the 3-pane mode enabled, you can observe live changes in CSS features as you edit the rules applied to the page. For example, you could edit a `CSS Grid <https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Grid_Layout>`_ property and observe the change immediately in the :doc:`Grid Inspector <../how_to/examine_grid_layouts/index>`. + +.. raw:: html + + <iframe width="560" height="315" src="https://www.youtube.com/embed/ELS2OOUvxIw" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe> + <br/> + <br/> + +Enabling the 3-pane inspector pre-Firefox 62 +******************************************** + +In earlier versions of Firefox (since Firefox 59/60), you can enable 3 pane mode in Release/Beta by going to about:config and flipping the following prefs to ``true``: + +``devtools.inspector.split-rule-enabled`` — this switches 3-pane mode on and off. + +``devtools.inspector.split-sidebar-toggle`` — this adds the UI toggle button that lets you toggle it on and off. + +In Firefox 61, these preferences got renamed to: + + +- ``devtools.inspector.three-pane-enabled`` +- ``devtools.inspector.three-pane-toggle`` + +You need to flip these two to ``true`` in Release/Beta to test the feature in Firefox 61. + +.. note:: + + The 3-pane inspector is already enabled in Nightly/Developer edition before Firefox 62. diff --git a/devtools/docs/user/page_inspector/3-pane_mode/toggle-icon-final.png b/devtools/docs/user/page_inspector/3-pane_mode/toggle-icon-final.png Binary files differnew file mode 100644 index 0000000000..437234bda8 --- /dev/null +++ b/devtools/docs/user/page_inspector/3-pane_mode/toggle-icon-final.png diff --git a/devtools/docs/user/page_inspector/how_to/debug_scrollable_overflow/index.rst b/devtools/docs/user/page_inspector/how_to/debug_scrollable_overflow/index.rst new file mode 100644 index 0000000000..795e8bc3ad --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/debug_scrollable_overflow/index.rst @@ -0,0 +1,24 @@ +========================= +Debug scrollable overflow +========================= + +A `scroll container <https://developer.mozilla.org/en-US/docs/Glossary/Scroll_container>`_ is created by applying `overflow: scroll <https://developer.mozilla.org/en-US/docs/Web/CSS/overflow>`_ to a container, or `overflow: auto <https://developer.mozilla.org/en-US/docs/Web/CSS/overflow>`_ when there is enough content to cause overflow. The Firefox DevTools make it easy to discover both scrollable elements and any elements that are causing overflow. + + +In the :ref:`HTML Pane <page_inspector_ui_tour_html_pane>`, ascrollable element has the ``scroll`` badge next to it, as shown in the following image: + +.. image:: scroll_hover.png + :alt: HTML Pane Scroll badge + :class: center + +You can toggle the ``scroll`` badge to highlight elements causing an overflow, expanding nodes as needed to make the nodes visible: + +.. image:: scroll_badge_pressed.png + :alt: Scroll badge toggled on 1 + :class: center + +You will also see an ``overflow`` badge next to the node causing the overflow. + +.. image:: overflow_badge.png + :alt: HTML Pane: Overflow badge + :class: center diff --git a/devtools/docs/user/page_inspector/how_to/debug_scrollable_overflow/overflow_badge.png b/devtools/docs/user/page_inspector/how_to/debug_scrollable_overflow/overflow_badge.png Binary files differnew file mode 100644 index 0000000000..49f11b96c0 --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/debug_scrollable_overflow/overflow_badge.png diff --git a/devtools/docs/user/page_inspector/how_to/debug_scrollable_overflow/scroll_badge_pressed.png b/devtools/docs/user/page_inspector/how_to/debug_scrollable_overflow/scroll_badge_pressed.png Binary files differnew file mode 100644 index 0000000000..f6071b8c2d --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/debug_scrollable_overflow/scroll_badge_pressed.png diff --git a/devtools/docs/user/page_inspector/how_to/debug_scrollable_overflow/scroll_hover.png b/devtools/docs/user/page_inspector/how_to/debug_scrollable_overflow/scroll_hover.png Binary files differnew file mode 100644 index 0000000000..7eba64c6fe --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/debug_scrollable_overflow/scroll_hover.png diff --git a/devtools/docs/user/page_inspector/how_to/edit_css_filters/click_to_edit_filter.png b/devtools/docs/user/page_inspector/how_to/edit_css_filters/click_to_edit_filter.png Binary files differnew file mode 100644 index 0000000000..f89427ef01 --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/edit_css_filters/click_to_edit_filter.png diff --git a/devtools/docs/user/page_inspector/how_to/edit_css_filters/css_filter_edit.png b/devtools/docs/user/page_inspector/how_to/edit_css_filters/css_filter_edit.png Binary files differnew file mode 100644 index 0000000000..9eeb63b57a --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/edit_css_filters/css_filter_edit.png diff --git a/devtools/docs/user/page_inspector/how_to/edit_css_filters/edit_filter_settings.png b/devtools/docs/user/page_inspector/how_to/edit_css_filters/edit_filter_settings.png Binary files differnew file mode 100644 index 0000000000..c93f688af7 --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/edit_css_filters/edit_filter_settings.png diff --git a/devtools/docs/user/page_inspector/how_to/edit_css_filters/filter_presets.png b/devtools/docs/user/page_inspector/how_to/edit_css_filters/filter_presets.png Binary files differnew file mode 100644 index 0000000000..a3edb85c50 --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/edit_css_filters/filter_presets.png diff --git a/devtools/docs/user/page_inspector/how_to/edit_css_filters/index.rst b/devtools/docs/user/page_inspector/how_to/edit_css_filters/index.rst new file mode 100644 index 0000000000..1cf3e9e4bd --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/edit_css_filters/index.rst @@ -0,0 +1,36 @@ +================ +Edit CSS filters +================ + +`CSS filter <https://developer.mozilla.org/en-US/docs/Web/CSS/filter>`_ properties in the :ref:`Rules view <page_inspector_ui_tour_rules_view>` have a circular gray and white swatch next to them: + +.. image:: click_to_edit_filter.png + :class: border + +Clicking the swatch opens a filter editor: + +.. image:: css_filter_edit.png + :class: center + +The filter editor lists each of the effects performed by that filter on a separate line. You can edit these lines, remove them individually, or drag the effects to change the order in which they are applied. + +You can also add new effects by selecting an effect from the dropdown list at the bottom of the dialog. Once you have selected the effect you want to add, click the plus sign (+) to the right of the dropdown list. + +.. image:: edit_filter_settings.png + :class: center + +Once you have added an effect, enter the settings you want and then press :kbd:`Enter` to update the effect. The change will be apparent as soon as you press :kbd:`Enter`. + +Saving filter presets +********************* + +From Firefox 42 onwards, you can also add filters to a list of presets. The list of presets will be preserved between browser sessions, making it easy to apply the settings in the future. You can save the current filter to the preset list: + + +1. Click to edit the filter, display the preset list by clicking the icon as shown below. +2. Type a name for your preset, and then click the plus sign to add it to the list of presets. + +.. image:: filter_presets.png + :class: center + +You can then apply saved filters to new elements. To apply one of your saved presets, click its name in the list. diff --git a/devtools/docs/user/page_inspector/how_to/edit_css_shapes/circle.png b/devtools/docs/user/page_inspector/how_to/edit_css_shapes/circle.png Binary files differnew file mode 100644 index 0000000000..4e8dc9ec3f --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/edit_css_shapes/circle.png diff --git a/devtools/docs/user/page_inspector/how_to/edit_css_shapes/clipped-margin-box.png b/devtools/docs/user/page_inspector/how_to/edit_css_shapes/clipped-margin-box.png Binary files differnew file mode 100644 index 0000000000..1ca15471c7 --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/edit_css_shapes/clipped-margin-box.png diff --git a/devtools/docs/user/page_inspector/how_to/edit_css_shapes/ellipse.png b/devtools/docs/user/page_inspector/how_to/edit_css_shapes/ellipse.png Binary files differnew file mode 100644 index 0000000000..473d7049fe --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/edit_css_shapes/ellipse.png diff --git a/devtools/docs/user/page_inspector/how_to/edit_css_shapes/enable-shapes-editor.png b/devtools/docs/user/page_inspector/how_to/edit_css_shapes/enable-shapes-editor.png Binary files differnew file mode 100644 index 0000000000..d0869701e9 --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/edit_css_shapes/enable-shapes-editor.png diff --git a/devtools/docs/user/page_inspector/how_to/edit_css_shapes/index.rst b/devtools/docs/user/page_inspector/how_to/edit_css_shapes/index.rst new file mode 100644 index 0000000000..d8eadf0c2c --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/edit_css_shapes/index.rst @@ -0,0 +1,104 @@ +======================= +Edit Shape Paths in CSS +======================= + +The Shape Path Editor is a tool that helps you see and edit shapes created using `clip-path <https://developer.mozilla.org/en-US/docs/Web/CSS/clip-path>`_ and also the CSS `shape-outside <https://developer.mozilla.org/en-US/docs/Web/CSS/shape-outside>`_ property and `<basic-shape> <https://developer.mozilla.org/en-US/docs/Web/CSS/basic-shape>`_ values. This guide walks you through all of the available options. + + +Activate / deactivate the Shape Path Editor +******************************************* + +The Shape Path Editor is accessed via the CSS Rules Panel, which can be opened as described in the guide to :doc:`Opening the Inspector <../open_the_inspector/index>`. Once you have selected your element, you should see the shape icon alongside any valid value, e.g. one for ``shape-outside``. + +.. image:: enable-shapes-editor.png + :class: border + + +Clicking the icon will cause the Editor to highlight the shape. + +.. image:: circle.png + :class: center + + +To deactivate the Shape Path Editor click on the icon again, or select another element or a different editor. Note that the Shape Path Editor does not persist between page reloads — if you reload your page you will need to select the element again. + + +Understanding the lines drawn by the editor +******************************************* + +Once you have selected a shape on your page, the Shape Path Editor will draw lines to help you understand the path that is being created. + + +- **A solid line** shows the outline of the shape that is wrapping the text. This is your shape. If the shape is clipped by the margin box then the margin box will make up part of this line. +- **A dashed line** demonstrates the outline of the shape which extends past the margin box reference; this is the area that will be clipped by the margin box. To understand the margin box, and other boxes used by CSS Shapes see our guide to `Shapes from box values <https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Shapes/From_box_values>`_. + +.. image:: clipped-margin-box.png + :class: center + + +Editing Basic Shapes +******************** + +The options given to you by the tool will differ depending on the type of basic shape that you are editing. Options can be accessed by activating the Shape Path Editor with a regular click on the icon, and you can use the context menu (:kbd:`Ctrl`/:kbd:`Cmd` + click) to access additional functionality. + +circle() +-------- + +If the value of ``shape-outside`` is ``circle()``, you are creating a `circle basic shape <https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Shapes/Basic_Shapes#circle()>`_. Clicking on the shapes icon next to the value of ``circle()`` will highlight the shape, and also give you the option to resize the circle or move its center. If you move or resize the circle past the margin box, the edges become clipped by it. + +.. image:: clipped-margin-box.png + :class: center + + +In the Rules Panel you can see the values for ``circle()`` change as you edit the shape. You can then copy these values back into your stylesheet to create the new, tweaked shape path. + + +ellipse() +--------- + +If the value of ``shape-outside`` is ``ellipse()`` then you are using the `ellipse basic shape <https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Shapes/Basic_Shapes#ellipse()>`_. The ``ellipse()`` value works in much the same way as ``circle()`` in the Shape Path Editor. An ellipse is a squashed circle and therefore has the option to resize horizontally and vertically when you click on the shapes icon. + +.. image:: ellipse.png + :class: center + + +inset() +------- + +If the value of ``shape-outside`` is ``inset()`` then you are using the `inset basic shape <https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Shapes/Basic_Shapes#inset()>`_, which enables the creation of offset values pulling the content in from the margin box. + +Each side of the rectangle can be targeted after clicking on the shapes icon to activate the Shape Path Editor, and dragging each side will update the values for the top, right, bottom, and left offset values. + +.. image:: inset.png + :class: center + + +polygon() +--------- + +If the value of ``shape-outside`` is ``polygon()`` then you are using the `polygon basic shape <https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Shapes/Basic_Shapes#polygon()>`_. This is the most complex of the basic shape values, therefore the tool gives you more options when editing these: + + +- Clicking on the shapes icon will activate the Shapes Path Editor and give you the option to move any of the points of your polygon shape. +- Double-click anywhere on a line of the shape and you will get a new point to adjust. +- Double click on an existing point and it will be removed. *Remember that a polygon needs at least three points*. + +.. image:: polygon-edit.png + :class: center + + +Moving and scaling shapes +------------------------- + +There is extra functionality available on the shape highlight — if you :kbd:`Ctrl`/:kbd:`Cmd` + click on the shapes icon for your shape the highlight will change, instead providing the ability to scale and/or move it. Once again, clipping will occur if you exceed the bounds of the margin box. + +.. image:: scaled-circle.png + :class: center + + +If your shape is a polygon, you also get the ability to rotate it around an axis. + +Browser support +*************** + +The Shape Path Editor currently works for shapes generated via `clip-path <https://developer.mozilla.org/en-US/docs/Web/CSS/clip-path>`_; it will also work for shapes generated via `shape-outside <https://developer.mozilla.org/en-US/docs/Web/CSS/shape-outside>`_ as of Firefox 62. diff --git a/devtools/docs/user/page_inspector/how_to/edit_css_shapes/inset.png b/devtools/docs/user/page_inspector/how_to/edit_css_shapes/inset.png Binary files differnew file mode 100644 index 0000000000..70968ea11f --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/edit_css_shapes/inset.png diff --git a/devtools/docs/user/page_inspector/how_to/edit_css_shapes/polygon-edit.png b/devtools/docs/user/page_inspector/how_to/edit_css_shapes/polygon-edit.png Binary files differnew file mode 100644 index 0000000000..90d9df8c31 --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/edit_css_shapes/polygon-edit.png diff --git a/devtools/docs/user/page_inspector/how_to/edit_css_shapes/scaled-circle.png b/devtools/docs/user/page_inspector/how_to/edit_css_shapes/scaled-circle.png Binary files differnew file mode 100644 index 0000000000..faa9935fd7 --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/edit_css_shapes/scaled-circle.png diff --git a/devtools/docs/user/page_inspector/how_to/edit_fonts/all-fonts-on-page_new63.png b/devtools/docs/user/page_inspector/how_to/edit_fonts/all-fonts-on-page_new63.png Binary files differnew file mode 100644 index 0000000000..8896ec40c7 --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/edit_fonts/all-fonts-on-page_new63.png diff --git a/devtools/docs/user/page_inspector/how_to/edit_fonts/change_font_after_cropped.png b/devtools/docs/user/page_inspector/how_to/edit_fonts/change_font_after_cropped.png Binary files differnew file mode 100644 index 0000000000..b5ff4d99a0 --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/edit_fonts/change_font_after_cropped.png diff --git a/devtools/docs/user/page_inspector/how_to/edit_fonts/change_font_before_cropped.png b/devtools/docs/user/page_inspector/how_to/edit_fonts/change_font_before_cropped.png Binary files differnew file mode 100644 index 0000000000..4a4437ecfc --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/edit_fonts/change_font_before_cropped.png diff --git a/devtools/docs/user/page_inspector/how_to/edit_fonts/font-italic_cropped.png b/devtools/docs/user/page_inspector/how_to/edit_fonts/font-italic_cropped.png Binary files differnew file mode 100644 index 0000000000..6d33a65246 --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/edit_fonts/font-italic_cropped.png diff --git a/devtools/docs/user/page_inspector/how_to/edit_fonts/font-size_cropped.png b/devtools/docs/user/page_inspector/how_to/edit_fonts/font-size_cropped.png Binary files differnew file mode 100644 index 0000000000..eea408e6c3 --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/edit_fonts/font-size_cropped.png diff --git a/devtools/docs/user/page_inspector/how_to/edit_fonts/font-weight_cropped.png b/devtools/docs/user/page_inspector/how_to/edit_fonts/font-weight_cropped.png Binary files differnew file mode 100644 index 0000000000..56510effc5 --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/edit_fonts/font-weight_cropped.png diff --git a/devtools/docs/user/page_inspector/how_to/edit_fonts/fonts-editor-closeup-63-cropped.png b/devtools/docs/user/page_inspector/how_to/edit_fonts/fonts-editor-closeup-63-cropped.png Binary files differnew file mode 100644 index 0000000000..e63bfc6f64 --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/edit_fonts/fonts-editor-closeup-63-cropped.png diff --git a/devtools/docs/user/page_inspector/how_to/edit_fonts/fonts-used.png b/devtools/docs/user/page_inspector/how_to/edit_fonts/fonts-used.png Binary files differnew file mode 100644 index 0000000000..f28a2c0e9b --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/edit_fonts/fonts-used.png diff --git a/devtools/docs/user/page_inspector/how_to/edit_fonts/fonts_62_tooltip_cropped.png b/devtools/docs/user/page_inspector/how_to/edit_fonts/fonts_62_tooltip_cropped.png Binary files differnew file mode 100644 index 0000000000..176d17c10c --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/edit_fonts/fonts_62_tooltip_cropped.png diff --git a/devtools/docs/user/page_inspector/how_to/edit_fonts/full-fonts-tab-new63.png b/devtools/docs/user/page_inspector/how_to/edit_fonts/full-fonts-tab-new63.png Binary files differnew file mode 100644 index 0000000000..2f3b73b032 --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/edit_fonts/full-fonts-tab-new63.png diff --git a/devtools/docs/user/page_inspector/how_to/edit_fonts/index.rst b/devtools/docs/user/page_inspector/how_to/edit_fonts/index.rst new file mode 100644 index 0000000000..8a08ca39fb --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/edit_fonts/index.rst @@ -0,0 +1,257 @@ +========== +Edit fonts +========== + + +This article provides a tour of the Font tools available in the Firefox DevTools. This tool contains several useful features for viewing and manipulating fonts applied to any document loaded in the browser including inspection of all fonts applied to the page, and precise adjustment of variable font axis values. + +.. note:: + + The updated Font tools as shown in this article are available in Firefox 63 onwards; if you are using an older version of Firefox the tools will not look or behave quite the same, but they will be similar (most notably the Font Editor will not be available). + + +The Fonts tab +************* + +The Fonts tab is located on the right-hand side of the :doc:`Page Inspector <../../index>` when it is docked to the bottom of the screen. When it is docked to the right or left sides of the screen, the Fonts tab appears beneath the HTML pane. To access it: + + +1. :doc:`Open the Page Inspector <../open_the_inspector/index>`. +2. Select the Fonts tab; the last of the tabs shown in the right-hand side of the CSS pane. + +.. image:: full-fonts-tab-new63.png + :class: border + + +The Fonts tab has three major sections: + +- "Fonts used" by the currently inspected element. +- The new Fonts Editor. In Firefox 61 and 62, this section does not exist. +- "All fonts on page" — This section lists all of the fonts in use on the page. In Firefox 61 and 62, this area is labeled "Other fonts in page" and doesn't include the fonts mentioned in the "Fonts used" section. + + +Fonts used +********** + +The top section of the Font Editor shows the fonts used by the currently inspected element, grouped by font family. + +.. image:: fonts-used.png + :class: border + +Fonts are considered "used" when there is text content in the inspected element that has the font applied to it. Empty elements will not have any fonts used and will display the message "No fonts were found for the current element." + +Fonts will be included in this section for one of the following reasons: + + +- They are listed in the element's ``font-family`` CSS declaration value. +- They are applied to the element as part of the browser's default styling (Times New Roman for most browsers), and no author-defined font has been supplied. +- They are used by a descendant of the inspected element, for example, when it is a container for other elements which have text content with fonts applied. +- They are system fallback fonts used when nothing from the ``font-family`` CSS declaration has been applied. + + +Fonts Editor +************ + +Firefox 63 adds the Font Editor — a new area below "Fonts used" with additional controls for editing the fonts’ characteristics. + +.. image:: fonts-editor-closeup-63-cropped.png + :class: border + + +For standard (static) fonts, you will be able to change the settings listed below + + +Size +---- + +The `font-size <https://developer.mozilla.org/en-US/docs/Web/CSS/font-size>`_ for the inspected element. + +.. image:: font-size_cropped.png + :class: border + + +This can be set using ``em``, ``rem``, ``%``, ``px``, ``vh``, or ``vw`` units. You can select values using the slider or enter a numeric value directly into the text box. + +.. note:: + If you want to use a different unit such as ``pt`` for ``font-size`` or ``line-height``, you can set the property value applied to the currently inspected element to use that unit via the :ref:`rules view <page_inspector_ui_tour_rules_view>`, and the font editor will automatically pick it up and make it available in the associated units dropdown menu. + + +Changing the unit of measure converts the numerical value to its equivalent in the new unit, so the same computed value is maintained. + +Example: If ``1rem`` is equivalent to 10 pixels, when you change the unit of measurement from ``rem`` to ``px``, ``2rem`` becomes ``20px``. + + +Line height +----------- + +The `line-height <https://developer.mozilla.org/en-US/docs/Web/CSS/line-height>`_ of the inspected element. + +.. image:: line-height_cropped.png + :class: border + + +This can be set using unitless, ``em``, *%*, or ``px`` units. You can select values using the slider or enter a numeric value directly into the text box. + +Changing the unit of measure changes the value relative to the ``font-size`` setting. + +Example: If the font is 20 pixels high and the line-height is ``1.5em``, when you change the unit of measure from ``em`` to ``px``, the value will become ``30px``. + + +Weight +------ + +The `font-weight <https://developer.mozilla.org/en-US/docs/Web/CSS/font-weight>`_ for the inspected element. + +.. image:: font-weight_cropped.png + :alt: Font weight setting + :class: border + + +You can select values using the slider or enter a numeric value directly into the text box. For non-variable fonts the slider ranges from 100 to 900 in increments of 100. + +.. note:: + For `variable fonts <https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Fonts/Variable_Fonts_Guide>`_ (see below) that define a ``wght`` variation axis, this range is custom. + + +Italic +------ + +The `font-style <https://developer.mozilla.org/en-US/docs/Web/CSS/font-style>`_ for the inspected element. + +.. image:: font-italic_cropped.png + :class: border + + +This setting toggles between ``italic`` and ``normal`` values for the ``font-style`` CSS property. + +.. note:: + + As you change settings, Firefox applies inline styles to the element to make the changes instantly visible on the page. + + +All fonts on page +***************** + +The remaining area, at the bottom of the Fonts tab, shows an expandable list of all of the fonts in use on the page. + +.. image:: all-fonts-on-page_new63.png + :class: border + + +The list is useful because you can easily determine whether a font is a web font or a font hosted on your system. + +Each font listed in this section shows you: + + +- The ``font-family`` identifier and full name of the font. +- The URL to the font file in the case of web fonts not available on your system, or "System" in the case of fonts loaded from your computer (either default system fonts, or web fonts that you've also got installed on your system). You can copy the URL to the font file by clicking on the icon to the right of the URL. +- The `@font-face <https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face>`_ descriptor that loads the font into the page, in the case of web fonts. The descriptor is expandable — when opened it shows its full syntax as defined in the stylesheet. +- A text sample, to give you an idea of what the font looks like when rendered. The default text for the sample is "Abc" but the preview text can be edited by clicking on the input field at the top of the section and entering a new value. Once entered, all of the sample text will be set to the same custom value. + + +Variable font support in Firefox Developer Tools +************************************************ + +Firefox 62 added support for variable fonts and Firefox 63 features support for editing the properties of variable fonts in the Font Editor. + +What are variable fonts? +------------------------ + +`Variable Fonts <https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Fonts/Variable_Fonts_Guide>`_, or **OpenType Font Variations**, define a new font file format that allows the font designer to include multiple variations of a typeface inside a single font file. That means you no longer have to apply several different web fonts to a single page to represent a complete typeface for which a variable font is available, provided it includes the desired values for the different characteristics you want to vary. + +Variable fonts make it easy to vary font characteristics in a much more granular fashion because their allowable ranges are defined by **axes of variation** (see `Introducing the 'variation axis' <https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Fonts/Variable_Fonts_Guide#introducing_the_'variation_axis'>`_ for more information). For example, `font-weight <https://developer.mozilla.org/en-US/docs/Web/CSS/font-weight>`_ can be set to any value between 1 and 1000 in variable fonts (although it is not guaranteed that a variable font will support this entire range). + +There are several registered axes. Although it isn't required that these axes be defined for every font, if the font designer *does* implement a registered axis, its behavior *must* follow the defined behavior. + +All variable font axes have a four-character axis tag. The CSS `font-variation-settings <https://developer.mozilla.org/en-US/docs/Web/CSS/font-variation-settings>`_ property uses the tag as part of the key-value pair. For example, to set `font-weight <https://developer.mozilla.org/en-US/docs/Web/CSS/font-weight>`_ using ``font-variation-settings``, you could do something like this: + + +.. code-block:: css + + font-variation-settings: "wght" 350; + + +However, you should only use ``font-variation-settings`` as a last resort if there is no basic font property available for setting those characteristic values (e.g. custom axes). + +.. note:: + Font characteristics set using ``font-variation-settings`` will always override those set using the corresponding basic font properties, e.g. ``font-weight``, no matter where they appear in the cascade. + + +Here are the registered axes along with their corresponding CSS properties: + + +.. list-table:: + :widths: 40 60 + :header-rows: 1 + + * - Axis Tab + - CSS Property + + * - "wght" + - `font-weight <https://developer.mozilla.org/en-US/docs/Web/CSS/font-weight>`_ + + * - "wdth" + - `font-stretch <https://developer.mozilla.org/en-US/docs/Web/CSS/font-stretch>`_ + + * - "slnt" (slant) + - `font-style <https://developer.mozilla.org/en-US/docs/Web/CSS/font-style>`_: ``oblique + angle`` + + * - "ital" + - `font-style <https://developer.mozilla.org/en-US/docs/Web/CSS/font-style>`_: ``italic`` + + * - "opsz" + - `font-optical-sizing <https://developer.mozilla.org/en-US/docs/Web/CSS/font-optical-sizing>`_ + + +Any axis that is not on the list of registered axes is considered a custom axis. Custom axes do not have corresponding CSS font properties. Font designers can define whatever axis they want; each one needs to be given a unique four-character tag. The axis name and its range is up to the font designer. + +.. note:: + Registered axis tags are identified using lower-case tags, whereas custom axes should be given upper-case tags. Note that font designers aren't forced follow this practice in any way, and some won't. The important takeaway here is that axis tags are case-sensitive. + + +.. warning:: + In order to use variable fonts, you need to make sure that your operating system is up to date. For example Linux OSes need the latest Linux Freetype version, and macOS prior to 10.13 does not support variable fonts. If your operating system is not up to date, you will not be able to use variable fonts in web pages or the Firefox Developer Tools. + + +Working with Variable fonts in the Font Editor +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If the inspected element uses a variable font, the Fonts tab shows the axes that have been implemented for that particular font, providing control to alter the value of each one. This is very useful for quickly finding out what axes are available in a particular font — they can vary quite dramatically as font designers can implement basically anything they like. + +.. image:: v_fonts_example_cropped.png + :class: border + + +You can adjust the axes individually or, if the font designer has included defined instances, you can select one from the "Instance" drop-down list and view the updates live on your page. + +Here are a couple of examples of fonts with different axes defined: + +.. image:: v_fonts-examples_cropped.png + :class: border + + +In the following example, you can see that the font "Cheee Variable" includes settings for Yeast and Gravity. These are custom axes defined by the font designer. + +.. image:: change_font_before_cropped.png + :class: border + + +The first image shows the font as it is used on the page with default settings. The second image shows the same font after selecting the "Hi Yeast Hi Gravity" variation. + +.. image:: change_font_after_cropped.png + :class: border + + +Tips +**** + +Finally, here are a few tips for making effective use of the Fonts tab: + + +- When using the Page Inspector's :doc:`3-pane mode <../../3-pane_mode/index>`, you can view the CSS rules for the inspected element simultaneously alongside the Fonts tab. +- If you hover over the `font-family <https://developer.mozilla.org/en-US/docs/Web/CSS/font-family>`_ property in the Rules view, a tooltip shows a sample of the font: + + .. image:: fonts_62_tooltip_cropped.png + :class: border + +- You'll also notice in the above screenshot that the font in the ``font-family`` font stack that is actually applied to the inspected element is underlined. This makes it easy to see exactly what is being applied where, when font stacks are specified. diff --git a/devtools/docs/user/page_inspector/how_to/edit_fonts/line-height_cropped.png b/devtools/docs/user/page_inspector/how_to/edit_fonts/line-height_cropped.png Binary files differnew file mode 100644 index 0000000000..21c3b25345 --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/edit_fonts/line-height_cropped.png diff --git a/devtools/docs/user/page_inspector/how_to/edit_fonts/v_fonts-examples_cropped.png b/devtools/docs/user/page_inspector/how_to/edit_fonts/v_fonts-examples_cropped.png Binary files differnew file mode 100644 index 0000000000..8489e04aef --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/edit_fonts/v_fonts-examples_cropped.png diff --git a/devtools/docs/user/page_inspector/how_to/edit_fonts/v_fonts_example_cropped.png b/devtools/docs/user/page_inspector/how_to/edit_fonts/v_fonts_example_cropped.png Binary files differnew file mode 100644 index 0000000000..6c3ea01f74 --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/edit_fonts/v_fonts_example_cropped.png diff --git a/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/add_new_rule.png b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/add_new_rule.png Binary files differnew file mode 100644 index 0000000000..85ec6e49aa --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/add_new_rule.png diff --git a/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/color_scheme_dark.png b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/color_scheme_dark.png Binary files differnew file mode 100644 index 0000000000..680708d33a --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/color_scheme_dark.png diff --git a/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/color_scheme_light.png b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/color_scheme_light.png Binary files differnew file mode 100644 index 0000000000..46da0f8872 --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/color_scheme_light.png diff --git a/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/color_scheme_null.png b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/color_scheme_null.png Binary files differnew file mode 100644 index 0000000000..f498ddf585 --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/color_scheme_null.png diff --git a/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/compat_view.png b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/compat_view.png Binary files differnew file mode 100644 index 0000000000..159b43fecf --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/compat_view.png diff --git a/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/computed_css.png b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/computed_css.png Binary files differnew file mode 100644 index 0000000000..cb58b1e39d --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/computed_css.png diff --git a/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/computed_css_details.png b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/computed_css_details.png Binary files differnew file mode 100644 index 0000000000..3c8d15719e --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/computed_css_details.png diff --git a/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/edit_rule_autocomplete.png b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/edit_rule_autocomplete.png Binary files differnew file mode 100644 index 0000000000..0b84b74c19 --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/edit_rule_autocomplete.png diff --git a/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/edit_rule_var_autocomplete.png b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/edit_rule_var_autocomplete.png Binary files differnew file mode 100644 index 0000000000..f881a3a28e --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/edit_rule_var_autocomplete.png diff --git a/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/editable-context-menu.png b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/editable-context-menu.png Binary files differnew file mode 100644 index 0000000000..3fc6df7dfc --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/editable-context-menu.png diff --git a/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/filter_rules.png b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/filter_rules.png Binary files differnew file mode 100644 index 0000000000..9e708b77be --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/filter_rules.png diff --git a/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/filter_rules_2.png b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/filter_rules_2.png Binary files differnew file mode 100644 index 0000000000..d76abc6e47 --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/filter_rules_2.png diff --git a/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/filter_rules_2_strict.png b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/filter_rules_2_strict.png Binary files differnew file mode 100644 index 0000000000..2a44bc79ce --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/filter_rules_2_strict.png diff --git a/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/filtered_rules.png b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/filtered_rules.png Binary files differnew file mode 100644 index 0000000000..b7f3628981 --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/filtered_rules.png diff --git a/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/firefox_compatibility_tootips.jpg b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/firefox_compatibility_tootips.jpg Binary files differnew file mode 100644 index 0000000000..9aa0b05047 --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/firefox_compatibility_tootips.jpg diff --git a/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/hover_indicators.png b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/hover_indicators.png Binary files differnew file mode 100644 index 0000000000..ce9f7f1ddc --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/hover_indicators.png diff --git a/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/index.rst b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/index.rst new file mode 100644 index 0000000000..8260bf5405 --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/index.rst @@ -0,0 +1,470 @@ +==================== +Examine and edit CSS +==================== + +You can examine and edit CSS in the Inspector's :ref:`CSS pane <page_inspector_ui_tour_rules_view>`. + + +.. _page-inspector-how-to-examine-and-edit-css-examine-css-rules: + +Examine CSS rules +***************** + +The :ref:`Rules view <page_inspector_ui_tour_rules_view>` lists all the rules that apply to the selected element, ordered from most-specific to least-specific: + +.. image:: rules_view_ff_87.png + :alt: Rules view panel as of Firefox 87 + :class: border + + +The six buttons on the right top of the rules view allow you to change the display of certain CSS and rules view features. You can: + + +- :ref:`toggle pseudo-classes <page-inspector-how-to-examine-and-edit-css-viewing-common-pseudo-classes>`; +- :ref:`toggle classes <page-inspector-how-to-examine-and-edit-css-viewing-and-changing-classes-on-an-element>` +- add a new rule; +- change the display based on :ref:`prefers-color-scheme media rules <page-inspector-view-media-rules-for-prefers-color-scheme>`. +- change the display based on :ref:`print media rules <page-inspector-view-media-rules-for-print>`. + +.. image:: rules_view_buttons_fx_72.png + :alt: Toolbar buttons of the Rules view, as of Fx 72 + :class: center + + +Invalid value warnings +---------------------- + +A warning icon appears next to unsupported CSS properties or rules that have invalid values. This can help you understand why certain styles are not being applied. In the following example, a spelling error, "background-colour" instead of "background-color" has made the rule invalid: + +.. image:: invalid_property.png + :class: border + + +Browser compat warnings +----------------------- + +CSS properties have varied level of support across different browsers. From Firefox 81, compatibility tooltips may be displayed next to any CSS properties that have known compatibility issues,as shown below. + +.. image:: firefox_compatibility_tootips.jpg + :alt: Tooltip displayed next to CSS element. Hover to find out browsers with compatibility issues. + :class: center + + +The tooltips, which arepopulated from the MDN `browser compatibility project <https://github.com/mdn/browser-compat-data>`_, identify the *reason* for the incompatibility (not supported, deprecated, experimental etc.), display icons for incompatible browsers, and provide a link to the associated property page for more information. + + +CSS Compatibility +----------------- + +In addition to compatibility tooltips, the *CSS Compatibility View* shows any CSS compatibility issues for both the selected element and for the current page (as a whole). + +.. image:: compat_view.png + :alt: Screenshot of the Compatibility view + :class: center + + +For more information see: :ref:`Page Inspector > CSS Compatibility View <page_inspector_ui_tour_compatibility_view>`. + + +Rule display +------------ + +It displays each rule as in a stylesheet, with a list of selectors followed by a list of ``property:value;`` declarations. + +.. image:: rules_pane.png + :class: center + + +- *Highlight matched elements*: next to the selector is a target icon: click this to highlight all nodes in the page that match this selector. +- *Overridden declaration*: declarations that are overridden by later rules are crossed out. See :ref:`overridden declarations <page-inspector-how-to-examine-and-edit-css-overridden-declarations>`. +- *Inactive rules* (not shown): if a rule is inactive (e.g., ``padding`` on a ``:visited`` pseudo-element), it is colored gray, with an info icon that gives more information when clicked. +- *Filter rules containing this property*: next to overridden declarations is an icon you can click to filter the rules list to show only those rules that include that property. See :ref:`overridden declarations <page-inspector-how-to-examine-and-edit-css-overridden-declarations>`. +- *Enable/disable*: if you hover over a declaration, a checkbox appears next to it: you can use this to toggle the declaration on or off. +- *Filename and line number*: on the right-hand side is a link to the rule. See :ref:`link to CSS file <page-inspector-how-to-examine-and-edit-css-link-to-css-file>`. + + +.. |image1| image:: screen_shot_2016-12-16_at_10.51.15_am.png + :width: 20 + +If the element has a `display: grid <https://developer.mozilla.org/en-US/docs/Web/CSS/display>`_ declaration, then it gets a grid icon next to it, like this: |image1|. Click that icon to display the grid overlaid on the page, including grid lines and tracks. See :doc:`Examine grid layouts <../examine_grid_layouts/index>` for more on this. + +To view `user-agent styles <https://developer.mozilla.org/en-US/docs/Web/CSS/Cascade>`_ (*i.e.,* browser-default CSS rules), enable "Inspector > Show Browser Styles" under the :doc:`developer tool settings <../../../settings/index>` panel. (Note that this setting is independent of the "Browser styles" checkbox in the :ref:`Computed view <page_inspector_how_to_examine_and_edit_css_examine_computed_css>`.) + +User-agent styles are displayed against a different background, and the link to the filename and line number contains the prefix ``(user agent)``: + +.. image:: user-agent_css.png + :class: border + + +.. _page_inspector_how_to_examine_and_edit_css_element_rule: + +element {} rule +--------------- + +The ``element {}`` rule at the top of the rules list isn't actually a CSS rule. It represents the CSS properties assigned to the element via its `style <https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes#attr-style>`_ attribute. + +.. |image2| image:: target-icon.png + :width: 20 + +This also gets the target icon: |image2|, giving you a convenient way to highlight the currently selected element in the page. + + +Filtering rules +--------------- + +There's a box at the top of the Rules view labeled "Filter Styles": + +.. image:: filter_rules.png + :class: border + +As you type: + +- any rules which don't contain the typed string at all are hidden +- any declarations which contain the typed string are highlighted + +.. image:: filtered_rules.png + :class: border + +Click the "X" at the end of the search box to remove the filter. + +.. note:: + While in the Rules view, you can press :kbd:`Ctrl` / :kbd:`Cmd` + :kbd:`F` to focus the search field. Once you've typed in a filter, you can press :kbd:`Esc` to remove it again. + + +.. raw:: html + + <iframe width="560" height="315" src="https://www.youtube.com/embed/9w8vDIWqnAE" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe> + <br/> + <br/> + +Strict search +~~~~~~~~~~~~~ + +By default, the search box highlights all declarations which contain any part of the string. For example, searching for "color" will highlight declarations containing `border-bottom-color <https://developer.mozilla.org/en-US/docs/Web/CSS/border-bottom-color>`_ and `background-color <https://developer.mozilla.org/en-US/docs/Web/CSS/background-color>`_ as well as just `color <https://developer.mozilla.org/en-US/docs/Web/CSS/color>`_: + +.. image:: filter_rules_2.png + :class: border + +If you enclose the search query in backticks, like this: `color`, the search is restricted to exact matches: + +.. image:: filter_rules_2_strict.png + :class: border + + +Expanding shorthand properties +------------------------------ + +`Shorthand properties <https://developer.mozilla.org/en-US/docs/Web/CSS/Shorthand_properties>`_ can be expanded to display their related longhand properties by clicking the arrow besides them. + + +Displaying pseudo-elements +-------------------------- + +The Rule view displays the following `pseudo-elements <https://developer.mozilla.org/en-US/docs/Web/CSS/Pseudo-elements>`_, if they are applied to the selected element: + +- ``::after`` +- ``::backdrop`` +- ``::before`` +- ``::first-letter`` +- ``::first-line`` +- ``::selection`` +- ``:-moz-color-swatch`` +- ``:-moz-number-spin-box`` +- ``:-moz-number-spin-down`` +- ``:-moz-number-spin-up`` +- ``:-moz-number-text`` +- ``:-moz-number-wrapper`` +- ``:-moz-placeholder`` +- ``:-moz-progress-bar`` +- ``:-moz-range-progress`` +- ``:-moz-range-thumb`` +- ``:-moz-range-track`` +- ``:-moz-selection`` + +If the selected element has pseudo-elements applied to it, they are displayed before the selected element but hidden by a disclosure triangle: + +.. image:: pseudo-elements.png + :class: border + + +Clicking the triangle displays them: + +.. image:: pseudo-elements_displayed.png + :class: border + + +.. _page-inspector-how-to-examine-and-edit-css-viewing-common-pseudo-classes: + +Viewing common pseudo-classes +----------------------------- + +There's a button to the right of the filter box: + +.. image:: show_pseudo_classes.png + :class: border + + +Click the button to see checkboxes that you can use to enable the `:hover <https://developer.mozilla.org/en-US/docs/Web/CSS/:hover>`_, `:active <https://developer.mozilla.org/en-US/docs/Web/CSS/:active>`_ and `:focus <https://developer.mozilla.org/en-US/docs/Web/CSS/:focus>`_, `:focus-within <https://developer.mozilla.org/en-US/docs/Web/CSS/:focus-within>`_, `:focus-visible <https://developer.mozilla.org/en-US/docs/Web/CSS/:focus-visible>`_, `:visited <https://developer.mozilla.org/en-US/docs/Web/CSS/:visited>`_, and `:target <https://developer.mozilla.org/en-US/docs/Web/CSS/:target>`_ pseudo-classes for the selected element: + + +.. image:: show_pseudo_classes_hover.png + :class: border + +This feature can also be accessed from the :ref:`popup menu in the HTML view <page-inspector-how-to-element-popup-context-menu>` + +If you enable one of these pseudo-classes for a node, an orange dot appears in the markup view next to all nodes to which the pseudo-class has been applied. In addition, the information that appears on the page itself show you what pseudo-class you are examining. For example: + +.. image:: hover_indicators.png + :class: border + + +.. _page-inspector-how-to-examine-and-edit-css-viewing-and-changing-classes-on-an-element: + +Viewing and changing classes on an element +------------------------------------------ + +With an element selected in the HTML pane, you can click the **.cls** button in the Rules pane toolbar, to display the classes defined on that element. + + +- You can clear the checkbox for a particular class name, to see how the element would appear without that class applied to it. +- You can add a class to the element by typing a name in the *Add new class* field below the Rules toolbar. From Firefox 81, autocompletions based on existing classes are suggested as you type. + + +.. _page-inspector-how-to-examine-and-edit-css-link-to-css-file: + +Link to CSS file +---------------- + +At the top right of each rule, the source filename and line number is displayed as a link: clicking it opens the file in the :doc:`Style Editor <../../../style_editor/index>`. + +You can copy the location of the source file: right-click the link and select "Copy Location". + +The Inspector understands CSS source maps. That means that if you are using a CSS preprocessor that has support for source maps, and you've enabled source map support in the :ref:`Style Editor settings <settings-style-editor>`, then the link will take you to the original source, not the generated CSS. Read more about CSS source map support in the :ref:`Style Editor documentation <style-editor-source-map-support>`. + + +.. _page-inspector-how-to-examine-and-edit-css-overridden-declarations: + +Overridden declarations +----------------------- + +If a CSS declaration is overridden by some other CSS rule with a greater weight, then the declaration is shown with a line through it. + +Overridden declarations have a funnel next to them. Click the funnel to filter the rule view to show only the rules applying to the current node that try to set the same property: that is, the complete cascade for the given property. + +This makes it easy to see which rule is overriding the declaration + + +.. _page-inspector-view-media-rules-for-print: + +View @media rules for Print +--------------------------- + +You can toggle the display into a mode that emulates @media rules for print. + +.. raw:: html + + <iframe width="560" height="315" src="https://www.youtube.com/embed/AEmq9hNDOGU" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe> + <br/> + <br/> + + +When on, any rules defined for printing the page will be displayed similar to the "Print Preview" mode that many word processing applications provide. + + +.. _page-inspector-view-media-rules-for-prefers-color-scheme: + +View @media rules for prefers-color-scheme +------------------------------------------ + +The color scheme simulator buttons can be used to test the rendering of styles based on the `prefers-color-scheme <https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-color-scheme>`_ media query (if any are defined for the page). There are two buttons, which enable the light and dark preference, respectively. Selecting either button deselects the other. If neither button is selected then the simulator does not set a preference, and the browser renders using the default feature value set by the operating system. + + +.. |image3| image:: color_scheme_null.png + :class: border + +.. |image4| image:: color_scheme_light.png + :class: border + +.. |image5| image:: color_scheme_dark.png + :class: border + + +.. list-table:: + :widths: 30 20 50 + :header-rows: 1 + + * - Icon + - Value + - Description + + * - |image3| + - null + - The ``prefers-color-scheme`` media feature is not set by the simulator. + + + * - |image4| + - ``light`` + - The ``prefers-color-scheme`` media feature is set to ``light``. + + * - |image5| + - ``dark`` + - The ``prefers-color-scheme`` media feature is set to ``dark``. + + +Note that if the operating system mode is set to a particular mode, then simulating that mode will not change page rendering (i.e. simulating dark mode when the operating system is using dark mode will not change the display). + +.. note:: + If ``privacy.resistFingerprinting`` has been set **true**, the `prefers-color-scheme <https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-color-scheme>`_ preference is forced to ``light``. You must set``privacy.resistFingerprinting`` to **false** in order to use this feature. + + +.. note:: + Before Firefox 87 this feature is behind the preference ``devtools.inspector.color-scheme-simulation.enabled``. + + +.. _page_inspector_how_to_examine_and_edit_css_examine_computed_css: + +Examine computed CSS +******************** + +To see the complete computed CSS for the selected element, select the :ref:`Computed panel <page_inspector_ui_tour_computed_view>` in the righthand pane.This panel shows the calculated value that each CSS property has for the selected element. (This calculated value is exactly the same as what `getComputedStyle <https://developer.mozilla.org/en-US/docs/Web/API/Window/getComputedStyle>`_ would return.) + +.. image:: computed_css.png + :class: border + + +You can :kbd:`Tab` through the stylesto select them, and you can find more information about each property— pressing :kbd:`F1` on a selected property will open up its MDN reference page. + +Clicking the arrow next to the property name (or pressing :kbd:`Enter` or :kbd:`Space` while it is selected) shows the rule that set this value, along with a link to the source filename and line number: + +.. image:: computed_css_details.png + :class: border + + +By default, this view only shows values that have been explicitly set by the page: to see all values, click the "Browser styles" box. You can :kbd:`Tab` through the filenames/line numbers; pressing :kbd:`Enter`/:kbd:`Return` will open up the relevant file at that point in the :doc:`Style Editor <../../../style_editor/index>`. + +Typing in the search box performs a live filtering of the list, so, for example, if you just want to see font-related settings, you can type "font" in the search box, and only properties with "font" in the name will be listed. You can also search for the values of properties: to find the rule responsible for setting the font to "Lucida Grande", type that in the search box. + +.. note:: + While in the Computed view, you can press :kbd:`Ctrl` / :kbd:`Cmd` + :kbd:`F` to focus the search field. Once you've typed in a filter, you can press :kbd:`Esc` to remove it again. + + +Edit rules +********** + +If you click on a declaration or a selector in the Rules view you can edit it and see the results immediately. You can also :kbd:`Tab` through the different existing properties and values, and start editing them by pressing :kbd:`Enter` or :kbd:`Space`. To add a new declaration to a rule, click on the last line of the rule (the line occupied by the closing brace). + +As you start typing a property name, you'll see a list of autocomplete suggestions. Press:kbd:`Tab` to accept the current suggestion or :kbd:`Up` and :kbd:`Down` to move through the list. The default choice is the most common property that starts with the letters you've typed. For example, here the user has typed "c" and the default choice is "color": + +.. image:: edit_rule_autocomplete.png + :class: border + + +If you enter an invalid value for a property when editing it, or an unknown property name, a yellow alert icon appears besides the declaration. + +Edits that you make in the Rules view are reflected in the :doc:`Style Editor <../../../style_editor/index>`, and vice versa. Any changes you make are temporary: reloading the page will restore the original styling. + +While you're editing CSS, the context menu you'll see is the normal one for working with editable text: + +.. image:: editable-context-menu.png + :class: center + + +CSS variable autocompletion +--------------------------- + +`CSS variable names <https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties>`_ will auto-complete depending on the variables defined in the CSS. If you enter ``var(`` into a property value and then type a dash (``-``), any variables you have declared in your CSS will then appear in an autocomplete list, which shows a color swatch so you can see exactly what color each variable choice is storing (`bug 1451211 <https://bugzilla.mozilla.org/show_bug.cgi?id=1451211>`_) + +.. image:: edit_rule_var_autocomplete.png + :class: border + + +In addition, hovering over a CSS variable name brings up a tooltip showing what color value is stored in that variable `bug 1431949 <https://bugzilla.mozilla.org/show_bug.cgi?id=1431949>`_. + +.. image:: var_value.png + :class: border + + +Editing keyboard shortcuts +-------------------------- + +You can use the arrow and page up/down keys (along with others) to increase/decrease numeric rules while editing: + + +- The :kbd:`Up` arrow increments values by 1 — for example, "1px" changes to "2px". +- :kbd:`Shift` + :kbd:`Up`/:kbd:`Down` increments or decrements values by 10. +- :kbd:`Ctrl` + :kbd:`Up`/:kbd:`Down` (on Linux and Windows) or :kbd:`Alt` + :kbd:`Up`/:kbd:`Down` (on Mac) increments or decrements values by 0.1. +- :kbd:`Shift` + :kbd:`Page up`/:kbd:`Page down` increments or decrements values by 100. + + +Track changes +------------- + +When you are editing the rules in the rules view, you can see the changes you have made in the Changes pane. + +.. image:: track_changes.png + :class: border + + +.. note:: + You can view changes made to the rules view only. If you edit the CSS using the Style Editor, the changes will not be shown in the changes pane. + + Also remember, as noted above, that changes you make to the CSS rules are temporary and will be reset if you reload the page. + + +If you are satisfied with the changes you have made, you can copy the new settings to page the edited rule into your stylesheet. Right-click on the changes panel and select **Copy Rule** from the context menu. + +.. image:: save_changes_panel.png + :class: border + + +The Copy Rule command copies the entire element, class, or id definition, including any unchanged rules and the rules that describe your changes. For example, copying the changes in the preceding image, you get the following: + +.. code-block:: css + + .text-content p { + box-sizing:border-box; + max-width:24rem; + text-decoration: underline; + color: cadetblue; + font-weight: bold; + } + + +.. _page_inspector_how_to_examine_and_edit_css_add_rules: + +Add rules +********* + +You can add new rules in the Rules view. Just right-click to show the context menu and select "Add rule". This will add a new CSS rule whose selector matches the currently selected node. + +.. image:: add_new_rule.png + :class: border + + +There's also a button that enables you to do the same thing: + +.. image:: rules_panel.png + :class: border + + +Copy rules +********** + +To copy rules, and pieces of rules, use one of the following context menu items in the Rules view: + + +- Copy Rule +- Copy Selector +- Copy Property Declaration +- Copy Property Name +- Copy Property Value + +.. image:: rules_context_menu.png + :class: center + + +See also +******** + +- Complete list of Page Inspector :ref:`Keyboard shortcuts <keyboard-shortcuts-page-inspector>`. +- The Inspector also includes a number of specialized tools for working with particular CSS features, such as colors, fonts, and animations. To read about these see the list of :doc:`how to guides <../../index>`. diff --git a/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/invalid_property.png b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/invalid_property.png Binary files differnew file mode 100644 index 0000000000..2015da3d84 --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/invalid_property.png diff --git a/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/pseudo-elements.png b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/pseudo-elements.png Binary files differnew file mode 100644 index 0000000000..45dd756270 --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/pseudo-elements.png diff --git a/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/pseudo-elements_displayed.png b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/pseudo-elements_displayed.png Binary files differnew file mode 100644 index 0000000000..6f8f2df915 --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/pseudo-elements_displayed.png diff --git a/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/rules_context_menu.png b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/rules_context_menu.png Binary files differnew file mode 100644 index 0000000000..f9b04aad7b --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/rules_context_menu.png diff --git a/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/rules_pane.png b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/rules_pane.png Binary files differnew file mode 100644 index 0000000000..93572dfc00 --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/rules_pane.png diff --git a/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/rules_panel.png b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/rules_panel.png Binary files differnew file mode 100644 index 0000000000..0e37e4f376 --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/rules_panel.png diff --git a/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/rules_view_buttons_fx_72.png b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/rules_view_buttons_fx_72.png Binary files differnew file mode 100644 index 0000000000..34a9de97e7 --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/rules_view_buttons_fx_72.png diff --git a/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/rules_view_ff_87.png b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/rules_view_ff_87.png Binary files differnew file mode 100644 index 0000000000..0d92933d8a --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/rules_view_ff_87.png diff --git a/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/save_changes_panel.png b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/save_changes_panel.png Binary files differnew file mode 100644 index 0000000000..6637725c27 --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/save_changes_panel.png diff --git a/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/screen_shot_2016-12-16_at_10.51.15_am.png b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/screen_shot_2016-12-16_at_10.51.15_am.png Binary files differnew file mode 100644 index 0000000000..3cb6150e42 --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/screen_shot_2016-12-16_at_10.51.15_am.png diff --git a/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/show_pseudo_classes.png b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/show_pseudo_classes.png Binary files differnew file mode 100644 index 0000000000..6436db0188 --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/show_pseudo_classes.png diff --git a/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/show_pseudo_classes_hover.png b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/show_pseudo_classes_hover.png Binary files differnew file mode 100644 index 0000000000..e4f078722e --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/show_pseudo_classes_hover.png diff --git a/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/target-icon.png b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/target-icon.png Binary files differnew file mode 100644 index 0000000000..54ab83e68e --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/target-icon.png diff --git a/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/track_changes.png b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/track_changes.png Binary files differnew file mode 100644 index 0000000000..5ab5cb6f5a --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/track_changes.png diff --git a/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/user-agent_css.png b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/user-agent_css.png Binary files differnew file mode 100644 index 0000000000..8bc5fe28d1 --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/user-agent_css.png diff --git a/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/var_value.png b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/var_value.png Binary files differnew file mode 100644 index 0000000000..333367b35b --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/var_value.png diff --git a/devtools/docs/user/page_inspector/how_to/examine_and_edit_html/child-node-indicator.png b/devtools/docs/user/page_inspector/how_to/examine_and_edit_html/child-node-indicator.png Binary files differnew file mode 100644 index 0000000000..e0626644f8 --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/examine_and_edit_html/child-node-indicator.png diff --git a/devtools/docs/user/page_inspector/how_to/examine_and_edit_html/custom_pc_01.png b/devtools/docs/user/page_inspector/how_to/examine_and_edit_html/custom_pc_01.png Binary files differnew file mode 100644 index 0000000000..94a66c4cf8 --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/examine_and_edit_html/custom_pc_01.png diff --git a/devtools/docs/user/page_inspector/how_to/examine_and_edit_html/custom_pc_02.png b/devtools/docs/user/page_inspector/how_to/examine_and_edit_html/custom_pc_02.png Binary files differnew file mode 100644 index 0000000000..496b9a0471 --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/examine_and_edit_html/custom_pc_02.png diff --git a/devtools/docs/user/page_inspector/how_to/examine_and_edit_html/edit_html.png b/devtools/docs/user/page_inspector/how_to/examine_and_edit_html/edit_html.png Binary files differnew file mode 100644 index 0000000000..698bce9182 --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/examine_and_edit_html/edit_html.png diff --git a/devtools/docs/user/page_inspector/how_to/examine_and_edit_html/editable-context-menu.png b/devtools/docs/user/page_inspector/how_to/examine_and_edit_html/editable-context-menu.png Binary files differnew file mode 100644 index 0000000000..cbc9415ce1 --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/examine_and_edit_html/editable-context-menu.png diff --git a/devtools/docs/user/page_inspector/how_to/examine_and_edit_html/html_breadcrumbs.png b/devtools/docs/user/page_inspector/how_to/examine_and_edit_html/html_breadcrumbs.png Binary files differnew file mode 100644 index 0000000000..d5cf8d0dd6 --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/examine_and_edit_html/html_breadcrumbs.png diff --git a/devtools/docs/user/page_inspector/how_to/examine_and_edit_html/html_tree.png b/devtools/docs/user/page_inspector/how_to/examine_and_edit_html/html_tree.png Binary files differnew file mode 100644 index 0000000000..ee08f0dc30 --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/examine_and_edit_html/html_tree.png diff --git a/devtools/docs/user/page_inspector/how_to/examine_and_edit_html/index.rst b/devtools/docs/user/page_inspector/how_to/examine_and_edit_html/index.rst new file mode 100644 index 0000000000..dcc688fd91 --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/examine_and_edit_html/index.rst @@ -0,0 +1,466 @@ +===================== +Examine and edit HTML +===================== + +You can examine and edit the page's HTML in the :ref:`HTML pane <page_inspector_ui_tour_html_pane>`. + + +Navigating the HTML +******************* + +.. _page-inspector-how-to-examine-and-edit-html-breadcrumbs: + +HTML breadcrumbs +---------------- + +At the bottom on the HTML pane is a breadcrumbs toolbar. This shows the complete hierarchy through the document for the branch containing the selected element: + +.. image:: html_breadcrumbs.png + :class: border + + +Hovering over a breadcrumb highlights that element in the page. + +The breadcrumbs bar has its own :ref:`keyboard shortcuts <keyboard-shortcuts-breadcrumbs-bar>`. + + +.. _page_inspector_how_to_examine_and_edit_html_searching: + +Searching +--------- + +The Page Inspector's search box matches all markup in the current document and in any frames. + +To start searching the markup, click in the search box to expand it or press :kbd:`Ctrl` + :kbd:`F` , or :kbd:`Cmd` + :kbd:`F` on a Mac. There are three types of searches that are performed automatically depending on what you enter, a full text search, a CSS selector search, and an XPath search. + + +Full text search +~~~~~~~~~~~~~~~~ + +The full text search will always be executed, independently of what you enter. That allows you to find CSS selectors and XPath expressions occurring within the text. + + +CSS selector search +~~~~~~~~~~~~~~~~~~~ + +You can search elements by entering a `CSS selector <https://developer.mozilla.org/en-US/docs/Glossary/CSS_Selector>`_ + +As you type, an autocomplete popup shows any class or ID attributes that match the current search term: + +.. image:: search_html.png + :class: border + + +Press :kbd:`Up` and :kbd:`Down` to cycle through suggestions, :kbd:`Tab` to choose the current suggestion, then :kbd:`Enter` to select the first node with that attribute. + + +To cycle through matches, press :kbd:`Enter`. You can cycle backwards through matches using :kbd:`Shift` + :kbd:`Enter`. + + +XPath search +~~~~~~~~~~~~ + +It is also possible to search via `XPaths <https://developer.mozilla.org/en-US/docs/Web/XPath>`_. This allows you to search for specific elements without the conflict of matching words within the text. For example, ``//a`` matches all `a <https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a>`_ elements but not the letter "a" within the text content. Furthermore it allows for some more advanced searches like finding elements that start with a specific text, for example. + +.. image:: xpath_search.png + :alt: Match of an Inspector search using an XPath expression + :class: border + + +HTML tree +--------- + +The rest of the pane shows you the page's HTML as a tree (this UI is also called the Markup View). Just to the left of each node is an arrow: click the arrow to expand the node. If you hold the Alt key while clicking the arrow, it expands the node and all the nodes underneath it. + +.. image:: html_tree.png + :alt: The new Firefox 57 inspector HTML tree. + :class: center + + +Moving the mouse over a node in the tree highlights that element in the page. + +Nodes that are not visible are shown faded/desaturated. This can happen for different reasons such as using `display: none <https://developer.mozilla.org/en-US/docs/Web/CSS/display>`_ or that the element doesn't have any dimensions. + +.. |image1| image:: child-node-indicator.png + :width: 20 + +There is an ellipsis shown between the opening and closing tag of an element when the node is collapsed if it has larger contents. Now children are indicated in the tree with this icon: |image1| + + +Markers ("badges") are displayed to the right of some nodes. The table below explains the meaning of each badge: + +.. |br| raw:: html + + <br/> + + +.. list-table:: + :widths: 25 75 + :header-rows: 0 + + * - ``event`` + - The element has one or several event listeners attached to it. Clicking the marker opens a tooltip listing the event listeners and allows you for each listener to switch to the line of JavaScript code in the :doc:`Debugger <../../../debugger/index>` where the listener is defined. + + * - ``scroll`` + - The element is a `scroll container <https://developer.mozilla.org/en-US/docs/Glossary/Scroll_container>`_, i.e. it has either ``overflow: scroll`` applied, or ``overflow: auto`` and sufficient content to cause `scrollable overflow <https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Overflow>`_. |br| |br| If preference ``devtools.overflow.debugging.enabled`` is ``true``, toggling the ``scroll`` badge will highlight any elements causing the overflow, and these nodes will additionally display the ``overflow`` badge. + + * - ``overflow`` + - The element is causing `scrollable overflow <https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Overflow>`_ in a `scroll container <https://developer.mozilla.org/en-US/docs/Glossary/Scroll_container>`_ (either the current node or a parent node—the affected nodewill display the ``scroll`` badge). |br| |br| **Note**: The ``overflow`` badge is introduced in Firefox 83. In earlier versions it can be enabled using the preference ``devtools.overflow.debugging.enabled`` is ``true``. + + * - ``grid`` + - The element is a `grid container <https://developer.mozilla.org/en-US/docs/Glossary/Grid_Container>`_, i.e. it has `display: grid <https://developer.mozilla.org/en-US/docs/Web/CSS/display>`_ applied to it. Clicking the marker enables the grid highlighter. + + * - ``flex`` + - The element is a `flex container <https://developer.mozilla.org/en-US/docs/Glossary/Flex_Container>`_, i.e. it has `display: flex <https://developer.mozilla.org/en-US/docs/Web/CSS/display>`_ applied to it. Clicking the marker enables the flexbox highlighter. + + * - ``inline-grid`` + - The element is an inline grid container, i.e. it has `display: inline-grid <https://developer.mozilla.org/en-US/docs/Web/CSS/display>`_ or ``display: inline grid`` applied to it. Clicking the marker enables the grid highlighter. + + * - ``inline-flex`` + - The element is an inline flex container, i.e. it has `display: inline-flex <https://developer.mozilla.org/en-US/docs/Web/CSS/display>`_ or ``display: inline flex`` applied to it. Clicking the marker enables the flexbox highlighter. + + * - ``custom…`` + - The element is a custom element. Clicking the marker switches to the line of JavaScript code in the Debugger where the custom element got defined. + + + +.. note:: + There are some useful keyboard shortcuts that can be used in the HTML tree — see the :ref:`HTML pane keyboard shortcuts list <keyboard-shortcuts-html-pane>`. + + +::before and ::after +-------------------- + +You can inspect pseudo-elements added using `::before <https://developer.mozilla.org/en-US/docs/Web/CSS/::before>`_ and `::after <https://developer.mozilla.org/en-US/docs/Web/CSS/::after>`_ + +.. raw:: html + + <iframe width="560" height="315" src="https://www.youtube.com/embed/ecfqTGvzsNc" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe> + <br/> + <br/> + + +Custom element definition +------------------------- + +When you open the Inspector on a page that includes custom elements, you can view the class definition for the custom element in the Debugger: + + +1. Inspect the element +2. Click on the word ``custom`` + + +.. image:: custom_pc_01.png + :class: center + + +The source for the element's class will be displayed in the Debugger. + +.. image:: custom_pc_02.png + :class: center + + +Whitespace-only text nodes +-------------------------- + +Web developers don’t write all their code in just one line of text. They use white space such as spaces, returns, or tabs between their HTML elements because it makes markup more readable. + +Usually this white space seems to have no effect and no visual output, but in fact, when a browser parses HTML it will automatically generate anonymous text nodes for elements not contained in a node. This includes white space (which is after all a type of text). + +If these auto generated text nodes are `inline level <https://developer.mozilla.org/en-US/docs/Web/CSS/Visual_formatting_model#inline-level_elements_and_inline_boxes>`_, browsers will give them a non-zero width and height. Then you will find strange gaps between elements, even if you haven’t set any margin or padding on them. + +.. |image2| image:: new-whitespace-text-indicator.png + :width: 20 + +Since Firefox 52, the Inspector displays these whitespace nodes, so you can see where the gaps in your markup come from. Whitespace nodes are represented with a dot: |image2| and you get an explanatory tooltip when you hover over them: + +.. image:: white_space_only.png + :class: center + + +To see this in action, see the demo at https://firefox-devtools.github.io/devtools-examples/whitespace-only-demo/index.html. + + +Shadow roots +------------ + +Any shadow roots present in the DOM are exposed in the HTML page in the same manner as the regular DOM. The shadow root is signified by a node named ``#shadow-root`` — you can click its expansion arrow to see the full contents of the shadow DOM, and then manipulate the contained nodes in a similar way to other part of the page's DOM (although with a limited featureset — you can't, for example, drag and drop or delete shadow DOM nodes). + + +.. image:: inspector_shadowdom.png + :alt: A view of a shadow root shown inside the DOM tree in the Firefox DevTools + :class: center + + +If a shadow DOM contains a "slotted" element (an element with a ``slot`` attribute after it has been inserted inside a `slot <https://developer.mozilla.org/en-US/docs/Web/HTML/Element/slot>`_ element — see `Adding flexibility with slots <https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_templates_and_slots#adding_flexibility_with_slots>`_ for an explanation of how these are used), the "slotted" element will be shown inside its corresponding `slot <https://developer.mozilla.org/en-US/docs/Web/HTML/Element/slot>`_ element, with a "reveal" link alongside it. Clicking the "reveal" link will highlight the element with the ``slot`` attribute as it exists outside the shadow DOM + +.. image:: inspector_slot.png + :alt: A view of a shadow root shown inside the DOM tree in the Firefox DevTools + :class: center + + +This is very useful when you've got a ``<slot>`` element and you can't find the source of its content. + + +.. note:: + + Shadow DOM inspection was implemented in Firefox 61, but was hidden behind the ``dom.webcomponents.shadowdom.enabled`` pref until Firefox 63. It is now turned on by default. + + +.. _page-inspector-how-to-element-popup-context-menu: + +Element popup context menu +-------------------------- + +You can perform certain common tasks on a specific node using a popup context menu. To activate this menu, context-click the element. The menu contains the following items — click on the links to find the description of each command in the :ref:`Context menu reference <page_inspector_how_to_examine_and_edit_html_context_menu_reference>`: + + +- Edit As HTML +- Create New Node +- Duplicate Node +- Delete Node +- Attributes + + - Add Attribute + - Copy Attribute Value + - Edit Attribute + - Remove Attribute + +- Break on ... + + - Subtree Modification + - Attribute Modification + - Node Removal + +.. _page_inspector_how_to_examine_and_edit_html_use_in_console: + +- Use in Console +- Show DOM Properties +- Show Accessibility Properties +- Change Pseudo-class + + - hover + - active + - focus + - focus-visible + - focus-within + - visited + +- Screenshot Node + +.. _page_inspector_how_to_examine_and_edit_scroll_into_view: + +- Scroll Into View +- Copy + + - Inner HTML + - Outer HTML + - CSS Selector + - CSS Path + - XPath + - Image Data-URL + - Attribute + +- Paste + + - Inner HTML + - Outer HTML + - Before + - After + - As First Child + - As Last Child + +- Expand All +- Collapse All +- Open Link in New Tab [1] +- Open File in Debugger [1] +- Open File in Style-Editor [1] +- Copy Link Address [1] + + +[1] These options only appear in certain contexts, for example the "Open File in Style-Editor" option only appears when you context-click over the top of a link to a CSS file. + + +.. _page_inspector_how_to_examine_and_edit_html_context_menu_reference: + +Context menu reference +---------------------- + +.. list-table:: + :widths: 30 70 + :header-rows: 0 + + * - Edit as HTML + - :ref:`Edit the element's HTML <page-inspector-how-to-examine-and-edit-html-editing_html>`. + + * - (Copy) Inner HTML + - Copy the inner HTML for the element. + + * - (Copy) Outer HTML + - Copy the outer HTML for the element. + + Pressing :kbd:`Ctrl` + :kbd:`C` (or :kbd:`Cmd` + :kbd:`C` on a Mac) also performs this action. + + + * - (Copy) Unique Selector/CSS Selector + - Copy a CSS selector that uniquely selects the element. + + * - (Copy) CSS Path + - Copy a CSS selector that represents the full path to the element. + + * - (Copy) Image Data-URL + - Copy image as a data:// URL, if the selected element is an image. + + * - (Copy) Attribute + - Copy the attribute of the element. + + * - Show DOM Properties + - Open the :doc:`split console <../../../web_console/split_console/index>` and enter the console command "``inspect($0)``" to :doc:`inspect <../../../web_console/index>` the currently selected element. + + * - Use in Console + - Assigns the currently selected node to a variable named ``temp0`` (or ``temp1`` if ``temp0`` is already taken, and so on), then opens the :doc:`split console <../../../web_console/split_console/index>`, enabling you to interact with that node using the console's command line. + + * - Expand All + - In the tree view, expand the current element and all the elements underneath it. This is equivalent to holding the :kbd:`Alt` key and clicking the disclosure triangle next to an element. + + * - Collapse + - In the tree view, collapse the current element. This is equivalent to clicking the disclosure arrow next to an element that's expanded. + + * - (Paste) Inner HTML + - Paste the clipboard contents into the node as its `innerHTML <https://developer.mozilla.org/en-US/docs/Web/API/Element/innerHTML>`_. + + * - (Paste) Outer HTML + - Paste the clipboard contents into the node as its `outerHTML <https://developer.mozilla.org/en-US/docs/Web/API/Element/outerHTML>`_. + + * - (Paste) Before + - Paste the clipboard contents into the document immediately before this node. + + * - (Paste) After + - Paste the clipboard contents into the document immediately after this node. + + * - (Paste) As First Child + - Paste the clipboard contents into the document as the first child of this node. + + * - (Paste) As Last Child + - Paste the clipboard contents into the document as the last child of this node. + + * - Scroll Into View + - Scrolls the web page so the selected node is visible. + + From Firefox 44, pressing the keyboard shortcut :kbd:`S` will also scroll the selected node into view. + + * - Screenshot Node + - Takes a screenshot of the selected node, saved to your Downloads directory. See :doc:`Taking screenshots <../../../taking_screenshots/index>`. + + * - Create New Node + - Create a new empty <div> as the last child of the currently selected element. See :ref:`Inserting new nodes <page-inspector-how-to-examine-and-edit-html-inserting-new-nodes>`. + + * - Duplicate Node + - Create a copy of this element, and insert the copy immediately after this element. + + * - Delete Node + - Delete the element from the DOM. + + * - Attribute/Add Attribute + - Add an attribute to the element. + + * - Attribute/Edit Attribute + - (only when invoked on an attribute) Edit the attribute. + + * - Attribute/Remove Attribute + - (only when invoked on an attribute) Remove the attribute. + + * - Open Link in New Tab + - (only when invoked over a link, such as an href attribute) Opens the linked item in a new tab. + + * - Open File in Debugger + - (only when invoked over a link to a JS source) Opens the linked source in the Debugger. + + * - Open File in Style-Editor + - (only when invoked over a link to a CSS source) Opens the linked source in the Style Editor. + + * - Copy Link Address + - (only when invoked over a URL) Copy the URL. + + * - (Change Pseudo-class) hover + - Set the `:hover <https://developer.mozilla.org/en-US/docs/Web/CSS/:hover>`_ CSS pseudo-class. + + * - (Change Pseudo-class) active + - Set the `:active <https://developer.mozilla.org/en-US/docs/Web/CSS/:active>`_ CSS pseudo-class. + + * - (Change Pseudo-class) focus + - Set the `:focus <https://developer.mozilla.org/en-US/docs/Web/CSS/:focus>`_ CSS pseudo-class. + + * - (Change Pseudo-class) focus-visible + - Set the `:focus-visible <https://developer.mozilla.org/en-US/docs/Web/CSS/:focus-visible>`_ CSS pseudo-class. + + * - (Change Pseudo-class) focus-within + - Set the `:focus-within <https://developer.mozilla.org/en-US/docs/Web/CSS/:focus-within>`_ CSS pseudo-class. + + * - (Change Pseudo-class) visited + - Set the :visited CSS pseudo-class. + + +.. _page-inspector-how-to-examine-and-edit-html-editing_html: + +Editing HTML +************ + +You can edit the HTML — tags, attributes, and content — directly in the HTML pane: double-click the text you want to edit, change it, and press Enter to see the changes reflected immediately. + +To edit an element's `outerHTML <https://developer.mozilla.org/en-US/docs/Web/API/Element/outerHTML>`_, activate the element's popup menu and select "Edit As HTML". You'll see a text box in the HTML pane: + +.. image:: edit_html.png + :alt: Edit HTML directly in the Inspector panel in Firefox 57 + :class: border + +You can add any HTML in here: changing the element's tag, changing existing elements, or adding new ones. Once you click outside the box, the changes are applied to the page. + +When you're editing HTML, the context menu you'll see is the normal one for working with editable text: + +.. image:: editable-context-menu.png + :class: center + + +Copy and paste +-------------- + +You can use the :ref:`popup menu <page-inspector-how-to-element-popup-context-menu>` to copy nodes in the HTML tree and paste them into the desired location. + + +Drag and drop +------------- + +You can reorganize the HTML content of a page by moving nodes in the HTML tree. Just click and hold on any element and drag it up or down in the tree. When you release the mouse button, the element will be inserted at the corresponding position: + +.. raw:: html + + <iframe width="560" height="315" src="https://www.youtube.com/embed/oI-a035nfWk" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe> + <br/> + <br/> + +You can cancel the drag and drop by pressing the :kbd:`Esc` key. + + +.. _page-inspector-how-to-examine-and-edit-html-inserting-new-nodes: + +Inserting new nodes +------------------- + +There's a "+" icon at the top of the markup view: + +.. image:: html_tree.png + :class: border + + +Click this icon to insert an empty {{HTMLElement("div")}} into the document as the last child of the currently selected element. You can then edit the new node's content and styling just as you would any other node in the document. + +.. raw:: html + + <iframe width="560" height="315" src="https://www.youtube.com/embed/NG5daffvVZM" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe> + <br/> + <br/> + +You can access the same functionality using the "Create New Node" popup menu item. + +Note that this button is disabled if the selected element's type is such that adding a last-child would have no effect (for example, if it is an `html <https://developer.mozilla.org/en-US/docs/Web/HTML/Element/html>`_ or `iframe <https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe>`_ element). However, it is enabled in places where it is not valid to insert a `div <https://developer.mozilla.org/en-US/docs/Web/HTML/Element/div>`_, such as `style <https://developer.mozilla.org/en-US/docs/Web/HTML/Element/style>`_ or `link <https://developer.mozilla.org/en-US/docs/Web/HTML/Element/link>`_. In these cases the element is added as text. diff --git a/devtools/docs/user/page_inspector/how_to/examine_and_edit_html/inspector_shadowdom.png b/devtools/docs/user/page_inspector/how_to/examine_and_edit_html/inspector_shadowdom.png Binary files differnew file mode 100644 index 0000000000..515ff2bfdc --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/examine_and_edit_html/inspector_shadowdom.png diff --git a/devtools/docs/user/page_inspector/how_to/examine_and_edit_html/inspector_slot.png b/devtools/docs/user/page_inspector/how_to/examine_and_edit_html/inspector_slot.png Binary files differnew file mode 100644 index 0000000000..590ba86f50 --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/examine_and_edit_html/inspector_slot.png diff --git a/devtools/docs/user/page_inspector/how_to/examine_and_edit_html/new-whitespace-text-indicator.png b/devtools/docs/user/page_inspector/how_to/examine_and_edit_html/new-whitespace-text-indicator.png Binary files differnew file mode 100644 index 0000000000..e925cabd49 --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/examine_and_edit_html/new-whitespace-text-indicator.png diff --git a/devtools/docs/user/page_inspector/how_to/examine_and_edit_html/search_html.png b/devtools/docs/user/page_inspector/how_to/examine_and_edit_html/search_html.png Binary files differnew file mode 100644 index 0000000000..c1b84eaa18 --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/examine_and_edit_html/search_html.png diff --git a/devtools/docs/user/page_inspector/how_to/examine_and_edit_html/white_space_only.png b/devtools/docs/user/page_inspector/how_to/examine_and_edit_html/white_space_only.png Binary files differnew file mode 100644 index 0000000000..d7a6f5c428 --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/examine_and_edit_html/white_space_only.png diff --git a/devtools/docs/user/page_inspector/how_to/examine_and_edit_html/xpath_search.png b/devtools/docs/user/page_inspector/how_to/examine_and_edit_html/xpath_search.png Binary files differnew file mode 100644 index 0000000000..95342b7f8d --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/examine_and_edit_html/xpath_search.png diff --git a/devtools/docs/user/page_inspector/how_to/examine_and_edit_the_box_model/box-model-tooltip.png b/devtools/docs/user/page_inspector/how_to/examine_and_edit_the_box_model/box-model-tooltip.png Binary files differnew file mode 100644 index 0000000000..0b83f8b144 --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/examine_and_edit_the_box_model/box-model-tooltip.png diff --git a/devtools/docs/user/page_inspector/how_to/examine_and_edit_the_box_model/box-model.png b/devtools/docs/user/page_inspector/how_to/examine_and_edit_the_box_model/box-model.png Binary files differnew file mode 100644 index 0000000000..cbb926183f --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/examine_and_edit_the_box_model/box-model.png diff --git a/devtools/docs/user/page_inspector/how_to/examine_and_edit_the_box_model/index.rst b/devtools/docs/user/page_inspector/how_to/examine_and_edit_the_box_model/index.rst new file mode 100644 index 0000000000..691630f211 --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/examine_and_edit_the_box_model/index.rst @@ -0,0 +1,52 @@ +============================== +Examine and edit the box model +============================== + +Viewing the box model +********************* + +With the :ref:`Select Element button <page_inspector_select_element_button>` pressed, if you hover over an element in the page, the `box model <https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Box_Model/Introduction_to_the_CSS_box_model>`_ for the element is shown overlaid on the page: + +.. raw:: html + + <iframe width="560" height="315" src="https://www.youtube.com/embed/vDRzN-svJHQ" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe> + <br/> + <br/> + + +It's also shown overlaid if you hover over an element's markup in the HTML pane: + +.. raw:: html + + <iframe width="560" height="315" src="https://www.youtube.com/embed/xA4IxTttNLk" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe> + <br/> + <br/> + +If the element is inline and is split over multiple line boxes, the highlighter shows each individual line box that together make up the element: + +.. image:: inline-box-model.png + :class: center + + +.. _page-inspector-how-to-examine-and-edit-the-box-model-view: + + +The Box Model view +------------------ + +When an element's selected, you can get a detailed look at the box model in the :ref:`Box Model view <page_inspector_ui_tour_computed_view>`: + +.. image:: box-model.png + :class: center + + +If you hover over a value, you'll see a tooltip telling you which rule the value comes from: + +.. image:: box-model-tooltip.png + :class: center + + +Editing the box model +********************* + +You can also edit the values in the :ref:`Box Model view <page-inspector-how-to-examine-and-edit-the-box-model-view>`, and see the results immediately in the page. diff --git a/devtools/docs/user/page_inspector/how_to/examine_and_edit_the_box_model/inline-box-model.png b/devtools/docs/user/page_inspector/how_to/examine_and_edit_the_box_model/inline-box-model.png Binary files differnew file mode 100644 index 0000000000..5da14d5e0f --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/examine_and_edit_the_box_model/inline-box-model.png diff --git a/devtools/docs/user/page_inspector/how_to/examine_event_listeners/index.rst b/devtools/docs/user/page_inspector/how_to/examine_event_listeners/index.rst new file mode 100644 index 0000000000..0595d6164b --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/examine_event_listeners/index.rst @@ -0,0 +1,27 @@ +======================= +Examine Event Listeners +======================= + +The inspector shows the word "event" next to elements in the :ref:`HTML Pane <page_inspector_ui_tour_html_pane>`, that have event listeners bound to them: + +.. image:: inspect_element_with_eventhandler.png + :class: border + +Click the icon, then you'll see a popup listing all the event listeners bound to this element: + +.. image:: inspector_event_handlers.png + :class: border + +Each line contains: + + +- a right-pointing arrowhead; click to expand the row and show the listener function source code +- the name of the event for which a handler was attached to this element +- the name and line number for the listener; you can also click here to expand the row and view the listener function source code +- a curved arrow pointing to a stack; click it to show the code for the handler in the debugger +- a label indicating whether the event bubbles +- a label indicating the system that defines the event. Firefox can display: + + - standard DOM events + - `jQuery events <https://api.jquery.com/category/events/>`_ + - `React events <https://facebook.github.io/react/docs/events.html>`_ diff --git a/devtools/docs/user/page_inspector/how_to/examine_event_listeners/inspect_element_with_eventhandler.png b/devtools/docs/user/page_inspector/how_to/examine_event_listeners/inspect_element_with_eventhandler.png Binary files differnew file mode 100644 index 0000000000..df8b66eb53 --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/examine_event_listeners/inspect_element_with_eventhandler.png diff --git a/devtools/docs/user/page_inspector/how_to/examine_event_listeners/inspector_event_handlers.png b/devtools/docs/user/page_inspector/how_to/examine_event_listeners/inspector_event_handlers.png Binary files differnew file mode 100644 index 0000000000..34e3efecee --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/examine_event_listeners/inspector_event_handlers.png diff --git a/devtools/docs/user/page_inspector/how_to/examine_flexbox_layouts/css-pane.png b/devtools/docs/user/page_inspector/how_to/examine_flexbox_layouts/css-pane.png Binary files differnew file mode 100644 index 0000000000..3cb2104e12 --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/examine_flexbox_layouts/css-pane.png diff --git a/devtools/docs/user/page_inspector/how_to/examine_flexbox_layouts/flex-cont.png b/devtools/docs/user/page_inspector/how_to/examine_flexbox_layouts/flex-cont.png Binary files differnew file mode 100644 index 0000000000..7eb08580a6 --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/examine_flexbox_layouts/flex-cont.png diff --git a/devtools/docs/user/page_inspector/how_to/examine_flexbox_layouts/flex-items.png b/devtools/docs/user/page_inspector/how_to/examine_flexbox_layouts/flex-items.png Binary files differnew file mode 100644 index 0000000000..8e423449ed --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/examine_flexbox_layouts/flex-items.png diff --git a/devtools/docs/user/page_inspector/how_to/examine_flexbox_layouts/flexbox_icon.gif b/devtools/docs/user/page_inspector/how_to/examine_flexbox_layouts/flexbox_icon.gif Binary files differnew file mode 100644 index 0000000000..53a045837e --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/examine_flexbox_layouts/flexbox_icon.gif diff --git a/devtools/docs/user/page_inspector/how_to/examine_flexbox_layouts/html-pane.png b/devtools/docs/user/page_inspector/how_to/examine_flexbox_layouts/html-pane.png Binary files differnew file mode 100644 index 0000000000..989bf63ec7 --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/examine_flexbox_layouts/html-pane.png diff --git a/devtools/docs/user/page_inspector/how_to/examine_flexbox_layouts/index.rst b/devtools/docs/user/page_inspector/how_to/examine_flexbox_layouts/index.rst new file mode 100644 index 0000000000..cbd14ea5e8 --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/examine_flexbox_layouts/index.rst @@ -0,0 +1,133 @@ +============================================== +CSS Flexbox Inspector: Examine Flexbox layouts +============================================== + +The **Flexbox Inspector** allows you to examine `CSS Flexbox Layouts <https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Flexible_Box_Layout>`_ using the Firefox DevTools, which is useful for discovering flex containers on a page, examining and modifying them, debugging layout issues, and more. + + +Discovering Flex Containers +*************************** + +When an HTML element on your page has `display: flex <https://developer.mozilla.org/en-US/docs/Web/CSS/display>`_ applied to it, a number of features are made available in the DevTools to provide easy access to Flexbox layout features. + + +In the HTML pane +---------------- + +In the :ref:`HTML Pane <page_inspector_ui_tour_html_pane>`, an element laid out with Flexbox has the word ``flex`` next to it as shown in the following image: + +.. image:: html-pane.png + :alt: Indicators in the inspector showing an element is a flex container + :class: center + + +Click the word ``flex`` in the HTML pane to keep the overlay visible when you move the mouse away from the container. + + +In the infobar +-------------- + +When you hover over an element in the HTML pane, you will see a tooltip that gives you more information about the element. When you hover over a flex container or flex item, the tooltip includes the appropriate information. + +This header is a flex container: + +.. image:: infobar-cont.png + :alt: Tooltip showing element is a flex container + :class: center + +Each navbar link is a flex item: + +.. image:: infobar-item.png + :alt: Tooltip showing an element is a flex item + :class: center + +The ``nav`` element within the header is both a flex item and a flex container which holds the navigation links: + +.. image:: infobar-both.png + :alt: Tooltip showing an element is both a flex container and a flex item + :class: center + + +In the CSS pane +--------------- + +.. |image1| image:: flexbox_icon.gif + :width: 20 + +In the :ref:`CSS pane <page_inspector_ui_tour_rules_view>`'s Rules view, any instance of a `display: flex <https://developer.mozilla.org/en-US/docs/Web/CSS/display>`_ declaration gets a small Flexbox icon |image1| next to the word ``flex``. + +.. image:: css-pane.png + :alt: The CSS pane of the Firefox devtools, showing the CSS for a flex container with an icon to toggle the Flexbox overly + :class: center + + +Clicking the icon toggles the display of an overlay on the page, which appears over the selected flex container that displays an outline around each flex item: + +.. image:: overlay.png + :alt: Flexbox overlay showing a flex container and its children + :class: center + + +The overlay will still be shown when you select other elements from the Inspector panel, so you can edit related CSS properties and see how the flex items are affected by your changes. + + +The Layout Flex Container section +--------------------------------- + +The CSS pane's Layout view includes a collapsible "Flex Container" section. If you expand the section without selecting a flexbox container, it will only display the message, "Select a Flex container or item to continue". Once you select an element whose display is defined as flex, the panel will include a number of options for viewing details about the flex container and flex items within it. You can find out more about those in the section below. + +.. note:: + + The Layout view can be found underneath the *Layout* tab on the right-hand pane of the Page Inspector. The above and below screenshots should give you further hints on how to get to this. + + +Flex Container options +********************** + +The Flex Container section of the Layout view looks like this: + +.. image:: flex-cont.png + :alt: Layout pane in Firefox Devtools showing options for the flexbox overlay + :class: center + + +There are two settings you can change in the Flex Container section: + + +- You can control the color of the overlay by clicking on the small circle next to the selector. This will toggle a color picker so you can select a different color for the overlay. +- The switch on the right-hand side of the Flex Container section will also toggle the overlay on and off. + + +Flex item properties +******************** + +The flex items within the flex container are displayed as a numbered list in the Flex Items section. Each entry displays the item's selector. Hover over an element to highlight it on the page. + +.. image:: flex-items.png + :alt: List of flex items displayed in the Layout pane of Firefox Devtools + :class: center + +If you click on the item, the display shifts to show details about that element: + +.. image:: item-details.png + :alt: Details of flex item sizing in the Layout pane of Firefox DevTools + :class: center + + +This view shows information about the calculations for the size of the selected flex item: + + +- A diagram visualizing the sizing of the flex item +- Content Size - the size of the component without any restraints imposed on it by its parent +- Flexibility - how much a flex item grew or shrunk based on its flex-grow value when there is extra free space or its flex-shrink value when there is not enough space +- Minimum Size (only appears when an item is clamped to its minimum size) - the minimum content size of a flex item when there is no more free space in the flex container +- Final Size - the size of the flex item after all sizing constraints imposed on it have been applied (based on the values of flex-grow, flex-shrink and flex-basis) + +At the top of the section is a drop-down list of all the items in the selected flexbox container: + +.. image:: select-items.png + :alt: Dropdown in Layout pane that allows you to select between different flex children + :class: border + + +You can use this drop-down to select any of the other flex items in the flex container. diff --git a/devtools/docs/user/page_inspector/how_to/examine_flexbox_layouts/infobar-both.png b/devtools/docs/user/page_inspector/how_to/examine_flexbox_layouts/infobar-both.png Binary files differnew file mode 100644 index 0000000000..90c528d096 --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/examine_flexbox_layouts/infobar-both.png diff --git a/devtools/docs/user/page_inspector/how_to/examine_flexbox_layouts/infobar-cont.png b/devtools/docs/user/page_inspector/how_to/examine_flexbox_layouts/infobar-cont.png Binary files differnew file mode 100644 index 0000000000..44dda1790e --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/examine_flexbox_layouts/infobar-cont.png diff --git a/devtools/docs/user/page_inspector/how_to/examine_flexbox_layouts/infobar-item.png b/devtools/docs/user/page_inspector/how_to/examine_flexbox_layouts/infobar-item.png Binary files differnew file mode 100644 index 0000000000..71b827be14 --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/examine_flexbox_layouts/infobar-item.png diff --git a/devtools/docs/user/page_inspector/how_to/examine_flexbox_layouts/item-details.png b/devtools/docs/user/page_inspector/how_to/examine_flexbox_layouts/item-details.png Binary files differnew file mode 100644 index 0000000000..05e25aae17 --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/examine_flexbox_layouts/item-details.png diff --git a/devtools/docs/user/page_inspector/how_to/examine_flexbox_layouts/overlay.png b/devtools/docs/user/page_inspector/how_to/examine_flexbox_layouts/overlay.png Binary files differnew file mode 100644 index 0000000000..048973f54c --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/examine_flexbox_layouts/overlay.png diff --git a/devtools/docs/user/page_inspector/how_to/examine_flexbox_layouts/select-items.png b/devtools/docs/user/page_inspector/how_to/examine_flexbox_layouts/select-items.png Binary files differnew file mode 100644 index 0000000000..82b26ab657 --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/examine_flexbox_layouts/select-items.png diff --git a/devtools/docs/user/page_inspector/how_to/examine_grid_layouts/css-pane.png b/devtools/docs/user/page_inspector/how_to/examine_grid_layouts/css-pane.png Binary files differnew file mode 100644 index 0000000000..39f785c741 --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/examine_grid_layouts/css-pane.png diff --git a/devtools/docs/user/page_inspector/how_to/examine_grid_layouts/extend-lines.png b/devtools/docs/user/page_inspector/how_to/examine_grid_layouts/extend-lines.png Binary files differnew file mode 100644 index 0000000000..32cc8ba968 --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/examine_grid_layouts/extend-lines.png diff --git a/devtools/docs/user/page_inspector/how_to/examine_grid_layouts/grid-named-areas.png b/devtools/docs/user/page_inspector/how_to/examine_grid_layouts/grid-named-areas.png Binary files differnew file mode 100644 index 0000000000..8d488f4a33 --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/examine_grid_layouts/grid-named-areas.png diff --git a/devtools/docs/user/page_inspector/how_to/examine_grid_layouts/grid-options.png b/devtools/docs/user/page_inspector/how_to/examine_grid_layouts/grid-options.png Binary files differnew file mode 100644 index 0000000000..12f2973c6f --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/examine_grid_layouts/grid-options.png diff --git a/devtools/docs/user/page_inspector/how_to/examine_grid_layouts/grid-overlay.png b/devtools/docs/user/page_inspector/how_to/examine_grid_layouts/grid-overlay.png Binary files differnew file mode 100644 index 0000000000..c039dbdb50 --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/examine_grid_layouts/grid-overlay.png diff --git a/devtools/docs/user/page_inspector/how_to/examine_grid_layouts/html-pane.png b/devtools/docs/user/page_inspector/how_to/examine_grid_layouts/html-pane.png Binary files differnew file mode 100644 index 0000000000..680dbf0f7c --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/examine_grid_layouts/html-pane.png diff --git a/devtools/docs/user/page_inspector/how_to/examine_grid_layouts/index.rst b/devtools/docs/user/page_inspector/how_to/examine_grid_layouts/index.rst new file mode 100644 index 0000000000..f8ae34c1ea --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/examine_grid_layouts/index.rst @@ -0,0 +1,189 @@ +======================================== +CSS Grid Inspector: Examine grid layouts +======================================== + +The **Grid Inspector** allows you to examine `CSS Grid Layouts <https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Grid_Layout>`_ using the Firefox DevTools, discovering grids present on a page, examining and modifying them, debugging layout issues, and more. + +.. note:: + + The examples shown in the screenshots appearing in this article are Jen Simmons' `Futurismo <https://labs.jensimmons.com/2016/examples/futurismo-1.html>`_ and `Variations on a grid <https://labs.jensimmons.com/2017/01-003.html>`_ experiments, and a `live named grid area example <https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Grid_Layout/Grid_Template_Areas#naming_a_grid_area>`_ from Rachel Andrew. + + +Discovering CSS grids +********************* + +When an HTML element on your page has `display: grid <https://developer.mozilla.org/en-US/docs/Web/CSS/display>`_ applied to it, a number of features are made available in the DevTools to provide easy access to grid features. + + +In the HTML pane +---------------- + +In the :ref:`HTML Pane <page_inspector_ui_tour_html_pane>`, elements laid out using a grid have a "grid" marker beside them. + +.. image:: html-pane.png + :alt: The HTML pane of the Firefox devtools, showing an element annotated with a grid marker, meaning that it has display: grid set on it + :class: border + + +In the CSS pane +--------------- + +.. |image1| image:: screen_shot_2016-12-16_at_10.51.15_am.png + :width: 20 + +In the :ref:`CSS pane <page_inspector_ui_tour_rules_view>`'s Rules view, any instance of a `display: grid <https://developer.mozilla.org/en-US/docs/Web/CSS/display>`_ declaration gets a grid icon included within it: |image1|. + +.. image:: css-pane.png + :alt: The CSS pane of the Firefox devtools, showing the CSS for a grid layout with a grid icon included next to display: grid + :class: border + + +Clicking the icon toggles the display of a grid overlay on the page, which appears over the element, laid out like a grid to show the position of its grid lines and tracks: + +.. image:: grid-overlay.png + :alt: A screenshot of the Firefox web browser, showing a colored overlay on top of a section of the page laid out like a grid + :class: border + + +The overlay is still shown when you select other elements, so you can edit related CSS properties and see how the grid is affected. + + +The Layout view Grid section +---------------------------- + +When grids are included on a page, the CSS pane's Layout view includes a "Grid" section containing a number of options for viewing those Grids. You can find out more about those in the section below. + +.. note:: + + The Layout view can be found underneath the *Layout* tab on the right-hand pane of the Page Inspector. The above and below screenshots should give you further hints on how to get to this. + + +Grid options +************ + +The Grid section of the Layout view looks like this: + +.. image:: grid-options.png + :alt: The grid options section of the Firefox devtools Layout view, showing multiple options for specifying how you want to see CSS grids displayed + :class: border + + +You'll see a number of options contained within: + + +- Overlay Grid: Contains a checkbox for each grid present on the page, along with various options. Allows overlay views to be toggled on and off. +- Grid Display Settings: + + - Display line numbers: Turn the line numbers shown for each grid overlay on and off (on by default). + - Display area names: Turn area names on and off, in the case of grids with named grid areas (on by default, where relevant). + - Extend lines infinitely: By default, grid lines/tracks are only shown inside the element with ``display: grid`` set on it; when toggling this option on, the grid lines extend to the edge of the viewport along each axis. + +- Mini grid view: A smaller view of the currently overlaid grid. + + +.. note:: + + Your grid preferences such as overlay color and display settings choices are persisted across page loads for each separate page. + +Let's examine these features in more detail. + + +Overlay grid +------------ + +Each grid present on a page has an entry in the "Overlay grid" section: + +.. image:: overlay-grid-entry.png + :alt: An entry for a single grid in the Overlay Grid section of the Grid options, showing a grid's name, overlay color, and more. + :class: border + +Each entry consists of (from left to right): + + +- A checkbox allowing you to toggle the grid overlay for that grid on and off. +- A name label to represent the grid, consisting of a selector identifying the HTML element that has the grid applied to it. Clicking this also toggles the grid overlay on and off. +- A target icon that when clicked immediately selects the HTML element that this grid entry relates to, inside the HTML pane. +- A color picker icon that allows you to change the primary color of the grid overlay. This is useful for selecting different colors so you can easily tell your grids apart. + + +Inspecting a subgrid +-------------------- + +When the page contains a grid with a subgrid, the entry for the subgrid is indented under its parent in the Overlay grid section. When you select the checkbox for the subgrid, the lines for the parent grid are displayed also displayed; if the checkbox for the parent grid is unselected, then its lines are translucent. + +.. image:: subgrid-lines.png + :alt: Screenshot showing the overlay lines for a subgrid, with the subgrid lines and parent grid lines called out. + :class: center + + +Display line numbers +-------------------- + +By default, the line numbers are displayed on the grid overlay. + +.. image:: line-numbers.png + :alt: A CSS grid overlay with grid line numbers displayed + :class: border + + +Unchecking the "Display line numbers" box turns them off. + +.. image:: no-line-numbers.png + :alt: A CSS grid overlay with grid line numbers not displayed + :class: border + + +Display area names +------------------ + +In a grid with named areas, the area names are shown on the grid overlay by default. + +.. image:: grid-named-areas.png + :alt: A CSS grid overlay with named area names displayed + :class: border + +Unchecking the "Display area names" box turns them off. + +.. image:: no-grid-named-areas.png + :alt: A CSS grid overlay with named area names not displayed + :class: border + + +Extend lines infinitely +----------------------- + +By default, the grid lines/tracks are only shown inside the element with ``display: grid`` set on it. + +.. image:: no-extend-lines.png + :alt: A CSS grid overlay with grid lines not extended infinitely + :class: border + +When you check the "Extend lines infinitely" option, the grid lines extend to the edge of the viewport along each axis. + +.. image:: extend-lines.png + :alt: A CSS grid overlay with grid lines extended infinitely + :class: border + + +Mini grid view +-------------- + +Shows a small version of the currently overlaid grid, which is in proportion to the real thing. + +.. image:: mini-grid-view.png + :alt: A mini CSS grid view from the Firefox DevTools + :class: border + +Hovering over the different areas of the mini grid causes the equivalent area on the grid overlay to also highlight, along with a tooltip containing useful information such as the dimensions of that area, its row and column numbers, etc. + +.. image:: mini-grid-highlight.png + :alt: A firefox screenshot showing an area of a mini CSS grid being highlighted in the DevTools, and the corresponding area in the real grid being highlighted on the web page. + :class: border + + +See also +******** + +- `labs.jensimmons.com <https://labs.jensimmons.com/>`_ — lots of interesting grid examples. +- `Grid by Example <https://gridbyexample.com/>`_ — CSS Grid learning resources from Rachel Andrew. +- `CSS Grid Layout <https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Grid_Layout>`_ — MDN CSS Grid Layout references and tutorials. diff --git a/devtools/docs/user/page_inspector/how_to/examine_grid_layouts/line-numbers.png b/devtools/docs/user/page_inspector/how_to/examine_grid_layouts/line-numbers.png Binary files differnew file mode 100644 index 0000000000..7ee2f66af1 --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/examine_grid_layouts/line-numbers.png diff --git a/devtools/docs/user/page_inspector/how_to/examine_grid_layouts/mini-grid-highlight.png b/devtools/docs/user/page_inspector/how_to/examine_grid_layouts/mini-grid-highlight.png Binary files differnew file mode 100644 index 0000000000..52b6c6cbfd --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/examine_grid_layouts/mini-grid-highlight.png diff --git a/devtools/docs/user/page_inspector/how_to/examine_grid_layouts/mini-grid-view.png b/devtools/docs/user/page_inspector/how_to/examine_grid_layouts/mini-grid-view.png Binary files differnew file mode 100644 index 0000000000..3b183a30f2 --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/examine_grid_layouts/mini-grid-view.png diff --git a/devtools/docs/user/page_inspector/how_to/examine_grid_layouts/no-extend-lines.png b/devtools/docs/user/page_inspector/how_to/examine_grid_layouts/no-extend-lines.png Binary files differnew file mode 100644 index 0000000000..60fef3b1ce --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/examine_grid_layouts/no-extend-lines.png diff --git a/devtools/docs/user/page_inspector/how_to/examine_grid_layouts/no-grid-named-areas.png b/devtools/docs/user/page_inspector/how_to/examine_grid_layouts/no-grid-named-areas.png Binary files differnew file mode 100644 index 0000000000..7663001908 --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/examine_grid_layouts/no-grid-named-areas.png diff --git a/devtools/docs/user/page_inspector/how_to/examine_grid_layouts/no-line-numbers.png b/devtools/docs/user/page_inspector/how_to/examine_grid_layouts/no-line-numbers.png Binary files differnew file mode 100644 index 0000000000..0f7eeacb00 --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/examine_grid_layouts/no-line-numbers.png diff --git a/devtools/docs/user/page_inspector/how_to/examine_grid_layouts/overlay-grid-entry.png b/devtools/docs/user/page_inspector/how_to/examine_grid_layouts/overlay-grid-entry.png Binary files differnew file mode 100644 index 0000000000..3362f2577d --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/examine_grid_layouts/overlay-grid-entry.png diff --git a/devtools/docs/user/page_inspector/how_to/examine_grid_layouts/screen_shot_2016-12-16_at_10.51.15_am.png b/devtools/docs/user/page_inspector/how_to/examine_grid_layouts/screen_shot_2016-12-16_at_10.51.15_am.png Binary files differnew file mode 100644 index 0000000000..1ab8f708fa --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/examine_grid_layouts/screen_shot_2016-12-16_at_10.51.15_am.png diff --git a/devtools/docs/user/page_inspector/how_to/examine_grid_layouts/subgrid-lines.png b/devtools/docs/user/page_inspector/how_to/examine_grid_layouts/subgrid-lines.png Binary files differnew file mode 100644 index 0000000000..ba95af74dc --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/examine_grid_layouts/subgrid-lines.png diff --git a/devtools/docs/user/page_inspector/how_to/index.rst b/devtools/docs/user/page_inspector/how_to/index.rst new file mode 100644 index 0000000000..07b4fd5a8a --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/index.rst @@ -0,0 +1,26 @@ +====== +How to +====== + +Links for various HOW TO's can be found here. These links describe in depth the HOW TO techniques. + + +- :doc:`CSS Flexbox Inspector: Examine Flexbox layouts <examine_flexbox_layouts/index>` +- :doc:`CSS Grid Inspector: Examine grid layouts <examine_grid_layouts/index>` +- :doc:`Debug scrollable overflow <debug_scrollable_overflow/index>` +- :doc:`Edit CSS filters <edit_css_filters/index>` +- :doc:`Edit Shape Paths in CSS <edit_css_shapes/index>` +- :doc:`Edit fonts <edit_fonts/index>` +- :doc:`Examine Event Listeners <examine_event_listeners/index>` +- :doc:`Examine and edit CSS <examine_and_edit_css/index>` +- :doc:`Examine and edit HTML <examine_and_edit_html/index>` +- :doc:`Examine and edit the box model <examine_and_edit_the_box_model/index>` +- :doc:`Inspect and select colors <inspect_and_select_colors/index>` +- :doc:`Open the Inspector <open_the_inspector/index>` +- :doc:`Reposition elements in the page <reposition_elements_in_the_page/index>` +- :doc:`Select an element <select_an_element/index>` +- :doc:`Select and highlight elements <select_and_highlight_elements/index>` +- :doc:`Use the Inspector from the Web Console <use_the_inspector_from_the_web_console/index>` +- :doc:`View background images <view_background_images/index>` +- :doc:`Visualize transforms <visualize_transforms/index>` +- :doc:`Work with animations <work_with_animations/index>` diff --git a/devtools/docs/user/page_inspector/how_to/inspect_and_select_colors/color-picker-bad-contrast.png b/devtools/docs/user/page_inspector/how_to/inspect_and_select_colors/color-picker-bad-contrast.png Binary files differnew file mode 100644 index 0000000000..237cedfd2f --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/inspect_and_select_colors/color-picker-bad-contrast.png diff --git a/devtools/docs/user/page_inspector/how_to/inspect_and_select_colors/color-picker-good-contrast.png b/devtools/docs/user/page_inspector/how_to/inspect_and_select_colors/color-picker-good-contrast.png Binary files differnew file mode 100644 index 0000000000..56f47743ca --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/inspect_and_select_colors/color-picker-good-contrast.png diff --git a/devtools/docs/user/page_inspector/how_to/inspect_and_select_colors/css_color_vars.png b/devtools/docs/user/page_inspector/how_to/inspect_and_select_colors/css_color_vars.png Binary files differnew file mode 100644 index 0000000000..49701dd100 --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/inspect_and_select_colors/css_color_vars.png diff --git a/devtools/docs/user/page_inspector/how_to/inspect_and_select_colors/index.rst b/devtools/docs/user/page_inspector/how_to/inspect_and_select_colors/index.rst new file mode 100644 index 0000000000..e521ef3947 --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/inspect_and_select_colors/index.rst @@ -0,0 +1,31 @@ +========================= +Inspect and select colors +========================= + +In the CSS Pane's :ref:`Rules view <page_inspector_ui_tour_rules_view>`, if a rule contains a color value, you'll see a sample of the color next to the value: + +.. image:: inspector-css-color-swatch.png + +A color sample is also shown for CSS custom properties (variables) that represent colors. + +.. image:: css_color_vars.png + :alt: CSS in the Rules pane showing a color swatch on a CSS variable + :class: border + +If you click on the color sample, you'll see a color picker popup, enabling you to change the color: + +.. image:: color-picker-good-contrast.png + :alt: Color picker showing a case of good contrast with the background + +.. image:: color-picker-bad-contrast.png + :alt: Color picker showing a case of poor contrast" src="color-picker-bad-contrast.png + +If the color is a foreground color, the color picker tells you whether its contrast with the background color meets accessibility guidelines. Hovering the mouse over the contrast message gives a more detailed explanation. + +The color picker includes an eyedropper icon: clicking this icon enables you to use the eyedropper to select a new color for the element from the page: + +.. raw:: html + + <iframe width="560" height="315" src="https://www.youtube.com/embed/0Zx1TN21QOo" 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/page_inspector/how_to/inspect_and_select_colors/inspector-css-color-swatch.png b/devtools/docs/user/page_inspector/how_to/inspect_and_select_colors/inspector-css-color-swatch.png Binary files differnew file mode 100644 index 0000000000..742a25678d --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/inspect_and_select_colors/inspector-css-color-swatch.png diff --git a/devtools/docs/user/page_inspector/how_to/open_the_inspector/index.rst b/devtools/docs/user/page_inspector/how_to/open_the_inspector/index.rst new file mode 100644 index 0000000000..4e8fac602b --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/open_the_inspector/index.rst @@ -0,0 +1,32 @@ +================== +Open the Inspector +================== + +There are two main ways to open the Inspector: + +- Select the *Inspector* panel in the Web Developer Tools, accessible from the Browser Tools submenu +- Right-click an element on a web page and select *Inspect Element*. + + +The Inspector will appear at the bottom of the browser window: + +.. image:: pageinspector.png + :alt: The all-new Inspector in Firefox 57 DevTools. + :class: center + +You can also set the pane to appear at the left side of the browser window: + +.. image:: inspector_leftside.png + :class: center + +To the right side of the browser window: + +.. image:: inspector_rightside.png + :class: center + +Or in a separate window: + +.. image:: inspector_sidexside.png + :class: center + +To start finding your way around the Inspector, see the :doc:`UI tour <../../ui_tour/index>`. diff --git a/devtools/docs/user/page_inspector/how_to/open_the_inspector/inspector_leftside.png b/devtools/docs/user/page_inspector/how_to/open_the_inspector/inspector_leftside.png Binary files differnew file mode 100644 index 0000000000..be76e2862c --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/open_the_inspector/inspector_leftside.png diff --git a/devtools/docs/user/page_inspector/how_to/open_the_inspector/inspector_rightside.png b/devtools/docs/user/page_inspector/how_to/open_the_inspector/inspector_rightside.png Binary files differnew file mode 100644 index 0000000000..187bd6f3c6 --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/open_the_inspector/inspector_rightside.png diff --git a/devtools/docs/user/page_inspector/how_to/open_the_inspector/inspector_sidexside.png b/devtools/docs/user/page_inspector/how_to/open_the_inspector/inspector_sidexside.png Binary files differnew file mode 100644 index 0000000000..f8d8f079d4 --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/open_the_inspector/inspector_sidexside.png diff --git a/devtools/docs/user/page_inspector/how_to/open_the_inspector/pageinspector.png b/devtools/docs/user/page_inspector/how_to/open_the_inspector/pageinspector.png Binary files differnew file mode 100644 index 0000000000..a43b0d71e9 --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/open_the_inspector/pageinspector.png diff --git a/devtools/docs/user/page_inspector/how_to/reposition_elements_in_the_page/box-model-reposition.png b/devtools/docs/user/page_inspector/how_to/reposition_elements_in_the_page/box-model-reposition.png Binary files differnew file mode 100644 index 0000000000..5df8f12024 --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/reposition_elements_in_the_page/box-model-reposition.png diff --git a/devtools/docs/user/page_inspector/how_to/reposition_elements_in_the_page/in-content-box-model-editing.png b/devtools/docs/user/page_inspector/how_to/reposition_elements_in_the_page/in-content-box-model-editing.png Binary files differnew file mode 100644 index 0000000000..ba5e561554 --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/reposition_elements_in_the_page/in-content-box-model-editing.png diff --git a/devtools/docs/user/page_inspector/how_to/reposition_elements_in_the_page/index.rst b/devtools/docs/user/page_inspector/how_to/reposition_elements_in_the_page/index.rst new file mode 100644 index 0000000000..6b600172f4 --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/reposition_elements_in_the_page/index.rst @@ -0,0 +1,20 @@ +=============================== +Reposition elements in the page +=============================== + +Starting in Firefox 48 you can move absolutely positioned elements by dragging them around the page. + +If an element has its `position <https://developer.mozilla.org/en-US/docs/Web/CSS/Position>`_ property set to ``absolute``, ``relative`` or ``fixed`` and one or more of the `top <https://developer.mozilla.org/en-US/docs/Web/CSS/top>`_, `bottom <https://developer.mozilla.org/en-US/docs/Web/CSS/bottom>`_ , `left <https://developer.mozilla.org/en-US/docs/Web/CSS/left>`_ or `right <https://developer.mozilla.org/en-US/docs/Web/CSS/right>`_ properties, :ref:`Box Model view <page_inspector_ui_tour_computed_view>` displays a button: + +.. image:: box-model-reposition.png + :class: center + +If you click that button, two handles appear next to the element: + +.. image:: in-content-box-model-editing.png + :alt: Example for changing the position of an element within the content + :class: center + +You can use these handles to drag the element around the page. + +If the element is absolutely positioned, dashed lines are shown representing the offset parent. For relatively positioned elements the dashed lines indicate the original position of the node. The offsets are indicated by a line and a tooltip for each side. diff --git a/devtools/docs/user/page_inspector/how_to/select_an_element/index.rst b/devtools/docs/user/page_inspector/how_to/select_an_element/index.rst new file mode 100644 index 0000000000..b6cfe9fba1 --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/select_an_element/index.rst @@ -0,0 +1,37 @@ +================= +Select an element +================= + +The *selected element* is the element in the page that the Inspector is currently focused on. The selected element is shown in the :ref:`HTML pane <page_inspector_ui_tour_html_pane>` and its CSS is displayed in the :doc:`CSS pane <../../ui_tour/index>`. + +The *highlighted element* is the element that's overlaid in the page with a graphic showing the box model, and a tooltip showing its tag and size: + +.. image:: inspector-highlighted.png + :class: center + + +With the context menu +********************* + +To open the Inspector and select an element immediately, activate the context menu over the element in the page and select "Inspect Element" + + +With the HTML pane +****************** + +When the inspector is open, as you move the mouse around the elements listed in the HTML pane, the corresponding elements are highlighted in the page. Click an element in the HTML pane to select it. + +You can also use the arrow keys to move around the DOM with the keyboard. + + +.. _page-inspector-how-to-select-an-element-with-the-node-picker: + +With the node picker +******************** + +.. |image1| image:: node-picker.png + :width: 20 + +To select an element in the page itself, activate the "node picker" by clicking its icon: |image1| (also called the *Select Element* icon). After that, as you move the mouse around the page, the element under the mouse is highlighted. Click the element to select it: + +Starting in Firefox 52, if you :kbd:`Shift` + click the element, then it is selected but the picker stays active. This lets you see the rules for the element in the CSS pane, but conveniently select another element in the page. diff --git a/devtools/docs/user/page_inspector/how_to/select_an_element/inspector-highlighted.png b/devtools/docs/user/page_inspector/how_to/select_an_element/inspector-highlighted.png Binary files differnew file mode 100644 index 0000000000..2afa672cb5 --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/select_an_element/inspector-highlighted.png diff --git a/devtools/docs/user/page_inspector/how_to/select_an_element/node-picker.png b/devtools/docs/user/page_inspector/how_to/select_an_element/node-picker.png Binary files differnew file mode 100644 index 0000000000..b1f86488b8 --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/select_an_element/node-picker.png diff --git a/devtools/docs/user/page_inspector/how_to/select_and_highlight_elements/index.rst b/devtools/docs/user/page_inspector/how_to/select_and_highlight_elements/index.rst new file mode 100644 index 0000000000..e24dd5121d --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/select_and_highlight_elements/index.rst @@ -0,0 +1,33 @@ +============================= +Select and highlight elements +============================= + +The *selected* element is the element in the page that the Inspector is currently focused on. The selected element is shown in the :ref:`HTML pane <page_inspector_ui_tour_html_pane>` and its CSS is displayed in the :doc:`CSS pane <../../ui_tour/index>`. + +The *highlighted* element is the element that's overlaid in the page with a graphic showing the box model, and a tooltip showing its tag and size: + +.. image:: inspector-highlighted.png + :class: center + + +With the context menu +********************* + +To open the Inspector and select an element immediately, activate the context menu over the element in the page and select "Inspect Element" + + +With the HTML pane +****************** + +When the inspector is open, as you move the mouse around the elements listed in the HTML pane, the corresponding elements are highlighted in the page. Click an element in the HTML pane to select it + +You can also use the arrow keys to move around the DOM with the keyboard. + + +With the node picker +******************** + +.. |image1| image:: node-picker.png + :width: 20 + +To select an element in the page itself, activate the "node picker" by clicking its icon: |image1| (also called the *Select Element* icon). After that, as you move the mouse around the page, the element under the mouse is highlighted. Click the element to select it: diff --git a/devtools/docs/user/page_inspector/how_to/select_and_highlight_elements/inspector-highlighted.png b/devtools/docs/user/page_inspector/how_to/select_and_highlight_elements/inspector-highlighted.png Binary files differnew file mode 100644 index 0000000000..2afa672cb5 --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/select_and_highlight_elements/inspector-highlighted.png diff --git a/devtools/docs/user/page_inspector/how_to/select_and_highlight_elements/node-picker.png b/devtools/docs/user/page_inspector/how_to/select_and_highlight_elements/node-picker.png Binary files differnew file mode 100644 index 0000000000..b1f86488b8 --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/select_and_highlight_elements/node-picker.png diff --git a/devtools/docs/user/page_inspector/how_to/use_the_inspector_from_the_web_console/console-$0.png b/devtools/docs/user/page_inspector/how_to/use_the_inspector_from_the_web_console/console-$0.png Binary files differnew file mode 100644 index 0000000000..9ce705cfbe --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/use_the_inspector_from_the_web_console/console-$0.png diff --git a/devtools/docs/user/page_inspector/how_to/use_the_inspector_from_the_web_console/console-highlight.png b/devtools/docs/user/page_inspector/how_to/use_the_inspector_from_the_web_console/console-highlight.png Binary files differnew file mode 100644 index 0000000000..35bcda498b --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/use_the_inspector_from_the_web_console/console-highlight.png diff --git a/devtools/docs/user/page_inspector/how_to/use_the_inspector_from_the_web_console/index.rst b/devtools/docs/user/page_inspector/how_to/use_the_inspector_from_the_web_console/index.rst new file mode 100644 index 0000000000..b3a015dbba --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/use_the_inspector_from_the_web_console/index.rst @@ -0,0 +1,13 @@ +====================================== +Use the Inspector from the Web Console +====================================== + +The element that's currently selected in the Page Inspector can be referenced in the Web Console using the variable ``$0``. + +.. image:: console-$0.png + :class: center + +DOM elements in the Web Console output get a target next to them. If you hover over this target, the element is highlighted in the page, and if you click the target, the element is selected in the Inspector: + +.. image:: console-highlight.png + :class: center diff --git a/devtools/docs/user/page_inspector/how_to/view_background_images/css-copy-image-data-url.png b/devtools/docs/user/page_inspector/how_to/view_background_images/css-copy-image-data-url.png Binary files differnew file mode 100644 index 0000000000..461d442e4d --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/view_background_images/css-copy-image-data-url.png diff --git a/devtools/docs/user/page_inspector/how_to/view_background_images/css-image-preview.png b/devtools/docs/user/page_inspector/how_to/view_background_images/css-image-preview.png Binary files differnew file mode 100644 index 0000000000..14d0109f24 --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/view_background_images/css-image-preview.png diff --git a/devtools/docs/user/page_inspector/how_to/view_background_images/index.rst b/devtools/docs/user/page_inspector/how_to/view_background_images/index.rst new file mode 100644 index 0000000000..ae2a72aadd --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/view_background_images/index.rst @@ -0,0 +1,14 @@ +====================== +View background images +====================== + +In the :ref:`Rules view <page_inspector_ui_tour_rules_view>`, you can see a preview of images specified using `background-image <https://developer.mozilla.org/en-US/docs/Web/CSS/background-image>`_. Just hover over the rule: + +.. image:: css-image-preview.png + :class: center + + +From Firefox 41, if you right-click the image declaration, you'll see an option to copy the image as a data: URL: + +.. image:: css-copy-image-data-url.png + :class: center diff --git a/devtools/docs/user/page_inspector/how_to/visualize_transforms/index.rst b/devtools/docs/user/page_inspector/how_to/visualize_transforms/index.rst new file mode 100644 index 0000000000..46eb500581 --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/visualize_transforms/index.rst @@ -0,0 +1,8 @@ +==================== +Visualize transforms +==================== + +If you hover over a `transform <https://developer.mozilla.org/en-US/docs/Web/CSS/transform>`_ property in the :ref:`Rules view <page_inspector_ui_tour_rules_view>`, you'll see the transformation overlaid in the page: + +.. image:: transform.png + :class: center diff --git a/devtools/docs/user/page_inspector/how_to/visualize_transforms/transform.png b/devtools/docs/user/page_inspector/how_to/visualize_transforms/transform.png Binary files differnew file mode 100644 index 0000000000..e11bba7292 --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/visualize_transforms/transform.png diff --git a/devtools/docs/user/page_inspector/how_to/work_with_animations/animation_details.png b/devtools/docs/user/page_inspector/how_to/work_with_animations/animation_details.png Binary files differnew file mode 100644 index 0000000000..1e6e934fae --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/work_with_animations/animation_details.png diff --git a/devtools/docs/user/page_inspector/how_to/work_with_animations/animation_icon_details.png b/devtools/docs/user/page_inspector/how_to/work_with_animations/animation_icon_details.png Binary files differnew file mode 100644 index 0000000000..ef3fdd74c7 --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/work_with_animations/animation_icon_details.png diff --git a/devtools/docs/user/page_inspector/how_to/work_with_animations/animation_icon_scale.png b/devtools/docs/user/page_inspector/how_to/work_with_animations/animation_icon_scale.png Binary files differnew file mode 100644 index 0000000000..44a5dbb37a --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/work_with_animations/animation_icon_scale.png diff --git a/devtools/docs/user/page_inspector/how_to/work_with_animations/animation_inspector_(firefox_41_and_42)/index.rst b/devtools/docs/user/page_inspector/how_to/work_with_animations/animation_inspector_(firefox_41_and_42)/index.rst new file mode 100644 index 0000000000..1299bca57c --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/work_with_animations/animation_inspector_(firefox_41_and_42)/index.rst @@ -0,0 +1,25 @@ +======================================= +Animation inspector (Firefox 41 and 42) +======================================= + +.. note:: + Note that the Animation inspector's UI was revamped in Firefox 43. To see what the Animation inspector looks like in Firefox 43 and subsequent releases, see :ref:`the main "Work with animations" page <page-inspector-how-to-work-with-animations-animation-inspector>`. + + +The Animation inspector enables you to: + + +- see information about all animations running in the page +- play/pause all animations +- play/pause/rewind/fast-forward each animation +- jump to a specific point in an animation +- highlight and inspect the animated node +- adjust the playback rate of each animation +- see whether an animation is running in the compositor thread (a lightning bolt icon is displayed next to such animations) + + +.. raw:: html + + <iframe width="560" height="315" src="https://www.youtube.com/embed/0vSIuKaqD8o" 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/page_inspector/how_to/work_with_animations/animation_inspector_example_colon__css_transitions/developer.png b/devtools/docs/user/page_inspector/how_to/work_with_animations/animation_inspector_example_colon__css_transitions/developer.png Binary files differnew file mode 100644 index 0000000000..331428f162 --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/work_with_animations/animation_inspector_example_colon__css_transitions/developer.png diff --git a/devtools/docs/user/page_inspector/how_to/work_with_animations/animation_inspector_example_colon__css_transitions/index.rst b/devtools/docs/user/page_inspector/how_to/work_with_animations/animation_inspector_example_colon__css_transitions/index.rst new file mode 100644 index 0000000000..a4bd7bea2d --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/work_with_animations/animation_inspector_example_colon__css_transitions/index.rst @@ -0,0 +1,93 @@ +============================================ +Animation inspector example: CSS transitions +============================================ + +Firefox Logo Animation +********************** + +Example animation using `CSS transitions <https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Transitions/Using_CSS_transitions>`_. + +HTML Content +------------ + +.. code-block:: html + + <div class="channel"> + <img src="developer.png" class="icon"/> + <span class="note">Firefox Developer Edition</span> + </div> + + +CSS Content +----------- + +.. code-block:: css + + .channel { + padding: 2em; + margin: 0.5em; + box-shadow: 1px 1px 5px #808080; + margin: 1.5em; + } + + .channel > * { + vertical-align: middle; + line-height: normal; + } + + .icon { + width: 50px; + height: 50px; + filter: grayscale(100%); + transition: transform 750ms ease-in, filter 750ms ease-in-out; + } + + .note { + margin-left: 1em; + font: 1.5em "Open Sans",Arial,sans-serif; + overflow: hidden; + white-space: nowrap; + display: inline-block; + + opacity: 0; + width: 0; + transition: opacity 500ms 150ms, width 500ms 150ms; + } + + .icon#selected { + filter: grayscale(0%); + transform: scale(1.5); + } + + .icon#selected+span { + opacity: 1; + width: 300px; + } + + +JavaScript Content +------------------ + +.. code-block:: JavaScript + + function toggleSelection(e) { + if (e.button != 0) { + return; + } + if (e.target.classList.contains("icon")) { + var wasSelected = (e.target.getAttribute("id") == "selected"); + clearSelection(); + if (!wasSelected) { + e.target.setAttribute("id", "selected"); + } + } + } + + function clearSelection() { + var selected = document.getElementById("selected"); + if (selected) { + selected.removeAttribute("id"); + } + } + + document.addEventListener("click", toggleSelection); diff --git a/devtools/docs/user/page_inspector/how_to/work_with_animations/animation_inspector_example_colon__web_animations_api/developer.png b/devtools/docs/user/page_inspector/how_to/work_with_animations/animation_inspector_example_colon__web_animations_api/developer.png Binary files differnew file mode 100644 index 0000000000..331428f162 --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/work_with_animations/animation_inspector_example_colon__web_animations_api/developer.png diff --git a/devtools/docs/user/page_inspector/how_to/work_with_animations/animation_inspector_example_colon__web_animations_api/index.rst b/devtools/docs/user/page_inspector/how_to/work_with_animations/animation_inspector_example_colon__web_animations_api/index.rst new file mode 100644 index 0000000000..6d6f2cb045 --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/work_with_animations/animation_inspector_example_colon__web_animations_api/index.rst @@ -0,0 +1,117 @@ +=============================================== +Animation inspector example: Web Animations API +=============================================== + +Firefox Logo Animation +********************** + +Example animation using the `Web Animations API <https://developer.mozilla.org/en-US/docs/Web/API/Web_Animations_API>`_. + + +HTML Content +------------ + +.. code-block:: html + + <div class="channel"> + <img src="developer.png" id="icon"/> + <span id="note">Firefox Developer Edition</span> + </div> + + +CSS Content +----------- + +.. code-block:: css + + .channel { + padding: 2em; + margin: 0.5em; + box-shadow: 1px 1px 5px #808080; + margin: 1.5em; + } + + .channel > * { + vertical-align: middle; + line-height: normal; + } + + #icon { + width: 50px; + height: 50px; + filter: grayscale(100%); + } + + #note { + margin-left: 1em; + font: 1.5em "Open Sans",Arial,sans-serif; + overflow: hidden; + white-space: nowrap; + display: inline-block; + opacity: 0; + width: 0; + } + + +.. _page-inspector-work-with-animations-web-example-js-content: + +JavaScript Content +------------------ + +.. code-block:: JavaScript + + var iconKeyframeSet = [ + { transform: 'scale(1)', filter: 'grayscale(100%)'}, + { filter: 'grayscale(100%)', offset: 0.333}, + { transform: 'scale(1.5)', offset: 0.666 }, + { transform: 'scale(1.5)', filter: 'grayscale(0%)'} + ]; + + var noteKeyframeSet = [ + { opacity: '0', width: '0'}, + { opacity: '1', width: '300px'} + ]; + + var iconKeyframeOptions = { + duration: 750, + fill: 'forwards', + easing: 'ease-in', + endDelay: 100 + } + + var noteKeyframeOptions = { + duration: 500, + fill: 'forwards', + easing: 'ease-out', + delay: 150 + } + + var icon = document.getElementById("icon"); + var note = document.getElementById("note"); + + var iconAnimation = icon.animate(iconKeyframeSet, iconKeyframeOptions); + var noteAnimation = note.animate(noteKeyframeSet, noteKeyframeOptions); + + iconAnimation.pause(); + noteAnimation.pause(); + + var firstTime = true; + + function animateChannel(e) { + if (e.button != 0) { + return; + } + if (e.target.id != "icon") { + return; + } + if (firstTime) { + iconAnimation.play(); + noteAnimation.play(); + firstTime = false; + } else { + iconAnimation.reverse(); + noteAnimation.reverse(); + } + } + + document.addEventListener("click", animateChannel); diff --git a/devtools/docs/user/page_inspector/how_to/work_with_animations/animation_not_optimized.png b/devtools/docs/user/page_inspector/how_to/work_with_animations/animation_not_optimized.png Binary files differnew file mode 100644 index 0000000000..9105060404 --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/work_with_animations/animation_not_optimized.png diff --git a/devtools/docs/user/page_inspector/how_to/work_with_animations/animation_pane.png b/devtools/docs/user/page_inspector/how_to/work_with_animations/animation_pane.png Binary files differnew file mode 100644 index 0000000000..02fe47b31e --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/work_with_animations/animation_pane.png diff --git a/devtools/docs/user/page_inspector/how_to/work_with_animations/animation_swoosh_01.png b/devtools/docs/user/page_inspector/how_to/work_with_animations/animation_swoosh_01.png Binary files differnew file mode 100644 index 0000000000..ea91cc8756 --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/work_with_animations/animation_swoosh_01.png diff --git a/devtools/docs/user/page_inspector/how_to/work_with_animations/compositor.png b/devtools/docs/user/page_inspector/how_to/work_with_animations/compositor.png Binary files differnew file mode 100644 index 0000000000..ec9f9a4789 --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/work_with_animations/compositor.png diff --git a/devtools/docs/user/page_inspector/how_to/work_with_animations/index.rst b/devtools/docs/user/page_inspector/how_to/work_with_animations/index.rst new file mode 100644 index 0000000000..215a86a318 --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/work_with_animations/index.rst @@ -0,0 +1,227 @@ +==================== +Work with animations +==================== + +This article covers three tools you can use to visualize and edit animations: + + +- :ref:`the animation inspector <page-inspector-how-to-work-with-animations-animation-inspector>` + +- :ref:`diting @keyframes <page-inspector-how-to-work-with-animations-edit-keyframes>` + +- :ref:`editing timing functions <page-inspector-how-to-work-with-animations-edit-timing-functions>` + + +.. _page-inspector-how-to-work-with-animations-animation-inspector: + +Animation inspector +******************* + +The Page Inspector's :ref:`Animations view <page_inspector_ui_tour_animations_view>` displays animations in the page synchronized along a timeline, with a draggable widget you can use to move to any point in the timeline and see the page at that point. + +It displays animations created using `CSS transitions <https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Transitions>`_, `CSS @keyframes rules <https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Animations/Using_CSS_animations>`_, or the `Web Animations API <https://developer.mozilla.org/en-US/docs/Web/API/Web_Animations_API>`_. Starting in Firefox 48, it will show animations applied to the `::before <https://developer.mozilla.org/en-US/docs/Web/CSS/::before>`_ and `::after <https://developer.mozilla.org/en-US/docs/Web/CSS/::after>`_ pseudo-elements. + +To see how it works, we'll walk through an example. The box below contains a grayscale icon, representing `Firefox Developer Edition <https://www.mozilla.org/en-US/firefox/developer/>`_. If you click the icon, it enlarges and changes to color, and the name of the browser appears. Click the icon again to reverse the effect. + + +These animations are made using the `Web Animations API <https://developer.mozilla.org/en-US/docs/Web/API/Web_Animations_API>`_. + +Let's use the animation inspector to see what's going on in this example. + + +1. Right-click in the box and select "Inspect Element" +2. Make sure the selected element is the ``<div class="channel">`` +3. Switch over to the "Animations" tab +4. Play the animation + + +.. raw:: html + + <iframe width="560" height="315" src="https://www.youtube.com/embed/XmKeAKryE5I" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe> + <br/> + <br/> + + +Let's take a closer look at the contents of the animation inspector here: + +.. image:: animation_pane.png + :class: border + + +It shows a synchronized timeline for every animation applied to the selected element or its children. The timeline starts at the start of the first animation, ends at the end of the last animation, and is labeled with markers every 250 milliseconds (this depends on the time scale of the animations currently displayed). + + +Animation bars +-------------- + +Each animation or transition is shown as a horizontal bar laid across the timeline. The bar is: + + +- blue if a `transition <https://developer.mozilla.org/en-US/docs/Web/CSS/transition>`_) was used to animate a property +- orange if a `@keyframes animation <https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Animations/Using_CSS_animations>`_ was used +- green if the `Web Animations API <https://developer.mozilla.org/en-US/docs/Web/API/Web_Animations_API>`_ was used + +.. |image1| image:: compositor.png + :width: 20 + +The bar contains a lightning bolt icon |image1| if the property was animated using the compositor thread (see more about the :ref:`cost of animating different CSS properties <performance-scenarios-animating_css_properties-css-property-cost>`). + +The bar is shaped to reflect the easing effect used for the animation. In the example above you can see that the first bar is concave, representing ease-in, and the second is convex, representing ease-out. + +If the animation used CSS transitions, there is one bar for each property transitioned, and it is labeled with the name of the property being transitioned. If the animation used CSS ``@keyframes``, there is one bar for each animation, labeled with its name. + +If the animation or transition had a delay, this is shown as a cross-hatched portion of the bar. `delay and endDelay <https://developer.mozilla.org/en-US/docs/Web/API/KeyframeEffect/KeyframeEffect>`_ are both represented. + +If you hover over the bar, a tooltip appears, giving you more detailed information about the animation or transition, including: + + +- the type of animation: CSS transition, CSS animation, or Web Animations API +- the duration of the animation +- the animation's start and end delay +- the animation's easing (or timing function). +- the animation's fill +- the Playback rate of the animation + + +.. image:: animation_details.png + :class: border + + +Information about the animated element +-------------------------------------- + +To the left of each bar is a selector for the element that the animation applies to. If you hover over this selector, the element is highlighted in the page. Click the selector to select the element in the inspector. + +.. |image2| image:: target-icon.png + +To the left of the selector is a "target" icon (|image2|). Clicking this icon locks the highlighter on the element. + + +Animation details +----------------- + +If you click one of the bars, you'll see details of all the properties that were changed in the animation. For example, try clicking on the bar for ``img#icon`` animation: + +.. image:: animation_icon_details.png + :class: border + + +This is telling us that two properties were modified: `filter <https://developer.mozilla.org/en-US/docs/Web/CSS/filter>`_ and `transform <https://developer.mozilla.org/en-US/docs/Web/CSS/transform>`_. Each dot represents an entry for that property in the set of keyframes used for the animation. Both properties were initialized at 0ms and finalized at 750ms. ``filter`` was given a value at 250ms and ``transform`` at 500ms. If you hover over a dot, you'll see the value assigned to that property at that point in the timeline: + +.. image:: animation_icon_scale.png + :class: border + + +This is essentially a visual representation of the animation's +:ref:`keyframes <page-inspector-work-with-animations-web-example-js-content>`: + +.. code-block:: JavaScript + + var iconKeyframeSet = [ + { transform: 'scale(1)', filter: 'grayscale(100%)' }, + { filter: 'grayscale(100%)', offset: 0.333 }, + { transform: 'scale(1.5)', offset: 0.666 }, + { transform: 'scale(1.5)', filter: 'grayscale(0%)' } + ]; + + +Application to the example +-------------------------- + +Applying all this to our example, we can see that: + + +- The animation involved two elements, ``span#note`` and ``img#icon``. Hovering over these selectors, we can see that those elements are, respectively, the browser name "Firefox Developer Edition" and the browser icon. +- The ``img#icon`` animation: + + - animated the `filter <https://developer.mozilla.org/en-US/docs/Web/CSS/filter>`_ and `transform <https://developer.mozilla.org/en-US/docs/Web/CSS/transform>`_ properties, to scale the icon and color it + - lasted 750ms, had an ``endDelay`` of 100ms + - used the compositor thread + - was given an `easing <https://developer.mozilla.org/en-US/docs/Web/API/KeyframeEffect/KeyframeEffect>`_ value of ``ease-in``: you can see this by the concave shape of the green bar. + +- The ``span#note`` animation: + + - animated the `width <https://developer.mozilla.org/en-US/docs/Web/CSS/width>`_ and `opacity <https://developer.mozilla.org/en-US/docs/Web/CSS/opacity>`_ properties, to make the name gradually appear + - lasted 500ms, and had a ``delay`` of 150ms + - was given an `easing <https://developer.mozilla.org/en-US/docs/Web/API/KeyframeEffect/KeyframeEffect>`_ value of ``ease-out``: you can see this by the convex shape of the green bar. + + +Animation playback +------------------ + +At the top of the animation inspector: + + +- there are buttons to play/pause and restart the animation +- there's a dropdown to change the animation playback rate +- the current time in the animation is displayed. + + +Finally, if you click inside the bar at the top of the timeline, you get a scrubber that you can drag left and right to move backwards and forwards through the animation, and pinpoint exactly what's happening when. + + +Further information about animation compositing +----------------------------------------------- + +If you open `animation-inspector-compositing.html <https://firefox-devtools.github.io/devtools-examples/animation-inspector/animation-inspector-compositing.html>`_ and click the red rectangle, a simple `opacity <https://developer.mozilla.org/en-US/docs/Web/CSS/opacity>`_ animation will start. If you look at this in the Animation Inspector in Firefox 49+, you'll see that: + + +- The white lightning bolt icon now indicates whether all the animation properties have been optimized by running them through the compositor, where possible. +- The bar tooltip also includes this information, as a further reminder. You'll get a message of "All animation properties are optimized." +- The expanded animation information now includes a lightning bolt icon next to the properties whose animation has been optimized via the compositor. + + +.. image:: animation_swoosh_01.png + :class: border + +Let's now look at `animation-inspector-compositing-silly.html <https://firefox-devtools.github.io/devtools-examples/animation-inspector/animation-inspector-compositing-silly.html>`_ — this is the same example, except that now once the red rectangle is clicked we animate both the `left <https://developer.mozilla.org/en-US/docs/Web/CSS/left>`_ and `transform <https://developer.mozilla.org/en-US/docs/Web/CSS/transform>`_ (with a translation) properties at the same time as `opacity <https://developer.mozilla.org/en-US/docs/Web/CSS/opacity>`_. It doesn't make much sense to try to animate a geometric property and a translation at the same time — the two effects won't be synchronized — so the ``transform`` property is deliberately not handed over to the compositor to handle. The Animation Inspector will tell you this — look at it now and you'll see that: + + +- The white lightning bolt icon in the bar has been replaced with a grey lightning bolt icon, to indicate that only some of the relevant properties are being optimized by the compositor. +- The bar tooltip also includes this information, as a further reminder. You'll get a message of "Some animation properties are optimized." +- Properties whose animation is **not** being optimized, but could be if you improved your code, are now given a dotted underline — see transform in the screenshot below. Hovering over this gives you a tooltip that explains why. In this case, the message is "Animations of 'transform' cannot be run on the compositor when geometric properties are animated on the same element at the same time." + + +.. image:: animation_not_optimized.png + :class: border + + +.. _page-inspector-how-to-work-with-animations-edit-keyframes: + +Edit @keyframes +*************** + +Any `@keyframes rules <https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Animations/Using_CSS_animations>`_ associated with the currently selected element are displayed in the :ref:`Rules view <page_inspector_ui_tour_rules_view>` and are editable: + +.. raw:: html + + <iframe width="560" height="315" src="https://www.youtube.com/embed/mDHtLK88ZW4" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe> + <br/> + <br/> + + +.. _page-inspector-how-to-work-with-animations-edit-timing-functions: + +Edit timing functions +********************* + +When you `create a CSS animation <https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Animations/Using_CSS_animations>`_ you can specify a `timing function <https://developer.mozilla.org/en-US/docs/Web/CSS/animation-timing-function>`_: this determines the rate at which the animation progresses. One way to specify the timing function is with a cubic Bézier curve. + +Timing functions defined as cubic Bézier curves get an icon in the Rules view. If you click the icon you get a visual editor for the curve, enabling you to drag `P1 and P2 <https://developer.mozilla.org/en-US/docs/Web/CSS/easing-function#the_cubic-bezier()_class_of_timing-functions>`_, and see the results in the page: + +.. raw:: html + + <iframe width="560" height="315" src="https://www.youtube.com/embed/GW5-R2ewaqA" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe> + <br/> + <br/> + + +This feature uses open source code from `Lea Verou’s cubic-bezier.com <https://cubic-bezier.com/>`_. + +The cubic Bézier editor includes a number of presets, grouped under "Ease-in", "Ease-out", and "Ease-in-out": + +.. raw:: html + + <iframe width="560" height="315" src="https://www.youtube.com/embed/Jx-J2Yy0aSg" 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/page_inspector/how_to/work_with_animations/target-icon.png b/devtools/docs/user/page_inspector/how_to/work_with_animations/target-icon.png Binary files differnew file mode 100644 index 0000000000..84ab9afa0c --- /dev/null +++ b/devtools/docs/user/page_inspector/how_to/work_with_animations/target-icon.png diff --git a/devtools/docs/user/page_inspector/index.rst b/devtools/docs/user/page_inspector/index.rst new file mode 100644 index 0000000000..f9608e2ac7 --- /dev/null +++ b/devtools/docs/user/page_inspector/index.rst @@ -0,0 +1,47 @@ +============== +Page Inspector +============== + +Use the Page Inspector to examine and modify the HTML and CSS of a page. + +You can examine pages loaded in the local copy of Firefox or in a remote target such as Firefox for Android. See :doc:`about debugging <../about_colon_debugging/index>` to learn how to connect the developer tools to a remote target. + + +User Interface Tour +******************* + +To find your way around the Inspector, here's a :doc:`quick tour of the UI <ui_tour/index>`. + +You can split the Rules view out into its own pane, separate from the other tabs on the CSS pane — this is called :doc:`3-pane mode <3-pane_mode/index>`. + + +How to +****** + +To find out what you can do with the Inspector, see the following how to guides: + +- :doc:`Open the Inspector <how_to/open_the_inspector/index>` +- :doc:`Examine and edit HTML <how_to/examine_and_edit_html/index>` +- :doc:`Examine and edit the box model <how_to/examine_and_edit_the_box_model/index>` +- :doc:`Inspect and select colors <how_to/inspect_and_select_colors/index>` +- :doc:`Reposition elements in the page <how_to/reposition_elements_in_the_page/index>` +- :doc:`Edit fonts <how_to/edit_fonts/index>` +- :doc:`Visualize transforms <how_to/visualize_transforms/index>` +- :doc:`Select an element <how_to/select_an_element/index>` +- :doc:`Examine and edit CSS <how_to/examine_and_edit_css/index>` +- :doc:`Examine event listeners <how_to/examine_event_listeners/index>` +- :doc:`Work with animations <how_to/work_with_animations/index>` +- :doc:`Edit CSS filters <how_to/edit_css_filters/index>` +- :doc:`Edit CSS shapes <how_to/edit_css_shapes/index>` +- :doc:`View background images <how_to/view_background_images/index>` +- :doc:`Use the Inspector from the Web Console <how_to/use_the_inspector_from_the_web_console/index>` +- :doc:`Examine CSS grid layouts <how_to/examine_grid_layouts/index>` +- :doc:`Examine CSS flexbox layouts <how_to/examine_flexbox_layouts/index>` +- :doc:`Use the Accessibility Inspector <../accessibility_inspector/index>` + + +Reference +********* + +- :ref:`Keyboard shortcuts <keyboard-shortcuts-page-inspector>` +- :ref:`Settings <settings-inspector>` diff --git a/devtools/docs/user/page_inspector/ui_tour/animation_detail.png b/devtools/docs/user/page_inspector/ui_tour/animation_detail.png Binary files differnew file mode 100644 index 0000000000..95909753cf --- /dev/null +++ b/devtools/docs/user/page_inspector/ui_tour/animation_detail.png diff --git a/devtools/docs/user/page_inspector/ui_tour/compat_panel_settings.png b/devtools/docs/user/page_inspector/ui_tour/compat_panel_settings.png Binary files differnew file mode 100644 index 0000000000..2401873c8e --- /dev/null +++ b/devtools/docs/user/page_inspector/ui_tour/compat_panel_settings.png diff --git a/devtools/docs/user/page_inspector/ui_tour/compat_view.png b/devtools/docs/user/page_inspector/ui_tour/compat_view.png Binary files differnew file mode 100644 index 0000000000..138621bcd2 --- /dev/null +++ b/devtools/docs/user/page_inspector/ui_tour/compat_view.png diff --git a/devtools/docs/user/page_inspector/ui_tour/index.rst b/devtools/docs/user/page_inspector/ui_tour/index.rst new file mode 100644 index 0000000000..33abe11538 --- /dev/null +++ b/devtools/docs/user/page_inspector/ui_tour/index.rst @@ -0,0 +1,161 @@ +======= +UI Tour +======= + +This article is a quick tour of the main sections of the Page Inspector's user interface. + +It covers the three top-level components of the Inspector's UI: + +- the "Select element" button +- the HTML pane +- the CSS pane + + +.. image:: pageinspector.png + :alt: The all-new Inspector panel in Firefox 57. + +This guide is intentionally kept as short as possible. It links to various how to guides for the details of how to work with the Inspector. + + +.. _page_inspector_select_element_button: + +Select element button +********************* + +The Inspector gives you detailed information about the currently selected element. The Select element button is one way you can select an element for inspection: + +.. image:: select_element_button.png + :alt: This is the button in Firefox 57 Inspector you can use to select elements on a web page. + :class: center + +Note that it's actually part of the :ref:`main toolbox toolbar <tools-toolbox-toolbar>`, so it's immediately accessible from any tool, not just the Inspector. + +To learn how to select an element, see the guide to :doc:`selecting an element <../how_to/select_an_element/index>`. + + +.. _page_inspector_ui_tour_html_pane: + +HTML pane +********* + +The Inspector is split into two or three sections, depending on your settings. You can toggle the 3-pane view of the Inspector. The following image shows the 2-pane layout: + +.. image:: inspector_2pane.png + :alt: These are the tasty new HTML and CSS panes in Firefox 57. + :class: border + + +In 2-pane mode, the Inspector includes the HTML Pane, and the CSS Pane, which can contain one of six tools: + +- Rules view +- Layout view +- Computed view +- Changes view +- Compatibility view (Firefox Developer Edition 77 and later) +- Fonts view +- Animations view + +The following image shows the 3-pane mode (available from Firefox 62 onwards) which moves the CSS Rules view into a separate pane in the center of the Inspector. The following image shows 3-pane mode: + +.. image:: inspector_tool.png + :class: border + +As you can see, the CSS pane has moved into the center of the Inspector. To learn more about the structure of the HTML pane, see the guide to :doc:`examining and editing HTML <../how_to/examine_and_edit_html/index>`. + + +.. _page_inspector_ui_tour_rules_view: + +Rules view +********** + +The Rules view lists all the rules that apply to the selected element, ordered from most-specific to least-specific. See above. + +.. image:: indpextor_rules.png + :alt: The rules view within the Inspector. + :class: border + +See :doc:`Examine and edit CSS <../how_to/examine_and_edit_css/index>` for more details. + + +Layout view +*********** + +The Layout view displays the box model of the page. If the page includes any sections using either the Flexbox display model or CSS Grids, this view shows the Flexbox or Grid settings used on the page. + +.. image:: inspector_layout.png + :class: border + +To learn more about the Layout view, see :doc:`Examine and edit the box model <../how_to/examine_and_edit_the_box_model/index>`. Note that before Firefox 50, the box model view did not appear in the "Layout view" tab, but had its own tab. + + +Changes view +************ + +When you are editing in the Rules view, you can see the changes you have made in the Changes view. + +.. image:: track_changes.png + :class: border + +.. _page_inspector_ui_tour_computed_view: + +Computed view +************* + +The Computed view shows you the complete computed CSS for the selected element (The computed values are the same as what `getComputedStyle <https://developer.mozilla.org/en-US/docs/Web/API/Window/getComputedStyle>`_ would return): + +.. image:: inspector_computed.png + :alt: The Computed view within the Inspector + :class: border + +To learn more about the CSS declarations listed in this view, see :ref:`Examine computed CSS <page_inspector_how_to_examine_and_edit_css_examine_computed_css>`. + + +.. _page_inspector_ui_tour_compatibility_view: + +Compatibility view +****************** + +Starting with Firefox Developer Edition version 77, the Compatibility view shows CSS compatibility issues, if any, for properties applied to the selected element, and for the current page as a whole. It shows icons for the browsers that *do* support the properties, and notes properties that are experimental or deprecated. + +.. image:: compat_view.png + :alt: Screenshot of the Compatibility view + :class: center + + +- Click the name of the property to open the reference article for that property on *MDN Web Docs*. The "Browser compatibility" section of the article gives details of browser support for the property. + +- In the **All Issues** section, click the name of the element that uses the property to select that element in the inspector. If more than one element has a given property applied to it, click the triangle to show all the occurrences. + +- To configure the set of browsers you want the Compatibility view to check for, click **Settings** at the bottom of the panel. + +.. image:: compat_panel_settings.png + :alt: Screenshot of the Settings for the Compatibility view + + +Untick the checkbox for any browser you are not interested in. As new browser versions are released, the version numbers in this list will be updated. + + +Fonts view +********** + +The Fonts view shows all the fonts in the page along with editable samples. + +.. image:: inspector_fonts.png + :alt: The all-new Inspector panel in Firefox 57. + :class: border + +See :doc:`View fonts <../how_to/edit_fonts/index>` for more details. + + +.. _page_inspector_ui_tour_animations_view: + +Animations view +*************** + +The Animations view gives you details of any animations applied to the selected element, and a controller to pause them: + +.. image:: animation_detail.png + :alt: This is the Animations pane in the Firefox 57 Inspector. + :class: border + +See :doc:`Work with animations <../how_to/work_with_animations/index>` for more details. diff --git a/devtools/docs/user/page_inspector/ui_tour/indpextor_rules.png b/devtools/docs/user/page_inspector/ui_tour/indpextor_rules.png Binary files differnew file mode 100644 index 0000000000..c1f3c35e7c --- /dev/null +++ b/devtools/docs/user/page_inspector/ui_tour/indpextor_rules.png diff --git a/devtools/docs/user/page_inspector/ui_tour/inspector_2pane.png b/devtools/docs/user/page_inspector/ui_tour/inspector_2pane.png Binary files differnew file mode 100644 index 0000000000..42834664ea --- /dev/null +++ b/devtools/docs/user/page_inspector/ui_tour/inspector_2pane.png diff --git a/devtools/docs/user/page_inspector/ui_tour/inspector_computed.png b/devtools/docs/user/page_inspector/ui_tour/inspector_computed.png Binary files differnew file mode 100644 index 0000000000..dcd8594aca --- /dev/null +++ b/devtools/docs/user/page_inspector/ui_tour/inspector_computed.png diff --git a/devtools/docs/user/page_inspector/ui_tour/inspector_fonts.png b/devtools/docs/user/page_inspector/ui_tour/inspector_fonts.png Binary files differnew file mode 100644 index 0000000000..138361f572 --- /dev/null +++ b/devtools/docs/user/page_inspector/ui_tour/inspector_fonts.png diff --git a/devtools/docs/user/page_inspector/ui_tour/inspector_layout.png b/devtools/docs/user/page_inspector/ui_tour/inspector_layout.png Binary files differnew file mode 100644 index 0000000000..dfdcc2b714 --- /dev/null +++ b/devtools/docs/user/page_inspector/ui_tour/inspector_layout.png diff --git a/devtools/docs/user/page_inspector/ui_tour/inspector_tool.png b/devtools/docs/user/page_inspector/ui_tour/inspector_tool.png Binary files differnew file mode 100644 index 0000000000..9c32d3ae62 --- /dev/null +++ b/devtools/docs/user/page_inspector/ui_tour/inspector_tool.png diff --git a/devtools/docs/user/page_inspector/ui_tour/pageinspector.png b/devtools/docs/user/page_inspector/ui_tour/pageinspector.png Binary files differnew file mode 100644 index 0000000000..a43b0d71e9 --- /dev/null +++ b/devtools/docs/user/page_inspector/ui_tour/pageinspector.png diff --git a/devtools/docs/user/page_inspector/ui_tour/select_element_button.png b/devtools/docs/user/page_inspector/ui_tour/select_element_button.png Binary files differnew file mode 100644 index 0000000000..8c19f3b1c0 --- /dev/null +++ b/devtools/docs/user/page_inspector/ui_tour/select_element_button.png diff --git a/devtools/docs/user/page_inspector/ui_tour/track_changes.png b/devtools/docs/user/page_inspector/ui_tour/track_changes.png Binary files differnew file mode 100644 index 0000000000..d4e234b9c5 --- /dev/null +++ b/devtools/docs/user/page_inspector/ui_tour/track_changes.png diff --git a/devtools/docs/user/performance/index.rst b/devtools/docs/user/performance/index.rst new file mode 100644 index 0000000000..ec9075cee9 --- /dev/null +++ b/devtools/docs/user/performance/index.rst @@ -0,0 +1,7 @@ +=========== +Performance +=========== + +The documentation about the new performance tool (also known as the Firefox +Profiler) can be found on the `Firefox Profiler website +<https://profiler.firefox.com/docs/>`_. diff --git a/devtools/docs/user/responsive_button.png b/devtools/docs/user/responsive_button.png Binary files differnew file mode 100644 index 0000000000..71d2bc8d1a --- /dev/null +++ b/devtools/docs/user/responsive_button.png diff --git a/devtools/docs/user/responsive_design_mode/index.rst b/devtools/docs/user/responsive_design_mode/index.rst new file mode 100644 index 0000000000..58c2b1485c --- /dev/null +++ b/devtools/docs/user/responsive_design_mode/index.rst @@ -0,0 +1,213 @@ +====================== +Responsive Design Mode +====================== + +`Responsive design <https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps/Responsive/responsive_design_building_blocks>`_ is the practice of designing a website so it looks and works properly on a range of different devices — particularly mobile phones and tablets as well as desktops and laptops. + +The most obvious factor here is screen size, but there are other factors as well, including the pixel density of the display and whether it supports touch. Responsive Design Mode gives you a simple way to simulate these factors, to test how your website will look and behave on different devices. + + +Toggling Responsive Design Mode +******************************* + +There are three ways to toggle Responsive Design Mode: + + +- From the Firefox menu: Select **Responsive Design Mode** from the **Browser Tools** submenu in the Firefox Menu (or **Tools** menu if you display the menu bar or are on macOS). +- From the Developer Tools toolbox: Press the **Responsive Design Mode** button in the :ref:`Toolbox's toolbar <tools-toolbox-toolbar>` +- From the keyboard: Press :kbd:`Ctrl` + :kbd:`Shift` + :kbd:`M` (or :kbd:`Cmd` + :kbd:`Opt` + :kbd:`M` on macOS). + + +Controlling Responsive Design Mode +********************************** + +With Responsive Design Mode enabled, the content area for web pages is set to the screen size for a mobile device. Initially, it's set to 320 x 480 pixels. + +.. note:: + + The device you select when in Responsive Design Mode and the orientation (portrait or landscape) is saved between sessions. + +.. image:: responsive_ui.png + :class: center + +Information for the selected device is centered over the display. From left to right, the display includes: + + +- *Name of the selected device* - A drop-down list that includes whatever devices you have selected from the Device Settings screen. +- *Screen size* - You can edit the width and height values to change the device size by editing a number directly or using the :kbd:`Up` and :kbd:`Down` keys to increase or decrease the value by 1 pixels on each keypress or hold and :kbd:`Shift` to change the value by 10. + + - The mouse wheel changes the size values by 1 pixel at a time + - You can also change the device's screen size by grabbing the bottom-right corner of the viewport and dragging it to the size you want. + + +- *Orientation (portrait or landscape)* - This setting persists between sessions +- *DPR (pixel ratio)* - Beginning with Firefox 68, the DPR is no longer editable; create a custom device in order to change the DPR +- *Throttling* - A drop-down list where you can select the connection throttling to apply, for example 2G, 3G, or LTE +- *Enable/Disable touch simulation* - Toggles whether or not Responsive Design Mode simulates touch events. While touch event simulation is enabled, mouse events are translated into `touch events <https://developer.mozilla.org/en-US/docs/Web/API/Touch_events>`_; this includes (starting in Firefox 79) translating a mouse-drag event into a touch-drag event. (Note that when touch simulation is enabled, this toolbar icon is blue; when simulation is disabled, it is black. + + +On the right end of the screen, three buttons allow you to: + + +.. _responsive-design-mode-camera-button: + +- *Camera button* - take a screenshot + + - Screenshots are saved to Firefox's default download location. + - If you checked "Screenshot to clipboard" in the Developer Tools :doc:`Settings <../settings/index>` page, then the screenshot will be copied to the system clipboard. + +- *Settings button* - Opens the RDM settings menu +- *Close button* - closes RDM mode and returns to regular browsing + + +The Settings menu includes the following commands: + +.. image:: responsive_setting_menu.png + :class: center + +- *Left-align Viewport* - when checked moves the RDM viewport to the left side of the browser window +- *Show user agent* - when checked displays the user agent string +- The final two options define when the page is reloaded: + + - *Reload when touch simulation is toggled:* when this option is enabled, the page is reloaded whenever you toggle touch support. + - *Reload when user agent is changed:* when this option is enabled, the page is reloaded whenever the user agent is changed. + + +Reloading on these changes can be helpful because certain page behaviors would otherwise not be applied. For example, many pages check for touch support on load and only add event handlers if it is supported, or only enable certain features on certain browsers. + +However, if you are not interested in examining such features (maybe you are just checking the overall layout at different sizes), these reloads can waste time and possibly result in the loss of productive work, so it is useful to be able to control these reloads. + +Now when you change such settings for the first time, you are given a warning message that tells you these reloads are no longer automatic, and informed about how you can make them automatic. For example: + + +.. image:: page-reload-warning.png + :class: center + + +Developer Toolbox with RDM +************************** + +You can show or hide the Developer Tools toolbox independently of toggling Responsive Design Mode itself: + +.. image:: rdmdevtools.png + :class: center + +While Responsive Design Mode is enabled, you can continue browsing as you normally would in the resized content area. + + +Device selection +**************** + +Just above the viewport there is a label "no device selected"; click this to see a list of device names. Select a device, and Responsive Design Mode sets the following properties to match the selected device: + + +- Screen size +- Device pixel ratio (the ratio of device physical pixels to device-independent pixels) +- Touch event simulation + + +Additionally, Firefox sets the `User-Agent <https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent>`_ HTTP request header to identify itself as the default browser on the selected device. For example, if you've selected an iPhone, then Firefox identifies itself as Safari. The `navigator.userAgent <https://developer.mozilla.org/en-US/docs/Web/API/Navigator/userAgent>`_ property is set to the same value. + +.. raw:: html + + <iframe width="560" height="315" src="https://www.youtube.com/embed/JNAyKemudv0" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe> + <br/> + <br/> + + +The devices listed in the drop-down are just a subset of the devices that can be selected. At the end of the drop-down, there is an item labeled **Edit list**. Select this to see a panel containing all the choices, which enables you to check the devices you want to see in the drop-down. + + +Creating custom devices +----------------------- + +You can create and save custom devices in Responsive Design Mode by clicking the **Add Custom Device** button. Each device can have its own: + + +- Name +- Size +- DevicePixelRatio +- User Agent String +- Touch Screen + + +Also, you can preview the properties of existing devices by hovering over the name in the device modal, where they display in a tooltip. + +.. raw:: html + + <iframe width="560" height="315" src="https://www.youtube.com/embed/SA0RlGtOCmE" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe> + <br/> + <br/> + +Network throttling +****************** + +If you do all your development and testing using a very fast network connection, users may experience problems with your site if they are using a slower connection. In Responsive Design Mode, you can instruct the browser to emulate, very approximately, the characteristics of various different types of networks. + +The characteristics emulated are: + +- Download speed +- Upload speed +- Minimum latency + + +The table below lists the numbers associated with each network type, but please do not rely on this feature for exact performance measurements; it's intended to give an approximate idea of the user experience in different conditions. + +.. list-table:: + :widths: 25 25 25 25 + :header-rows: 1 + + * - Selection + - Download speed + - Upload speed + - Minimum latency (ms) + + * - GPRS + - 50 Kb/s + - 20 Kb/s + - 500 + + * - Regular 2G + - 250 Kb/s + - 50 Kb/s + - 300 + + * - Good 2G + - 450 Kb/s + - 150 Kb/s + - 150 + + * - Regular 3G + - 750 Kb/s + - 250 Kb/s + - 100 + + * - Good 3G + - 1.5 Mb/s + - 750 Kb/s + - 40 + + * - Regular 4G/LTE + - 4 Mb/s + - 3 Mb/s + - 20 + + * - DSL + - 2 Mb/s + - 1 Mb/s + - 5 + + * - Wi-Fi + - 30 Mb/s + - 15 Mb/s + - 2 + + * - Offline + - 0 Mb/s + - 0 Mb/s + - 5 + +To select a network, click the list box that's initially labeled "No throttling": + +.. image:: rdm_throttling.png + :class: center diff --git a/devtools/docs/user/responsive_design_mode/page-reload-warning.png b/devtools/docs/user/responsive_design_mode/page-reload-warning.png Binary files differnew file mode 100644 index 0000000000..3091b6ae5f --- /dev/null +++ b/devtools/docs/user/responsive_design_mode/page-reload-warning.png diff --git a/devtools/docs/user/responsive_design_mode/rdm_button.png b/devtools/docs/user/responsive_design_mode/rdm_button.png Binary files differnew file mode 100644 index 0000000000..5e3e3dcdc2 --- /dev/null +++ b/devtools/docs/user/responsive_design_mode/rdm_button.png diff --git a/devtools/docs/user/responsive_design_mode/rdm_throttling.png b/devtools/docs/user/responsive_design_mode/rdm_throttling.png Binary files differnew file mode 100644 index 0000000000..978d97254b --- /dev/null +++ b/devtools/docs/user/responsive_design_mode/rdm_throttling.png diff --git a/devtools/docs/user/responsive_design_mode/rdmdevtools.png b/devtools/docs/user/responsive_design_mode/rdmdevtools.png Binary files differnew file mode 100644 index 0000000000..c84263c770 --- /dev/null +++ b/devtools/docs/user/responsive_design_mode/rdmdevtools.png diff --git a/devtools/docs/user/responsive_design_mode/responsive_setting_menu.png b/devtools/docs/user/responsive_design_mode/responsive_setting_menu.png Binary files differnew file mode 100644 index 0000000000..7a1a75469f --- /dev/null +++ b/devtools/docs/user/responsive_design_mode/responsive_setting_menu.png diff --git a/devtools/docs/user/responsive_design_mode/responsive_ui.png b/devtools/docs/user/responsive_design_mode/responsive_ui.png Binary files differnew file mode 100644 index 0000000000..a2df5e6e50 --- /dev/null +++ b/devtools/docs/user/responsive_design_mode/responsive_ui.png diff --git a/devtools/docs/user/rulers/index.rst b/devtools/docs/user/rulers/index.rst new file mode 100644 index 0000000000..4f4408cb18 --- /dev/null +++ b/devtools/docs/user/rulers/index.rst @@ -0,0 +1,28 @@ +====== +Rulers +====== + +You can overlay horizontal and vertical rulers on a web page: + +.. image:: viewport_rulers.png + :class: center + +The units are in pixels. + +The dimensions of the viewport are displayed near the top-right corner of the viewport. + +To be able to toggle rulers for a page, you first need to enable the button by going to the settings page for the Developer Tools and checking "Toggle rulers for the page" under Available Toolbox Buttons. + +.. image:: settings_available_buttons.png + :class: center + +Once enabled, the "Toggle rulers for the page" button appears at the top right of the Toolbox, in the same place as the Settings/Options button. + +.. image:: ruler_toggle_button.png + :class: center + + +Behavior to keep in mind when using rulers: + +- The rulers command must be reapplied in **new tabs** and after **each page refresh.** +- The command isn't permanent. diff --git a/devtools/docs/user/rulers/ruler_toggle_button.png b/devtools/docs/user/rulers/ruler_toggle_button.png Binary files differnew file mode 100644 index 0000000000..5ce8d715e0 --- /dev/null +++ b/devtools/docs/user/rulers/ruler_toggle_button.png diff --git a/devtools/docs/user/rulers/settings_available_buttons.png b/devtools/docs/user/rulers/settings_available_buttons.png Binary files differnew file mode 100644 index 0000000000..0aeeaa65cd --- /dev/null +++ b/devtools/docs/user/rulers/settings_available_buttons.png diff --git a/devtools/docs/user/rulers/viewport_rulers.png b/devtools/docs/user/rulers/viewport_rulers.png Binary files differnew file mode 100644 index 0000000000..4a6f61ea5b --- /dev/null +++ b/devtools/docs/user/rulers/viewport_rulers.png diff --git a/devtools/docs/user/settings/dev_tools_settings.png b/devtools/docs/user/settings/dev_tools_settings.png Binary files differnew file mode 100644 index 0000000000..820c928597 --- /dev/null +++ b/devtools/docs/user/settings/dev_tools_settings.png diff --git a/devtools/docs/user/settings/devtools_layoutmenu.png b/devtools/docs/user/settings/devtools_layoutmenu.png Binary files differnew file mode 100644 index 0000000000..69dbb71603 --- /dev/null +++ b/devtools/docs/user/settings/devtools_layoutmenu.png diff --git a/devtools/docs/user/settings/devtools_menu.png b/devtools/docs/user/settings/devtools_menu.png Binary files differnew file mode 100644 index 0000000000..48dd74639d --- /dev/null +++ b/devtools/docs/user/settings/devtools_menu.png diff --git a/devtools/docs/user/settings/index.rst b/devtools/docs/user/settings/index.rst new file mode 100644 index 0000000000..7b3a2eb104 --- /dev/null +++ b/devtools/docs/user/settings/index.rst @@ -0,0 +1,228 @@ +======== +Settings +======== + +.. _tool-toolbox-settings: + +Opening Settings +**************** + +Beginning with Firefox 62, the icon to open Developer Tools settings has been moved into a menu accessed by clicking/touching ... (the ellipsis) on the right of the tab. + +.. image:: devtools_layoutmenu.png + :class: center + +The menu includes settings to control the location of the Developer Tools. You can choose between the default setting at the bottom of the windows, or move the tools to the left or right side of the screen. These settings are particularly useful if you have a widescreen monitor. You can also choose to open the tools in a separate window. + +**Show split console** adds a section at the bottom of the tools showing the console. It makes visible the command line and one or two lines of the console output. + +.. image:: split_console.png + :class: center + +The rest of the settings are on the Developer Tools Settings Pane. To see the settings, open any of the Developer Tools, and then: + + +- click the "Settings" command in the menu: + + .. image:: devtools_menu.png + :class: border + +- or press :kbd:`F1` to toggle between the active tool and the Settings pane + + +The Settings pane looks something like this: + +.. image:: dev_tools_settings.png + :alt: Depicts the Toolbox options + :class: center + + +Categories +********** + +Default Firefox Developer Tools +------------------------------- + +This group of checkboxes determines which tools are enabled in the toolbox. New tools are often included in Firefox but not enabled by default. + + +Available Toolbox Buttons +------------------------- + +This group of checkboxes determines which tools get :ref:`an icon in the Toolbox's toolbar <tools-toolbox-extra-tools>`. + +As of Firefox 62, if the option to "Select an iframe as the currently targeted document" is checked, the icon will appear in the toolbar while the Settings tab is displayed, even if the current page doesn't include any iframes. + +Note that in Firefox 52 we removed the checkbox to toggle the :ref:`"Select element" button <page_inspector_select_element_button>`. The "Select element" button is now always shown. + + +.. _settings-themes: + +Themes +****** + +This enables you to choose one of two themes. + +- There's a light theme, which is the default: + + .. image:: theme-light.png + :alt: Light theme for DevTools + :class: border + +- A dark theme (the default on `Firefox Developer Edition <https://www.mozilla.org/en-US/firefox/developer/>`_): + + .. image:: theme-dark.png + :alt: Dark theme for DevTools + :class: border + + +.. _settings-common-preferences: + +Common preferences +------------------ + +Settings that apply to more than one tool. There's just one of these: + +*Enable persistent logs* + A setting to control whether or not the Web Console and Network Monitor clear their output when you navigate to a new page. + +.. note:: + + If Common Preferences is not included in the Settings, Web Console logs can be persisted by using the 'about:config' url in browser address bar, searching for: 'devtools.webconsole.persistlog' then toggling this value to true + + +.. _settings-inspector: + +Inspector +--------- + +*Show browser styles* + A setting to control whether styles applied by the browser (`user-agent styles <https://developer.mozilla.org/en-US/docs/Web/CSS/Cascade>`_) should be displayed in the Inspector's :doc:`Rules view <../page_inspector/how_to/examine_and_edit_css/index>`. Note that this setting is independent of the "Browser styles" checkbox in the Inspector's :ref:`Computed view <page_inspector_how_to_examine_and_edit_css_examine_computed_css>`. + +*Truncate DOM attributes* + By default, the Inspector truncates DOM attributes that are more than 120 characters long. Uncheck this box to prevent this behavior. This setting works by toggling the about:config preference ``devtools.markup.collapseAttributes``. To change the threshold at which attributes are truncated, you can edit the about:config preference ``devtools.markup.collapseAttributeLength``. + +*Default color unit* + A setting to control how colors are represented in the inspector: + + - Hex + - HSL(A) + - RGB(A) + - HWB + - color name + - As authored. + + +*Enable layout panel* + Enable the experimental layout panel. This setting only exists in Firefox Nightly. + + +.. _settings-web-console: + +Web Console +----------- + +*Enable timestamps* + Controls whether the Web Console displays timestamps. The Web Console defaults to hiding timestamps. + +*Enable new console frontend* + Switch to the experimental new console. This setting only exists in Firefox Nightly. + + +.. _settings-debugger: + +Debugger +-------- + +*Enable Source Maps* + Enable :doc:`source map support <../debugger/how_to/use_a_source_map/index>` in the debugger. + +*Enable new debugger frontend* + Enable the new debugger. This setting only exists in Firefox Nightly. + + + +.. _settings-style-editor: + +Style Editor +------------ + +*Show original sources* + When a CSS preprocessor supporting source maps is used, this enables the Style Editor to display the original, preprocessor, sources rather than the generated CSS. :ref:`Learn more about Style Editor support for CSS source maps <style-editor-source-map-support>`. With this setting checked, the :ref:`Page Inspector Rules view will also provide links to the original sources <page-inspector-how-to-examine-and-edit-css-link-to-css-file>`. + +*Autocomplete CSS* + Enable the Style Editor to offer autocomplete suggestions. + + +Screenshot Behavior +------------------- + +*Screenshot to clipboard* + When you click the icon for the :doc:`Screenshot tool <../taking_screenshots/index>`, copy the screenshot image to the clipboard (the image will still be saved to your Downloads directory). New in Firefox 53. + +*Play camera shutter sound* + When you click the icon for the :doc:`Screenshot tool <../taking_screenshots/index>`, play a shutter sound. New in Firefox 53. + + + +.. _settings-editor-preferences: + +Editor Preferences +****************** + +Preferences for the `CodeMirror <https://codemirror.net/>`_ source editor, which is included in Firefox and used by several developer tools, including the :doc:`Style Editor <../style_editor/index>`. + +*Detect indentation* + Auto-indent new lines based on the current indentation. + +*Autoclose brackets* + Determines whether typing an opening character like ``[`` or ``{`` will cause the editor to insert the matching closing character ``]`` or ``}`` for you. + +*Indent using spaces* + When checked, indentation will be performed using spaces, when off, the editor will use tabs instead. + +*Tab size* + The frequency of tab stops in the editor. Select 2, 4, or 8. + +*Keybindings* + Choose the default CodeMirror keybindings or keybindings from one of several popular editors: + + - Vim + - Emacs + - Sublime Text + + +.. _settings_advanced_settings: + +Advanced settings +***************** + +*Show Gecko platform data* + A setting to control whether or not profiles should include Gecko platform symbols. + +*Disable HTTP Cache* + Disable the browser HTTP cache to simulate first-load performance in all tabs that have the Toolbox open. This setting persists, meaning that if it is set, caching will be disabled whenever you reopen the devtools. Caching is re-enabled when the devtools are closed. Note that service workers are not affected by this option. + +.. note:: + + Note that this option was called "Disable Cache" in Firefox versions previous to 49, but it was renamed to make it clearer that this affects the HTTP cache, and not `Service Workers <https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API>`_/the `Cache API <https://developer.mozilla.org/en-US/docs/Web/API/Cache>`_.</div> + +*Disable JavaScript* + Reload the current tab with JavaScript disabled. + +*Enable Service Workers over HTTP* + Enable Service Worker registrations from insecure websites. + +*Enable browser chrome and add-on debugging toolboxes* + Enable you to use developer tools in the context of the browser itself, and not only web content. + +*Enable remote debugging* + Enable the developer tools debug remote Firefox instances. + +*Enable worker debugging* + Enable a panel within the debugger to debug workers. + + Note: This option got removed from the UI in Firefox 56, because this version ships with a :doc:`new Debugger UI <../debugger/index>`, but it can still be enabled for the old UI by setting the preference ``devtools.debugger.workers`` to ``true``. + +*Enable custom formatters* + Allow websites to define :doc:`custom formatters <../custom_formatters/index>` for JavaScript objects. diff --git a/devtools/docs/user/settings/split_console.png b/devtools/docs/user/settings/split_console.png Binary files differnew file mode 100644 index 0000000000..0f8210aa09 --- /dev/null +++ b/devtools/docs/user/settings/split_console.png diff --git a/devtools/docs/user/settings/theme-dark.png b/devtools/docs/user/settings/theme-dark.png Binary files differnew file mode 100644 index 0000000000..67b5aa0a97 --- /dev/null +++ b/devtools/docs/user/settings/theme-dark.png diff --git a/devtools/docs/user/settings/theme-light.png b/devtools/docs/user/settings/theme-light.png Binary files differnew file mode 100644 index 0000000000..ed5e377544 --- /dev/null +++ b/devtools/docs/user/settings/theme-light.png diff --git a/devtools/docs/user/shader_editor/index.rst b/devtools/docs/user/shader_editor/index.rst new file mode 100644 index 0000000000..3a4310480f --- /dev/null +++ b/devtools/docs/user/shader_editor/index.rst @@ -0,0 +1,71 @@ +============= +Shader Editor +============= + +.. warning:: + + This tool has been deprecated and will soon be removed from Firefox. For details, see :doc:`Deprecated tools <../index>`. + +The Shader Editor enables you to see and edit the vertex and fragment shaders used by `WebGL <https://developer.mozilla.org/en-US/docs/Web/API/WebGL_API>`_. + +.. raw:: html + + <iframe width="560" height="315" src="https://www.youtube.com/embed/hnoKqFuJhu0" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe> + <br/> + <br/> + +WebGL is a `JavaScript <https://developer.mozilla.org/en-US/docs/Web/JavaScript>`_ API for rendering interactive 3D graphics and 2D graphics in the browser without using plugins. With WebGL you provide 2 programs called **shaders** which are called at the appropriate stages of the `OpenGL rendering pipeline <https://www.opengl.org/wiki/Rendering_Pipeline_Overview>`_: a `vertex shader <https://www.opengl.org/wiki/Vertex_Shader>`_, which computes the clip space coordinates of each vertex to be drawn, and a `fragment shader <https://www.opengl.org/wiki/Fragment_Shader>`_, which determines the color for each pixel to be drawn. + + +These shaders are written in **OpenGL Shading Language**, or `GLSL <https://www.opengl.org/documentation/glsl/>`_. In WebGL they can be included in a page in several ways: as text hardcoded in JavaScript strings, as separate files included using `<script> <https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script>`_ tags, or retrieved from the server as plain text. JavaScript code running in the page then sends them for compilation using the WebGL APIs, and they're executed on the device's GPU when needed. + +With the Shader Editor, you can examine and edit the source of the vertex and fragment shaders. + + +Opening the Shader Editor +************************* + +The Shader Editor is disabled by default. To enable it, open the :doc:`Toolbox settings <../tools_toolbox/index>` and check "Shader Editor" in the "Default Firefox Developer Tools" item. You'll now see "Shader Editor" appear in the toolbar. Click it and the Shader Editor opens. + + +At first you'll just see a blank window with a button asking you to reload the page: + +.. image:: shader-editor-open.png + +To get started, load a page which creates a WebGL context and loads a program into it. The screenshots below are from the `Unreal Engine <https://www.unrealengine.com/html5/>`_ demo. + +You'll now see a window divided into three panes: a list of all the GLSL programs on the left, the vertex shader for the currently selected program in the middle, and the fragment shader for the currently selected program on the right: + +.. image:: shader-editor-loaded.png + + +Managing programs +***************** + +The left hand pane lists all programs currently in use by a WebGL context. If you hover over an entry in the list, the geometry drawn by that program is highlighted in red: + +.. image:: shader-editor-highlight.png + + +If you click the eyeball icon just left of the program's entry, that program is disabled. This is useful for focusing on certain shaders or hiding overlapping geometry: + +.. image:: shader-editor-disable.png + +If you click the entry, its vertex and fragment shaders are shown in the other two panes, and you can edit them. + +Editing shaders +*************** + +The middle and right hand panes show the vertex and fragment shaders for the currently selected program. + +You can edit these programs and see the results the next time the WebGL context redraws (for example, in the next animation frame). For example, you can modify the colors: + +.. image:: shader-editor-edit-color.png + +The editor highlights syntax errors in your code: + +.. image:: shader-editor-error.png + +If you hover over the cross shown next to a line containing an error, you'll see more details about the problem: + +.. image:: shader-editor-error-info.png diff --git a/devtools/docs/user/shader_editor/shader-editor-disable.png b/devtools/docs/user/shader_editor/shader-editor-disable.png Binary files differnew file mode 100644 index 0000000000..ec634eea9f --- /dev/null +++ b/devtools/docs/user/shader_editor/shader-editor-disable.png diff --git a/devtools/docs/user/shader_editor/shader-editor-edit-color.png b/devtools/docs/user/shader_editor/shader-editor-edit-color.png Binary files differnew file mode 100644 index 0000000000..3fc215c26c --- /dev/null +++ b/devtools/docs/user/shader_editor/shader-editor-edit-color.png diff --git a/devtools/docs/user/shader_editor/shader-editor-error-info.png b/devtools/docs/user/shader_editor/shader-editor-error-info.png Binary files differnew file mode 100644 index 0000000000..f41172a218 --- /dev/null +++ b/devtools/docs/user/shader_editor/shader-editor-error-info.png diff --git a/devtools/docs/user/shader_editor/shader-editor-error.png b/devtools/docs/user/shader_editor/shader-editor-error.png Binary files differnew file mode 100644 index 0000000000..f52cc86db2 --- /dev/null +++ b/devtools/docs/user/shader_editor/shader-editor-error.png diff --git a/devtools/docs/user/shader_editor/shader-editor-highlight.png b/devtools/docs/user/shader_editor/shader-editor-highlight.png Binary files differnew file mode 100644 index 0000000000..cfa449377d --- /dev/null +++ b/devtools/docs/user/shader_editor/shader-editor-highlight.png diff --git a/devtools/docs/user/shader_editor/shader-editor-loaded.png b/devtools/docs/user/shader_editor/shader-editor-loaded.png Binary files differnew file mode 100644 index 0000000000..91c2102319 --- /dev/null +++ b/devtools/docs/user/shader_editor/shader-editor-loaded.png diff --git a/devtools/docs/user/shader_editor/shader-editor-open.png b/devtools/docs/user/shader_editor/shader-editor-open.png Binary files differnew file mode 100644 index 0000000000..c354a6f70b --- /dev/null +++ b/devtools/docs/user/shader_editor/shader-editor-open.png diff --git a/devtools/docs/user/storage_inspector/cache_storage.png b/devtools/docs/user/storage_inspector/cache_storage.png Binary files differnew file mode 100644 index 0000000000..e45e4da184 --- /dev/null +++ b/devtools/docs/user/storage_inspector/cache_storage.png diff --git a/devtools/docs/user/storage_inspector/cache_storage/cache_storage_detail.png b/devtools/docs/user/storage_inspector/cache_storage/cache_storage_detail.png Binary files differnew file mode 100644 index 0000000000..42a8f5c7e3 --- /dev/null +++ b/devtools/docs/user/storage_inspector/cache_storage/cache_storage_detail.png diff --git a/devtools/docs/user/storage_inspector/cache_storage/index.rst b/devtools/docs/user/storage_inspector/cache_storage/index.rst new file mode 100644 index 0000000000..68dc86cd2b --- /dev/null +++ b/devtools/docs/user/storage_inspector/cache_storage/index.rst @@ -0,0 +1,12 @@ +============= +Cache Storage +============= + +Under the *Cache Storage* type within the :doc:`Storage Inspector <../index>` you can see the contents of any DOM caches created using the `Cache API <https://developer.mozilla.org/en-US/docs/Web/API/Cache>`_. If you select a cache, you'll see a list of the resources it contains. For each resource, you'll see: + + +- the URL for the resource. +- the status code for the request that was made to fetch it. + +.. image:: cache_storage_detail.png + :class: border diff --git a/devtools/docs/user/storage_inspector/cookie_context_menu.png b/devtools/docs/user/storage_inspector/cookie_context_menu.png Binary files differnew file mode 100644 index 0000000000..1dce7ef370 --- /dev/null +++ b/devtools/docs/user/storage_inspector/cookie_context_menu.png diff --git a/devtools/docs/user/storage_inspector/cookie_storage.png b/devtools/docs/user/storage_inspector/cookie_storage.png Binary files differnew file mode 100644 index 0000000000..300c729834 --- /dev/null +++ b/devtools/docs/user/storage_inspector/cookie_storage.png diff --git a/devtools/docs/user/storage_inspector/cookies/cookie_table_widget_context.png b/devtools/docs/user/storage_inspector/cookies/cookie_table_widget_context.png Binary files differnew file mode 100644 index 0000000000..e0f898dc9e --- /dev/null +++ b/devtools/docs/user/storage_inspector/cookies/cookie_table_widget_context.png diff --git a/devtools/docs/user/storage_inspector/cookies/index.rst b/devtools/docs/user/storage_inspector/cookies/index.rst new file mode 100644 index 0000000000..d6dabffd26 --- /dev/null +++ b/devtools/docs/user/storage_inspector/cookies/index.rst @@ -0,0 +1,42 @@ +======= +Cookies +======= + +When you select an origin inside the *Cookies* storage type from the storage tree, all the cookies present for that origin will be listed in a table. The cookies table has the following columns: + + +- *Name* — The name of the cookie. +- *Value* — The value of the cookie. +- *Domain* — The domain of the cookie. +- *Path* — The path property of the cookie. +- *Expires / Max-Age* — The time when the cookie will expire. If the cookie is a session cookie, the value of this column will be "Session" +- *Size* — The size of the cookie name plus value in bytes. +- *HttpOnly* — Is this cookie HTTP only? +- *Secure* — Is this cookie a secure cookie? +- *SameSite* — Is this cookie a same-site cookie? Same-site cookies allow servers to mitigate the risk of CSRF and information leakage attacks by asserting that a particular cookie should only be sent with requests initiated from the same registrable domain. +- *Last accessed* — Date and time when the cookie was last read. +- *Created* — Date and time when the cookie was created. +- *HostOnly* — Is this cookie a domain cookie? That is, the domain value matches exactly the domain of the current website. + + +.. note:: + + Some of the columns are not shown by default — to change the column display, right-click on the existing table headings and use the resulting context menu to show/hide the columns. + + +You can edit cookies by double-clicking inside cells in the :ref:`Table Widget <storage-inspector-table-widget>` and editing the values they contain, and add new cookies by clicking the "Plus" (+) button and then editing the resulting new row to the value you want. + +Context menu +------------ + +The context menu for each cookie includes the following commands: + + +- *Add item* - add a new cookie. +- *Delete <cookie name>.<domain>* - deletes the selected cookie +- *Delete All From <domain>* - deletes all cookies from the selected domain. This must be an exact match. For example, if you select "Delete All From test8.example.com" only cookies from that domain will be deleted. Cookies from "test13.example.com" will not be deleted. +- *Delete All* - deletes all cookies for the current host. +- *Delete All Session Cookies* - deletes all cookies for the current host that are scheduled to be deleted when the browser shuts down + +.. image:: cookie_table_widget_context.png + :class: border diff --git a/devtools/docs/user/storage_inspector/extension_storage/extension_storage.png b/devtools/docs/user/storage_inspector/extension_storage/extension_storage.png Binary files differnew file mode 100644 index 0000000000..aaf3787932 --- /dev/null +++ b/devtools/docs/user/storage_inspector/extension_storage/extension_storage.png diff --git a/devtools/docs/user/storage_inspector/extension_storage/index.rst b/devtools/docs/user/storage_inspector/extension_storage/index.rst new file mode 100644 index 0000000000..5c6b8300e9 --- /dev/null +++ b/devtools/docs/user/storage_inspector/extension_storage/index.rst @@ -0,0 +1,13 @@ +================= +Extension Storage +================= + +This storage type is only shown when debugging extensions. When selecting an extension ID in the storage tree of the :doc:`Storage Inspector <../index>`, a table lists the details of all the extension storage present for the extension. This table contains the following columns: + + +- *Key* — The name of the stored item. +- *Value* — The value of the stored item. +- *Storage Area* — The name of the area where the item is stored. + +.. image:: extension_storage.png + :class: center diff --git a/devtools/docs/user/storage_inspector/index.rst b/devtools/docs/user/storage_inspector/index.rst new file mode 100644 index 0000000000..fcb6d6226a --- /dev/null +++ b/devtools/docs/user/storage_inspector/index.rst @@ -0,0 +1,144 @@ +================= +Storage Inspector +================= + +The Storage Inspector enables you to inspect various types of storage that a web page can use. Currently it can be used to inspect the following storage types: + + +- *Cache Storage* — any DOM caches created using the `Cache API <https://developer.mozilla.org/en-US/docs/Web/API/Cache>`_. + +- *Cookies* — All the `cookies <https://developer.mozilla.org/en-US/docs/Web/API/Document/cookie>`_ created by the page or any iframes inside of the page. Cookies created as a part of response of network calls are also listed, but only for calls that happened while the tool is open. + +- *IndexedDB* — All `IndexedDB <https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API>`_ databases created by the page or any iframes inside the page, their Object Stores and the items stored in these Object Stores. + +- *Local Storage* — All `local storage <https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage>`_ items created by the page or any iframes inside the page. + +- *Session Storage* — All `session storage <https://developer.mozilla.org/en-US/docs/Web/API/Window/sessionStorage>`_ items created by the page or any iframes inside the page. + + +For the time being, the Storage Inspector only gives you a read-only view of storage. But we're working to let you edit storage contents in future releases. + + +Opening the Storage Inspector +***************************** + +You can open the Storage Inspector by selecting the *Storage* panel in the Web Developer Tools, accessible from the Browser Tools submenu + +The :doc:`Toolbox <../tools_toolbox/index>` will appear at the bottom of the browser window, with the Storage Inspector activated. It's just called "Storage" in the Developer Toolbox. + +.. image:: storage_inspector.png + :class: center + + +Storage Inspector User Interface +******************************** + +The Storage Inspector UI is split into three main components: + +- :ref:`Storage tree <storage-inspector-storage-tree>` +- :ref:`Table Widget <storage-inspector-table-widget>` +- :ref:`Sidebar <storage-inspector-sidebar>` + + +.. image:: storage_labeled.png + :class: center + + +.. _storage-inspector-storage-tree: + +Storage tree +------------ + +The storage tree lists all the storage types that the Storage Inspector can inspect: + +.. image:: storage_types.png + :class: center + +Under each type, objects are organized by origin. For cookies, the protocol does not differentiate the origin. For Indexed DB or local storage an origin is a combination of protocol + hostname. For example, "``http://mozilla.org``" and "``https://mozilla.org``" are two different origins so local storage items cannot be shared between them. + +Under "Cache Storage", objects are organized by origin and then by the name of the cache: + +.. image:: cache_storage.png + :class: border + + +IndexedDB objects are organized by origin, then by database name, then by object store name: + +.. image:: indexeddb_storage.png + :class: border + + +With the Cookies, Local Storage, and Session Storage types, there's only one level in the hierarchy, so stored items are listed directly under each origin: + +.. image:: cookie_storage.png + :class: border + + +You can click on each item in the tree to expand or collapse its children. The tree is live, so if a new origin gets added (by adding an iframe, for example), it will be added to each storage type automatically. + +Clicking on a tree item will display detailed information about that item in the Table Widget on the right. For example, clicking on an origin which is a child of the Cookies storage type will show all the cookies belonging to that domain. + + +.. _storage-inspector-table-widget: + +Table Widget +------------ + +The table widget displays a list of all the items corresponding to the selected tree item (be it an origin, or database) are listed. Depending on the storage type and tree item, the number of columns in the table might differ. + +All the columns in a Table Widget are resizable. You can hide and show columns by context-clicking on the table header and selecting the columns you want to see: + +.. image:: cookie_context_menu.png + :class: border + + +Search +------ + +There's a search box at the top of the Table Widget: + +.. image:: storage_detail_filter.png + :class: border + + +This filters the table to show only items which match the search term. Items match the search term if any of their fields (including fields whose columns you have hidden) contain the search term. + +You can use :kbd:`Ctrl` + :kbd:`F` (:kbd:`Cmd` + :kbd:`F` on a Mac) to focus the search box. + + +Add and refresh storage +----------------------- + +You'll also have buttons available to add a new storage entry or refresh the view of the currently viewed storage type where applicable (you can't add new entries to IndexedDB or Cache): + +.. image:: storage_detail_add_refresh.png + :class: border + + +.. _storage-inspector-sidebar: + +Sidebar +------- + +When you select any row in the Storage table widget, the sidebar is shown with details about that row. If a cookie is selected, it will list all the details about that cookie. + +The sidebar can parse the value of the cookie or local storage item or an IndexedDB item and convert it into a meaningful object instead of just a string. For example: + + +- A stringified JSON like ``'{"foo": "bar"}'`` is shown as the origin JSON: ``{foo: "bar"}``. +- A string containing a key separated value, like ``"1~2~3~4"`` or ``"1=2=3=4"`` is shown like an array: ``[1, 2, 3, 4]``. +- A string containing key-value pairs, like ``"ID=1234:foo=bar"`` is shown as JSON: ``{ID:1234, foo: "bar"}``. + +The shown values can also be filtered using the search box at the top of the sidebar. + + +Working with the Storage Inspector +********************************** + +The following articles cover different aspects of using the Storage Inspector: + +- :doc:`Cookies <../storage_inspector/cookies/index>` +- :doc:`Local Storage / Session Storage <../storage_inspector/local_storage_session_storage/index>` +- :doc:`Cache Storage <../storage_inspector/cache_storage/index>` +- :doc:`IndexedDB <../storage_inspector/indexeddb/index>` +- :doc:`Extension Storage <../storage_inspector/extension_storage/index>` diff --git a/devtools/docs/user/storage_inspector/indexeddb/index.rst b/devtools/docs/user/storage_inspector/indexeddb/index.rst new file mode 100644 index 0000000000..7273e8c456 --- /dev/null +++ b/devtools/docs/user/storage_inspector/indexeddb/index.rst @@ -0,0 +1,52 @@ +========= +IndexedDB +========= + +When you select an origin inside the *Indexed DB* storage type in the storage tree of the :doc:`Storage Inspector <../index>`, a table lists the details of all the databases present for that origin. + +.. note:: + + The data shown in an IndexedDB database is a snapshot of the data as it was when you opened the Storage Inspector tool. + + +Databases have the following details: + + +- *Database Name* — The name of the database. +- *Storage* — The `storage type <https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API/Browser_storage_limits_and_eviction_criteria#different_types_of_data_storage>`_ specified for the database. +- *Origin* — The origin of the database. +- *Version* — The database version. +- *Object Stores* — The number of object stores in the database. + + +When an IndexedDB database is selected in the storage tree, details about all the object stores are listed in the table. Any object store has the following details: + + +- *Object Store Name* — The name of the object store. +- *Key* — The `keyPath <https://developer.mozilla.org/en-US/docs/Web/API/IDBIndex/keyPath>`_ property of the object store. +- *Auto Increment* — Is automatic incrementation of the keys enabled? +- *Indexes* — Array of indexes present in the object store as shown below. + + +.. image:: indexed_db_details.png + :class: border + + +When an object store is selected in the storage tree, all the items in that object store are listed in the table. All items have a key and a value associated with them. + +You can delete an IndexedDB database using the context menu in the storage tree: + +.. image:: indexed_db_context_menu.png + :class: border + + +If the database cannot be deleted (most commonly because there are still active connections to the database), a warning message will be displayed in the Storage Inspector: + +.. image:: indexeddb_delete_warning.png + :class: border + + +You can use the context menu in the table widget to delete all items in an object store, or a particular item: + +.. image:: indexed_db_table_widget_context.png + :class: border diff --git a/devtools/docs/user/storage_inspector/indexeddb/indexed_db_context_menu.png b/devtools/docs/user/storage_inspector/indexeddb/indexed_db_context_menu.png Binary files differnew file mode 100644 index 0000000000..45dbc214fe --- /dev/null +++ b/devtools/docs/user/storage_inspector/indexeddb/indexed_db_context_menu.png diff --git a/devtools/docs/user/storage_inspector/indexeddb/indexed_db_details.png b/devtools/docs/user/storage_inspector/indexeddb/indexed_db_details.png Binary files differnew file mode 100644 index 0000000000..8cb4602a26 --- /dev/null +++ b/devtools/docs/user/storage_inspector/indexeddb/indexed_db_details.png diff --git a/devtools/docs/user/storage_inspector/indexeddb/indexed_db_table_widget_context.png b/devtools/docs/user/storage_inspector/indexeddb/indexed_db_table_widget_context.png Binary files differnew file mode 100644 index 0000000000..6c243c1816 --- /dev/null +++ b/devtools/docs/user/storage_inspector/indexeddb/indexed_db_table_widget_context.png diff --git a/devtools/docs/user/storage_inspector/indexeddb/indexeddb_delete_warning.png b/devtools/docs/user/storage_inspector/indexeddb/indexeddb_delete_warning.png Binary files differnew file mode 100644 index 0000000000..8e4dc2c30f --- /dev/null +++ b/devtools/docs/user/storage_inspector/indexeddb/indexeddb_delete_warning.png diff --git a/devtools/docs/user/storage_inspector/indexeddb_storage.png b/devtools/docs/user/storage_inspector/indexeddb_storage.png Binary files differnew file mode 100644 index 0000000000..c83f347e67 --- /dev/null +++ b/devtools/docs/user/storage_inspector/indexeddb_storage.png diff --git a/devtools/docs/user/storage_inspector/local_storage_session_storage/delete_storage_menu.png b/devtools/docs/user/storage_inspector/local_storage_session_storage/delete_storage_menu.png Binary files differnew file mode 100644 index 0000000000..48226a9456 --- /dev/null +++ b/devtools/docs/user/storage_inspector/local_storage_session_storage/delete_storage_menu.png diff --git a/devtools/docs/user/storage_inspector/local_storage_session_storage/index.rst b/devtools/docs/user/storage_inspector/local_storage_session_storage/index.rst new file mode 100644 index 0000000000..31e0b0ebe4 --- /dev/null +++ b/devtools/docs/user/storage_inspector/local_storage_session_storage/index.rst @@ -0,0 +1,23 @@ +=============================== +Local Storage / Session Storage +=============================== + +When an origin corresponding to local storage or session storage is selected within the :doc:`Storage Inspector <../index>`, the names and values of all the items corresponding to local storage or session storage will be listed in a table. + +You can edit local and session storage items by double-clicking inside cells in the :ref:`Table Widget <storage-inspector-table-widget>` and editing the values they contain: + +.. raw:: html + + <iframe width="560" height="315" src="https://www.youtube.com/embed/UKLgBBUi11c" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe> + <br/> + <br/> + +You can delete local storage and session storage entries using the context menu: + +.. image:: delete_storage_menu.png + :class: border + + +You can also delete local and session storage entries by selecting an item and pressing the :kbd:`Delete` or :kbd:`Backspace` key. + +Finally, you can add new storage items by clicking the "Plus" (+) button and then editing the resulting new row to the value you want. diff --git a/devtools/docs/user/storage_inspector/storage_detail_add_refresh.png b/devtools/docs/user/storage_inspector/storage_detail_add_refresh.png Binary files differnew file mode 100644 index 0000000000..4ffeed2800 --- /dev/null +++ b/devtools/docs/user/storage_inspector/storage_detail_add_refresh.png diff --git a/devtools/docs/user/storage_inspector/storage_detail_filter.png b/devtools/docs/user/storage_inspector/storage_detail_filter.png Binary files differnew file mode 100644 index 0000000000..dc6888654a --- /dev/null +++ b/devtools/docs/user/storage_inspector/storage_detail_filter.png diff --git a/devtools/docs/user/storage_inspector/storage_inspector.png b/devtools/docs/user/storage_inspector/storage_inspector.png Binary files differnew file mode 100644 index 0000000000..ec9c21f77d --- /dev/null +++ b/devtools/docs/user/storage_inspector/storage_inspector.png diff --git a/devtools/docs/user/storage_inspector/storage_labeled.png b/devtools/docs/user/storage_inspector/storage_labeled.png Binary files differnew file mode 100644 index 0000000000..28cecc6ea0 --- /dev/null +++ b/devtools/docs/user/storage_inspector/storage_labeled.png diff --git a/devtools/docs/user/storage_inspector/storage_types.png b/devtools/docs/user/storage_inspector/storage_types.png Binary files differnew file mode 100644 index 0000000000..4a17e73fc5 --- /dev/null +++ b/devtools/docs/user/storage_inspector/storage_types.png diff --git a/devtools/docs/user/style_editor/index.rst b/devtools/docs/user/style_editor/index.rst new file mode 100644 index 0000000000..fb91a5d95f --- /dev/null +++ b/devtools/docs/user/style_editor/index.rst @@ -0,0 +1,153 @@ +============ +Style Editor +============ + +The Style Editor enables you to: + + +- view and edit all the stylesheets associated with a page +- create new stylesheets from scratch and apply them to the page +- import existing stylesheets and apply them to the page + +.. raw:: html + + <iframe width="560" height="315" src="https://www.youtube.com/embed/7839qc55r7o" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe> + <br/> + <br/> + +To open the Style Editor select the *Style Editor* panel in the Web Developer Tools, accessible from the Browser Tools submenu + +.. image:: style-editor.png + :class: center + +The Style Editor is divided into three main sections: + +- :ref:`the style sheet pane on the left <style-editor-the-style-sheet-pane>` +- :ref:`the editor on the right <style-editor-the-editor-pane>` +- :ref:`the At-rules sidebar <style-editor-the-at-rules-sidebar>` + + +.. _style-editor-the-style-sheet-pane: + +The style sheet pane +******************** + +The style sheet pane, on the left, lists all the style sheets being used by the current document. You can quickly toggle the use of a given sheet on and off by clicking the eyeball icon to the left of the sheet's name. You can save any changes you've made to the style sheet to your local computer by clicking the Save button in the bottom-right corner of each sheet's entry in the list. + +From Firefox 40 onwards, the style sheet pane also includes a context menu that lets you open the selected style sheet in a new tab. + + +.. _style-editor-the-editor-pane: + +The editor pane +*************** + +On the right is the editor pane. This is where the source for the selected style sheet is available for you to read and edit. Any changes you make are immediately applied to the page. This makes it easy to experiment with, revise, and test changes. Once you're satisfied with your changes, you can save a copy locally by clicking the Save button on the sheet's entry in the style sheet pane. + +The editor provides line numbers and syntax highlighting to help make it easier to read your CSS. It also supports a number of :ref:`keyboard shortcuts <style-editor-keyboard-shortcuts>`. + +The Style Editor automatically de-minimizes style sheets that it detects, without affecting the original. This makes it much easier to work on pages that have been optimized. + +The Style Editor supports autocomplete. Just start typing, and it will offer you a list of suggestions. + +.. image:: style-editor-autocomplete.png + :class: center + +You can switch autocomplete off in the :ref:`Style Editor settings <settings-style-editor>`. + + +.. _style-editor-the-at-rules-sidebar: + +The At-rules sidebar +******************** + +The Style Editor displays a sidebar on the right-hand side whenever the current sheet contains any of the following At-rules: + +- `@media <https://developer.mozilla.org/en-US/docs/Web/CSS/Media_Queries/Using_media_queries>`_ +- `@supports <https://developer.mozilla.org/en-US/docs/Web/CSS/@supports>`_ +- `@layer <https://developer.mozilla.org/en-US/docs/Web/CSS/@layer>`_ +- `@container <https://developer.mozilla.org/en-US/docs/Web/CSS/Media_Queries/Using_media_queries>`_ + +The sidebar lists the rules and provides a link to the line of the sheet where the rule is defined. Click an item to jump to that rule in the sheet. For ``@media`` rules, the condition text of the rule is greyed-out if the media query doesn’t currently apply. + +.. image:: style-editor-at-rules-sidebar-detail.png + :class: center + +The At-rules sidebar works especially well with :doc:`Responsive Design View <../responsive_design_mode/index>` for creating and debugging responsive layouts: + +.. raw:: html + + <iframe width="560" height="315" src="https://www.youtube.com/embed/aVUXmvLSwoM" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe> + <br/> + <br/> + +From Firefox 46 onwards, if an ``@media`` rule contains a screen size in a condition, then it is made clickable: clicking it then resizes the screen to that size using the Responsive Design View. + + +Creating and importing style sheets +*********************************** + +You can create a new style sheet by clicking the New button in the toolbar. Then you can just start entering CSS into the new editor and watch as the new styles are applied in real time just like changes to the other sheets. + +You can load a style sheet from disk and apply it to the page by clicking the Import button. + + +.. _style-editor-source-map-support: + +Source map support +****************** + +.. raw:: html + + <iframe width="560" height="315" src="https://www.youtube.com/embed/zu2eZbYtEUQ" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe> + <br/> + <br/> + +Web developers often create CSS files using a preprocessor like `Sass <https://sass-lang.com/>`_, `Less <https://lesscss.org/>`_, or `Stylus <https://learnboost.github.io/stylus/>`_. These tools generate CSS files from a richer and more expressive syntax. If you do this, being able to see and edit the generated CSS is not so useful, because the code you maintain is the preprocessor syntax, not the generated CSS. So you'd need to edit the generated CSS, then manually work out how to reapply that to the original source. + +Source maps enable the tools to map back from the generated CSS to the original syntax, so they can display, and allow you to edit, files in the original syntax. From Firefox 29 onwards, the Style Editor can understand CSS source maps. + +This means that if you use, for example, Sass, then the Style Editor will show you, and allow you to edit, Sass files, rather than the CSS that is generated from them: + +.. image:: style-editor-sourcemap.png + :class: center + + +For this to work, you must: + + +- use a CSS preprocessor that understands the `Source Map Revision 3 proposal <https://docs.google.com/document/d/1U1RGAehQwRypUTovF1KRlpiOFze0b-_2gc6fAH0KY0k/edit>`_. Currently this means `Sass 3.3.0 <https://sass-lang.com/>`_ or above or the `1.5.0 version of Less <http://roots.io/using-less-source-maps/>`_. Other preprocessors are actively working on adding support, or considering it. +- actually instruct the preprocessor to generate a source map, for example by passing the ``--source-map`` argument to the Lass command-line tool, but in some preprocessors like Sass, source maps are generated by default and you don't need to do anything. + + +Viewing original sources +------------------------ + +Now, if you check "Show original sources" in the :ref:`Style Editor settings <settings-style-editor>`, the links next to CSS rules in the :ref:`Rules view <page_inspector_ui_tour_rules_view>` will link to the original sources in the Style Editor. + +From Firefox 35 onwards original sources are displayed by default. + + +Editing original sources +------------------------ + +You can also edit the original sources in the Style Editor and see the results applied to the page immediately. To get this to work there are two extra steps. + +First, set up your preprocessor so it watches the original source and automatically regenerates the CSS when the source changes. With Sass you can do this by passing the ``--watch`` option: + +.. code-block:: + + sass index.scss:index.css --watch + + +Next, save the original source in the Style Editor by clicking the "Save" button next to the file, and saving it over the original file. + +Now when you make changes to the source file in the Style Editor the CSS is regenerated and you can see the changes right away. + + +.. _style-editor-keyboard-shortcuts: + +Keyboard shortcuts +****************** + + - :ref:`Source editor shortcuts <keyboard-shortcuts-style-editor>` diff --git a/devtools/docs/user/style_editor/style-editor-at-rules-sidebar-detail.png b/devtools/docs/user/style_editor/style-editor-at-rules-sidebar-detail.png Binary files differnew file mode 100644 index 0000000000..bf6200a1a4 --- /dev/null +++ b/devtools/docs/user/style_editor/style-editor-at-rules-sidebar-detail.png diff --git a/devtools/docs/user/style_editor/style-editor-autocomplete.png b/devtools/docs/user/style_editor/style-editor-autocomplete.png Binary files differnew file mode 100644 index 0000000000..fa916dbf43 --- /dev/null +++ b/devtools/docs/user/style_editor/style-editor-autocomplete.png diff --git a/devtools/docs/user/style_editor/style-editor-sourcemap.png b/devtools/docs/user/style_editor/style-editor-sourcemap.png Binary files differnew file mode 100644 index 0000000000..1b77fb5afe --- /dev/null +++ b/devtools/docs/user/style_editor/style-editor-sourcemap.png diff --git a/devtools/docs/user/style_editor/style-editor.png b/devtools/docs/user/style_editor/style-editor.png Binary files differnew file mode 100644 index 0000000000..8d322cc5b7 --- /dev/null +++ b/devtools/docs/user/style_editor/style-editor.png diff --git a/devtools/docs/user/taking_screenshots/camera-icon.png b/devtools/docs/user/taking_screenshots/camera-icon.png Binary files differnew file mode 100644 index 0000000000..faa229d55c --- /dev/null +++ b/devtools/docs/user/taking_screenshots/camera-icon.png diff --git a/devtools/docs/user/taking_screenshots/index.rst b/devtools/docs/user/taking_screenshots/index.rst new file mode 100644 index 0000000000..e989879818 --- /dev/null +++ b/devtools/docs/user/taking_screenshots/index.rst @@ -0,0 +1,127 @@ +================== +Taking screenshots +================== + +You can use the Developer Tools to take a screenshot of the entire page, or of a single element in the page. + +.. _taking_screenshots_taking_a_screenshot_of_the_page: + + +Taking a screenshot of the page +******************************* + +.. |image1| image:: camera-icon.png + :width: 20 + + +Use the screenshot icon: |image1| to take a full-page screenshot of the current page. + +By default, the screenshot icon is not enabled. To enable it: + + +- visit the :doc:`Settings <../settings/index>` page +- find the section labeled "Available Toolbox Buttons" +- check the box labeled "Take a screenshot of the entire page". + + +You'll now see the icon in the toolbar: + +.. raw:: html + + <iframe width="560" height="315" src="https://www.youtube.com/embed/KB5V9uJgcS4" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe> + <br/> + <br/> + +Click the icon to take a screenshot of the current page. The screenshot is saved to your browser's "Downloads" directory: + +.. raw:: html + + <iframe width="560" height="315" src="https://www.youtube.com/embed/HKS6MofdXVE" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe> + <br/> + <br/> + + +.. _taking-screenshots-of-an-element: + +Taking a screenshot of an element +********************************* + +To take a screenshot of a single element in the page, activate the context menu on that element in the :ref:`Inspector's HTML pane <page_inspector_ui_tour_html_pane>`, and select "Screenshot Node". The screenshot is saved to the browser's "Downloads" directory: + +.. raw:: html + + <iframe width="560" height="315" src="https://www.youtube.com/embed/p2pjF_BrE1o" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe> + <br/> + <br/> + + +Copying screenshots to the clipboard +************************************ + +From Firefox 53, you can also copy the screenshot to the clipboard. Just check the box in Settings labeled "Screenshot to clipboard": + +.. raw:: html + + <iframe width="560" height="315" src="https://www.youtube.com/embed/AZedFGh6F78" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe> + <br/> + <br/> + +Now, whenever you take a screenshot, the screenshot is also copied to the clipboard. + + +Taking screenshots with the web console +*************************************** + +If you need to specify a different device-pixel-ratio, set a delay before taking the screenshot, or specify your own file name, starting in Firefox 62 you can use the ``:screenshot`` helper function in the :doc:`Web Console <../web_console/index>`. + +Type ``:screenshot`` in the Web Console to create a screenshot of the current page. By default, the image file will be named ``Screen Shot yyy-mm-dd at hh.mm.ss.png``. + +.. note:: + + **Tip**: You could type ``:s`` and then hit :kbd:`Tab` to autocomplete ``:screenshot``. + +The command has the following optional parameters: + +.. list-table:: + :widths: 20 20 60 + :header-rows: 1 + + * - Command + - Type + - Description + + * - ``--clipboard`` + - boolean + - When present, this parameter will cause the screenshot to be copied to the clipboard. Prevents saving to a file unless you use the ``--file`` option to force file writing. + + * - ``--delay`` + - number + - The number of seconds to delay before taking the screenshot; you can use an integer or floating point number. This is useful if you want to pop open a menu or invoke a hover state for the screenshot. + + * - ``--dpr`` + - number + - The device pixel ratio to use when taking the screenshot. Values above 1 yield "zoomed-in" images, whereas values below 1 create "zoomed-out" images. + + * - ``--file`` + - boolean + - When present, the screenshot will be saved to a file, even if other options (e.g. ``--clipboard``) are included. + + * - ``--filename`` + - string + - The name to use in saving the file. The file should have a ".png" extension. + + * - ``--fullpage`` + - boolean + - If included, the full webpage will be saved. With this parameter, even the parts of the webpage which are outside the current bounds of the window will be included in the screenshot. When used, "<span style="white-space: nowrap;">-fullpage</span>" will be appended to the file name. + + * - ``--selector`` + - string + - A CSS selector that selects a single element on the page. When supplied, only this element and its descendants will be included in the screenshot. + + +.. note:: + If you capture an image to a filename like ``test.png``, and then you capture to that same filename, the new image will overwrite the old image. So if you’re using the up-arrow history scroll to capture images in quick succession, be careful — you need to remember to change the filename for each new capture. + + +.. note:: + Thanks to Eric Meyer for his enthusiasm for our screenshot feature, and help! Small portions of this section have been borrowed from his `Firefox’s :screenshot command <https://meyerweb.com/eric/thoughts/2018/08/24/firefoxs-screenshot-command-2018/>`_ article. diff --git a/devtools/docs/user/tips/black_boxing.png b/devtools/docs/user/tips/black_boxing.png Binary files differnew file mode 100644 index 0000000000..2c0eeba27a --- /dev/null +++ b/devtools/docs/user/tips/black_boxing.png diff --git a/devtools/docs/user/tips/create_style_sheet_button.png b/devtools/docs/user/tips/create_style_sheet_button.png Binary files differnew file mode 100644 index 0000000000..34d2280408 --- /dev/null +++ b/devtools/docs/user/tips/create_style_sheet_button.png diff --git a/devtools/docs/user/tips/filter.png b/devtools/docs/user/tips/filter.png Binary files differnew file mode 100644 index 0000000000..627542687c --- /dev/null +++ b/devtools/docs/user/tips/filter.png diff --git a/devtools/docs/user/tips/import_button.png b/devtools/docs/user/tips/import_button.png Binary files differnew file mode 100644 index 0000000000..59379cdf90 --- /dev/null +++ b/devtools/docs/user/tips/import_button.png diff --git a/devtools/docs/user/tips/index.rst b/devtools/docs/user/tips/index.rst new file mode 100644 index 0000000000..5b9e51244b --- /dev/null +++ b/devtools/docs/user/tips/index.rst @@ -0,0 +1,144 @@ +==== +Tips +==== + +General +******* + +Screenshots: + +.. |image1| image:: screenshot_button.png + :alt: Button to take screenshots of the entire page + :width: 20 + +- Entire page: Click the screenshot button (|image1| :ref:`needs to be enabled <tools-toolbox-extra-tools>` first). +- Viewport: Click the screenshot button (|image1|) in :ref:`Responsive Design Mode <responsive-design-mode-camera-button>`. +- Node: Right-click a node within the Inspector and click :ref:`"Screenshot Node" <taking-screenshots-of-an-element>`. +- Via :doc:`Web Console command <../web_console/helpers/index>`: ``screenshot <filename.png> --fullpage``. + + +Settings: + +- Choose between a :ref:`light and a dark theme <settings-themes>` for the developer tools. +- :ref:`Change the keyboard bindings <settings-editor-preferences>` to Vim, Emacs or Sublime Text if you're used to different shortcuts. +- Check or uncheck the different tools to enable or disable them. (There are more than the default tools!) + + +Page Inspector +************** + +In the :ref:`markup view <page_inspector_ui_tour_html_pane>`: + + +- Press :kbd:`H` with a node selected to hide/show it. +- Press :kbd:`Backspace` or :kbd:`Del` with a node selected to delete it. +- :kbd:`Alt` + click on a node to expand or collapse it and all its descendants. +- Click on the last :ref:`breadcrumb button <page-inspector-how-to-examine-and-edit-html-breadcrumbs>` to scroll the selection into view in the inspector. +- Click the "ev" icon besides a node to :doc:`see all event listeners attached to it <../page_inspector/examine_event_listeners/index>`. +- Press :kbd:`S` with a node selected to see it in the page (same as right-click a node and click :ref:`Scroll Into View <page_inspector_how_to_examine_and_edit_scroll_into_view>`). +- Right-click a node and click :ref:`Use in Console<page_inspector_how_to_examine_and_edit_html_use_in_console>` to :doc:`command line <../web_console/the_command_line_interpreter/index>` as ``tempN`` variable. + + +When :ref:`selecting elements <page_inspector_select_element_button>`: + + +- :kbd:`Shift` + click to select an element but keep selecting (picker mode doesn't disengage). +- Use :kbd:`←`/:kbd:`→` to navigate to parents/children elements (if they're hard to select). + + +In the :ref:`rules view <page_inspector_ui_tour_rules_view>`: + +.. |image2| image:: picker.png + :width: 20 + +.. |image3| image:: filter.png + :width: 20 + +- Click the inspector icon |image2| next to any selector to highlight all elements that match it. +- Click the inspector icon |image2| next to the ``element{}`` rule to lock the highlighter on the current element. +- Right-click any property and select "Show MDN Docs" to view the MDN docs for this property. +- Click on the filter icon |image3| next to an overridden property to :ref:`find which other property overrides it <page-inspector-how-to-examine-and-edit-css-overridden-declarations>`. +- Right-click on a name, value, or rule to copy anything from the name, the value, the declaration or the whole rule to your clipboard. + + +Web Console +*********** + +In all panels: + +- :kbd:`Esc` opens the :doc:`split console <../web_console/split_console/index>`; useful when debugging, or inspecting nodes + + +In the :doc:`command line <../web_console/the_command_line_interpreter/index>`: + + +- :ref:`$0 <web_console_helpers_$0>` references the currently selected node. +- :ref:`$() <web_console_helpers_$>` is a shortcut to `document.querySelector() <https://developer.mozilla.org/en-US/docs/Web/API/Document/querySelector>`_ +- :ref:`$$() <web_console_helpers_$$>` returns an array with the results from `document.querySelector() <https://developer.mozilla.org/en-US/docs/Web/API/Document/querySelector>`_. +- :ref:`copy <web_console_helpers_copy>` copies anything as a string. +- Right-click a node in the Inspector and click :ref:`Use in Console <page_inspector_how_to_examine_and_edit_html_use_in_console>` to create a :ref:`temp*N* <web_console_helpers_tempn>` variable for it. +- `console.table() <https://developer.mozilla.org/en-US/docs/Web/API/console/table>`_ displays tabular data as table. +- :ref:`help <web_console_helpers_help>` opens the MDN page describing the available commands. +- ``:screenshot <filename.png> --fullpage`` saves a screenshot to your downloads directory using the optional file name. If no filename is included, the file name will be in this format: + +.. code-block:: + + Screen Shot date at time.png + +The ``--fullpage`` parameter is optional. If you include it, the screenshot will be of the whole page, not just the section visible in the browser windows. The file name will have ``-fullpage`` appended to it as well. See :doc:`Web Console Helpers <../web_console/helpers/index>` for all parameters. + + +In the console output: + + +- Click on the inspector icon |image2| next to an element in the output to :ref:`select it within the Inspector <web_console_rich_output_highlighting_and_inspecting_dom_nodes>`. +- Check :ref:`"Enable persistent logs" <settings-common-preferences>` in the settings to keep logged messages from before even after navigation. +- Check :ref:`"Enable timestamps" <settings-web-console>` in the settings to show timestamps besides the logged messages. + + +Debugger +******** + +.. |image4| image:: black_boxing.png + :width: 20 + + +- Skip JavaScript libraries in debugging sessions via the black box icon |image4|. +- Press :kbd:`Ctrl` + :kbd:`Alt` + :kbd:`F` to search in all scripts. +- Press :kbd:`Ctrl` + :kbd:`D` to search for a function definition. +- Press :kbd:`Ctrl` + :kbd:`L` to go to a specific line. + + +Style Editor +************ + +.. |image5| image:: import_button.png + :alt: Button to import a style sheet from the file system + :width: 20 + +.. |image6| image:: create_style_sheet_button.png + :alt: Button to create a new style sheet + :width: 20 + +- The black box icon |image4| in the style sheet pane toggles the visibility of a style sheet. +- Click an :ref:`@media rule <style-editor-the-at-rules-sidebar>` to apply it in :doc:`Responsive Design Mode <../responsive_design_mode/index>`. +- Click the import button |image5| to import a style sheet or the create button |image6| to create a new one. +- Click the options button in the :ref:`style sheet pane <style-editor-the-style-sheet-pane>` and click :ref:`"Show original sources" <style-editor-source-map-support>` to toggle the display of CSS preprocessor files. + + +Network Monitor +*************** + +- Click the request summary to :doc:`compare performance of cache vs. no-cache page loading <../network_monitor/performance_analysis/index>`. +- When a request is selected click :ref:`"Edit and Resend" <network-monitor-request-list-edit-and-resend>` to modify its headers and send it again. +- Check :ref:`"enable persistent logs" <settings-common-preferences>` in the settings to keep requests from before even after navigation. +- Hover the :ref:`"js" icon within the "Cause" column <request-list-requst-list-cause-column>` to see the JavaScript stack trace, which caused the request. +- Check :ref:`"Disable HTTP Cache (when toolbox is open)" <settings_advanced_settings>` in the settings to disable the network cache while debugging network issues. + + +Storage Inspector +***************** + +- Right-click the column headers to open a menu allowing to toggle the display of the columns. +- Right-click an entry and click "Delete *name*" to delete it or "Delete All" to delete all entries. +- Select an entry to see the parsed value of it in the sidebar. diff --git a/devtools/docs/user/tips/picker.png b/devtools/docs/user/tips/picker.png Binary files differnew file mode 100644 index 0000000000..39ea6adc6a --- /dev/null +++ b/devtools/docs/user/tips/picker.png diff --git a/devtools/docs/user/tips/screenshot_button.png b/devtools/docs/user/tips/screenshot_button.png Binary files differnew file mode 100644 index 0000000000..f3ee5ae219 --- /dev/null +++ b/devtools/docs/user/tips/screenshot_button.png diff --git a/devtools/docs/user/tools_toolbox/docking-mode.png b/devtools/docs/user/tools_toolbox/docking-mode.png Binary files differnew file mode 100644 index 0000000000..3bc91ceb8a --- /dev/null +++ b/devtools/docs/user/tools_toolbox/docking-mode.png diff --git a/devtools/docs/user/tools_toolbox/hamburger.png b/devtools/docs/user/tools_toolbox/hamburger.png Binary files differnew file mode 100644 index 0000000000..93e525c3c6 --- /dev/null +++ b/devtools/docs/user/tools_toolbox/hamburger.png diff --git a/devtools/docs/user/tools_toolbox/index.rst b/devtools/docs/user/tools_toolbox/index.rst new file mode 100644 index 0000000000..428c117a4c --- /dev/null +++ b/devtools/docs/user/tools_toolbox/index.rst @@ -0,0 +1,133 @@ +======= +Toolbox +======= + +The Toolbox provides a single home for most of the developer tools that are built into Firefox. + +There are three main ways to open the Toolbox: + +- Right-click a mouse on any element in the page, and select **Inspect** from the popup menu. + +- Open the Hamburger menu |image1| and select **More tools > Web Developer Tools** (Firefox 88 and earlier use the top-level menu **Web Developer** rather than **More tools**). + +- Press :kbd:`Ctrl` + :kbd:`Shift` + :kbd:`I` on Windows and Linux, or :kbd:`Cmd` + :kbd:`Opt` + :kbd:`I` on OS X. See also :doc:`keyboard shortcuts <../keyboard_shortcuts/index>`. + +.. |image1| image:: hamburger.png + :width: 20 + + +By default, the window appears docked to the bottom side of the Firefox window, but you can detach it if you like. This is what it looks like when it's docked: + +.. image:: toolbox.png + :class: border + +The window itself is split into two parts: a toolbar along the top, and a main pane underneath: + +.. image:: toolbox-labelled.png + :class: border + +.. note:: + + Since Firefox 62, you can drag and drop tabs in the main toolbar of the toolbox to reorder your tools as you wish (`Bug 1226272 <https://bugzilla.mozilla.org/show_bug.cgi?id=1226272>`_) + + +.. _tools-toolbox-docking-mode: + +Docking mode +************ + +By default, the Toolbox appears docked to the bottom of the browser window, but you can also dock it to the right-hand side of the window, or make it a standalone window, using :ref:`buttons in toolbar <tools-toolbox-toolbox-controls>`. + +.. image:: docking-mode.png + :class: center + + +.. _tools-toolbox-toolbar: + +Toolbar +******* + +The toolbar contains controls to activate a particular tool, to dock/float the window, and to close the window. + +.. image:: toolbox-toolbar-labelled.png + :class: center + + +Node picker +*********** + +On the far left there's a button to activate the node picker. This lets you select a page element for inspection. See :doc:`Selecting elements <../page_inspector/how_to/select_an_element>` + + +Toolbox-hosted tools +******************** + +Then there is an array of labeled buttons which enables you to switch between the different tools hosted by the Toolbox. The array may include the following tools: + +- :doc:`Page Inspector <../page_inspector/index>` +- :doc:`Web Console <../web_console/index>` +- :doc:`JavaScript Debugger <../debugger/index>` +- :doc:`Network Monitor <../network_monitor/index>` +- :doc:`Style Editor <../style_editor/index>` +- :doc:`Performance <../performance/index>` +- :doc:`Memory Tool <../memory/index>` +- :doc:`Storage Inspector <../storage_inspector/index>` +- :doc:`Accessibility Inspector <../accessibility_inspector/index>` +- :doc:`Application Tool <../application/index>` +- :doc:`DOM Property Viewer <../dom_property_viewer/index>` + + +Note that not all the hosted tools are always listed here: only the tools actually available in this context are shown (for example, not all tools support remote debugging yet, so if the debugging target is not the Firefox instance that launched the window, not all the hosted tools will be shown). + + +.. _tools-toolbox-extra-tools: + +Extra tools +*********** + +Next there's an array of buttons that can be added or removed in the :ref:`settings <tool-toolbox-settings>`. None of these tools are enabled by default, but you can add them in the :doc:`developer tools settings <../settings/index>` + + +- :doc:`Select a frame as the currently targeted document <../working_with_iframes/index>` (this is only included by default from Firefox 41 onwards) +- :doc:`Highlight painted area <../paint_flashing_tool/index>` +- :ref:`Take a screenshot of the entire page <taking_screenshots_taking_a_screenshot_of_the_page>`: take a screenshot of the complete web page and saves it in your Downloads directory +- :doc:`Toggle rulers for the page <../rulers/index>` +- :doc:`Measure a portion of the page <../measure_a_portion_of_the_page/index>`: measure a part of the website by selecting areas within the page + + + +.. _tools-toolbox-toolbox-controls: + +Toolbox controls +**************** + +Finally there's a row of buttons to: + +- close the window +- :doc:`Responsive Design Mode <../responsive_design_mode/index>` + + +There's also a meatball menu button that consists of following options: + +- A group of options to toggle the toolbox to be docked bottom, right, left or even be a separate window by itself. + +- access :doc:`developer tool settings <../settings/index>` + +- :doc:`Toggle split console <../web_console/split_console/index>` + +- two buttons leading to documentation and community + + + +Settings +******** + +:doc:`See the separate page on the Developer Tools Settings <../settings/index>` + + +Main Pane +********* + +The content of the main pane in the window is entirely controlled by, and specific to, the hosted tool currently selected. + +:ref:`Toolbox shortcuts <keyboard-shortcuts-toolbox>` lists the shortcuts that work whenever the toolbox is open, no matter which tool is active. This same page also lists tool-specific keyboard shortcuts. diff --git a/devtools/docs/user/tools_toolbox/toolbox-labelled.png b/devtools/docs/user/tools_toolbox/toolbox-labelled.png Binary files differnew file mode 100644 index 0000000000..44c240ccbc --- /dev/null +++ b/devtools/docs/user/tools_toolbox/toolbox-labelled.png diff --git a/devtools/docs/user/tools_toolbox/toolbox-toolbar-labelled.png b/devtools/docs/user/tools_toolbox/toolbox-toolbar-labelled.png Binary files differnew file mode 100644 index 0000000000..ab127817ff --- /dev/null +++ b/devtools/docs/user/tools_toolbox/toolbox-toolbar-labelled.png diff --git a/devtools/docs/user/tools_toolbox/toolbox.png b/devtools/docs/user/tools_toolbox/toolbox.png Binary files differnew file mode 100644 index 0000000000..a1a75935e8 --- /dev/null +++ b/devtools/docs/user/tools_toolbox/toolbox.png diff --git a/devtools/docs/user/validators/index.rst b/devtools/docs/user/validators/index.rst new file mode 100644 index 0000000000..65abf1c4f2 --- /dev/null +++ b/devtools/docs/user/validators/index.rst @@ -0,0 +1,11 @@ +========== +Validators +========== + +This article lists different resources for developers to check web documents. + + +- `W3C HTML Validator <https://validator.w3.org/>`_ validates HTML documents. +- `W3C CSS Validator <https://jigsaw.w3.org/css-validator/>`_ validates CSS stylesheets. +- `W3C Link Checker <https://validator.w3.org/checklink>`_ checks for broken links in HTML documents. +- `HTML Tidy <https://www.html-tidy.org/>`_ tool finds errors in HTML documents, and can automatically fix some errors. diff --git a/devtools/docs/user/view_source/index.rst b/devtools/docs/user/view_source/index.rst new file mode 100644 index 0000000000..12f7983dc8 --- /dev/null +++ b/devtools/docs/user/view_source/index.rst @@ -0,0 +1,90 @@ +=========== +View Source +=========== + +View Source lets you look at the HTML or XML source for the page you're viewing. To activate View Source: + +- context-click in the page and select *View Page Source* +- press :kbd:`Ctrl` + :kbd:`U` on Windows and Linux, or :kbd:`Cmd` + :kbd:`U` on macOS + +The command opens a new tab with the source for the current page. + +View Source features +******************** + +View Source has three additional features, which can be accessed from the context menu in the View Source tab: + +.. image:: view_source_context_menu.png + :class: center + +Go to Line + Scrolls to the specified line. If the number is higher than the lines in a file, you receive an error message. +Wrap Long Lines (toggle) + Wraps long lines to the width of the page. +Syntax Highlighting (toggle) + Applies syntax highlighting to the code.When syntax highlighting is on, View Source also highlights parsing errors in red. Hovering your mouse over errors displays a tooltip explaining the error. + +.. image:: view_source_error.png + :class: border + + +This feature is useful when you're looking for HTML errors. + +To access Go to Line from the keyboard, press :kbd:`Control` + :kbd:`Option` + :kbd:`L` on macOS, or :kbd:`Alt` + :kbd:`Shift` + :kbd:`L` on Windows or Linux. + + +Link to a line number +********************* + +It is possible to link to a particular line, by adding the #lineNNN anchor to the url the browser will jump to the NNN line. + +For example view-source:https://www.mozilla.org/#line100 + + +View Selection Source +********************* + +If you select part of a web page and context-click, you'll see a context menu item labeled "View Selection Source", that behaves just like "View Page Source", except you only see the source for the selection. + + +View MathML Source +****************** + +If you context-click while the mouse is over some `MathML <https://developer.mozilla.org/en-US/docs/Web/MathML>`_, you'll see a context menu item labeled "View MathML Source": click it to see the MathML source. + + +Limitations of View Source +************************** + +There are limitations to what View Source does for you that you need to be aware of. + +Error reporter ≠ validator +-------------------------- + +View Source only reports parsing errors, **not** HTML validity errors. For example, putting a `div <https://developer.mozilla.org/en-US/docs/Web/HTML/Element/div>`_ element as a child of a `ul <https://developer.mozilla.org/en-US/docs/Web/HTML/Element/ul>`_ element isn't a parse error, but it **is not** valid HTML. Therefore, this error will not be flagged in View Source. If you want to check that HTML is valid, you should use an HTML validator, such as `the one offered by W3C <https://validator.w3.org/>`_. + +Not all parse errors are reported +--------------------------------- + +Even though all the reported errors are parse errors according to the HTML specification, not all parse errors are reported by View Source. Among the errors that don't get reported: + + +- Bytes that are illegal according to the document's encoding aren't marked as errors. +- Forbidden characters aren't reported as errors. +- Errors related to the end-of-file aren't reported. +- Tree builder errors relating to text (as opposed to tags, comments, or doctypes) aren't reported. +- Parse errors related to ``xmlns`` attributes aren't reported. + + +XML syntax highlighting +*********************** + +View Source uses the HTML tokenizer when highlighting XML source. While the tokenizer has support for processing instructions when highlighting XML source, that's the only XML-specific capability provided. Because of this, doctypes that have an internal subset are not highlighted correctly, and entity references to custom entities are also not highlighted correctly. + +This mishighlighting can be seen by viewing the source of Firefox chrome files (such as XUL documents). However, this shouldn't be a problem in practice when viewing typical XML files. + + +See also +******** + +- `HTML5 Parser-Based View Source Syntax Highlighting <https://hsivonen.iki.fi/view-source/>`_ (Blog post) diff --git a/devtools/docs/user/view_source/view_source_context_menu.png b/devtools/docs/user/view_source/view_source_context_menu.png Binary files differnew file mode 100644 index 0000000000..c0f2039997 --- /dev/null +++ b/devtools/docs/user/view_source/view_source_context_menu.png diff --git a/devtools/docs/user/view_source/view_source_error.png b/devtools/docs/user/view_source/view_source_error.png Binary files differnew file mode 100644 index 0000000000..a38c932f9b --- /dev/null +++ b/devtools/docs/user/view_source/view_source_error.png diff --git a/devtools/docs/user/web_audio_editor/index.rst b/devtools/docs/user/web_audio_editor/index.rst new file mode 100644 index 0000000000..4318714424 --- /dev/null +++ b/devtools/docs/user/web_audio_editor/index.rst @@ -0,0 +1,86 @@ +================ +Web Audio Editor +================ + +.. note:: + + Notice: This tool has been deprecated and will soon be removed from Firefox. For details, see :doc:`Deprecated tools <../deprecated_tools/index>`. + + +With the `Web Audio API <https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API/Using_Web_Audio_API>`_, developers create an `audio context <https://developer.mozilla.org/en-US/docs/Web/API/AudioContext>`_ Within that context they then construct a number of `audio nodes <https://developer.mozilla.org/en-US/docs/Web/API/AudioNode>`_, including: + + +- nodes providing the `audio source <https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API#defining_audio_sources>`_, such as an oscillator or a data buffer source +- nodes performing `transformations <https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API#defining_audio_effects_filters>`_ such as delay and gain +- nodes representing the `destination of the audio stream <https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API#defining_audio_destinations>`_, such as the speakers + + +Each node has zero or more `AudioParam <https://developer.mozilla.org/en-US/docs/Web/API/AudioParam>`_ properties that configure its operation. For example, the `GainNode <https://developer.mozilla.org/en-US/docs/Web/API/GainNode>`_ has a single ``gain`` property, while the `OscillatorNode <https://developer.mozilla.org/en-US/docs/Web/API/OscillatorNode>`_ has ``frequency`` and ``detune`` properties. + +The developer connects the nodes in a graph, and the complete graph defines the behavior of the audio stream. + +The Web Audio Editor examines an audio context constructed in the page and provides a visualization of its graph. This gives you a high-level view of its operation, and enables you to ensure that all the nodes are connected in the way you expect. You can then examine and edit the ``AudioParam`` properties for each node in the graph. Some non-``AudioParam`` properties, like an ``OscillatorNode``'s ``type`` property, are displayed, and you can edit these as well. + +This tool is still experimental. If you find bugs, we'd love it if you `filed them in Bugzilla <https://bugzilla.mozilla.org/enter_bug.cgi?product=Firefox&component=Developer%20Tools%3A%20Web%20Audio%20Editor>`_. If you have feedback or suggestions for new features, `dev-developer-tools <https://lists.mozilla.org/listinfo/dev-developer-tools>`_ or `Twitter <https://twitter.com/firefoxdevtools>`_ are great places to register them. + + +Opening the Web Audio Editor +**************************** + +The Web Audio Editor is not enabled by default in Firefox 32. To enable it, open the :ref:`Developer Tool Settings <tool-toolbox-settings>` and check "Web Audio". Now there should be an extra tab in the :ref:`Toolbox toolbar <tools-toolbox-toolbar>` labeled "Web Audio". Click the tab and load a page that constructs an audio context. Two good demos are: + + +- the `Voice-change-O-Matic <https://github.com/mdn/voice-change-o-matic>`_, which can apply various effects to the microphone input and also provides a visualisation of the result +- the `Violent Theremin <https://mdn.github.io/webaudio-examples/violent-theremin/>`_, which changes the pitch and volume of a sine wave as you move the mouse pointer + + +Visualizing the graph +********************* + +The Web Audio Editor will now display the graph for the loaded audio context. Here's the graph for the Violent Theremin demo: + +.. image:: web-audio-editor.png + :class: center + +You can see that it uses three nodes: an `OscillatorNode <https://developer.mozilla.org/en-US/docs/Web/API/OscillatorNode>`_ as the source, a `GainNode <https://developer.mozilla.org/en-US/docs/Web/API/GainNode>`_ to control the volume, and an `GainNode <https://developer.mozilla.org/en-US/docs/Web/API/GainNode>`_ as the destination. + + +Connections to AudioParams +-------------------------- + +Displaying connections to AudioParams is new in Firefox 34. + + +Connections between nodes are displayed as solid lines. If, instead, you've connected a node to an AudioParam in another node, then the connection is shown as a dashed line between the nodes, and is labeled with the name of the ``AudioParam``: + +.. image:: web_audio-editor-connect-param.png + :class: center + + +Inspecting and modifying AudioNodes +*********************************** + +If you click on a node, it's highlighted and you get a node inspector on the right hand side. This list the values of that node's ``AudioParam`` properties. For example, here's what the OscillatorNode looks like: + +.. image:: web-audio-editor-props.png + :class: center + +With the Violent Theremin demo, the frequency parameter is modified as the user moves the mouse left and right, and you can see this reflected in the node inspector. However, the value isn't updated in real time: you have to click the node again to see the updated value. + +If you click on a value in the node inspector you can modify it: press :kbd:`Enter` or :kbd:`Tab` and the new value takes effect immediately. + + +Bypassing nodes +*************** + +New in Firefox 38. + +In the pane that shows you the node's details, there's an on/off button: + +.. image:: web-audio-editor-on-off.png + :class: center + +Click it, and the graph will be modified to bypass this node, so it will no longer have any effect. Nodes that are bypassed are shown with a hatched background: + +.. image:: web-audio-editor-bypassed.png + :class: center diff --git a/devtools/docs/user/web_audio_editor/web-audio-editor-bypassed.png b/devtools/docs/user/web_audio_editor/web-audio-editor-bypassed.png Binary files differnew file mode 100644 index 0000000000..ed8a734fb8 --- /dev/null +++ b/devtools/docs/user/web_audio_editor/web-audio-editor-bypassed.png diff --git a/devtools/docs/user/web_audio_editor/web-audio-editor-on-off.png b/devtools/docs/user/web_audio_editor/web-audio-editor-on-off.png Binary files differnew file mode 100644 index 0000000000..b9aabc4552 --- /dev/null +++ b/devtools/docs/user/web_audio_editor/web-audio-editor-on-off.png diff --git a/devtools/docs/user/web_audio_editor/web-audio-editor-props.png b/devtools/docs/user/web_audio_editor/web-audio-editor-props.png Binary files differnew file mode 100644 index 0000000000..f9d8d973e9 --- /dev/null +++ b/devtools/docs/user/web_audio_editor/web-audio-editor-props.png diff --git a/devtools/docs/user/web_audio_editor/web-audio-editor.png b/devtools/docs/user/web_audio_editor/web-audio-editor.png Binary files differnew file mode 100644 index 0000000000..295b242544 --- /dev/null +++ b/devtools/docs/user/web_audio_editor/web-audio-editor.png diff --git a/devtools/docs/user/web_audio_editor/web_audio-editor-connect-param.png b/devtools/docs/user/web_audio_editor/web_audio-editor-connect-param.png Binary files differnew file mode 100644 index 0000000000..33bd74359a --- /dev/null +++ b/devtools/docs/user/web_audio_editor/web_audio-editor-connect-param.png diff --git a/devtools/docs/user/web_console/console_messages/async-trace.png b/devtools/docs/user/web_console/console_messages/async-trace.png Binary files differnew file mode 100644 index 0000000000..d9c83ac57d --- /dev/null +++ b/devtools/docs/user/web_console/console_messages/async-trace.png diff --git a/devtools/docs/user/web_console/console_messages/blocked-icon.png b/devtools/docs/user/web_console/console_messages/blocked-icon.png Binary files differnew file mode 100644 index 0000000000..79643681b3 --- /dev/null +++ b/devtools/docs/user/web_console/console_messages/blocked-icon.png diff --git a/devtools/docs/user/web_console/console_messages/console-messages-fx79.png b/devtools/docs/user/web_console/console_messages/console-messages-fx79.png Binary files differnew file mode 100644 index 0000000000..99fbe9237e --- /dev/null +++ b/devtools/docs/user/web_console/console_messages/console-messages-fx79.png diff --git a/devtools/docs/user/web_console/console_messages/console-msg-annotated.png b/devtools/docs/user/web_console/console_messages/console-msg-annotated.png Binary files differnew file mode 100644 index 0000000000..c0038402de --- /dev/null +++ b/devtools/docs/user/web_console/console_messages/console-msg-annotated.png diff --git a/devtools/docs/user/web_console/console_messages/console-toolbar.png b/devtools/docs/user/web_console/console_messages/console-toolbar.png Binary files differnew file mode 100644 index 0000000000..55ba23e4e6 --- /dev/null +++ b/devtools/docs/user/web_console/console_messages/console-toolbar.png diff --git a/devtools/docs/user/web_console/console_messages/console_clear_filter.png b/devtools/docs/user/web_console/console_messages/console_clear_filter.png Binary files differnew file mode 100644 index 0000000000..2fa5712f2b --- /dev/null +++ b/devtools/docs/user/web_console/console_messages/console_clear_filter.png diff --git a/devtools/docs/user/web_console/console_messages/css_warnings.png b/devtools/docs/user/web_console/console_messages/css_warnings.png Binary files differnew file mode 100644 index 0000000000..3b5093fbe4 --- /dev/null +++ b/devtools/docs/user/web_console/console_messages/css_warnings.png diff --git a/devtools/docs/user/web_console/console_messages/error-icon.png b/devtools/docs/user/web_console/console_messages/error-icon.png Binary files differnew file mode 100644 index 0000000000..57c2f5245b --- /dev/null +++ b/devtools/docs/user/web_console/console_messages/error-icon.png diff --git a/devtools/docs/user/web_console/console_messages/error-stack.png b/devtools/docs/user/web_console/console_messages/error-stack.png Binary files differnew file mode 100644 index 0000000000..f31eda5410 --- /dev/null +++ b/devtools/docs/user/web_console/console_messages/error-stack.png diff --git a/devtools/docs/user/web_console/console_messages/index.rst b/devtools/docs/user/web_console/console_messages/index.rst new file mode 100644 index 0000000000..71b26064d8 --- /dev/null +++ b/devtools/docs/user/web_console/console_messages/index.rst @@ -0,0 +1,374 @@ +================ +Console messages +================ + +Most of the Web Console is occupied by the message display pane: + +.. image:: console-messages-fx79.png + :alt: Screenshot of the web console, highlighting the messages area + :class: center + +Each message is displayed as a separate row: + +.. image:: console-msg-annotated.png + :alt: Screenshot of a single console message, with its parts annotated + :class: center + +.. |image1| image:: info-icon.png + :alt: An "i" inside a circle + +.. |image2| image:: warning-icon.png + :alt: A "!" inside a yellow triangle + +.. |image3| image:: error-icon.png + :alt: A "!" inside a solid red circle + +.. |image4| image:: blocked-icon.png + :alt: A red circle with a slash across it + + +.. list-table:: + :widths: 25 75 + :header-rows: 0 + + * - **Time** + - The time the message was recorded. This is not shown by default: you can opt to see timestamps by selecting **Show Timestamps** in the console settings menu (gear icon in the console toolbar). + + * - **Icon** + - Not all console messages contain icons. The following icons may be used: + + - |image1| Informational message + - |image2| Warning + - |image3| Error + - |image4| Blocked; for network messages + + In addition, a disclosure triangle indicates that further information is available; clicking it displays or collapses that information. + + * - **Message** + - The message itself. + + * - **Number of occurrences** + - If a line that generates a warning or error is executed more than once, it is only logged once and this counter appears to indicate how many times it was encountered. + + * - **Filename and line number** + - For JavaScript, CSS and console API messages, the message can be traced to a specific line of code. The console then provides a link to the filename and line number that generated the message. + + +By default, the console is cleared each time you navigate to a new page or reload the current page. To override this behavior, enable **Persist Logs** in the console settings menu (gear icon). + +The context menu options listed below are available on all message categories. Additional context menu options are described in the subsection for the message category they apply to. + + +- **Copy Message** copies the selected message to the clipboard. +- **Select All** selects all messages available in the message display pane. +- **Export Visible Messages To** + + - **Clipboard** copies all messages available in the display pane to the clipboard. + - **File** opens a file dialog box so you can save an export of all messages available in the display pane. + + +Message categories +****************** + +.. _web_console_console_messages: + +Network +------- + +.. note:: + Network log messages are not shown by default. Use the :ref:`filtering <web_console_ui_tour_filtering_by_category>` feature to show them. + + +Network requests are logged with a line that looks like this: + +.. image:: response-msg-annotated.png + :alt: Screenshot of a network response message, with its parts annotated + :class: center + + +.. list-table:: + :widths: 25 75 + :header-rows: 0 + + * - **Time** + - The time the message was recorded. + + * - **Method** + - The specific HTTP request method. + + If the request was made as an `XMLHttpRequest <https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest>`_, there's an additional "XHR" tag indicating this. + + If more information is available, a disclosure triangle lets you display it, in an embedded panel that is identical to the :doc:`Network Monitor request details <../../network_monitor/request_details/index>`. + + * - **URI** + - The target URI. + + * - **Summary** + - The HTTP version, response code, and time taken to complete. Clicking the response code takes you to the reference page for that code. + +.. raw:: html + + <iframe width="560" height="315" src="https://www.youtube.com/embed/cFlcWzJ9j4I" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe> + <br/> + <br/> + +The context menu for network messages includes a few extra items in addition the globally-available ones: + +.. image:: response-msg-context-menu.png + :alt: Screenshot showing the context menu for network response messages + :class: border + + +Copy link location + Acts as you would expect, copying the URL into the clipboard +Open in Network Panel + Switches context to the Network tab, selects the request and shows you the details +Resend Request + Sends the network request again. +Open URL in New Tab + Opens the URL in a new browser tab. If the resource is an image, the image will be opened in a new tab. If the resource is a stylesheet, you will see the CSS rules, etc. + + +JS +-- + +JavaScript errors contain a "Learn more" linkthat takes you to the `JavaScript error reference <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Errors>`_ containing additional advice for fixing issues. + + +Source maps +~~~~~~~~~~~ + +The Web Console understands `source maps <https://blog.teamtreehouse.com/introduction-source-maps>`_. This means that if your JavaScript sources are compressed, you can supply a source map for them. Then any messages or errors your source generates will show up in the Web Console with a link back to the original source, not the compressed version. + +Async stack frames +~~~~~~~~~~~~~~~~~~ + +Stack traces show stack frames for `async functions <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function>`_ separately from those for synchronous functions. When you run code containing an async function, its traces (`console.trace <https://developer.mozilla.org/en-US/docs/Web/API/console/trace>`_ or `thrown error <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error>`_) are shown with an *Async:* prefix. + +.. image:: async-trace.png + :alt: Console log showing a trace containing async code + :class: center + + +CSS +--- + +.. note:: + CSS warnings and reflow messages are not shown by default, for performance reasons (see `bug 1452143 <https://bugzilla.mozilla.org/show_bug.cgi?id=1452143>`_. Use the :ref:`filtering <web_console_ui_tour_filtering_by_category>` feature to show them. + + +Some CSS messages contain a disclosure triangle at the left of the message. Click it to view more information about the error, as well as which DOM nodes are affected by the error. + +.. image:: css_warnings.png + :class: center + + +Security +-------- + +The security messages shown in the Web Console help developers find potential or actual vulnerabilities in their sites. Additionally, many of these messages help educate developers because they end with a “Learn More” link that takes you to a page with background information and advice for mitigating the issue. + +The complete list of security messages is as follows: + +.. list-table:: + :widths: 50 50 + :header-rows: 1 + + * - Messages + - Details + + * - Blocked loading mixed active content + - The page contained mixed active content: that is, the main page was served over HTTPS, but asked the browser to load "active content", such as scripts, over HTTP. The browser blocked this active content. See `Mixed Content <https://developer.mozilla.org/en-US/docs/Web/Security/Mixed_content>`_ for more details. + + * - Blocked loading mixed display content + - The page contained mixed display content: that is, the main page was served over HTTPS, but asked the browser to load "display content", such as images, over HTTP. The browser blocked this display content. See `Mixed Content <https://developer.mozilla.org/en-US/docs/Web/Security/Mixed_content>`_ for more details. + + * - Loading mixed (insecure) active content on a secure page + - The page contained mixed active content: that is, the main page was served over HTTPS, but asked the browser to load "active content", such as scripts, over HTTP. The browser loaded this active content. See `Mixed Content <https://developer.mozilla.org/en-US/docs/Web/Security/Mixed_content>`_ for more details. + + * - Loading mixed (insecure) display content on a secure page + - The page contained mixed display content: that is, the main page was served over HTTPS, but asked the browser to load "display content", such as images, over HTTP. The browser loaded this display content. `Mixed Content <https://developer.mozilla.org/en-US/docs/Web/Security/Mixed_content>`_ for more details. + + * - This site specified both an X-Content-Security-Policy/Report-Only header and a Content-Security-Policy/Report-Only header. The X-Content-Security-Policy/Report-Only header(s) will be ignored. + - See `Content Security Policy <https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP>`_ for more details. + + * - The X-Content-Security-Policy and X-Content-Security-Report-Only headers will be deprecated in the future. Please use the Content-Security-Policy and Content-Security-Report-Only headers with CSP spec compliant syntax instead. + - See `Content Security Policy <https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP>`_ for more details. + + * - Password fields present on an insecure (http://) page. This is a security risk that allows user login credentials to be stolen. + - Pages containing login forms must be served over HTTPS, not HTTP. + + * - Password fields present in a form with an insecure (http://) form action. This is a security risk that allows user login credentials to be stolen. + - Forms containing password fields must submit them over HTTPS, not HTTP. + + * - Password fields present on an insecure (http://) iframe. This is a security risk that allows user login credentials to be stolen. + - iframes containing login forms must be served over HTTPS, not HTTP. + + * - The site specified an invalid Strict-Transport-Security header. + - See `HTTP Strict Transport Security <https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Strict-Transport-Security>`_ for more details. + + * - This site makes use of a SHA-1 Certificate; it's recommended you use certificates with signature algorithms that use hash functions stronger than SHA-1. + + - The site uses a certificate whose signature uses the SHA-1 hash algorithm. + + SHA-1 is still widely used in certificates, but it is starting to show its age. Web sites and Certification Authorities are encouraged to switch to stronger hash algorithms in future. See the `Weak Signature Algorithm <https://developer.mozilla.org/en-US/docs/Web/Security/Weak_Signature_Algorithm>`_ article for more details. + + Note that the SHA-1 certificate may not be your site's own certificate, but may be the certificate belonging to a Certification Authority that was used to sign your site's certificate. + + +`Bug 863874 <https://bugzilla.mozilla.org/show_bug.cgi?id=863874>`_ is the meta-bug for logging relevant security messages to the Web Console. If you have more ideas for useful features like the ones discussed here, or are interested in contributing, check out the metabug and its dependencies. + + +Logging +------- + +.. note:: + Messages logged from `Shared Workers <https://developer.mozilla.org/en-US/docs/Web/API/SharedWorker>`_, `Service Workers <https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API>`_, add-ons, and **Chrome Workers** are not shown by default. Use the :ref:`filtering <web_console_ui_tour_filtering_by_category>` feature to show them. + + +The Logging category includes messages logged using the `Console API <https://developer.mozilla.org/en-US/docs/Web/API/console>`_. + +The Web console supports the following `Console API <https://developer.mozilla.org/en-US/docs/Web/API/console>`_ messages: + + +- `assert() <https://developer.mozilla.org/en-US/docs/Web/API/console/assert>`_ +- `clear() <https://developer.mozilla.org/en-US/docs/Web/API/console/clear>`_ +- `count() <https://developer.mozilla.org/en-US/docs/Web/API/console/count>`_ +- `dir() <https://developer.mozilla.org/en-US/docs/Web/API/console/dir>`_ +- `dirxml() <https://developer.mozilla.org/en-US/docs/Web/API/console/dirxml>`_ +- `error() <https://developer.mozilla.org/en-US/docs/Web/API/console/error>`_ +- ``exception()`` +- `group() <https://developer.mozilla.org/en-US/docs/Web/API/console/group>`_ +- `groupEnd() <https://developer.mozilla.org/en-US/docs/Web/API/console/groupEnd>`_ +- ``info()`` +- `log() <https://developer.mozilla.org/en-US/docs/Web/API/console/log>`_ +- `table() <https://developer.mozilla.org/en-US/docs/Web/API/console/table>`_ +- `time() <https://developer.mozilla.org/en-US/docs/Web/API/console/time>`_ +- `timeEnd() <https://developer.mozilla.org/en-US/docs/Web/API/console/timeEnd>`_ +- `trace() <https://developer.mozilla.org/en-US/docs/Web/API/console/trace>`_ +- `warn() <https://developer.mozilla.org/en-US/docs/Web/API/console/warn>`_ + + +The console prints a stack trace for all error messages, like this: + +.. code-block:: javascript + + function foo() { + console.error("it explodes"); + } + + function bar() { + foo(); + } + + function doStuff() { + bar(); + } + + doStuff(); + +.. image:: error-stack.png + :class: center + + +.. _web_console_server: + +Server +------ + +.. note:: + + Server-side log messages was introduced in Firefox 43, but removed in Firefox 56. You can install the `Chrome Logger extension <https://addons.mozilla.org/en-US/firefox/addon/chromelogger/>`_ to (re)-enable the feature. + + +With the `Chrome Logger extension <https://addons.mozilla.org/en-US/firefox/addon/chromelogger/>`_, Web Console can display messages sent from the server. This enables you to use the Web Console to debug server-side code. + + +It uses the `Chrome Logger <https://craig.is/writing/chrome-logger>`_ protocol. Briefly, the way it works is: + + +- Your server-side code — Python, PHP, Node.js, etc. — includes a library that provides a console API. +- Your server-side code uses this API to log messages. +- The server-side library creates JSON objects from the messages and encodes them for transmission. +- The messages are transmitted to the client as a response header named ``X-ChromeLogger-Data``. +- The Web Console decodes these headers and displays them. + + +To find a suitable library for your server code, see the `Chrome Logger documentation <https://craig.is/writing/chrome-logger>`_. + + +.. _web_console_console_messages_interpreter_io: + +Interpreter input/output +------------------------ + +Commands sent to the browser using the :doc:`Web Console's JavaScript interpreter <../the_command_line_interpreter/index>`, and the corresponding responses, are logged in the console messages. + +For responses that contain objects or variables, the following context menu options are available: + + +Reveal in Inspector + Shows the selected DOM node in the Inspector pane. +Store as Global Variable + Creates a global variable (with a name like ``temp0``, ``temp1``, etc.) whose value is the selected object. The name of the variable appears as an input to the interpreter, and its value appears as a response. +Copy Object + Copies the selected object to the clipboard. + + + +Filtering and searching +*********************** + +.. _web_console_ui_tour_filtering_by_category: + +Filtering by category +--------------------- + +You can use the toolbar along the top to constrain the results displayed. + +.. image:: console-toolbar.png + :alt: Screenshot showing the web console, with the toolbar highlighted + :class: center + +To see only messages of particular categories, click the button labeled with that category (**Errors**, **CSS**, and so on). + +For Errors and Warnings, when you turn off display of the category, a number appears next to the button text to indicate how many messages of that type are available. For example, "Warnings (25)". + +Network requests with response codes in the 400-499 (client error) or 500-599 (server error) ranges are considered errors. Their display is controlled by the **Errors** button, not the **Requests** button. + + +.. _web_console_ui_tour_filtering_by_text: + +Filtering by text +----------------- + +To see only messages that contain a specific string, type in the text box labeled "Filter output". For example, if you entered the string img into the text box, you would have a list something like this: + +.. image:: console_clear_filter.png + :class: border + + +A small "x" icon appears at the right end of the text box when you have entered a string on which to filter the output. Click the "x" icon to clear the filter and show the entire list again. + +You can negate a text search by prefixing it with the ``-`` character. For example, ``-img`` shows only items that *do not* contain the string ``img``. + + +.. _web_console_ui_tour_filtering_by_regular_expressions: + +Filtering with Regular Expressions +---------------------------------- + +You can also use a valid regular expression to filter the console output. For example, the following video shows the results when filtering on two simple regular expressions: ``/(cool|rad)/`` and ``/(cool)/``. + +.. raw:: html + + <iframe width="560" height="315" src="https://www.youtube.com/embed/E6bGOe2fvW0" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe> + <br/> + <br/> + +You can negate a regular expression search by prefixing it with the ``-`` character. For example, ``-/(cool|rad)/`` shows only items that *do not* match the expression ``/(cool|rad)/``. + +Clearing the log +---------------- + +Finally, you can use the trashcan icon on the left to clear the contents of the console. When you clear the console, the console cache is also cleared. This prevents errors that have already been logged from reappearing when you reopen the console. diff --git a/devtools/docs/user/web_console/console_messages/info-icon.png b/devtools/docs/user/web_console/console_messages/info-icon.png Binary files differnew file mode 100644 index 0000000000..a823b483a8 --- /dev/null +++ b/devtools/docs/user/web_console/console_messages/info-icon.png diff --git a/devtools/docs/user/web_console/console_messages/response-msg-annotated.png b/devtools/docs/user/web_console/console_messages/response-msg-annotated.png Binary files differnew file mode 100644 index 0000000000..cec871d88c --- /dev/null +++ b/devtools/docs/user/web_console/console_messages/response-msg-annotated.png diff --git a/devtools/docs/user/web_console/console_messages/response-msg-context-menu.png b/devtools/docs/user/web_console/console_messages/response-msg-context-menu.png Binary files differnew file mode 100644 index 0000000000..18b0fca315 --- /dev/null +++ b/devtools/docs/user/web_console/console_messages/response-msg-context-menu.png diff --git a/devtools/docs/user/web_console/console_messages/warning-icon.png b/devtools/docs/user/web_console/console_messages/warning-icon.png Binary files differnew file mode 100644 index 0000000000..f8e8769a6e --- /dev/null +++ b/devtools/docs/user/web_console/console_messages/warning-icon.png diff --git a/devtools/docs/user/web_console/helpers/index.rst b/devtools/docs/user/web_console/helpers/index.rst new file mode 100644 index 0000000000..9a1013dc3e --- /dev/null +++ b/devtools/docs/user/web_console/helpers/index.rst @@ -0,0 +1,140 @@ +=================== +Web Console Helpers +=================== + +The JavaScript command line provided by the Web Console offers a few built-in helper functions that make certain tasks easier. + +$(selector, element) + Looks up a CSS selector string ``selector`` , returning the first node descended from ``element`` that matches. If unspecified, ``element`` defaults to ``document``. Equivalent to `document.querySelector() <https://developer.mozilla.org/en-US/docs/Web/API/Document/querySelector>`_ or calls the $ function in the page, if it exists. + + See the `QuerySelector code snippet <https://developer.mozilla.org/en-US/docs/Web/API/Document/querySelector>`_. + +.. _web_console_helpers_$$: + +$$(selector, element) + Looks up a CSS selector string ``selector``, returning an array of DOMnodesdescended from ``element`` that match. If unspecified, ``element`` defaults to ``document``. This is like for `document.querySelectorAll() <https://developer.mozilla.org/en-US/docs/Web/API/Document/querySelectorAll>`_, but returns an array instead of a `NodeList <https://developer.mozilla.org/en-US/docs/Web/API/NodeList>`_. + +.. _web_console_helpers_$0: + +$0 + The currently-inspected element in the page. + +.. _web_console_helpers_$: + +$_ + Stores the result of the last expression executed in the console's command line. For example, if you type "2+2 <enter>", then "$_ <enter>", the console will print 4. + +$x(xpath, element, resultType) + Evaluates the `XPath <https://developer.mozilla.org/en-US/docs/Web/XPath>`_ ``xpath`` expression in the context of ``element`` and returns an array of matching nodes. If unspecified, ``element`` defaults to ``document``. The resultType parameter specifies the type of result to return; it can be an `XPathResult constant <https://developer.mozilla.org/en-US/docs/Web/API/XPathResult#constants>`_, or a corresponding string: ``"number"``, ``"string"``, ``"bool"``, ``"node"``, or ``"nodes"``; if not provided, ``ANY_TYPE`` is used. + +:block + (Starting in Firefox 80) Followed by an unquoted string, blocks requests where the URL contains that string. In the :doc:`Network Monitor <../../network_monitor/index>`, the string now appears and is selected in the :ref:`Request Blocking sidebar <network_monitor_blocking_specific_urls>`. Unblock with ``:unblock``. + +clear() + Clears the console output area. + +clearHistory() + Just like a normal command line, the console command line :ref:`remembers the commands you've typed <command_line_interpreter_execution_history>`. Use this function to clear the console's command history. + +.. _web_console_helpers_copy: + +copy() + Copies the argument to the clipboard. If the argument is a string, it's copied as-is. If the argument is a DOM node, its `outerHTML <https://developer.mozilla.org/en-US/docs/Web/API/Element/outerHTML>`_ is copied. Otherwise, `JSON.stringify <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify>`_ will be called on the argument, and the result will be copied to the clipboard. + +**help()** (deprecated) + +.. _web_console_helpers_help: + +:help + Displays help text. Actually, in a delightful example of recursion, it brings you to this page. + +inspect() + Given an object, generates:doc:`rich output <../rich_output/index>` for that object. Once you select the object in the output area, you can use the arrow keys to navigate the object. + +keys() + Given an object, returns a list of the keys (or property names) on that object. This is a shortcut for `Object.keys <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/keys>`_. + +pprint() (deprecated) + Formats the specified value in a readable way; this is useful for dumping the contents of objects and arrays. + +:screenshot + Creates a screenshot of the current page with the supplied filename. If you don't supply a filename, the image file will be named with the following format: + + ``Screen Shot yyy-mm-dd at hh.mm.ss.png`` + + The command has the following optional parameters: + +.. list-table:: + :widths: 20 20 60 + :header-rows: 1 + + * - Command + - Type + - Description + + * - ``--clipboard`` + - boolean + - When present, this parameter will cause the screenshot to be copied to the clipboard. + + * - ``--dpr`` + - number + - The device pixel ratio to use when taking the screenshot. + + * - ``--file`` + - boolean + - When present, the screenshot will be saved to a file, even if other options (e.g. ``--clipboard``) are included. + + * - ``--filename`` + - string + - The name to use in saving the file. The file should have a ".png" extension. + + * - ``--fullpage`` + - boolean + - If included, the full webpage will be saved. With this parameter, even the parts of the webpage which are outside the current bounds of the window will be included in the screenshot. When used, ``-fullpage`` will be appended to the file name. + + * - ``--selector`` + - string + - The CSS query selector for a single element on the page. When supplied, only this element will be included in the screenshot. + + +:unblock + (Starting in Firefox 80) Followed by an unquoted string, removes blocking for URLs containing that string. In the :doc:`Network Monitor <../../network_monitor/index>`, the string is removed from the :ref:`Request Blocking sidebar <network_monitor_blocking_specific_urls>`. No error is given if the string was not previously blocked. + +values() + Given an object, returns a list of the values on that object; serves as a companion to ``keys()``. + + +Please refer to the `Console API <https://developer.mozilla.org/en-US/docs/Web/API/console>`_ for more information about logging from content. + + +Variables +********* + +.. _web_console_helpers_tempn: + +temp*N* + The :ref:`Use in Console <page_inspector_how_to_examine_and_edit_html_use_in_console>` option in the Inspector generates a variable for a node named ``temp0``, ``temp1``, ``temp2``, etc. referencing the node. + + +Examples +******** + +Looking at the contents of a DOMnode +------------------------------------ + +Let's say you have a DOMnode with the class"title". In fact, this page you're reading right now has one, so you can open up the Web Console and try this right now. + +Let's take a look at the contents of that node by using the ``$()`` and ``inspect()`` functions: + +.. code-block:: javascript + + inspect($(".title")) + + +This automatically generates rich output for the object, showing you the contents of the first DOMnode that matches the CSS selector ``".title"``, which is of course the first element with class ``"title"``. You can use the up- and down-arrow keys to navigate through the output, the right-arrow key to expand an item, and the left-arrow key to collapse it. + + +See also +******** + +- `console <https://developer.mozilla.org/en-US/docs/Web/API/console>`_ diff --git a/devtools/docs/user/web_console/index.rst b/devtools/docs/user/web_console/index.rst new file mode 100644 index 0000000000..2d0713410f --- /dev/null +++ b/devtools/docs/user/web_console/index.rst @@ -0,0 +1,55 @@ +=========== +Web Console +=========== + + +The **Web Console:** + + 1. Logs information associated with a web page: network requests, JavaScript, CSS, security errors and warnings as well as error, warning and informational messages explicitly logged by JavaScript code running in the page context + + 2. Enables you to interact with a web page by executing JavaScript expressions in the context of the page + + +.. raw:: html + + <iframe width="560" height="315" src="https://www.youtube.com/embed/C6Cyrpkb25k" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe> + <br/> + <br/> + +.. list-table:: + :widths: 30 70 + :header-rows: 0 + + * - :doc:`User interface of the Web Console <ui_tour/index>` + - Parts of the Web Console UI. + + * - :doc:`The JavaScript input interpreter <the_command_line_interpreter/index>` + - How to interact with a document using the Console. + + * - :doc:`Split console <split_console/index>` + - Use the Console alongside other tools. + + * - :doc:`Console messages <console_messages/index>` + - Details of the messages that the Console logs. + + * - :doc:`Helper commands <helpers/index>` + - Commands use can use that are not part of JavaScript. + + * - :doc:`Rich output <rich_output/index>` + - See and interact with objects logged by the Console. + + * - :ref:`Keyboard shortcuts <keyboard-shortcuts-web-console>` + - Shortcut reference + + +Opening the Web Console +*********************** + +You open the Web Console from a menu or with a keyboard shortcut: + +- Select the *Web Console* panel in the Web Developer Tools, accessible from the Browser Tools submenu + +- Press the :kbd:`Ctrl` + :kbd:`Shift` + :kbd:`K` (:kbd:`Cmd` + :kbd:`Opt` + :kbd:`K` on OS X) keyboard shortcut. + + +The :doc:`Toolbox <../tools_toolbox/index>` appear at the bottom, left, or right of the browser window (depending on your docking settings), with the Web Console activated (it's just called **Console** in the :ref:`DevTools toolbar <tools-toolbox-toolbar>` diff --git a/devtools/docs/user/web_console/invoke_getters_from_autocomplete/index.rst b/devtools/docs/user/web_console/invoke_getters_from_autocomplete/index.rst new file mode 100644 index 0000000000..c40b236686 --- /dev/null +++ b/devtools/docs/user/web_console/invoke_getters_from_autocomplete/index.rst @@ -0,0 +1,6 @@ +================================ +Invoke getters from autocomplete +================================ + +.. note:: + Draft diff --git a/devtools/docs/user/web_console/remoting/index.rst b/devtools/docs/user/web_console/remoting/index.rst new file mode 100644 index 0000000000..d94705380d --- /dev/null +++ b/devtools/docs/user/web_console/remoting/index.rst @@ -0,0 +1,648 @@ +==================== +Web Console remoting +==================== + +Introduction +************ + +This document describes the way Web Console remoting works. The Web Console is split between a client with its user interface, and the server which has listeners for all the things that happen in the tab. For communication between the server and the client we use the `Remote Debugging Protocol <https://wiki.mozilla.org/Remote_Debugging_Protocol>`_. This architecture allows you to connect a Web Console client instance to a server running on B2G, Fennec or some other Firefox instance. + +To better understand the architecture of the Web Console we recommend learning about the `debugger architecture <https://wiki.mozilla.org/Debugger_Architecture>`_. + +.. note:: + The remote Web Console is a feature introduced in Firefox 18. This document describes the latest protocol, with changes that have been made since then. + + +The ``WebConsoleActor`` and the ``WebConsoleClient`` +**************************************************** + +The ``WebConsoleActor`` lives in `dbg-webconsole-actors.js <http://mxr.mozilla.org/mozilla-central/source/toolkit/devtools/webconsole/dbg-webconsole-actors.js>`_, in the `toolkit/devtools/webconsole <http://mxr.mozilla.org/mozilla-central/source/toolkit/devtools/webconsole/>`_ folder. + +The ``WebConsoleClient`` lives in `WebConsoleClient.jsm <http://mxr.mozilla.org/mozilla-central/source/toolkit/devtools/webconsole/WebConsoleClient.jsm/>`_ (in `toolkit/devtools/webconsole <http://mxr.mozilla.org/mozilla-central/source/toolkit/devtools/webconsole/>`_) and it is used by the Web Console when working with the Web Console actor. + +To see how the debugger is used in the Web Console code, look in `browser/devtools/webconsole/webconsole.js <http://mxr.mozilla.org/mozilla-central/source/browser/devtools/webconsole/webconsole.js/>`_, and search for ``WebConsoleConnectionProxy``. + +The new Web Console actors are: + +- The ``WebConsoleActor`` allows JS evaluation, autocomplete, start/stop listeners, etc. +- The ``NetworkEventActor`` is used for each new network request. The client can request further network event details - like response body or request headers. + + +To attach to the ``WebConsoleActor``, follow these steps: + +.. code-block:: javascript + + connectToServer() // the usual + listTabs() + pickTheTabYouWant() + debuggerClient.attachConsole(tab.consoleActor, listeners, onAttachConsole) + + +The ``listeners`` argument is an array which specifies listeners you want to start in the web console. These can be: page errors, ``window.console`` API messages, network activity, and file activity. For example: + +.. code-block:: javascript + + ["PageError", "ConsoleAPI", "FileActivity"] + + +.. note:: + The Web Console actor does not start any listeners by default. The client has the option to start each listener when needed. This approach allows for lower resource usage on the server - this is a potential issue if the server runs on devices with fewer resources. + + +The ``onAttachConsole`` callback receives a new instance of the ``WebConsoleClient`` object. This object provides methods that abstract away protocol packets, things like ``startListeners(), stopListeners()``, etc. + +Protocol packets look as follows: + +.. code-block:: javascript + + { + "to": "root", + "type": "listTabs" + } + { + "from": "root", + "consoleActor": "conn0.console9", + "selected": 2, + "tabs": [ + { + "actor": "conn0.tab2", + "consoleActor": "conn0.console7", + "title": "", + "url": "https://tbpl.mozilla.org/?tree=Fx-Team" + }, + // ... + ] + } + + +Notice that the ``consoleActor`` is also available as a **global actor**. When you attach to the global ``consoleActor`` you receive all of the network requests, page errors, and the other events from all of the tabs and windows, including chrome errors and network events. This actor is used for the Browser Console implementation and for debugging remote Firefox/B2G instances. + + +``startListeners(listeners, onResponse)`` +----------------------------------------- + +The new ``startListeners`` packet: + +.. code-block:: javascript + + { + "to": "conn0.console9", + "type": "startListeners", + "listeners": [ + "PageError", + "ConsoleAPI", + "FileActivity" + ] + } + +The reply is: + +.. code-block:: javascript + + { + "startedListeners": [ + "PageError", + "ConsoleAPI", + "FileActivity" + ], + "from": "conn0.console9" + } + + +The reply tells which listeners were started. + + +Tab navigation +-------------- + +To listen to the tab navigation events you also need to attach to the tab actor for the given tab. The ``tabNavigated`` notification comes from tab actors. + +.. warning:: + Prior to Firefox 20 the Web Console actor provided a ``LocationChange`` listener, with an associated ``locationChanged`` notification. This is no longer the case: we have made changes to allow the Web Console client to reuse the ``tabNavigated`` notification (`bug 792062 <https://bugzilla.mozilla.org/show_bug.cgi?id=792062>`_). + + +When page navigation starts the following packet is sent from the tab actor: + +.. code-block:: + + { + "from": tabActor, + "type": "tabNavigated", + "state": "start", + "url": newURL, + } + + +When navigation stops the following packet is sent: + +.. code-block:: + + { + "from": tabActor, + "type": "tabNavigated", + "state": "stop", + "url": newURL, + "title": newTitle, + } + + +``getCachedMessages(types, onResponse)`` +---------------------------------------- + +The ``webConsoleClient.getCachedMessages(types, onResponse)`` method sends the following packet to the server: + +.. code-block:: json + + { + "to": "conn0.console9", + "type": "getCachedMessages", + "messageTypes": [ + "PageError", + "ConsoleAPI" + ] + } + + +The ``getCachedMessages`` packet allows one to retrieve the cached messages from before the Web Console was open. You can only get cached messages for page errors and console API calls. The reply looks like this: + +.. code-block:: + + { + "messages": [ ... ], + "from": "conn0.console9" + } + +Each message in the array is of the same type as when we send typical page errors and console API calls. These will be explained in the following sections of this document. + +Page errors +*********** + +Page errors come from the ``nsIConsoleService``. Each allowed page error is an ``nsIScriptError`` object. + +The ``pageError`` packet is: + +.. code-block:: json + + { + "from": "conn0.console9", + "type": "pageError", + "pageError": { + "errorMessage": "ReferenceError: foo is not defined", + "sourceName": "http://localhost/~mihai/mozilla/test.js", + "lineText": "", + "lineNumber": 6, + "columnNumber": 0, + "category": "content javascript", + "timeStamp": 1347294508210, + "error": false, + "warning": false, + "exception": true, + "strict": false, + "private": false, + } + } + + +The packet is similar to ``nsIScriptError`` - for simplicity. We only removed several unneeded properties and changed how flags work. + +The ``private`` flag tells if the error comes from a private window/tab (added in Firefox 24). + +Starting with Firefox 24 the ``errorMessage`` and ``lineText`` properties can be long string actor grips if the string is very long. + + +Console API messages +******************** + +The `window.console API <https://developer.mozilla.org/en-US/docs/Web/API/console>`_ calls send internal messages throughout Gecko which allow us to do whatever we want for each call. The Web Console actor sends these messages to the remote debugging client. + +We use the ``ObjectActor`` from `dbg-script-actors.js <https://mxr.mozilla.org/mozilla-central/source/toolkit/devtools/debugger/server/dbg-script-actors.js>`_ without a ``ThreadActor``, to avoid slowing down the page scripts - the debugger deoptimizes JavaScript execution in the target page. The `lifetime of object actors <https://wiki.mozilla.org/Remote_Debugging_Protocol#Grip_Lifetimes>`_ in the Web Console is different than the lifetime of these objects in the debugger - which is usually per pause or per thread. The Web Console manages the lifetime of ``ObjectActors`` manually. + + +.. warning:: + Prior to Firefox 23 we used a different actor (``WebConsoleObjectActor``) for working with JavaScript objects through the protocol. In `bug 783499 <https://bugzilla.mozilla.org/show_bug.cgi?id=783499>`_ we did a number of changes that allowed us to reuse the ``ObjectActor`` from the debugger. + + +Console API messages come through the ``nsIObserverService`` - the console object implementation lives in `dom/base/ConsoleAPI.js <http://mxr.mozilla.org/mozilla-central/source/dom/base/ConsoleAPI.js>`_. + +For each console message we receive in the server, we send the following ``consoleAPICall`` packet to the client: + +.. code-block:: json + + { + "from": "conn0.console9", + "type": "consoleAPICall", + "message": { + "level": "error", + "filename": "http://localhost/~mihai/mozilla/test.html", + "lineNumber": 149, + "functionName": "", + "timeStamp": 1347302713771, + "private": false, + "arguments": [ + "error omg aloha ", + { + "type": "object", + "className": "HTMLBodyElement", + "actor": "conn0.consoleObj20" + }, + " 960 739 3.141592653589793 %a", + "zuzu", + { "type": "null" }, + { "type": "undefined" } + ] + } + } + +Similar to how we send the page errors, here we send the actual console event received from the ``nsIObserverService``. We change the ``arguments`` array - we create ``ObjectActor`` instances for each object passed as an argument - and, lastly, we remove some unneeded properties (like window IDs). In the case of long strings we use the ``LongStringActor``. The Web Console can then inspect the arguments. + +The ``private`` flag tells if the console API call comes from a private window/tab (added in Firefox 24). + +We have small variations for the object, depending on the console API call method - just like there are small differences in the console event object received from the observer service. To see these differences please look in the Console API implementation: `dom/base/ConsoleAPI.js <http://mxr.mozilla.org/mozilla-central/source/dom/base/ConsoleAPI.js>`_. + + +JavaScript evaluation +--------------------- + +The ``evaluateJS`` request and response packets +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The Web Console client provides the ``evaluateJS(requestId, string, onResponse)`` method which sends the following packet: + +.. code-block:: json + + { + "to": "conn0.console9", + "type": "evaluateJS", + "text": "document", + "bindObjectActor": null, + "frameActor": null, + "url": null, + "selectedNodeActor": null, + } + + +The ``bindObjectActor`` property is an optional ``ObjectActor`` ID that points to a ``Debugger.Object``. This option allows you to bind ``_self`` to the ``Debugger.Object`` of the given object actor, during string evaluation. See ``evalInGlobalWithBindings()`` for information about bindings. + +.. note:: + The variable view needs to update objects and it does so by binding ``_self`` to the ``Debugger.Object`` of the ``ObjectActor`` that is being viewed. As such, variable view sends strings like these for evaluation: + +.. code-block:: javascript + + _self["prop"] = value; + +The ``frameActor`` property is an optional ``FrameActor`` ID. The FA holds a reference to a ``Debugger.Frame``. This option allows you to evaluate the string in the frame of the given FA. + +The ``url`` property is an optional URL to evaluate the script as (new in Firefox 25). The default source URL for evaluation is "debugger eval code". + +The ``selectedNodeActor`` property is an optional ``NodeActor`` ID, which is used to indicate which node is currently selected in the Inspector, if any. This ``NodeActor`` can then be referred to by the ``$0`` JSTerm helper. + +The response packet: + +.. code-block:: json + + { + "from": "conn0.console9", + "input": "document", + "result": { + "type": "object", + "className": "HTMLDocument", + "actor": "conn0.consoleObj20" + "extensible": true, + "frozen": false, + "sealed": false + }, + "timestamp": 1347306273605, + "exception": null, + "exceptionMessage": null, + "helperResult": null + } + + +- ``exception`` holds the JSON-ification of the exception thrown during evaluation. +- ``exceptionMessage`` holds the ``exception.toString()`` result. +- ``result`` has the result ``ObjectActor`` instance. +- ``helperResult`` is anything that might come from a JSTerm helper result, JSON stuff (not content objects!). + + +.. warning:: + In Firefox 23: we renamed the ``error`` and ``errorMessage`` properties to ``exception`` and ``exceptionMessage`` respectively, to avoid conflict with the default properties used when protocol errors occur. + + +Autocomplete and more +--------------------- + +The ``autocomplete`` request packet: + +.. code-block:: json + + { + "to": "conn0.console9", + "type": "autocomplete", + "text": "d", + "cursor": 1 + } + + +The response packet: + +.. code-block:: json + + { + "from": "conn0.console9", + "matches": [ + "decodeURI", + "decodeURIComponent", + "defaultStatus", + "devicePixelRatio", + "disableExternalCapture", + "dispatchEvent", + "doMyXHR", + "document", + "dump" + ], + "matchProp": "d" + } + + +There's also the ``clearMessagesCache`` request packet that has no response. This clears the console API calls cache and should clear the page errors cache - see `bug 717611 <https://bugzilla.mozilla.org/show_bug.cgi?id=717611>`_. +An alternate version was added in Firefox 104, ``clearMessagesCacheAsync``, which does exactly the same thing but resolves when the cache was actually cleared. + + +Network logging +*************** + +The ``networkEvent`` packet +--------------------------- + +Whenever a new network request starts being logged the ``networkEvent`` packet is sent: + +.. code-block:: json + + { + "from": "conn0.console10", + "type": "networkEvent", + "eventActor": { + "actor": "conn0.netEvent14", + "startedDateTime": "2012-09-17T19:50:03.699Z", + "url": "http://localhost/~mihai/mozilla/test2.css", + "method": "GET" + "isXHR": false, + "private": false + } + } + + +This packet is used to inform the Web Console of a new network event. For each request a new ``NetworkEventActor`` instance is created. The ``isXHR`` flag indicates if the request was initiated via an `XMLHttpRequest <https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest>`_ instance, that is: the ``nsIHttpChannel``'s notification is of an ``nsIXMLHttpRequest`` interface. + +The ``private`` flag tells if the network request comes from a private window/tab (added in Firefox 24). + + +The ``NetworkEventActor`` +------------------------- + +The new network event actor stores further request and response information. + +The ``networkEventUpdate`` packet +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The Web Console UI needs to be kept up-to-date when changes happen, when new stuff is added. The new ``networkEventUpdate`` packet is sent for this purpose. Examples: + +.. code-block:: + + { + "from": "conn0.netEvent14", + "type": "networkEventUpdate", + "updateType": "requestHeaders", + "headers": 10, + "headersSize": 425 + }, + { + "from": "conn0.netEvent14", + "type": "networkEventUpdate", + "updateType": "requestCookies", + "cookies": 0 + }, + { + "from": "conn0.netEvent14", + "type": "networkEventUpdate", + "updateType": "requestPostData", + "dataSize": 1024, + "discardRequestBody": false + }, + { + "from": "conn0.netEvent14", + "type": "networkEventUpdate", + "updateType": "responseStart", + "response": { + "httpVersion": "HTTP/1.1", + "status": "304", + "statusText": "Not Modified", + "headersSize": 194, + "discardResponseBody": true + } + }, + { + "from": "conn0.netEvent14", + "type": "networkEventUpdate", + "updateType": "eventTimings", + "totalTime": 1 + }, + { + "from": "conn0.netEvent14", + "type": "networkEventUpdate", + "updateType": "responseHeaders", + "headers": 6, + "headersSize": 194 + }, + { + "from": "conn0.netEvent14", + "type": "networkEventUpdate", + "updateType": "responseCookies", + "cookies": 0 + }, + { + "from": "conn0.netEvent14", + "type": "networkEventUpdate", + "updateType": "responseContent", + "mimeType": "text/css", + "contentSize": 0, + "discardResponseBody": true + } + + +Actual headers, cookies, and bodies are not sent. + + +The ``getRequestHeaders`` and other packets +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To get more details about a network event you can use the following packet requests (and replies). + +The ``getRequestHeaders`` packet: + +.. code-block:: + + { + "to": "conn0.netEvent15", + "type": "getRequestHeaders" + } + { + "from": "conn0.netEvent15", + "headers": [ + { + "name": "Host", + "value": "localhost" + }, ... + ], + "headersSize": 350 + } + + +The ``getRequestCookies`` packet: + +.. code-block:: json + + { + "to": "conn0.netEvent15", + "type": "getRequestCookies" + } + { + "from": "conn0.netEvent15", + "cookies": [] + } + + +The ``getResponseHeaders`` packet: + +.. code-block:: + + { + "to": "conn0.netEvent15", + "type": "getResponseHeaders" + } + { + "from": "conn0.netEvent15", + "headers": [ + { + "name": "Date", + "value": "Mon, 17 Sep 2012 20:05:27 GMT" + }, ... + ], + "headersSize": 320 + } + + +The ``getResponseCookies`` packet: + +.. code-block:: json + + { + "to": "conn0.netEvent15", + "type": "getResponseCookies" + } + { + "from": "conn0.netEvent15", + "cookies": [] + } + + +.. note:: + Starting with Firefox 19: for all of the header and cookie values in the above packets we use `LongStringActor grips <https://wiki.mozilla.org/Remote_Debugging_Protocol#Objects>`_ when the value is very long. This helps us avoid using too much of the network bandwidth. + + +The ``getRequestPostData`` packet: + +.. code-block:: + + { + "to": "conn0.netEvent15", + "type": "getRequestPostData" + } + { + "from": "conn0.netEvent15", + "postData": { text: "foobar" }, + "postDataDiscarded": false + } + +The ``getResponseContent`` packet: + +.. code-block:: json + + { + "to": "conn0.netEvent15", + "type": "getResponseContent" + } + { + "from": "conn0.netEvent15", + "content": { + "mimeType": "text/css", + "text": "\n@import \"test.css\";\n\n.foobar { color: green }\n\n" + }, + "contentDiscarded": false + } + + +The request and response content text value is most commonly sent using a ``LongStringActor`` grip. For very short request/response bodies we send the raw text. + +.. note:: + Starting with Firefox 19: for non-text response types we send the content in base64 encoding (again, most likely a ``LongStringActor`` grip). To tell the difference just check if ``response.content.encoding == "base64"``. + + +The ``getEventTimings`` packet: + +.. code-block:: json + + { + "to": "conn0.netEvent15", + "type": "getEventTimings" + } + { + "from": "conn0.netEvent15", + "timings": { + "blocked": 0, + "dns": 0, + "connect": 0, + "send": 0, + "wait": 16, + "receive": 0 + }, + "totalTime": 16 + } + + +The ``fileActivity`` packet +--------------------------- + +When a file load is observed the following ``fileActivity`` packet is sent to the client: + +.. code-block:: json + + { + "from": "conn0.console9", + "type": "fileActivity", + "uri": "file:///home/mihai/public_html/mozilla/test2.css" + } + + +History +******* + +Protocol changes by Firefox version: + +- Firefox 18: initial version. +- Firefox 19: `bug <https://bugzilla.mozilla.org/show_bug.cgi?id=787981>`_ - added ``LongStringActor`` usage in several places. +- Firefox 20: `bug <https://bugzilla.mozilla.org/show_bug.cgi?id=792062>`_ - removed ``locationChanged`` packet and updated the ``tabNavigated`` packet for tab actors. +- Firefox 23: `bug <https://bugzilla.mozilla.org/show_bug.cgi?id=783499>`_ - removed the ``WebConsoleObjectActor``. Now the Web Console uses the JavaScript debugger API and the ``ObjectActor``. +- Firefox 23: added the ``bindObjectActor`` and ``frameActor`` options to the ``evaluateJS`` request packet. +- Firefox 24: new ``private`` flags for the console actor notifications, `bug <https://bugzilla.mozilla.org/show_bug.cgi?id=874061>`_. Also added the ``lastPrivateContextExited`` notification for the global console actor. +- Firefox 24: new ``isXHR`` flag for the ``networkEvent`` notification, `bug <https://bugzilla.mozilla.org/show_bug.cgi?id=859046>`_. +- Firefox 24: removed the ``message`` property from the ``pageError`` packet notification, `bug <https://bugzilla.mozilla.org/show_bug.cgi?id=877773>`_. The ``lineText`` and ``errorMessage`` properties can be long string actors now. +- Firefox 25: added the ``url`` option to the ``evaluateJS`` request packet. + + +Conclusions +*********** + +As of this writing, this document is a dense summary of the work we did in `bug 768096 <https://bugzilla.mozilla.org/show_bug.cgi?id=768096>`_ and subsequent changes. We try to keep this document up-to-date. We hope this is helpful for you. + +If you make changes to the Web Console server please update this document. Thank you! diff --git a/devtools/docs/user/web_console/rich_output/commandline-highlightnode.png b/devtools/docs/user/web_console/rich_output/commandline-highlightnode.png Binary files differnew file mode 100644 index 0000000000..578f2e1f95 --- /dev/null +++ b/devtools/docs/user/web_console/rich_output/commandline-highlightnode.png diff --git a/devtools/docs/user/web_console/rich_output/console_export.png b/devtools/docs/user/web_console/rich_output/console_export.png Binary files differnew file mode 100644 index 0000000000..f973acbd4c --- /dev/null +++ b/devtools/docs/user/web_console/rich_output/console_export.png diff --git a/devtools/docs/user/web_console/rich_output/console_logobject.png b/devtools/docs/user/web_console/rich_output/console_logobject.png Binary files differnew file mode 100644 index 0000000000..3435d8cfe8 --- /dev/null +++ b/devtools/docs/user/web_console/rich_output/console_logobject.png diff --git a/devtools/docs/user/web_console/rich_output/index.rst b/devtools/docs/user/web_console/rich_output/index.rst new file mode 100644 index 0000000000..3ebed8428e --- /dev/null +++ b/devtools/docs/user/web_console/rich_output/index.rst @@ -0,0 +1,129 @@ +=========== +Rich output +=========== + +When the Web console prints objects, it includes a richer set of information than just the object's name. In particular, it: + + +- :ref:`provides extra information for certain types <web_console_rich_output_type_specific>` +- :ref:`enables detailed examination of the object's properties <web_console_rich_output_examining_object_properties>` +- :ref:`provides richer information for DOM elements, and enables you to select them in the Inspector <web_console_rich_output_highlighting_and_inspecting_dom_nodes>` + + +.. _web_console_rich_output_type_specific: + +Type-specific rich output +************************* + +The Web Console provides rich output for many object types, including the following: + + +.. list-table:: + :widths: 20 80 + :header-rows: 0 + + * - ``Object`` + - .. image:: web-console-object.png + + * - ``Date`` + - .. image:: web-console-date.png + + * - ``Promise`` + - .. image:: web-console-promise.png + + * - ``RegExp`` + - .. image:: web-console-regexp.png + + * - ``Window`` + - .. image:: web-console-window.png + + * - ``Document`` + - .. image:: web-console-document.png + + * - ``Element`` + - .. image:: web-console-element.png + + * - ``Event`` + - .. image:: webconsole-events.png + + +.. _web_console_rich_output_examining_object_properties: + +Examining object properties +*************************** + +When an object is logged to the console it has a right-pointing triangle next to it, indicating that it can be expanded. Click on the triangle, and the object will be expanded to show its contents: + +.. image:: console_logobject.png + :class: border + + +Starting with Firefox 67 (available now in Firefox Developer) you can use the arrow keys on your keyboard to navigate through objects displayed in the console. The right-arrow key opens the details of an object and the left-arrow key closes open objects. + + +.. _web_console_rich_output_examining_request_details: + +Examining request details +************************* + + +Similar to examining object details, you can see the details about a network request directly in the console. Click on the arrow next to the request and a details panel will open that is equivalent to the Headers panel in the Network Monitor tool. + +.. raw:: html + + <iframe width="560" height="315" src="https://www.youtube.com/embed/Cj3Pjq6jk9s" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe> + <br/> + <br/> + + +Export output to the clipboard +****************************** + +Once you have output in the console window, you can save it to the clipboard by right-clicking on the output and selecting **Export visible messages to clipboard**: + +.. image:: console_export.png + :class: center + + +This will copy all of the output to the clipboard. Then you can paste it into a document. The output will look something like this: + +.. code-block:: + + console.log(todoList) + Array(4) [ {…}, {…}, {…}, {…} ] + debugger eval code:1:9 + undefined + +If you expand objects, such as arrays, you get slightly different content. For example, by expanding the array in the above list, I get the following: + +.. code-block:: + + console.log(todoList) + (4) […] + + 0: Object { status: "Done", description: "Morning Pages", dateCreated: 1552404478137 } + + 1: Object { status: "In Progress", description: "Refactor styles", dateCreated: 1552404493169 } + + 2: Object { status: "To Do", description: "Create feedback form", dateCreated: 1552404512630 } + + 3: Object { status: "To Do", description: "Normalize table", dateCreated: 1552404533790 } + + length: 4 + + <prototype>: Array [] + debugger eval code:1:9 + undefined + + +.. _web_console_rich_output_highlighting_and_inspecting_dom_nodes: + +Highlighting and inspecting DOM nodes +************************************* + +If you hover the mouse over any DOM element in the console output, it's highlighted on the page: + +.. image:: commandline-highlightnode.png + :class: center + +In the screenshot above you'll also see a blue "target" icon next to the node in the console output: click it to switch to the :doc:`Inspector <../../page_inspector/index>` with that node selected. diff --git a/devtools/docs/user/web_console/rich_output/web-console-array.png b/devtools/docs/user/web_console/rich_output/web-console-array.png Binary files differnew file mode 100644 index 0000000000..3593201ae2 --- /dev/null +++ b/devtools/docs/user/web_console/rich_output/web-console-array.png diff --git a/devtools/docs/user/web_console/rich_output/web-console-date.png b/devtools/docs/user/web_console/rich_output/web-console-date.png Binary files differnew file mode 100644 index 0000000000..f88b8e6a33 --- /dev/null +++ b/devtools/docs/user/web_console/rich_output/web-console-date.png diff --git a/devtools/docs/user/web_console/rich_output/web-console-document.png b/devtools/docs/user/web_console/rich_output/web-console-document.png Binary files differnew file mode 100644 index 0000000000..b960ff3758 --- /dev/null +++ b/devtools/docs/user/web_console/rich_output/web-console-document.png diff --git a/devtools/docs/user/web_console/rich_output/web-console-element.png b/devtools/docs/user/web_console/rich_output/web-console-element.png Binary files differnew file mode 100644 index 0000000000..5df11b1b70 --- /dev/null +++ b/devtools/docs/user/web_console/rich_output/web-console-element.png diff --git a/devtools/docs/user/web_console/rich_output/web-console-object.png b/devtools/docs/user/web_console/rich_output/web-console-object.png Binary files differnew file mode 100644 index 0000000000..55a145597b --- /dev/null +++ b/devtools/docs/user/web_console/rich_output/web-console-object.png diff --git a/devtools/docs/user/web_console/rich_output/web-console-promise.png b/devtools/docs/user/web_console/rich_output/web-console-promise.png Binary files differnew file mode 100644 index 0000000000..d4d1f33c7e --- /dev/null +++ b/devtools/docs/user/web_console/rich_output/web-console-promise.png diff --git a/devtools/docs/user/web_console/rich_output/web-console-regexp.png b/devtools/docs/user/web_console/rich_output/web-console-regexp.png Binary files differnew file mode 100644 index 0000000000..573132cee2 --- /dev/null +++ b/devtools/docs/user/web_console/rich_output/web-console-regexp.png diff --git a/devtools/docs/user/web_console/rich_output/web-console-window.png b/devtools/docs/user/web_console/rich_output/web-console-window.png Binary files differnew file mode 100644 index 0000000000..d88e1e925f --- /dev/null +++ b/devtools/docs/user/web_console/rich_output/web-console-window.png diff --git a/devtools/docs/user/web_console/rich_output/webconsole-events.png b/devtools/docs/user/web_console/rich_output/webconsole-events.png Binary files differnew file mode 100644 index 0000000000..797c709c3f --- /dev/null +++ b/devtools/docs/user/web_console/rich_output/webconsole-events.png diff --git a/devtools/docs/user/web_console/split_console/index.rst b/devtools/docs/user/web_console/split_console/index.rst new file mode 100644 index 0000000000..13bee8efc7 --- /dev/null +++ b/devtools/docs/user/web_console/split_console/index.rst @@ -0,0 +1,26 @@ +============= +Split console +============= + +You can use the console alongside other tools. While you're in another tool in the Toolbox, just press :kbd:`Esc` or select the "Show split console" command in the :ref:`Toolbar <tools-toolbox-toolbar>` menu. The toolbox will now appear split, with the original tool above and the web console underneath. + +You can close the split console by pressing :kbd:`Esc` again, or by selecting the "Hide split console" menu command. + +.. image:: split-console.png + :class: border + +.. raw:: html + + <iframe width="560" height="315" src="https://www.youtube.com/embed/G2hyxhPHyXo" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe> + <br/> + <br/> + +As usual, ``$0`` works as a shorthand for the element currently selected in the Inspector: + +.. image:: split-console-debugger.png + :class: center + +When you use the split console with the debugger, the console's scope is the currently executing stack frame. So if you hit a breakpoint in a function, the scope will be the function's scope. You'll get autocomplete for objects defined in the function, and can easily modify them on the fly: + +.. image:: split-console-show-debug.png + :class: center diff --git a/devtools/docs/user/web_console/split_console/split-console-debugger.png b/devtools/docs/user/web_console/split_console/split-console-debugger.png Binary files differnew file mode 100644 index 0000000000..91991f487e --- /dev/null +++ b/devtools/docs/user/web_console/split_console/split-console-debugger.png diff --git a/devtools/docs/user/web_console/split_console/split-console-show-debug.png b/devtools/docs/user/web_console/split_console/split-console-show-debug.png Binary files differnew file mode 100644 index 0000000000..3a24d6d9a1 --- /dev/null +++ b/devtools/docs/user/web_console/split_console/split-console-show-debug.png diff --git a/devtools/docs/user/web_console/split_console/split-console.png b/devtools/docs/user/web_console/split_console/split-console.png Binary files differnew file mode 100644 index 0000000000..a848139a20 --- /dev/null +++ b/devtools/docs/user/web_console/split_console/split-console.png diff --git a/devtools/docs/user/web_console/the_command_line_interpreter/arraylist_autocomplete.png b/devtools/docs/user/web_console/the_command_line_interpreter/arraylist_autocomplete.png Binary files differnew file mode 100644 index 0000000000..dc104eb679 --- /dev/null +++ b/devtools/docs/user/web_console/the_command_line_interpreter/arraylist_autocomplete.png diff --git a/devtools/docs/user/web_console/the_command_line_interpreter/commandline-accessbuiltin.png b/devtools/docs/user/web_console/the_command_line_interpreter/commandline-accessbuiltin.png Binary files differnew file mode 100644 index 0000000000..9dfc3f96e4 --- /dev/null +++ b/devtools/docs/user/web_console/the_command_line_interpreter/commandline-accessbuiltin.png diff --git a/devtools/docs/user/web_console/the_command_line_interpreter/commandline-accesspageadded.png b/devtools/docs/user/web_console/the_command_line_interpreter/commandline-accesspageadded.png Binary files differnew file mode 100644 index 0000000000..19b4167d3d --- /dev/null +++ b/devtools/docs/user/web_console/the_command_line_interpreter/commandline-accesspageadded.png diff --git a/devtools/docs/user/web_console/the_command_line_interpreter/console_autocomplete_cropped.png b/devtools/docs/user/web_console/the_command_line_interpreter/console_autocomplete_cropped.png Binary files differnew file mode 100644 index 0000000000..4b1da9a82e --- /dev/null +++ b/devtools/docs/user/web_console/the_command_line_interpreter/console_autocomplete_cropped.png diff --git a/devtools/docs/user/web_console/the_command_line_interpreter/console_syntaxhighlighting.png b/devtools/docs/user/web_console/the_command_line_interpreter/console_syntaxhighlighting.png Binary files differnew file mode 100644 index 0000000000..4483a1d038 --- /dev/null +++ b/devtools/docs/user/web_console/the_command_line_interpreter/console_syntaxhighlighting.png diff --git a/devtools/docs/user/web_console/the_command_line_interpreter/index.rst b/devtools/docs/user/web_console/the_command_line_interpreter/index.rst new file mode 100644 index 0000000000..bb3ec8ce83 --- /dev/null +++ b/devtools/docs/user/web_console/the_command_line_interpreter/index.rst @@ -0,0 +1,170 @@ +================================ +The JavaScript input interpreter +================================ + +You can interpret JavaScript expressions in real time using the interpreter provided by the Web Console. It has two modes: single-line entry and multi-line entry. + +Single-line mode +**************** + +For single-line entry, you can type JavaScript expressions in the field at the bottom of the console log, at the **>>** prompt. + +.. image:: web_console_single.png + :alt: The Web Console, showing single-line mode + :class: center + + +To enter expressions in single-line mode, type at the prompt and press :kbd:`Enter`. To enter multi-line expressions, press :kbd:`Shift` + :kbd:`Enter` after typing each line, then :kbd:`Enter` to run all the entered lines. + +The expression you type is echoed under the input prompt, followed by the result. + +If your input does not appear to be complete when you press :kbd:`Enter`, then the Console treats this as :kbd:`Shift` + :kbd:`Enter` , enabling you to finish your input. + +For example, if you type: + +.. code-block:: JavaScript + + function foo() { + + +and then :kbd:`Enter`, the Console does not immediately execute the input, but behaves as if you had pressed :kbd:`Shift` + :kbd:`Enter` , so you can finish entering the function definition. + + +.. _command_line_interpreter_multi_line_mode: + +Multi-line mode +*************** + +For multi-line entry, click the "split panel" icon at the right hand side of the single-line entry field, or press :kbd:`Ctrl` + :kbd:`B` (Windows/Linux) or :kbd:`Cmd` + :kbd:`B` (macOS). The multi-line editing pane opens on the left side the of Web Console. + +.. image:: web_console_multi.png + :alt: Web Console in multi-line mode + :class: center + +You can enter multiple lines of JavaScript by default in this mode, pressing :kbd:`Enter` after each one. To execute the snippet that is currently in the editing pane, click the **Run** button or press :kbd:`Ctrl` + :kbd:`Enter` (or :kbd:`Cmd` + :kbd:`Return` on MacOS). The snippet is echoed under the input prompt (in the right-side pane), followed by the result. + +Starting in Firefox 76, if the code snippet is more than five lines long, only the first five lines are echoed in the console, preceded by a disclosure triangle (or "twistie"), and followed by an ellipsis (…). Click anywhere in the area containing the echoed code to show the whole snippet; click again in that area to collapse it. + +You can open files when in multi-line mode, and save the current contents of the editing pane to a file. + + +- To open a file, press :kbd:`Ctrl` + :kbd:`O` (:kbd:`Cmd` + :kbd:`O` on MacOS). A file dialog box opens so you can select the file to open. +- To save the contents of the editing pane, press :kbd:`Ctrl` + :kbd:`S` (:kbd:`Cmd` + :kbd:`S` on MacOS). A file dialog box opens so you can specify the location to save to. + + +To switch back to single-line mode, click the **X** icon at the top of the multi-line editing pane, or press :kbd:`Ctrl` + :kbd:`B` (Windows/Linux) or :kbd:`Cmd` + :kbd:`B` (MacOS). + + +Accessing variables +******************* + +You can access variables defined in the page, both built-in variables like ``window`` and variables added by JavaScript libraries like *jQuery*: + +.. image:: commandline-accessbuiltin.png + :class: center + +.. image:: commandline-accesspageadded.png + :class: center + + +.. _command_line_interpreter_autocomplete: + +Autocomplete +************ + +The editor has autocomplete: enter the first few letters and a popup appears with possible completions: + +.. image:: console_autocomplete_cropped.png + :class: center + + +Press :kbd:`Enter`, :kbd:`Tab`, or the right arrow key to accept the suggestion, use the up/down arrows to move to a different suggestion, or just keep typing if you don't like any of the suggestions. + +Console autocomplete suggestions are case-insensitive. + +The console suggests completions from the scope of the currently executing stack frame. This means that if you've hit a breakpoint in a function you get autocomplete for objects local to the function. + +You get autocomplete suggestions for array elements, as well: + +.. image:: arraylist_autocomplete.png + :class: border + + +You can enable or disable autocompletion via the Settings ("gear") menu in the Web Console toolbar. The menuitem **Enable Autocompletion** has a checkmark next to it when the feature is enabled, which is missing when it is disabled. Select the menuitem to change the state. + + +Instant evaluation +****************** + +.. note:: + This feature is available in Firefox Nightly, in versions labeled 74 and later. + +When the "instant evaluation" feature is enabled, the interpreter displays results of expressions as you're typing them in single-line mode. Note that the result might be an error message. Expressions that have side effects are not evaluated. + +You can enable or disable instant evaluation via the Settings ("gear") menu in the Web Console toolbar. The menuitem **Instant Evaluation** has a checkmark next to it when the feature is enabled, which is missing when it is disabled. Select the menuitem to change the state. + + +Execution context +***************** + +Code that you have executed becomes part of the execution context, regardless of what editing mode you were in when you executed it. For example, if you type a function definition in the multi-line editor, and click **Run**, you can switch to single-line mode and still use your function. + + +Syntax highlighting +******************* + +.. image:: console_syntaxhighlighting.png + :alt: Console output showing syntax highlighting + :class: border + + +The text you enter has syntax highlighting as soon as you have typed enough for the highlighter to parse it and infer the meanings of the "words". + +The output is highlighted as well where appropriate. + +.. note:: + Syntax highlighting is not visible in your browser if Accessibility features have been enabled. + + +.. _command_line_interpreter_execution_history: + +Execution history +***************** + +The interpreter remembers expressions you've typed. To move back and forward through your history: + + +- In single-line mode, use the up and down arrows. +- In multi-line mode, use the **⋀** and **⋁** icons in the editing panel's toolbar. + + +The expression history is persisted across sessions. To clear the history, use the ``clearHistory()`` :ref:`helper function <command_line_interpreter_helper_commands>`. + +You can initiate a reverse search through the expression history, much like you can in bash on Linux and Mac or PowerShell on Windows. On Windows and Linux press :kbd:`F9`. On Mac press :kbd:`Ctrl` + :kbd:`R` (**note:** not :kbd:`Cmd` + :kbd:`R`!) to initiate the reverse search. + +.. image:: reverse_search.png + :class: border + + +Enter the text you want to search for in the input box at the bottom of the Console. Start typing part of the expression you are looking for and the first match is displayed in the console. Repeatedly typing :kbd:`F9` on Windows and Linux ( :kbd:`Ctrl` + :kbd:`R` on Mac) cycles backwards through the matches. + +.. image:: reverse_search_example.png + :class: border + +Once you have initiated the reverse search, you can use :kbd:`Shift` + :kbd:`F9` on Windows or Linux ( :kbd:`Ctrl` + :kbd:`S` on Mac) to search forward in the list of matches. You can also use the **⋀** and **⋁** icons in the expression search bar. + +When you find the expression you want, press :kbd:`Enter` (:kbd:`Return`) to execute the statement. + + +Working with iframes +******************** + +:doc:`Working with iframes <../../working_with_iframes/index>` explains how to direct all debugging tools to target a particular iframe, including the command line interpreter. + + +.. _command_line_interpreter_helper_commands: + +Helper commands +*************** + +The JavaScript command line provided by the Web Console offers a few built-in helper functions that make certain tasks easier. For more information see :doc:`Web Console Helpers <../helpers/index>`. diff --git a/devtools/docs/user/web_console/the_command_line_interpreter/reverse_search.png b/devtools/docs/user/web_console/the_command_line_interpreter/reverse_search.png Binary files differnew file mode 100644 index 0000000000..b9dcd3f0b7 --- /dev/null +++ b/devtools/docs/user/web_console/the_command_line_interpreter/reverse_search.png diff --git a/devtools/docs/user/web_console/the_command_line_interpreter/reverse_search_example.png b/devtools/docs/user/web_console/the_command_line_interpreter/reverse_search_example.png Binary files differnew file mode 100644 index 0000000000..6899c3bb93 --- /dev/null +++ b/devtools/docs/user/web_console/the_command_line_interpreter/reverse_search_example.png diff --git a/devtools/docs/user/web_console/the_command_line_interpreter/web-console-iframe-document.png b/devtools/docs/user/web_console/the_command_line_interpreter/web-console-iframe-document.png Binary files differnew file mode 100644 index 0000000000..db22cfa616 --- /dev/null +++ b/devtools/docs/user/web_console/the_command_line_interpreter/web-console-iframe-document.png diff --git a/devtools/docs/user/web_console/the_command_line_interpreter/web-console-iframe-function.png b/devtools/docs/user/web_console/the_command_line_interpreter/web-console-iframe-function.png Binary files differnew file mode 100644 index 0000000000..88b5b47e1d --- /dev/null +++ b/devtools/docs/user/web_console/the_command_line_interpreter/web-console-iframe-function.png diff --git a/devtools/docs/user/web_console/the_command_line_interpreter/web_console_multi.png b/devtools/docs/user/web_console/the_command_line_interpreter/web_console_multi.png Binary files differnew file mode 100644 index 0000000000..b1be269584 --- /dev/null +++ b/devtools/docs/user/web_console/the_command_line_interpreter/web_console_multi.png diff --git a/devtools/docs/user/web_console/the_command_line_interpreter/web_console_single.png b/devtools/docs/user/web_console/the_command_line_interpreter/web_console_single.png Binary files differnew file mode 100644 index 0000000000..62827ea7a0 --- /dev/null +++ b/devtools/docs/user/web_console/the_command_line_interpreter/web_console_single.png diff --git a/devtools/docs/user/web_console/ui_tour/index.rst b/devtools/docs/user/web_console/ui_tour/index.rst new file mode 100644 index 0000000000..50495744b5 --- /dev/null +++ b/devtools/docs/user/web_console/ui_tour/index.rst @@ -0,0 +1,50 @@ +=================== +Web Console UI Tour +=================== + +The Web Console's interface is split into three horizontal sections, detailed in the sections below. + +.. image:: web_console.png + :alt: Web console" alt="Screenshot of FF web console + :class: center + + +.. _web_console_ui_tour_toolbar: + +Toolbar +******* + +The toolbar across the top contains a number of features: + + +- **Garbage can:** Click this icon to clear the contents of the console. +- **Funnel (filter):** Enter text to filter the messages that are displayed in the console message pane. :ref:`Plain-text <web_console_ui_tour_filtering_by_text>` and :ref:`regular expression <web_console_ui_tour_filtering_by_regular_expressions>` filtering are supported. +- :ref:`Filter categories <web_console_ui_tour_filtering_by_category>`: Toggle a filter category (such as Errors, Warnings, CSS, or XHR) to display messages of that type in the message page (the UI shows the number of hidden message for unselected categories). +- **Settings ("gear" menu):** Select the gear icon to access the settings menu (New in Firefox 71), where you can toggle the following features on and off: + + - **Persist Logs**: When enabled, the console doesn't clear on page reload, or new page load. + - **Show Timestamps**: When enabled, timestamps are shown on the left-hand side of each message row to say when the messages were logged. + - **Group Similar Messages**: When enabled, similar types of messages are grouped together, with an indicator of the number of occurrences. + - **Enable Autocompletion**: When enabled, the JavaScript interpreter attempts to autocomplete while you type. + - **Instant Evaluation**: When enabled, the interpreter displays the evaluated results of an expression, when possible, before you press :kbd:`Enter` to submit it. + + + +Message display pane +******************** + +This is where the messages appear, both those generated by the code in the page, and those generated by the commands entered on the command line. + +See :doc:`Console messages <../the_command_line_interpreter/index>` for a lot more detail on what the messages can contain. + +.. note:: + + You can clear the contents of the console by entering the keyboard command :kbd:`Ctrl` + :kbd:`Shift` + :kbd:`L` (Windows, macOS, and Linux) or :kbd:`Cmd` + :kbd:`K` on macOS. + + +Command line +************ + +The :doc:`command line <../the_command_line_interpreter/index>` starts with double angle brackets (>>). Use it to enter JavaScript expressions. + +In Firefox 71 onwards, there is a new "split pane" icon on the right hand side of the command line — clicking this will open the new console :ref:`multi-line mode <command_line_interpreter_multi_line_mode>`. diff --git a/devtools/docs/user/web_console/ui_tour/web_console.png b/devtools/docs/user/web_console/ui_tour/web_console.png Binary files differnew file mode 100644 index 0000000000..e8f5e27203 --- /dev/null +++ b/devtools/docs/user/web_console/ui_tour/web_console.png diff --git a/devtools/docs/user/working_with_iframes/developer_tools_select_iframe.png b/devtools/docs/user/working_with_iframes/developer_tools_select_iframe.png Binary files differnew file mode 100644 index 0000000000..17d2ec698b --- /dev/null +++ b/devtools/docs/user/working_with_iframes/developer_tools_select_iframe.png diff --git a/devtools/docs/user/working_with_iframes/developer_tools_settings_iframes.png b/devtools/docs/user/working_with_iframes/developer_tools_settings_iframes.png Binary files differnew file mode 100644 index 0000000000..04585375fe --- /dev/null +++ b/devtools/docs/user/working_with_iframes/developer_tools_settings_iframes.png diff --git a/devtools/docs/user/working_with_iframes/frame-selection-button.png b/devtools/docs/user/working_with_iframes/frame-selection-button.png Binary files differnew file mode 100644 index 0000000000..0820cebf1c --- /dev/null +++ b/devtools/docs/user/working_with_iframes/frame-selection-button.png diff --git a/devtools/docs/user/working_with_iframes/frame-selection-popup.png b/devtools/docs/user/working_with_iframes/frame-selection-popup.png Binary files differnew file mode 100644 index 0000000000..ae96760ae2 --- /dev/null +++ b/devtools/docs/user/working_with_iframes/frame-selection-popup.png diff --git a/devtools/docs/user/working_with_iframes/index.rst b/devtools/docs/user/working_with_iframes/index.rst new file mode 100644 index 0000000000..8d75d97a64 --- /dev/null +++ b/devtools/docs/user/working_with_iframes/index.rst @@ -0,0 +1,25 @@ +==================== +Working with iframes +==================== + +You can point the developer tools at a specific `iframe <https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe>`_ within a document. The :doc:`Inspector <../page_inspector/index>`, :doc:`Console <../web_console/index>`, :doc:`Debugger <../debugger/index>` and all other developer tools will then target that iframe (essentially behaving as if the rest of the page does not exist). + +.. raw:: html + + <iframe width="560" height="315" src="https://www.youtube.com/embed/Me9hjqd74m8" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe> + <br/> + <br/> + +To set an iframe as the target for the developer tools: + +- Select the *iframe context picker button* to launch a popup listing all the iframes in the document (and the main document itself). Note that the button is only displayed if the page includes iframes! + + .. image:: developer_tools_select_iframe.png + :alt: Screenshot showing how to set an iframe as the target of developer tools (using the iframe button) + :class: center + +- Select an entry to make it the *target iframe*. + + +.. note:: + The iframe context picker button feature is enabled by default (if it has been disabled the iframe button is never displayed). The feature can be re-enabled from the Settings menu, using the "Select an iframe as the currently targeted document" checkbox. |
