commit 62c12522bc6edd6fa334ab7b86017bae57257d25
parent 725e64c6c936486a471e3e5f32134a0e6b8df13a
Author: Masayuki Nakano <masayuki@d-toybox.com>
Date: Fri, 17 Oct 2025 02:49:24 +0000
Bug 1994353 - Add a guide to log native keyboard and IME event handler behavior r=m_kato,dom-core,smaug
When a bug reporter uses 3rd party's IME or keyboard layout, it's the
fastest/simplest/safest way to investigate the behavior to request the
reporter to attach a log file of our native keyboard and IME event
handler which can be logged with setting `MOZ_LOG` to
`KeyboardHandler:4,IMEHandler:4`. However, explaining the steps requires
not short text and the tester should know the privacy risk about posting
the log file. Therefore, there should be an official document how to
get logging the behavior.
Differential Revision: https://phabricator.services.mozilla.com/D268657
Diffstat:
2 files changed, 95 insertions(+), 0 deletions(-)
diff --git a/dom/docs/index.rst b/dom/docs/index.rst
@@ -17,3 +17,4 @@ These linked pages contain design documents for the DOM implementation in Gecko.
fedcm
streams
use-counters
+ loggingKeyboardIME
diff --git a/dom/docs/loggingKeyboardIME.rst b/dom/docs/loggingKeyboardIME.rst
@@ -0,0 +1,94 @@
+Logging native keyboard and IME event handler behavior
+======================================================
+
+If you're using 3rd party's IME or keyboard layout and you reported a bug which is reproducible with the IME or keyboard layout,
+you may be requested to attach a log file of that how Firefox/Gecko handled the native events coming from your IME or keyboard layout.
+
+Steps to log the behavior
++++++++++++++++++++++++++
+1-1. Logging from startup
+-------------------------
+If you or contributors in bugzilla request the IME information (mainly on Linux),
+you need to enable the logging at launching Firefox. You need to set 2 environment variables,
+one is ``MOZ_LOG``, set it to ``KeyboardHandler:4,IMEHandler:4,sync``, the other is ``MOZ_LOG_FILE``,
+set it to a full path to a logging file. With or after setting the environment variables,
+launch Firefox normally.
+
+If you need to reproduce the bug in a specific web site,
+you should open the tab and make Firefox restore the tab before doing the following steps.
+
+Ensure Firefox is completely closed, first.
+
+If you use Windows, you can set the environment variables with GUI.
+However, launching with terminal or commandline is simpler
+(replace ``<username>`` with your home folder/directory name):
+
+Windows (command prompt):
+
+::
+
+ set MOZ_LOG=KeyboardHandler:4,IMEHandler:4,sync
+ set MOZ_LOG_FILE=C:\Users\<username>\firefox-log
+ start firefox
+
+Windows (PowerShell):
+
+::
+
+ $env:MOZ_LOG = "KeyboardHandler:4,IMEHandler:4,sync"
+ $env:MOZ_LOG_FILE = "C:\Users\<username>\firefox-log"
+ Start-Process firefox
+
+macOS:
+
+::
+
+ MOZ_LOG=KeyboardHandler:4,IMEHandler:4,sync MOZ_LOG_FILE=/Users/<username>/firefox-log /Applications/Firefox.app/Contents/MacOS/firefox
+
+Note: Replace ``Firefox.app`` with ``Firefox\ Beta.app`` or ``Firefox\ Nightly.app`` if you use beta or nightly build.
+
+Linux:
+
+::
+
+ MOZ_LOG=KeyboardHandler:4,IMEHandler:4,sync MOZ_LOG_FILE=/home/<username>/firefox-log firefox
+
+1-2. Logging only during a test
+-------------------------------
+If you don't need the IME information which is logged only at startup,
+you can use ``about:logging``.
+
+1. Prepare to do the simplest steps to reproduce, e.g., open a simple test case into a tab.
+2. Open ``about:logging`` in a new tab.
+3. Set "New log modules" field to ``KeyboardHandler:4,IMEHandler:4,sync`` and type ``Enter`` key.
+4. Choose "Logging to a file" radio button below.
+5. Set "New log file" field to a full path for log file (see ``MOZ_LOG_FILE`` value of above examples in 1-1) and type ``Enter`` key.
+6. Then, **click** "Start Logging" button above.
+
+2. Reproduce the bug
+--------------------
+Then, your all inputs via keyboard is now being logged.
+
+Give focus to somewhere if you need with **mouse** and reproduce the bug with the minimum steps.
+
+Note: Keyboard operation for preparing to reproduce the bug is also logged and that makes harder to read.
+Therefore, keyboard should be used only when you reproduce the bug.
+
+Warning: In order to avoid leaking private information, do **NOT** do the following kindes of things while testing:
+
+- Typing private things like email address, passwords, etc.
+- Move focus to password fields whose value is already filled by the web site or the password manager.
+- Move focus to the URL bar if the URL contains private things like account name, session ID, etc.
+
+3. Close the Firefox instance
+-----------------------------
+Then, close Firefox with **mouse**.
+
+4. Attach the log file to the bug
+---------------------------------
+Now, you should find ``firefox-log-main.<process-id>.moz_log`` file which is not empty.
+This file is what the developers want.
+Let's attach the file to the bug with clicking "Attach New File" button in bugzilla.
+
+For making the log file easier to read,
+explaining what you typed during the test within the comment field is really helpful.
