gotcha

for more information, see https://pre-commit.ci

.github/workflows/deploy.yml

@@ -19,7 +19,7 @@ jobs:
     - uses: actions/checkout@v4
 
     - name: Build and Check Package
-      uses: hynek/build-and-inspect-python-package@v2.2
+      uses: hynek/build-and-inspect-python-package@v2.13
 
   deploy:
     needs: package
@@ -39,7 +39,9 @@ jobs:
         path: dist
 
     - name: Publish package to PyPI
-      uses: pypa/gh-action-pypi-publish@v1.8.14
+      uses: pypa/gh-action-pypi-publish@v1.12.4
+      with:
+        attestations: true
 
     - name: Push tag
       run: |

.github/workflows/test.yml

@@ -22,7 +22,7 @@ jobs:
     steps:
     - uses: actions/checkout@v4
     - name: Build and Check Package
-      uses: hynek/build-and-inspect-python-package@v2.2
+      uses: hynek/build-and-inspect-python-package@v2.13
 
   test:
 
@@ -34,22 +34,20 @@ jobs:
       fail-fast: false
       matrix:
         tox_env:
-          - "py38-pytestmin"
+          - "py39-pytestmin"
-          - "py38-pytestlatest"
           - "py39-pytestlatest"
           - "py310-pytestlatest"
           - "py311-pytestlatest"
           - "py311-pytestmain"
           - "py312-pytestlatest"
+          - "py313-pytestlatest"
           - "py310-psutil"
           - "py310-setproctitle"
 
         os: [ubuntu-latest, windows-latest]
         include:
-          - tox_env: "py38-pytestmin"
+          - tox_env: "py39-pytestmin"
-            python: "3.8"
+            python: "3.9"
-          - tox_env: "py38-pytestlatest"
-            python: "3.8"
           - tox_env: "py39-pytestlatest"
             python: "3.9"
           - tox_env: "py310-pytestlatest"
@@ -60,6 +58,8 @@ jobs:
             python: "3.11"
           - tox_env: "py312-pytestlatest"
             python: "3.12"
+          - tox_env: "py313-pytestlatest"
+            python: "3.13"
           - tox_env: "py310-psutil"
             python: "3.10"
           - tox_env: "py310-setproctitle"

.pre-commit-config.yaml

@@ -1,17 +1,17 @@
 repos:
 - repo: https://github.com/astral-sh/ruff-pre-commit
-  rev: "v0.3.7"
+  rev: "v0.12.3"
   hooks:
     - id: ruff
       args: ["--fix"]
     - id: ruff-format
 -   repo: https://github.com/asottile/blacken-docs
-    rev: 1.16.0
+    rev: 1.19.1
     hooks:
     -   id: blacken-docs
         additional_dependencies: [black==23.1.0]
 -   repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.6.0
+    rev: v5.0.0
     hooks:
     -   id: check-yaml
 -   repo: local
@@ -23,7 +23,7 @@ repos:
         language: python
         additional_dependencies: [pygments, restructuredtext_lint]
 -   repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v1.9.0
+    rev: v1.16.1
     hooks:
     -   id: mypy
         files: ^(src/|testing/)

CHANGELOG.rst

@@ -1,6 +1,63 @@
+pytest-xdist 3.8.0 (2025-06-30)
+===============================
+
+Features
+--------
+
+- `#1083 <https://github.com/pytest-dev/pytest-xdist/issues/1083>`_: Add ``--no-loadscope-reorder`` and ``--loadscope-reorder`` option to control whether to automatically reorder tests in loadscope for tests where relative ordering matters. This only applies when using ``loadscope``. 
+
+  For example, [test_file_1, test_file_2, ..., test_file_n] are given as input test files, if ``--no-loadscope-reorder`` is used, for either worker, the ``test_file_a`` will be executed before ``test_file_b`` only if ``a < b``.
+
+  The default behavior is to reorder the tests to maximize the number of tests that can be executed in parallel.
+
+pytest-xdist 3.7.0 (2025-05-26)
+===============================
+
+Features
+--------
+
+- `#1142 <https://github.com/pytest-dev/pytest-xdist/issues/1142>`_: Added support for Python 3.13.
+
+- `#1144 <https://github.com/pytest-dev/pytest-xdist/issues/1144>`_: The internal `steal` command is now atomic - it unschedules either all requested tests or none.
+
+  This is a prerequisite for group/scope support in the `worksteal` scheduler, so test groups won't be broken up incorrectly.
+
+- `#1170 <https://github.com/pytest-dev/pytest-xdist/issues/1170>`_: Add the `--px` arg to create proxy gateways.
+
+  Proxy gateways are passed to additional gateways using the `via` keyword.
+  They can serve as a way to run multiple workers on remote machines.
+
+- `#1200 <https://github.com/pytest-dev/pytest-xdist/issues/1200>`_: Now multiple ``xdist_group`` markers are considered when assigning tests to groups (order does not matter).
+
+  Previously, only the last marker would assign a test to a group, but now if a test has multiple ``xdist_group`` marks applied (for example via parametrization or via fixtures), they are merged to make a new group.
+
+
+Removals
+--------
+
+- `#1162 <https://github.com/pytest-dev/pytest-xdist/issues/1162>`_: Dropped support for EOL Python 3.8.
+
+
+Trivial Changes
+---------------
+
+- `#1092 <https://github.com/pytest-dev/pytest-xdist/issues/1092>`_: Update an error message to better indicate where users should go for more information.
+
+- `#1190 <https://github.com/pytest-dev/pytest-xdist/issues/1190>`_: Switched to using a SPDX license identifier introduced in PEP 639.
+
+pytest-xdist 3.6.1 (2024-04-28)
+===============================
+
+Bug Fixes
+---------
+
+- `#1071 <https://github.com/pytest-dev/pytest-xdist/issues/1071>`_: Add backward compatibility for deadlock issue with the ``execnet`` new ``main_thread_only`` "execmodel" triggered when pytest-cov accesses rinfo.
+
 pytest-xdist 3.6.0 (2024-04-19)
 ===============================
 
+This release was YANKED due to a regression fixed in 3.6.1.
+
 Features
 --------
 

MANIFEST.in

@@ -1,5 +0,0 @@
-exclude .appveyor.yml
-exclude .gitignore
-exclude .pre-commit-config.yaml
-exclude .travis.yml
-prune .github

docs/distribution.rst

@@ -19,6 +19,8 @@ if it is not or if it fails to determine the number of logical CPUs, fall back t
 
 Pass a number, e.g. ``-n 8``, to specify the number of processes explicitly.
 
+Use ``-n 0`` to disable xdist and run all tests in the main process.
+
 To specify a different meaning for ``-n auto`` and ``-n logical`` for your
 tests, you can:
 
@@ -66,7 +68,10 @@ The test distribution algorithm is configured with the ``--dist`` command-line o
 
 * ``--dist loadgroup``: Tests are grouped by the ``xdist_group`` mark. Groups are
   distributed to available workers as whole units. This guarantees that all
-  tests with same ``xdist_group`` name run in the same worker.
+  tests with same ``xdist_group`` name run in the same worker. If a test has
+  multiple groups, they will be joined together into a new group,
+  the order of the marks doesn't matter. This works along with marks from fixtures
+  and from the pytestmark global variable.
 
   .. code-block:: python
 
@@ -81,6 +86,36 @@ The test distribution algorithm is configured with the ``--dist`` command-line o
               pass
 
   This will make sure ``test1`` and ``TestA::test2`` will run in the same worker.
+
+  .. code-block:: python
+
+      @pytest.fixture(
+          scope="session",
+          params=[
+              pytest.param(
+                  "chrome",
+                  marks=pytest.mark.xdist_group("chrome"),
+              ),
+              pytest.param(
+                  "firefox",
+                  marks=pytest.mark.xdist_group("firefox"),
+              ),
+              pytest.param(
+                  "edge",
+                  marks=pytest.mark.xdist_group("edge"),
+              ),
+          ],
+      )
+      def setup_container():
+          pass
+
+
+      @pytest.mark.xdist_group(name="data-store")
+      def test_data_store(setup_container):
+          ...
+
+  This will generate 3 new groups: ``chrome_data-store``, ``data-store_firefox`` and ``data-store_edge`` (the markers are lexically sorted before being merged together).
+
   Tests without the ``xdist_group`` mark are distributed normally as in the ``--dist=load`` mode.
 
 * ``--dist worksteal``: Initially, tests are distributed evenly among all

docs/remote.rst

@@ -66,6 +66,20 @@ new socket host with something like this::
     pytest -d --tx socket=192.168.1.102:8888 --rsyncdir mypkg
 
 
+Using proxies to run multiple workers on remote machines
+---------------------------------------
+
+In case you want to run multiple workers on a remote machine,
+you can create a proxy gateway for the machine, and run multiple
+workers using the `via` attribute.::
+
+    pytest -d --px id=my_proxy//socket=192.168.1.102:8888 --tx 5*popen//via=my_proxy
+
+Here we declare a proxy gateway using the `--px` arg, and
+create 5 workers that run on the remote server using the proxy.
+Note that the proxy gateway does not run a worker, thus only 5
+workers are created.
+
 
 Running tests on many platforms at once
 ---------------------------------------

pyproject.toml

@@ -1,6 +1,6 @@
 [build-system]
 requires = [
-  "setuptools>=61.2",
+  "setuptools>=77.0",
   "setuptools-scm[toml]>=6.2.3",
 ]
 build-backend = "setuptools.build_meta"
@@ -9,13 +9,12 @@ build-backend = "setuptools.build_meta"
 name = "pytest-xdist"
 description = "pytest xdist plugin for distributed testing, most importantly across multiple CPUs"
 readme = "README.rst"
-license = {file="LICENSE"}
+license = "MIT"
 authors = [{name = "holger krekel and contributors", email = "pytest-dev@python.org"}, {email = "holger@merlinux.eu"}]
 classifiers = [
     "Development Status :: 5 - Production/Stable",
     "Framework :: Pytest",
     "Intended Audience :: Developers",
-    "License :: OSI Approved :: MIT License",
     "Operating System :: POSIX",
     "Operating System :: Microsoft :: Windows",
     "Operating System :: MacOS :: MacOS X",
@@ -25,13 +24,13 @@ classifiers = [
     "Programming Language :: Python",
     "Programming Language :: Python :: 3",
     "Programming Language :: Python :: 3 :: Only",
-    "Programming Language :: Python :: 3.8",
     "Programming Language :: Python :: 3.9",
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
 ]
-requires-python = ">=3.8"
+requires-python = ">=3.9"
 dependencies = [
     "execnet>=2.1",
     "pytest>=7.0.0",
@@ -54,18 +53,15 @@ testing = ["filelock"]
 psutil = ["psutil>=3.0"]
 setproctitle = ["setproctitle"]
 
-[tool.setuptools]
-zip-safe = false
-platforms = [
-    "linux",
-    "osx",
-    "win32",
-]
-include-package-data = false
-
 [tool.setuptools_scm]
 write_to = "src/xdist/_version.py"
 
+[tool.pytest.ini_options]
+# pytest-services also defines a worker_id fixture, disable
+# it so they don't conflict with each other (#611).
+addopts = "-ra -p no:pytest-services"
+testpaths = ["testing"]
+
 [tool.ruff]
 src = ["src"]
 
@@ -115,6 +111,7 @@ ignore = [
     "PLW0120",  # remove the else and dedent its contents
     "PLW2901",  # for loop variable overwritten by assignment target
     "PLR5501",  # Use `elif` instead of `else` then `if`
+    "UP031",  # Use format specifiers instead of percent format
 ]
 
 [tool.ruff.lint.pycodestyle]

src/xdist/__init__.py

@@ -7,8 +7,8 @@ from xdist.plugin import is_xdist_worker
 
 __all__ = [
     "__version__",
-    "is_xdist_worker",
-    "is_xdist_master",
-    "is_xdist_controller",
     "get_xdist_worker_id",
+    "is_xdist_controller",
+    "is_xdist_master",
+    "is_xdist_worker",
 ]

src/xdist/_path.py

@@ -1,8 +1,8 @@
+from collections.abc import Iterator
 from itertools import chain
 import os
 from pathlib import Path
 from typing import Callable
-from typing import Iterator
 
 
 def visit_path(

src/xdist/dsession.py

@@ -1,12 +1,12 @@
 from __future__ import annotations
 
+from collections.abc import Sequence
 from enum import auto
 from enum import Enum
 from queue import Empty
 from queue import Queue
 import sys
 from typing import Any
-from typing import Sequence
 import warnings
 
 import execnet

src/xdist/looponfail.py

@@ -9,12 +9,12 @@ the controlling process which should best never happen.
 
 from __future__ import annotations
 
+from collections.abc import Sequence
 import os
 from pathlib import Path
 import sys
 import time
 from typing import Any
-from typing import Sequence
 
 from _pytest._io import TerminalWriter
 import execnet
@@ -166,7 +166,7 @@ def init_worker_session(
     import sys
 
     outchannel = channel.gateway.newchannel()
-    sys.stdout = sys.stderr = outchannel.makefile("w")  # type: ignore[assignment]
+    sys.stdout = sys.stderr = outchannel.makefile("w")
     channel.send(outchannel)
     # prune sys.path to not contain relative paths
     newpaths = []

src/xdist/newhooks.py

@@ -14,9 +14,9 @@ must be taken in plugins in case ``xdist`` is not installed. Please see:
 
 from __future__ import annotations
 
+from collections.abc import Sequence
 import os
 from typing import Any
-from typing import Sequence
 from typing import TYPE_CHECKING
 
 import execnet

src/xdist/plugin.py

@@ -127,6 +127,32 @@ def pytest_addoption(parser: pytest.Parser) -> None:
             "(default) no: Run tests inprocess, don't distribute."
         ),
     )
+    group.addoption(
+        "--loadscope-reorder",
+        dest="loadscopereorder",
+        action="store_true",
+        default=True,
+        help=(
+            "Pytest-xdist will default reorder tests by number of tests per scope "
+            "when used in conjunction with loadscope.\n"
+            "This option will enable loadscope reorder which will improve the "
+            "parallelism of the test suite.\n"
+            "However, the partial order of tests might not be retained.\n"
+        ),
+    )
+    group.addoption(
+        "--no-loadscope-reorder",
+        dest="loadscopereorder",
+        action="store_false",
+        help=(
+            "Pytest-xdist will default reorder tests by number of tests per scope "
+            "when used in conjunction with loadscope.\n"
+            "This option will disable loadscope reorder, "
+            "and the partial order of tests can be retained.\n"
+            "This is useful when pytest-xdist is used together with "
+            "other plugins that specify tests in a specific order."
+        ),
+    )
     group.addoption(
         "--tx",
         dest="tx",
@@ -139,6 +165,17 @@ def pytest_addoption(parser: pytest.Parser) -> None:
             "--tx ssh=user@codespeak.net//chdir=testcache"
         ),
     )
+    group.addoption(
+        "--px",
+        dest="px",
+        action="append",
+        default=[],
+        metavar="xspec",
+        help=(
+            "Add a proxy gateway to pass to test execution environments using `via`. Example:\n"
+            "--px id=my_proxy//socket=192.168.1.102:8888 --tx 5*popen//via=my_proxy"
+        ),
+    )
     group._addoption(
         "-d",
         action="store_true",

src/xdist/remote.py

@@ -8,16 +8,19 @@ needs not to be installed in remote environments.
 
 from __future__ import annotations
 
+import collections
+from collections.abc import Generator
+from collections.abc import Iterable
+from collections.abc import Sequence
 import contextlib
 import enum
 import os
 import sys
 import time
 from typing import Any
-from typing import Generator
 from typing import Literal
-from typing import Sequence
 from typing import TypedDict
+from typing import Union
 import warnings
 
 from _pytest.config import _prepareconfig
@@ -66,7 +69,44 @@ def worker_title(title: str) -> None:
 
 class Marker(enum.Enum):
     SHUTDOWN = 0
-    QUEUE_REPLACED = 1
+
+
+class TestQueue:
+    """A simple queue that can be inspected and modified while the lock is held via the ``lock()`` method."""
+
+    Item = Union[int, Literal[Marker.SHUTDOWN]]
+
+    def __init__(self, execmodel: execnet.gateway_base.ExecModel):
+        self._items: collections.deque[TestQueue.Item] = collections.deque()
+        self._lock = execmodel.RLock()  # type: ignore[no-untyped-call]
+        self._has_items_event = execmodel.Event()
+
+    def get(self) -> Item:
+        while True:
+            with self.lock() as locked_items:
+                if locked_items:
+                    return locked_items.popleft()
+
+            self._has_items_event.wait()
+
+    def put(self, item: Item) -> None:
+        with self.lock() as locked_items:
+            locked_items.append(item)
+
+    def replace(self, iterable: Iterable[Item]) -> None:
+        with self.lock():
+            self._items = collections.deque(iterable)
+
+    @contextlib.contextmanager
+    def lock(self) -> Generator[collections.deque[Item]]:
+        with self._lock:
+            try:
+                yield self._items
+            finally:
+                if self._items:
+                    self._has_items_event.set()
+                else:
+                    self._has_items_event.clear()
 
 
 class WorkerInteractor:
@@ -77,22 +117,10 @@ class WorkerInteractor:
         self.testrunuid = workerinput["testrunuid"]
         self.log = Producer(f"worker-{self.workerid}", enabled=config.option.debug)
         self.channel = channel
-        self.torun = self._make_queue()
+        self.torun = TestQueue(self.channel.gateway.execmodel)
         self.nextitem_index: int | None | Literal[Marker.SHUTDOWN] = None
         config.pluginmanager.register(self)
 
-    def _make_queue(self) -> Any:
-        return self.channel.gateway.execmodel.queue.Queue()
-
-    def _get_next_item_index(self) -> int | Literal[Marker.SHUTDOWN]:
-        """Gets the next item from test queue. Handles the case when the queue
-        is replaced concurrently in another thread.
-        """
-        result = self.torun.get()
-        while result is Marker.QUEUE_REPLACED:
-            result = self.torun.get()
-        return result  # type: ignore[no-any-return]
-
     def sendevent(self, name: str, **kwargs: object) -> None:
         self.log("sending", name, kwargs)
         self.channel.send((name, kwargs))
@@ -146,30 +174,34 @@ class WorkerInteractor:
             self.steal(kwargs["indices"])
 
     def steal(self, indices: Sequence[int]) -> None:
-        indices_set = set(indices)
+        """
-        stolen = []
+        Remove tests from the queue.
 
-        old_queue, self.torun = self.torun, self._make_queue()
+        Removes either all requested tests, or none, if some of these tests
+        are not in the queue (for example, if they were processed already).
 
-        def old_queue_get_nowait_noraise() -> int | None:
+        :param indices: indices of the tests to remove.
-            with contextlib.suppress(self.channel.gateway.execmodel.queue.Empty):
+        """
-                return old_queue.get_nowait()  # type: ignore[no-any-return]
+        requested_set = set(indices)
-            return None
 
-        for i in iter(old_queue_get_nowait_noraise, None):
+        with self.torun.lock() as locked_queue:
-            if i in indices_set:
+            stolen = list(item for item in locked_queue if item in requested_set)
-                stolen.append(i)
+
+            # Stealing only if all requested tests are still pending
+            if len(stolen) == len(requested_set):
+                self.torun.replace(
+                    item for item in locked_queue if item not in requested_set
+                )
             else:
-                self.torun.put(i)
+                stolen = []
 
         self.sendevent("unscheduled", indices=stolen)
-        old_queue.put(Marker.QUEUE_REPLACED)
 
     @pytest.hookimpl
     def pytest_runtestloop(self, session: pytest.Session) -> bool:
         self.log("entering main loop")
         self.channel.setcallback(self.handle_command, endmarker=Marker.SHUTDOWN)
-        self.nextitem_index = self._get_next_item_index()
+        self.nextitem_index = self.torun.get()
         while self.nextitem_index is not Marker.SHUTDOWN:
             self.run_one_test()
             if session.shouldfail or session.shouldstop:
@@ -179,7 +211,7 @@ class WorkerInteractor:
     def run_one_test(self) -> None:
         assert isinstance(self.nextitem_index, int)
         self.item_index = self.nextitem_index
-        self.nextitem_index = self._get_next_item_index()
+        self.nextitem_index = self.torun.get()
 
         items = self.session.items
         item = items[self.item_index]
@@ -209,15 +241,17 @@ class WorkerInteractor:
         # add the group name to nodeid as suffix if --dist=loadgroup
         if config.getvalue("loadgroup"):
             for item in items:
-                mark = item.get_closest_marker("xdist_group")
+                gnames: set[str] = set()
-                if not mark:
+                for mark in item.iter_markers("xdist_group"):
+                    name = (
+                        mark.args[0]
+                        if len(mark.args) > 0
+                        else mark.kwargs.get("name", "default")
+                    )
+                    gnames.add(str(name))
+                if not gnames:
                     continue
-                gname = (
+                item._nodeid = f"{item.nodeid}@{'_'.join(sorted(gnames))}"
-                    mark.args[0]
-                    if len(mark.args) > 0
-                    else mark.kwargs.get("name", "default")
-                )
-                item._nodeid = f"{item.nodeid}@{gname}"
 
     @pytest.hookimpl
     def pytest_collection_finish(self, session: pytest.Session) -> None:

src/xdist/report.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
+from collections.abc import Sequence
 from difflib import unified_diff
-from typing import Sequence
 
 
 def report_collection_diff(
@@ -23,7 +23,8 @@ def report_collection_diff(
         "Different tests were collected between {from_id} and {to_id}. "
         "The difference is:\n"
         "{diff}\n"
-        "To see why this happens see Known limitations in documentation"
+        "To see why this happens see 'Known limitations' in documentation "
+        "for pytest-xdist"
     ).format(from_id=from_id, to_id=to_id, diff="\n".join(diff))
     msg = "\n".join(x.rstrip() for x in error_message.split("\n"))
     return msg

src/xdist/scheduler/each.py

@@ -1,12 +1,12 @@
 from __future__ import annotations
 
-from typing import Sequence
+from collections.abc import Sequence
 
 import pytest
 
 from xdist.remote import Producer
 from xdist.report import report_collection_diff
-from xdist.workermanage import parse_spec_config
+from xdist.workermanage import parse_tx_spec_config
 from xdist.workermanage import WorkerController
 
 
@@ -26,7 +26,7 @@ class EachScheduling:
 
     def __init__(self, config: pytest.Config, log: Producer | None = None) -> None:
         self.config = config
-        self.numnodes = len(parse_spec_config(config))
+        self.numnodes = len(parse_tx_spec_config(config))
         self.node2collection: dict[WorkerController, list[str]] = {}
         self.node2pending: dict[WorkerController, list[int]] = {}
         self._started: list[WorkerController] = []

src/xdist/scheduler/load.py

@@ -1,13 +1,13 @@
 from __future__ import annotations
 
+from collections.abc import Sequence
 from itertools import cycle
-from typing import Sequence
 
 import pytest
 
 from xdist.remote import Producer
 from xdist.report import report_collection_diff
-from xdist.workermanage import parse_spec_config
+from xdist.workermanage import parse_tx_spec_config
 from xdist.workermanage import WorkerController
 
 
@@ -58,7 +58,7 @@ class LoadScheduling:
     """
 
     def __init__(self, config: pytest.Config, log: Producer | None = None) -> None:
-        self.numnodes = len(parse_spec_config(config))
+        self.numnodes = len(parse_tx_spec_config(config))
         self.node2collection: dict[WorkerController, list[str]] = {}
         self.node2pending: dict[WorkerController, list[int]] = {}
         self.pending: list[int] = []

src/xdist/scheduler/loadscope.py

@@ -1,14 +1,14 @@
 from __future__ import annotations
 
 from collections import OrderedDict
+from collections.abc import Sequence
 from typing import NoReturn
-from typing import Sequence
 
 import pytest
 
 from xdist.remote import Producer
 from xdist.report import report_collection_diff
-from xdist.workermanage import parse_spec_config
+from xdist.workermanage import parse_tx_spec_config
 from xdist.workermanage import WorkerController
 
 
@@ -91,7 +91,7 @@ class LoadScopeScheduling:
     """
 
     def __init__(self, config: pytest.Config, log: Producer | None = None) -> None:
-        self.numnodes = len(parse_spec_config(config))
+        self.numnodes = len(parse_tx_spec_config(config))
         self.collection: list[str] | None = None
 
         self.workqueue: OrderedDict[str, dict[str, bool]] = OrderedDict()
@@ -371,11 +371,15 @@ class LoadScopeScheduling:
             work_unit = unsorted_workqueue.setdefault(scope, {})
             work_unit[nodeid] = False
 
-        # Insert tests scopes into work queue ordered by number of tests.
+        if self.config.option.loadscopereorder:
-        for scope, nodeids in sorted(
+            # Insert tests scopes into work queue ordered by number of tests.
-            unsorted_workqueue.items(), key=lambda item: -len(item[1])
+            for scope, nodeids in sorted(
-        ):
+                unsorted_workqueue.items(), key=lambda item: -len(item[1])
-            self.workqueue[scope] = nodeids
+            ):
+                self.workqueue[scope] = nodeids
+        else:
+            for scope, nodeids in unsorted_workqueue.items():
+                self.workqueue[scope] = nodeids
 
         # Avoid having more workers than work
         extra_nodes = len(self.nodes) - len(self.workqueue)

src/xdist/scheduler/protocol.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
+from collections.abc import Sequence
 from typing import Protocol
-from typing import Sequence
 
 from xdist.workermanage import WorkerController
 

src/xdist/scheduler/worksteal.py

@@ -1,13 +1,13 @@
 from __future__ import annotations
 
+from collections.abc import Sequence
 from typing import NamedTuple
-from typing import Sequence
 
 import pytest
 
 from xdist.remote import Producer
 from xdist.report import report_collection_diff
-from xdist.workermanage import parse_spec_config
+from xdist.workermanage import parse_tx_spec_config
 from xdist.workermanage import WorkerController
 
 
@@ -65,7 +65,7 @@ class WorkStealingScheduling:
     """
 
     def __init__(self, config: pytest.Config, log: Producer | None = None) -> None:
-        self.numnodes = len(parse_spec_config(config))
+        self.numnodes = len(parse_tx_spec_config(config))
         self.node2collection: dict[WorkerController, list[str]] = {}
         self.node2pending: dict[WorkerController, list[int]] = {}
         self.pending: list[int] = []

src/xdist/workermanage.py

@@ -1,5 +1,7 @@
 from __future__ import annotations
 
+from collections.abc import Sequence
+from concurrent.futures import ThreadPoolExecutor
 import enum
 import fnmatch
 import os
@@ -9,7 +11,6 @@ import sys
 from typing import Any
 from typing import Callable
 from typing import Literal
-from typing import Sequence
 from typing import Union
 import uuid
 import warnings
@@ -23,7 +24,7 @@ from xdist.remote import Producer
 from xdist.remote import WorkerInfo
 
 
-def parse_spec_config(config: pytest.Config) -> list[str]:
+def parse_tx_spec_config(config: pytest.Config) -> list[str]:
     xspeclist = []
     tx: list[str] = config.getvalue("tx")
     for xspec in tx:
@@ -57,8 +58,17 @@ class NodeManager:
         if self.testrunuid is None:
             self.testrunuid = uuid.uuid4().hex
         self.group = execnet.Group(execmodel="main_thread_only")
+        for proxy_spec in self._getpxspecs():
+            # Proxy gateways do not run workers, and are meant to be passed with the `via` attribute
+            # to additional gateways.
+            # They are useful for running multiple workers on remote machines.
+            if getattr(proxy_spec, "id", None) is None:
+                raise pytest.UsageError(
+                    f"Proxy gateway {proxy_spec} must include an id"
+                )
+            self.group.makegateway(proxy_spec)
         if specs is None:
-            specs = self._getxspecs()
+            specs = self._gettxspecs()
         self.specs: list[execnet.XSpec] = []
         for spec in specs:
             if not isinstance(spec, execnet.XSpec):
@@ -85,15 +95,23 @@ class NodeManager:
     ) -> list[WorkerController]:
         self.config.hook.pytest_xdist_setupnodes(config=self.config, specs=self.specs)
         self.trace("setting up nodes")
-        return [self.setup_node(spec, putevent) for spec in self.specs]
+        with ThreadPoolExecutor(max_workers=len(self.specs)) as executor:
+            futs = [
+                executor.submit(self.setup_node, spec, putevent, idx)
+                for idx, spec in enumerate(self.specs)
+            ]
+            return [f.result() for f in futs]
 
     def setup_node(
         self,
         spec: execnet.XSpec,
         putevent: Callable[[tuple[str, dict[str, Any]]], None],
+        idx: int | None = None,
     ) -> WorkerController:
         if getattr(spec, "execmodel", None) != "main_thread_only":
             spec = execnet.XSpec(f"execmodel=main_thread_only//{spec}")
+        if idx is not None:
+            spec = execnet.XSpec(f"{spec}//id=gw{idx}")
         gw = self.group.makegateway(spec)
         self.config.hook.pytest_xdist_newgateway(gateway=gw)
         self.rsync_roots(gw)
@@ -107,8 +125,11 @@ class NodeManager:
     def teardown_nodes(self) -> None:
         self.group.terminate(self.EXIT_TIMEOUT)
 
-    def _getxspecs(self) -> list[execnet.XSpec]:
+    def _gettxspecs(self) -> list[execnet.XSpec]:
-        return [execnet.XSpec(x) for x in parse_spec_config(self.config)]
+        return [execnet.XSpec(x) for x in parse_tx_spec_config(self.config)]
+
+    def _getpxspecs(self) -> list[execnet.XSpec]:
+        return [execnet.XSpec(x) for x in self.config.getoption("px")]
 
     def _getrsyncdirs(self) -> list[Path]:
         for spec in self.specs:
@@ -312,6 +333,11 @@ class WorkerController:
 
     def setup(self) -> None:
         self.log("setting up worker session")
+        # Cache rinfo for backward compatibility, since pytest-cov
+        # accesses rinfo while the main thread is busy executing our
+        # remote_exec call, which triggers a deadlock error for the
+        # main_thread_only execmodel if the rinfo has not been cached.
+        self.gateway._rinfo()
         spec = self.gateway.spec
         args = [str(x) for x in self.config.invocation_params.args or ()]
         option_dict = {}

testing/acceptance_test.py

@@ -1254,6 +1254,24 @@ class TestLoadScope:
             "test_b.py::test", result.outlines
         ) == {"gw0": 20}
 
+    def test_workqueue_ordered_by_input(self, pytester: pytest.Pytester) -> None:
+        test_file = """
+            import pytest
+            @pytest.mark.parametrize('i', range({}))
+            def test(i):
+                pass
+        """
+        pytester.makepyfile(test_a=test_file.format(10), test_b=test_file.format(20))
+        result = pytester.runpytest(
+            "-n2", "--dist=loadscope", "--no-loadscope-reorder", "-v"
+        )
+        assert get_workers_and_test_count_by_prefix(
+            "test_a.py::test", result.outlines
+        ) == {"gw0": 10}
+        assert get_workers_and_test_count_by_prefix(
+            "test_b.py::test", result.outlines
+        ) == {"gw1": 20}
+
     def test_module_single_start(self, pytester: pytest.Pytester) -> None:
         """Fix test suite never finishing in case all workers start with a single test (#277)."""
         test_file1 = """
@@ -1481,6 +1499,46 @@ class TestGroupScope:
 
         assert a_1.keys() == b_1.keys() and a_2.keys() == b_2.keys()
 
+    def test_multiple_group_marks(self, pytester: pytest.Pytester) -> None:
+        test_file = """
+            import pytest
+            @pytest.mark.xdist_group(name="group1")
+            @pytest.mark.xdist_group(name="group2")
+            def test_1():
+                pass
+        """
+        pytester.makepyfile(test_a=test_file, test_b=test_file)
+        result = pytester.runpytest("-n2", "--dist=loadgroup", "-v")
+        res = parse_tests_and_workers_from_output(result.outlines)
+        assert len(res) == 2
+        # get test names
+        a_1 = next(t[2] for t in res if "test_a.py::test_1" in t[2])
+        b_1 = next(t[2] for t in res if "test_b.py::test_1" in t[2])
+        # check groups
+        assert a_1.split("@")[1] == b_1.split("@")[1] == "group1_group2"
+
+    def test_multiple_group_order(self, pytester: pytest.Pytester) -> None:
+        test_file = """
+            import pytest
+            @pytest.mark.xdist_group(name="b")
+            @pytest.mark.xdist_group(name="d")
+            @pytest.mark.xdist_group(name="c")
+            @pytest.mark.xdist_group(name="c2")
+            @pytest.mark.xdist_group(name="a")
+            @pytest.mark.xdist_group(name="aa")
+            def test_1():
+                pass
+        """
+        pytester.makepyfile(test_a=test_file, test_b=test_file)
+        result = pytester.runpytest("-n2", "--dist=loadgroup", "-v")
+        res = parse_tests_and_workers_from_output(result.outlines)
+        assert len(res) == 2
+        # get test names
+        a_1 = next(t[2] for t in res if "test_a.py::test_1" in t[2])
+        b_1 = next(t[2] for t in res if "test_b.py::test_1" in t[2])
+        # check groups, order should be sorted
+        assert a_1.split("@")[1] == b_1.split("@")[1] == "a_aa_b_c_c2_d"
+
 
 class TestLocking:
     _test_content = """

testing/conftest.py

@@ -1,8 +1,8 @@
 from __future__ import annotations
 
+from collections.abc import Generator
 import shutil
 from typing import Callable
-from typing import Generator
 
 import execnet
 import pytest
@@ -12,7 +12,7 @@ pytest_plugins = "pytester"
 
 
 @pytest.fixture(autouse=True)
-def _divert_atexit(monkeypatch: pytest.MonkeyPatch) -> Generator[None, None, None]:
+def _divert_atexit(monkeypatch: pytest.MonkeyPatch) -> Generator[None]:
     import atexit
 
     finalizers = []

testing/test_dsession.py

@@ -1,8 +1,8 @@
 from __future__ import annotations
 
+from collections.abc import Sequence
 from typing import Any
 from typing import cast
-from typing import Sequence
 from typing import TYPE_CHECKING
 
 import execnet
@@ -543,7 +543,8 @@ def test_report_collection_diff_different() -> None:
         "+XXX\n"
         " ccc\n"
         "-YYY\n"
-        "To see why this happens see Known limitations in documentation"
+        "To see why this happens see 'Known limitations' in documentation "
+        "for pytest-xdist"
     )
 
     msg = report_collection_diff(from_collection, to_collection, "1", "2")

testing/test_plugin.py

@@ -295,7 +295,7 @@ class TestDistOptions:
     def test_getxspecs(self, pytester: pytest.Pytester) -> None:
         config = pytester.parseconfigure("--tx=popen", "--tx", "ssh=xyz")
         nodemanager = NodeManager(config)
-        xspecs = nodemanager._getxspecs()
+        xspecs = nodemanager._gettxspecs()
         assert len(xspecs) == 2
         print(xspecs)
         assert xspecs[0].popen
@@ -303,7 +303,7 @@ class TestDistOptions:
 
     def test_xspecs_multiplied(self, pytester: pytest.Pytester) -> None:
         config = pytester.parseconfigure("--tx=3*popen")
-        xspecs = NodeManager(config)._getxspecs()
+        xspecs = NodeManager(config)._gettxspecs()
         assert len(xspecs) == 3
         assert xspecs[1].popen
 

testing/test_remote.py

@@ -7,7 +7,6 @@ import sys
 from typing import Any
 from typing import Callable
 from typing import cast
-from typing import Dict
 from typing import Union
 import uuid
 
@@ -90,7 +89,7 @@ def worker(request: pytest.FixtureRequest, pytester: pytest.Pytester) -> WorkerS
 
 class TestWorkerInteractor:
     UnserializerReport = Callable[
-        [Dict[str, Any]], Union[pytest.CollectReport, pytest.TestReport]
+        [dict[str, Any]], Union[pytest.CollectReport, pytest.TestReport]
     ]
 
     @pytest.fixture
@@ -267,6 +266,12 @@ class TestWorkerInteractor:
 
         worker.sendcommand("steal", indices=[1, 2])
         ev = worker.popevent("unscheduled")
+        # Cannot steal index 1 because it is completed already, so do not steal any.
+        assert ev.kwargs["indices"] == []
+
+        # Index 2 can be stolen, as it is still pending.
+        worker.sendcommand("steal", indices=[2])
+        ev = worker.popevent("unscheduled")
         assert ev.kwargs["indices"] == [2]
 
         reports = [

testing/test_workermanage.py

@@ -82,11 +82,19 @@ class TestNodeManagerPopen:
         call = hookrecorder.popcall("pytest_xdist_setupnodes")
         assert len(call.specs) == 2
 
-        call = hookrecorder.popcall("pytest_xdist_newgateway")
+        # check expected gateways
-        assert call.gateway.spec == execnet.XSpec("execmodel=main_thread_only//popen")
+        gw_calls = [
-        assert call.gateway.id == "gw0"
+            hookrecorder.popcall("pytest_xdist_newgateway"),
-        call = hookrecorder.popcall("pytest_xdist_newgateway")
+            hookrecorder.popcall("pytest_xdist_newgateway"),
-        assert call.gateway.id == "gw1"
+        ]
+        assert {c.gateway.id for c in gw_calls} == {"gw0", "gw1"}
+
+        for c in gw_calls:
+            expected_spec = execnet.XSpec(
+                f"execmodel=main_thread_only//popen//id={c.gateway.id}"
+            )
+            assert c.gateway.spec == expected_spec
+
         assert len(hm.group) == 2
         hm.teardown_nodes()
         assert not len(hm.group)
@@ -206,8 +214,8 @@ class TestNodeManager:
         p = Path(p)
         print("remote curdir", p)
         assert p == dest.joinpath(config.rootpath.name)
-        assert p.joinpath("dir1").check()
+        assert p.joinpath("dir1").is_dir()
-        assert p.joinpath("dir1", "file1").check()
+        assert p.joinpath("dir1", "file1").is_file()
 
     def test_popen_rsync_subdir(
         self,
@@ -368,6 +376,34 @@ class TestNodeManager:
         (rep,) = reprec.getreports("pytest_runtest_logreport")
         assert rep.passed
 
+    def test_proxy_gateway_setup_nodes(self, pytester: pytest.Pytester) -> None:
+        nodemanager = NodeManager(
+            pytester.parseconfig(
+                "--px", "popen//id=my_proxy", "--tx", "popen//via=my_proxy"
+            )
+        )
+        nodes = nodemanager.setup_nodes(None)  # type: ignore[arg-type]
+
+        # Proxy gateways are considered as an execnet gateway
+        assert len(nodemanager.group) == 2
+
+        # Proxy gateways do not run workers
+        assert len(nodes) == 1
+
+    def test_proxy_gateway(self, pytester: pytest.Pytester) -> None:
+        pytester.makepyfile(
+            __init__="",
+            test_x="""
+            def test_one():
+                pass
+        """,
+        )
+        reprec = pytester.inline_run(
+            "-d", "--px", "popen//id=my_proxy", "--tx", "popen//via=my_proxy"
+        )
+        rep = reprec.getreports("pytest_runtest_logreport")
+        assert rep[1].passed
+
 
 class MyWarning(UserWarning):
     pass

tox.ini

@@ -1,34 +1,26 @@
 [tox]
-envlist=
+envlist =
   linting
-  py{38,39,310,311,312}-pytestlatest
+  py{39,310,311,312,313}-pytestlatest
   py310-pytestmain
   py310-psutil
   py310-setproctitle
 isolated_build = true
+
 [testenv]
-extras = testing
+extras =
+  testing
+  psutil: psutil
+  setproctitle: setproctitle
 deps =
   pytestmin: pytest==7.0.0
   pytestlatest: pytest
   pytestmain: git+https://github.com/pytest-dev/pytest.git
-commands=
-  pytest {posargs}
-
-[testenv:py310-psutil]
-extras =
-  testing
-  psutil
 commands =
-  pytest {posargs:-k psutil}
+  pytest {posargs:{env:_XDIST_TOX_DEFAULT_POSARGS:}}
-
+setenv =
-[testenv:py310-setproctitle]
+  _XDIST_TOX_DEFAULT_POSARGS={env:_XDIST_TOX_POSARGS_PSUTIL:}
-extras =
+  psutil: _XDIST_TOX_POSARGS_PSUTIL=-k psutil
-  testing
-  setproctitle
-deps = pytest
-commands =
-  pytest {posargs}
 
 [testenv:linting]
 skip_install = True
@@ -39,9 +31,8 @@ deps =
 commands = pre-commit run --all-files --show-diff-on-failure
 
 [testenv:release]
-changedir=
+changedir =
 description = do a release, required posarg of the version number
-basepython = python3.10
 skipsdist = True
 usedevelop = True
 passenv = *
@@ -51,16 +42,9 @@ commands =
   towncrier build --version {posargs} --yes
 
 [testenv:docs]
-basepython = python3.10
 usedevelop = True
 deps =
     sphinx
     sphinx_rtd_theme
 commands =
     sphinx-build -W --keep-going -b html docs docs/_build/html {posargs:}
-
-[pytest]
-# pytest-services also defines a worker_id fixture, disable
-# it so they don't conflict with each other (#611).
-addopts = -ra -p no:pytest-services
-testpaths = testing