1 files changed, 39 insertions, 0 deletions
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
+```