From 2a839720d0f586bfd5525dcd2536b972415ea9e5 Mon Sep 17 00:00:00 2001
From: LaTranquillum <a01023796849@gmail.com>
Date: Sat, 19 Sep 2026 17:58:32 +0200
Subject: [PATCH 1/2] Document parametrization requirements with pytest-xdist

---
 doc/en/how-to/parametrize.rst | 41 +++++++++++++++++++++++++++++++++++
 1 file changed, 41 insertions(+)

diff --git a/doc/en/how-to/parametrize.rst b/doc/en/how-to/parametrize.rst
index 5de28472705..b95f9b0a3c5 100644
--- a/doc/en/how-to/parametrize.rst
+++ b/doc/en/how-to/parametrize.rst
@@ -209,6 +209,47 @@ This will run the test with the arguments set to ``x=0/y=2``, ``x=1/y=2``,
 ``x=0/y=3``, and ``x=1/y=3`` exhausting parameters in the order of the decorators.
 
 
+.. _parametrize-xdist:
+
+Parametrization with pytest-xdist
+---------------------------------
+
+When running tests in parallel with :pypi:`pytest-xdist`, each worker collects
+its own tests. All workers must collect the same test IDs in the same order.
+Otherwise, pytest-xdist stops with an error such as
+``Different tests were collected between gw0 and gw1``.
+
+Unordered parameter values can cause workers to collect tests in different
+orders. For example, avoid passing a set directly to ``parametrize``. Use a
+list with a fixed order, or sort the values when they support ordering:
+
+.. code-block:: python
+
+    import pytest
+
+
+    @pytest.mark.parametrize("value", sorted({"alpha", "beta"}))
+    def test_value(value):
+        assert value.isalpha()
+
+Converting a set to a list without sorting does not make its order consistent
+across workers.
+
+Values generated during collection can also differ between workers. For
+example, a timestamp from ``datetime.now().isoformat()`` used as a parameter
+will usually produce different test IDs in different processes. Prefer fixed
+parameter values. If a test needs the current time, obtain it in a fixture or
+in the test body instead of using it to generate parameters during collection.
+
+Explicit parameter IDs can make IDs stable, but do not ensure that workers
+use the same parameter values or order. Keep the association between each ID
+and its test case consistent across workers as well.
+
+See the `pytest-xdist collection limitations
+<https://pytest-xdist.readthedocs.io/en/stable/known-limitations.html#order-and-amount-of-test-must-be-consistent>`_
+for more information.
+
+
 .. _`pytest_generate_tests`:
 
 Basic ``pytest_generate_tests`` example

From c1e89b0829ac744f921629e6f8ea26323a03acf4 Mon Sep 17 00:00:00 2001
From: LaTranquillum <a01023796849@gmail.com>
Date: Sat, 19 Sep 2026 17:59:39 +0200
Subject: [PATCH 2/2] Create 4101.doc.rst

---
 changelog/4101.doc.rst | 1 +
 1 file changed, 1 insertion(+)
 create mode 100644 changelog/4101.doc.rst

diff --git a/changelog/4101.doc.rst b/changelog/4101.doc.rst
new file mode 100644
index 00000000000..bd8ff915500
--- /dev/null
+++ b/changelog/4101.doc.rst
@@ -0,0 +1 @@
+Documented :ref:`parametrization with pytest-xdist <parametrize-xdist>`, including inconsistent collection order and dynamically generated test IDs.