index.rst (8040B)
1 =============== 2 Browser Console 3 =============== 4 5 The Browser Console is like the :doc:`Web Console <../web_console/index>`, but applied to the whole browser rather than a single content tab. 6 7 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. 8 9 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>`. 10 11 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. 12 13 .. container:: block_quote 14 15 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" option in the :doc:`developer tool settings <../settings/index>`. 16 17 18 Opening the Browser Console 19 *************************** 20 21 You can open the Browser Console in one of two ways: 22 23 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). 24 25 2. from the keyboard: press :kbd:`Ctrl` + :kbd:`Shift` + :kbd:`J` (or :kbd:`Cmd` + :kbd:`Shift` + :kbd:`J` on a Mac). 26 27 28 You can also start the Browser Console by launching Firefox from the command line and passing the ``-jsconsole`` argument: 29 30 .. code-block:: bash 31 32 /Applications/FirefoxAurora.app/Contents/MacOS/firefox -jsconsole 33 34 The Browser Console looks like this: 35 36 .. image:: browser_console_68.png 37 38 39 You can see that the Browser Console looks and behaves very much like the :doc:`Web Console <../web_console/index>`: 40 41 - most of the window is occupied by a :doc:`pane that display messages <../web_console/console_messages/index>` 42 43 - at the top, a :ref:`toolbar <web_console_ui_tour_toolbar>` enables you to filter the messages that appear. 44 45 - at the bottom, a :doc:`command line interpreter <../web_console/the_command_line_interpreter/index>` enables you to evaluate JavaScript expressions. 46 47 48 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. 49 50 .. image:: browser_console_68_02.png 51 52 53 Browser Console logging 54 *********************** 55 56 The Browser console logs the same sorts of messages as the Web Console: 57 58 - :ref:`HTTP requests <web_console_console_messages>` 59 60 - :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>`_ 61 62 - :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 63 64 65 However, it displays such messages from: 66 67 - web content hosted by all browser tabs 68 - the browser's own code 69 - add-ons 70 71 Messages from add-ons 72 --------------------- 73 74 The Browser Console displays messages logged by all Firefox add-ons. 75 76 Console.sys.mjs 77 ~~~~~~~~~~~~~~~ 78 79 To use the console API from a traditional or bootstrapped add-on, get it from the Console module. 80 81 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. 82 83 .. code-block:: JavaScript 84 85 const { console } = ChromeUtils.importESModule("resource://gre/modules/Console.sys.mjs"); 86 console.log("Hello from Firefox code"); //output messages to the console 87 88 Learn more: 89 90 - `Console API reference <https://developer.mozilla.org/en-US/docs/Web/API/console>`_ 91 - :searchfox:`Console.sys.mjs source code <toolkit/modules/Console.sys.mjs>` 92 93 94 Browser Console command line 95 **************************** 96 97 .. container:: block_quote 98 99 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>`. 100 101 102 Like the Web Console, the command line interpreter enables you to evaluate JavaScript expressions in real time: 103 104 .. image:: browser-console-commandline.png 105 106 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. 107 108 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``: 109 110 .. image:: browser-console-chromewindow.png 111 112 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. 113 114 115 Controlling the browser 116 ----------------------- 117 118 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`): 119 120 .. code-block:: JavaScript 121 122 var newTabBrowser = gBrowser.getBrowserForTab(gBrowser.selectedTab); 123 newTabBrowser.addEventListener("load", function() { 124 newTabBrowser.contentDocument.body.innerHTML = "<h1>this page has been eaten</h1>"; 125 }, true); 126 newTabBrowser.contentDocument.location.href = "https://mozilla.org/"; 127 128 129 It adds a listener to the currently selected tab's ``load`` event that will eat the new page, then loads a new page. 130 131 .. note:: 132 133 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. 134 135 136 Modifying the browser UI 137 ------------------------ 138 139 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: 140 141 .. code-block:: JavaScript 142 143 var parent = window.document.getElementById("appmenuPrimaryPane"); 144 var makeTheTea = gBrowser.ownerDocument.defaultView.document.createElementNS("http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul", "menuitem"); 145 makeTheTea.setAttribute("label", "A nice cup of tea?"); 146 parent.appendChild(makeTheTea); 147 148 .. image:: browser-console-modify-ui-windows.png 149 150 On macOS, this similar code will add a new item to the **Tools** menu: 151 152 .. code-block:: JavaScript 153 154 var parent = window.document.getElementById("menu_ToolsPopup"); 155 var makeTheTea = gBrowser.ownerDocument.defaultView.document.createElementNS("http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul", "menuitem"); 156 makeTheTea.setAttribute("label", "A nice cup of tea?"); 157 parent.appendChild(makeTheTea); 158 159 .. image:: browser-console-modify-ui-osx.png