From 40a355a42d4a9444dc753c04c6608dade2f06a23 Mon Sep 17 00:00:00 2001
From: Daniel Baumann <daniel.baumann@progress-linux.org>
Date: Fri, 19 Apr 2024 03:13:27 +0200
Subject: Adding upstream version 125.0.1.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
---
 devtools/docs/contributor/contributing/eslint.md   |   1 -
 .../docs/contributor/tests/mochitest-devtools.md   |  39 ++++
 devtools/docs/user/devtoolsapi/index.rst           |   2 +-
 devtools/docs/user/index.rst                       |   2 +
 .../docs/user/javascript_tracer/console-trace.png  | Bin 0 -> 18925 bytes
 devtools/docs/user/javascript_tracer/index.rst     | 201 +++++++++++++++++++++
 .../docs/user/javascript_tracer/pending-icon.png   | Bin 0 -> 1320 bytes
 .../docs/user/javascript_tracer/trace-icon.svg     |   6 +
 .../trace-returns-with-values.png                  | Bin 0 -> 8361 bytes
 .../docs/user/javascript_tracer/trace-returns.png  | Bin 0 -> 6602 bytes
 .../docs/user/javascript_tracer/trace-values.png   | Bin 0 -> 14753 bytes
 11 files changed, 249 insertions(+), 2 deletions(-)
 create mode 100644 devtools/docs/user/javascript_tracer/console-trace.png
 create mode 100644 devtools/docs/user/javascript_tracer/index.rst
 create mode 100644 devtools/docs/user/javascript_tracer/pending-icon.png
 create mode 100644 devtools/docs/user/javascript_tracer/trace-icon.svg
 create mode 100644 devtools/docs/user/javascript_tracer/trace-returns-with-values.png
 create mode 100644 devtools/docs/user/javascript_tracer/trace-returns.png
 create mode 100644 devtools/docs/user/javascript_tracer/trace-values.png

(limited to 'devtools/docs')

diff --git a/devtools/docs/contributor/contributing/eslint.md b/devtools/docs/contributor/contributing/eslint.md
index 88da959255..55584bf12b 100644
--- a/devtools/docs/contributor/contributing/eslint.md
+++ b/devtools/docs/contributor/contributing/eslint.md
@@ -153,5 +153,4 @@ This should help you write eslint-clean code:
 * When cleaning an entire file or folder from ESLint errors, do not forget to remove the corresponding entry from the `.eslintignore` file.
 * When writing new code, from scratch, please make it ESLint compliant from the start. This is a lot easier than having to revisit it later.
 * ESLint also runs on `<script>` tags in HTML files, so if you create new HTML test files for mochitests for example, make sure that JavaScript code in those files is free of ESLint errors.
-* Depending on how a dependency is loaded into a file, the symbols this dependency exports might not be considered as defined by ESLint. For instance, using `Cu.import("some.jsm")` doesn't explicitly say which symbols are now available in the scope of the file, and so using those symbols will be consider by ESLint as using undefined variables. When this happens, please avoid using the `/* globals ... */` ESLint comment (which tells it that these variables are defined). Instead, please use `/* import-globals-from relative/path/to/file.js */`. This way, you won't have a list of variables to maintain manually, the globals are going to be imported dynamically instead.
 * In test files (xpcshell and mochitest), all globals from the corresponding `head.js` file are imported automatically, so you don't need to define them using a `/* globals ... */` comment or a `/* import-globals-from head.js */` comment.
diff --git a/devtools/docs/contributor/tests/mochitest-devtools.md b/devtools/docs/contributor/tests/mochitest-devtools.md
index e5f44ba1d6..fcae64b49d 100644
--- a/devtools/docs/contributor/tests/mochitest-devtools.md
+++ b/devtools/docs/contributor/tests/mochitest-devtools.md
@@ -34,3 +34,42 @@ You can also run just a single test:
 ```bash
 ./mach mochitest --headless devtools/client/path/to/the/test_you_want_to_run.js
 ```
+
+## Tracing JavaScript
+
+You can log all lines being executed in the mochitest script by using DEBUG_STEP env variable.
+This will help you:
+ * if the test is stuck on some asynchronous waiting code, on which line it is waiting,
+ * visualize the test script execution compared to various logs and assertion logs.
+
+Note that it will only work with Mochitests importing `devtools/client/shared/test/shared-head.js` module,
+which is used by most DevTools browser mochitests.
+
+This way:
+```bash
+DEBUG_STEP=true ./mach mochitest browser_devtools_test.js
+```
+or that other way:
+```bash
+./mach mochitest browser_devtools_test.js --setenv DEBUG_STEP=true
+```
+This will log the following lines:
+```
+[STEP] browser_target_command_detach.js @ 19:15   ::   const tab = ↦ await addTab(TEST_URL);
+```
+which tells that test script at line 19 and column 15 is about to be executed.
+The '↦' highlights the precise execution's column.
+
+Instead of passing true, you may pass a duration in milliseconds where each test line will pause for a given amount of time.
+Be careful when using this feature as it will pause the event loop on each test line and allow another other event to be processed.
+This will cause the test to run in a unreal way that wouldn't happen otherwise.
+
+```bash
+DEBUG_STEP=250 ./mach mochitest browser_devtools_test.js
+```
+Each line of the mochitest script will pause for 1/4 of seconds.
+
+Last, but not least, this feature can be used on try via:
+```bash
+./mach mochitest try fuzzy devtools/test/folder/ --env DEBUG_STEP=true
+```
diff --git a/devtools/docs/user/devtoolsapi/index.rst b/devtools/docs/user/devtoolsapi/index.rst
index 31a44a022f..8c42ebd8db 100644
--- a/devtools/docs/user/devtoolsapi/index.rst
+++ b/devtools/docs/user/devtoolsapi/index.rst
@@ -45,7 +45,7 @@ Methods
 
   - ``toolDefinition {ToolDefinition}`` - An object that contains information about the tool. See :ref:`ToolDefinition <devtoolsapi-tool-definition>` for details.
 
-``unregisterTool(tool)``
+``unregisterTool(toolId)``
   Unregisters the given tool and removes it from all toolboxes.
 
   **Parameters:**
diff --git a/devtools/docs/user/index.rst b/devtools/docs/user/index.rst
index 67c9189bc7..681c1c140a 100644
--- a/devtools/docs/user/index.rst
+++ b/devtools/docs/user/index.rst
@@ -190,6 +190,8 @@ These developer tools are also built into Firefox. Unlike the "Core Tools" above
   * - :doc:`Custom formatters <custom_formatters/index>`
     - Customize the way objects are displayed within the DevTools.
 
+  * - :doc:`JavaScript tracer <javascript_tracer/index>`
+    - Live display all JavaScript function calls.
 
 .. image:: logo-developer-quantum.png
     :class: center
diff --git a/devtools/docs/user/javascript_tracer/console-trace.png b/devtools/docs/user/javascript_tracer/console-trace.png
new file mode 100644
index 0000000000..beabf0da9c
Binary files /dev/null and b/devtools/docs/user/javascript_tracer/console-trace.png differ
diff --git a/devtools/docs/user/javascript_tracer/index.rst b/devtools/docs/user/javascript_tracer/index.rst
new file mode 100644
index 0000000000..828c3f12c5
--- /dev/null
+++ b/devtools/docs/user/javascript_tracer/index.rst
@@ -0,0 +1,201 @@
+
+=================
+JavaScript Tracer
+=================
+
+How to use the JavaScript Tracer
+*****************************************
+
+.. note::
+
+  This feature is still under development and may drastically change at any time.
+  You will have to toggle `devtools.debugger.features.javascript-tracing preference` preference to true in about:config
+  before opening DevTools in order to use it.
+
+Once enabled, you have three ways to toggle the tracer:
+
+  * From the debugger, via the tracer icon on the top right of its toolbar |image1|.
+
+    You can right click on this button (only when the tracer is OFF) to configure its behavior.
+
+  * From the console, via the `:trace` command.
+
+    You can execute `:trace --help` to see all supported optional arguments.
+    Otherwise `:trace` will either start or stop the JS Tracer based on its current state.
+
+  * From the page, via Ctrl+Shift+5 key shortcut (or Cmd+Shift+5 on MacOS).
+
+    Triggering this key shortcut will either start or stop the JS Tracer based on its current state.
+    This will use the configuration current defined in the Debugger tracer icon's context menu.
+
+.. |image1| image:: trace-icon.svg
+
+Tracer options
+**************
+
+Logging output
+--------------
+
+ * Web Console (Default)
+
+   The JS Tracer will log all JS function calls into the Web Console panel.
+   This helps see the precise order of JS calls versus anything logged in the console:
+   console API usages, exceptions, CSS warnings, ...
+
+   |image2|
+
+   (`:trace --logMethod console`)
+
+ * Stdout
+
+   The JS Tracer will log all JS function calls in your terminal (assuming you launched Firefox from a terminal).
+   This output is especially useful when the page involves lots of JS activity as it is faster to render.
+   You may also use various terminal tricks to filter the output the way you want.
+   Note that source URLs are flagged with some special characters so that most terminal will allow you to click on them.
+   If Firefox is your default browser, the links should open the debugger on the right location.
+   Assuming this is the same Firefox instance that is logging the traces and the same instance that the terminal app tries to open.
+   And you need DevTools to be kept opened, otherwise the link will open as a regular URL in a new tab.
+
+.. code-block:: bash
+
+  —DOM | click
+  —[interpreter]—> https://bugzilla.mozilla.org/static/v20240305.1/js/jquery/jquery-min.js:2:37892 - λ add/v.handle
+  ——[baseline]—> https://bugzilla.mozilla.org/static/v20240305.1/js/jquery/jquery-min.js:2:39398 - λ dispatch
+  ———[interpreter]—> https://bugzilla.mozilla.org/static/v20240305.1/js/jquery/jquery-min.js:2:40960 - λ fix
+  ————[interpreter]—> https://bugzilla.mozilla.org/static/v20240305.1/js/jquery/jquery-min.js:2:41576 - λ ce.Event
+  ———[interpreter]—> https://bugzilla.mozilla.org/static/v20240305.1/js/jquery/jquery-min.js:2:30171 - λ get
+  ————[interpreter]—> https://bugzilla.mozilla.org/static/v20240305.1/js/jquery/jquery-min.js:2:29696 - λ F
+  ———[interpreter]—> https://bugzilla.mozilla.org/static/v20240305.1/js/jquery/jquery-min.js:2:40177 - λ handlers
+
+(`:trace --logMethod stdout`)
+
+.. |image2| image:: console-trace.png
+  :class: border
+
+Delayed start
+-------------
+
+There is two ways to delay the actual start of the JS Tracer.
+Both require to request the tracer to start by clicking on the debugger tracer icon, or run the `:trace` console command, or trigger the key shortcut.
+The Tracer will then be in pending mode, which is indicated via a blue badge on the tracer icon. |image3|
+
+ * on next user interaction
+
+   The tracer will only really start logging function calls when the first clicking or pressing a key on the page.
+   To be precise, the tracer will start on first mousdown or keydown event.
+
+   (`:trace --on-next-interaction`)
+
+ * on next page load
+
+   The tracer will only really start when navigating to another page or reloading the current page.
+   It will start just before anything starts being executed.
+   It help see the very first JavaScript code running on the page.
+
+   (Note that this feature is not available via the console command.)
+
+.. |image3| image:: pending-icon.png
+  :class: border
+
+Tracing function returns
+------------------------
+
+You may optionally log function returns, i.e. the precise execution ordering when a function ends and returns.
+This is disabled by default as it doubles the output of the tracer.
+
+.. image:: trace-returns.png
+
+(`:trace --returns`)
+
+Tracing values
+--------------
+
+You may optionally display all function call arguments as well as function return values (if enabled).
+This is disabled by default as it complexify the output of the tracer, making it slower and less readable.
+
+.. image:: trace-returns-with-values.png
+
+.. image:: trace-values.png
+
+(`:trace --values`)
+
+
+Web Console Command only options
+--------------------------------
+
+ * Log DOM Mutations
+
+You may optionally trace all DOM Mutations happening on the page.
+The mutation will appear according to their precise execution order versus JavaScript code modifying the DOM (JS Traces),
+but also errors, warnings and console API logs.
+By default, the console command argument `--dom-mutations` will record all types of mutations: new nodes being added to the document,
+attributes changed on a node and node being removed from the document.
+The argument also accept a coma separated list of options to control which type of mutation should be logged.
+
+(`:trace --dom-mutations` === `:trace --dom-mutations add,attributes,remove`)
+
+ * Depth limit
+
+You may optionally limit the depth of function calls being logged.
+For example, limiting the depth to "1" will typically only log the event listener function. i.e. the top level function being called by the Web Engine.
+This allows to drastically reduce the output of the trace, but may hide precious information.
+The tracer will not be automatically stopped by this option. This will only ignore nested function calls passed the given depth limit.
+
+For example, while :trace without any argument would log the following on bugzilla:
+
+.. code-block:: bash
+
+  —DOM | mousedown
+  —[interpreter]—> https://bugzilla.mozilla.org/static/v20240305.1/js/jquery/jquery-min.js:2:37892 - λ add/v.handle
+  ——[baseline]—> https://bugzilla.mozilla.org/static/v20240305.1/js/jquery/jquery-min.js:2:39398 - λ dispatch
+  ———[interpreter]—> https://bugzilla.mozilla.org/static/v20240305.1/js/jquery/jquery-min.js:2:40960 - λ fix
+  ————[interpreter]—> https://bugzilla.mozilla.org/static/v20240305.1/js/jquery/jquery-min.js:2:41576 - λ ce.Event
+  ———[interpreter]—> https://bugzilla.mozilla.org/static/v20240305.1/js/jquery/jquery-min.js:2:30171 - λ get
+  ————[interpreter]—> https://bugzilla.mozilla.org/static/v20240305.1/js/jquery/jquery-min.js:2:29696 - λ F
+  ———[interpreter]—> https://bugzilla.mozilla.org/static/v20240305.1/js/jquery/jquery-min.js:2:40177 - λ handlers
+  —DOM | mouseup
+  —[interpreter]—> https://bugzilla.mozilla.org/static/v20240305.1/js/jquery/jquery-min.js:2:37892 - λ add/v.handle
+  ——[baseline]—> https://bugzilla.mozilla.org/static/v20240305.1/js/jquery/jquery-min.js:2:39398 - λ dispatch
+  ———[interpreter]—> https://bugzilla.mozilla.org/static/v20240305.1/js/jquery/jquery-min.js:2:40960 - λ fix
+  ————[interpreter]—> https://bugzilla.mozilla.org/static/v20240305.1/js/jquery/jquery-min.js:2:41576 - λ ce.Event
+  ———[interpreter]—> https://bugzilla.mozilla.org/static/v20240305.1/js/jquery/jquery-min.js:2:30171 - λ get
+  ————[interpreter]—> https://bugzilla.mozilla.org/static/v20240305.1/js/jquery/jquery-min.js:2:29696 - λ F
+  ———[interpreter]—> https://bugzilla.mozilla.org/static/v20240305.1/js/jquery/jquery-min.js:2:40177 - λ handlers
+
+running `:trace --max-depth 1` will give us:
+
+.. code-block:: bash
+
+  —DOM | mousedown
+  —[interpreter]—> https://bugzilla.mozilla.org/static/v20240305.1/js/jquery/jquery-min.js:2:37892 - λ add/v.handle
+  —DOM | mouseup
+  —[interpreter]—> https://bugzilla.mozilla.org/static/v20240305.1/js/jquery/jquery-min.js:2:37892 - λ add/
+
+and running `:trace --max-depth 3` will give us:
+
+.. code-block:: bash
+
+  —DOM | mousedown
+  —[interpreter]—> https://bugzilla.mozilla.org/static/v20240305.1/js/jquery/jquery-min.js:2:37892 - λ add/v.handle
+  ——[baseline]—> https://bugzilla.mozilla.org/static/v20240305.1/js/jquery/jquery-min.js:2:39398 - λ dispatch
+  ———[interpreter]—> https://bugzilla.mozilla.org/static/v20240305.1/js/jquery/jquery-min.js:2:40960 - λ fix
+  ———[interpreter]—> https://bugzilla.mozilla.org/static/v20240305.1/js/jquery/jquery-min.js:2:30171 - λ get
+  ———[interpreter]—> https://bugzilla.mozilla.org/static/v20240305.1/js/jquery/jquery-min.js:2:40177 - λ handlers
+  —DOM | mouseup
+  —[interpreter]—> https://bugzilla.mozilla.org/static/v20240305.1/js/jquery/jquery-min.js:2:37892 - λ add/v.handle
+  ——[baseline]—> https://bugzilla.mozilla.org/static/v20240305.1/js/jquery/jquery-min.js:2:39398 - λ dispatch
+  ———[interpreter]—> https://bugzilla.mozilla.org/static/v20240305.1/js/jquery/jquery-min.js:2:40960 - λ fix
+  ———[interpreter]—> https://bugzilla.mozilla.org/static/v20240305.1/js/jquery/jquery-min.js:2:30171 - λ get
+  ———[interpreter]—> https://bugzilla.mozilla.org/static/v20240305.1/js/jquery/jquery-min.js:2:40177 - λ handlers
+
+(`:trace --max-depth 5`)
+
+ * Record limit
+
+You may optionally limit the number of "records" being logged, after which the tracer will be automatically stopped.
+A record is composed of one top level function call, including all its nested function being called from this top level one.
+
+This option can be especially useful in combination to tracer on next user interaction.
+This can help narrow down to a very precise code acting only on a mouse or key event processing.
+
+(`:trace --max-records 10`)
diff --git a/devtools/docs/user/javascript_tracer/pending-icon.png b/devtools/docs/user/javascript_tracer/pending-icon.png
new file mode 100644
index 0000000000..1941a7210a
Binary files /dev/null and b/devtools/docs/user/javascript_tracer/pending-icon.png differ
diff --git a/devtools/docs/user/javascript_tracer/trace-icon.svg b/devtools/docs/user/javascript_tracer/trace-icon.svg
new file mode 100644
index 0000000000..172f7b6c30
--- /dev/null
+++ b/devtools/docs/user/javascript_tracer/trace-icon.svg
@@ -0,0 +1,6 @@
+<!-- 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 width="16" height="16" viewBox="0 0 16 16" xmlns="http://www.w3.org/2000/svg">
+<path fill="context-fill" fill-rule="evenodd" clip-rule="evenodd" d="M7.99873 15C11.8647 15 14.9987 11.866 14.9987 8C14.9987 4.13401 11.8647 1 7.99873 1C4.13273 1 0.998726 4.13401 0.998726 8C0.998726 11.866 4.13273 15 7.99873 15ZM7.99872 1.75C8.41294 1.75 8.74872 2.08579 8.74872 2.5V8.5C8.74872 8.72784 8.64516 8.94332 8.46725 9.08565L5.96725 11.0857C5.6438 11.3444 5.17183 11.292 4.91307 10.9685C4.65432 10.6451 4.70676 10.1731 5.0302 9.91435L7.24872 8.13953V2.5C7.24872 2.08579 7.58451 1.75 7.99872 1.75ZM5.49873 2.75C5.91294 2.75 6.24873 3.08579 6.24873 3.5V7C6.24873 7.22784 6.14516 7.44332 5.96725 7.58565L3.46725 9.58565C3.1438 9.84441 2.67183 9.79197 2.41307 9.46852C2.15432 9.14507 2.20676 8.67311 2.5302 8.41435L4.74873 6.63953V3.5C4.74873 3.08579 5.08451 2.75 5.49873 2.75ZM11.25 9C11.25 8.58579 10.9142 8.25 10.5 8.25C10.0858 8.25 9.75 8.58579 9.75 9V12C9.75 12.4142 10.0858 12.75 10.5 12.75C10.9142 12.75 11.25 12.4142 11.25 12V9ZM8.74872 11.5C8.74873 11.0858 8.41294 10.75 7.99873 10.75C7.58451 10.75 7.24873 11.0858 7.24872 11.5V13C7.24872 13.4142 7.58451 13.75 7.99872 13.75C8.41294 13.75 8.74872 13.4142 8.74872 13V11.5ZM11.2487 3.5C11.2487 3.08579 10.9129 2.75 10.4987 2.75C10.0845 2.75 9.74873 3.08579 9.74873 3.5V6C9.74873 6.22784 9.8523 6.44332 10.0302 6.58565L12.2487 8.36047V10C12.2487 10.4142 12.5845 10.75 12.9987 10.75C13.4129 10.75 13.7487 10.4142 13.7487 10V8C13.7487 7.77216 13.6452 7.55668 13.4672 7.41435L11.2487 5.63953V3.5Z"/>
+</svg>
diff --git a/devtools/docs/user/javascript_tracer/trace-returns-with-values.png b/devtools/docs/user/javascript_tracer/trace-returns-with-values.png
new file mode 100644
index 0000000000..f6c3fcf3ff
Binary files /dev/null and b/devtools/docs/user/javascript_tracer/trace-returns-with-values.png differ
diff --git a/devtools/docs/user/javascript_tracer/trace-returns.png b/devtools/docs/user/javascript_tracer/trace-returns.png
new file mode 100644
index 0000000000..cb03e8844b
Binary files /dev/null and b/devtools/docs/user/javascript_tracer/trace-returns.png differ
diff --git a/devtools/docs/user/javascript_tracer/trace-values.png b/devtools/docs/user/javascript_tracer/trace-values.png
new file mode 100644
index 0000000000..fd63224605
Binary files /dev/null and b/devtools/docs/user/javascript_tracer/trace-values.png differ
-- 
cgit v1.2.3