2 files changed, 52 insertions, 5 deletions

diff --git a/devtools/server/actors/webconsole/commands/experimental-commands.ftl b/devtools/server/actors/webconsole/commands/experimental-commands.ftl
index b11c29006b..66cb9d151e 100644
--- a/devtools/server/actors/webconsole/commands/experimental-commands.ftl
+++ b/devtools/server/actors/webconsole/commands/experimental-commands.ftl
@@ -9,13 +9,29 @@
 webconsole-commands-usage-trace3 =
   :trace
 
-  Toggles the JavaScript tracer
+  Toggles the JavaScript tracer.
+
+  The tracer will display all functions being called by your page.
 
     It supports the following arguments:
-      --logMethod to be set to ‘console’ for logging to the web console (the default), or ‘stdout’ for logging to the standard output,
+      --logMethod to be set to ‘console’ for logging to the web console (the default), or ‘stdout’ for logging to the standard output.
+
+      --return Optional flag to be passed to also log when functions return.
+
       --values Optional flag to be passed to log function call arguments as well as returned values (when returned frames are enabled).
+
       --on-next-interaction Optional flag, when set, the tracer will only start on next mousedown or keydown event.
+
+      --dom-mutations Optional flag, when set, the tracer will log all DOM Mutations.
+                      When passing a value, you can restrict to a particular mutation type via a coma-separated list:
+                       - ‘add’ will only track DOM Node being added,
+                       - ‘attributes’ will only track DOM Node whose attributes changed,
+                       - ‘remove’ will only track DOM Node being removed.
+
       --max-depth Optional flag, will restrict logging trace to a given depth passed as argument.
+
       --max-records Optional flag, will automatically stop the tracer after having logged the passed amount of top level frames.
-      --prefix Optional string which will be logged in front of all the trace logs,
+
+      --prefix Optional string which will be logged in front of all the trace logs.
+
       --help or --usage to show this message.
diff --git a/devtools/server/actors/webconsole/commands/manager.js b/devtools/server/actors/webconsole/commands/manager.js
index 538ee7eac1..025e197e3b 100644
--- a/devtools/server/actors/webconsole/commands/manager.js
+++ b/devtools/server/actors/webconsole/commands/manager.js
@@ -11,6 +11,13 @@ loader.lazyRequireGetter(
   true
 );
 
+loader.lazyRequireGetter(
+  this,
+  ["DOM_MUTATIONS"],
+  "resource://devtools/server/tracer/tracer.jsm",
+  true
+);
+
 loader.lazyGetter(this, "l10n", () => {
   return new Localization(
     [
@@ -88,7 +95,7 @@ const WebConsoleCommandsManager = {
    *     }
    *   });
    */
-  register({ name, isSideEffectFree, command, validArguments, usage }) {
+  register({ name, isSideEffectFree, command, validArguments }) {
     if (
       typeof command != "function" &&
       !(typeof command == "object" && typeof command.get == "function")
@@ -684,7 +691,7 @@ WebConsoleCommandsManager.register({
 WebConsoleCommandsManager.register({
   name: "help",
   isSideEffectFree: false,
-  command(owner, args) {
+  command(owner) {
     owner.helperResult = { type: "help" };
   },
 });
@@ -873,13 +880,35 @@ WebConsoleCommandsManager.register({
     const tracerActor =
       owner.consoleActor.parentActor.getTargetScopedActor("tracer");
     const logMethod = args.logMethod || "console";
+    let traceDOMMutations = null;
+    if ("dom-mutations" in args) {
+      // When no value is passed, track all types of mutations
+      if (args["dom-mutations"] === true) {
+        traceDOMMutations = ["add", "attributes", "remove"];
+      } else if (typeof args["dom-mutations"] == "string") {
+        // Otherwise consider the value as coma seperated list and remove any white space.
+        traceDOMMutations = args["dom-mutations"].split(",").map(e => e.trim());
+        const acceptedValues = Object.values(DOM_MUTATIONS);
+        if (!traceDOMMutations.every(e => acceptedValues.includes(e))) {
+          throw new Error(
+            `:trace --dom-mutations only accept a list of strings whose values can be: ${acceptedValues}`
+          );
+        }
+      } else {
+        throw new Error(
+          ":trace --dom-mutations accept only no arguments, or a list mutation type strings (add,attributes,remove)"
+        );
+      }
+    }
     // Note that toggleTracing does some sanity checks and will throw meaningful error
     // when the arguments are wrong.
     const enabled = tracerActor.toggleTracing({
       logMethod,
       prefix: args.prefix || null,
+      traceFunctionReturn: !!args.returns,
       traceValues: !!args.values,
       traceOnNextInteraction: args["on-next-interaction"] || null,
+      traceDOMMutations,
       maxDepth: args["max-depth"] || null,
       maxRecords: args["max-records"] || null,
     });
@@ -895,7 +924,9 @@ WebConsoleCommandsManager.register({
     "max-depth",
     "max-records",
     "on-next-interaction",
+    "dom-mutations",
     "prefix",
+    "returns",
     "values",
   ],
 });