diff options
Diffstat (limited to 'devtools/docs/user/web_console')
49 files changed, 1616 insertions, 0 deletions
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..ed7578c7b0 --- /dev/null +++ b/devtools/docs/user/web_console/remoting/index.rst @@ -0,0 +1,666 @@ +==================== +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. + +Private browsing +---------------- + +The Browser Console can be used while the user has private windows open. Each page error, console API message and network request is annotated with a ``private`` flag. Private messages are cleared whenever the last private window is closed. The console actor provides the ``lastPrivateContextExited`` notification: + +.. code-block:: json + + { + "from": "conn0.console19", + "type": "lastPrivateContextExited" + } + + +This notification is sent only when your client is attached to the global console actor, it does not make sense for tab console actors. + +.. note:: + This notification has been introduced in Firefox 24. + +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 |
