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