commit 621b1c494173bd4af08cbf55a0b3248bc56e0fcc
parent 4ce73f1fabb1a60144986567300507d2dd247e8a
Author: Florian Quèze <florian@queze.net>
Date: Tue, 21 Oct 2025 08:42:46 +0000
Bug 1995058 - document requesttimeoutfactor in the xpcshell test documentation, r=jmaher,Standard8.
Differential Revision: https://phabricator.services.mozilla.com/D269193
Diffstat:
1 file changed, 39 insertions(+), 0 deletions(-)
diff --git a/testing/docs/xpcshell/index.rst b/testing/docs/xpcshell/index.rst
@@ -318,6 +318,45 @@ listed under the ``[DEFAULT]`` section of the manifest.
``[test_*]``
Test file names must start with ``test_`` and are listed in square
brackets
+``requesttimeoutfactor``
+ A multiplier applied to the default test timeout. The default timeout for
+ xpcshell tests is 30 seconds. Setting ``requesttimeoutfactor = 2`` will
+ increase the timeout to 60 seconds (30 × 2). This can be set either at the
+ manifest level (under ``[DEFAULT]``) to apply to all tests, or on individual
+ test entries to apply only to specific tests.
+
+ **Important:** Slower platforms (such as Android, debug builds, TSan, ASan) already
+ have platform-wide timeout factors defined in ``taskcluster/kinds/test/xpcshell.yml``
+ that apply to all tests running on those platforms. These platform factors are
+ multiplied with any manifest-level or test-level factors you specify. Therefore,
+ you should **not** set ``requesttimeoutfactor`` in manifests simply because a
+ platform is generally slower—only use it when a specific test needs extra time
+ beyond what the platform factor already provides.
+
+ This should be used when tests legitimately require more time due to:
+
+ - Specific tests being disproportionately slower on certain platforms (beyond the general platform slowness)
+ - Complex operations that take longer than the default timeout (e.g., large database operations, extensive network tests)
+ - Tests that run multiple time-consuming operations sequentially
+
+ You should **not** use this for tests that are slow due to inefficient test code
+ or unnecessary waits. Consider profiling and refactoring such tests instead.
+
+ Example usage in a manifest:
+
+ .. code:: toml
+
+ [DEFAULT]
+ # Apply a 2x timeout factor to all tests in this manifest
+ requesttimeoutfactor = 2
+
+ ["test_slow_on_windows.js"]
+ # This test needs 3x timeout (90 seconds) on Windows
+ requesttimeoutfactor = 3 # Slow on Windows
+
+ When a test-level factor is specified, it replaces (not multiplies) the manifest-level
+ factor. For example, if the manifest has ``requesttimeoutfactor = 2`` and a test has
+ ``requesttimeoutfactor = 3``, the test will use a 3x factor, not 6x.
Creating a new xpcshell.toml file
