gotcha

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

.github/dependabot.yml

@@ -0,0 +1,13 @@
+# Keep GitHub Actions up to date with GitHub's Dependabot...
+# https://docs.github.com/en/code-security/dependabot/working-with-dependabot/keeping-your-actions-up-to-date-with-dependabot
+# https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file#package-ecosystem
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    groups:
+      github-actions:
+        patterns:
+          - "*"  # Group all Actions updates into a single larger pull request
+    schedule:
+      interval: weekly

.github/workflows/deploy.yml

@@ -0,0 +1,57 @@
+name: deploy
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'Release version'
+        required: true
+        default: '1.2.3'
+
+jobs:
+
+  package:
+    runs-on: ubuntu-latest
+    env:
+      SETUPTOOLS_SCM_PRETEND_VERSION: ${{ github.event.inputs.version }}
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Build and Check Package
+      uses: hynek/build-and-inspect-python-package@v2.13
+
+  deploy:
+    needs: package
+    runs-on: ubuntu-latest
+    environment: deploy
+    permissions:
+      id-token: write  # For PyPI trusted publishers.
+      contents: write  # For tag.
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Download Package
+      uses: actions/download-artifact@v4
+      with:
+        name: Packages
+        path: dist
+
+    - name: Publish package to PyPI
+      uses: pypa/gh-action-pypi-publish@v1.12.4
+      with:
+        attestations: true
+
+    - name: Push tag
+      run: |
+        git config user.name "pytest bot"
+        git config user.email "pytestbot@gmail.com"
+        git tag --annotate --message=v${{ github.event.inputs.version }} v${{ github.event.inputs.version }} ${{ github.sha }}
+        git push origin v${{ github.event.inputs.version }}
+
+    - name: GitHub Release
+      uses: softprops/action-gh-release@v2
+      with:
+        files: dist/*
+        tag_name: v${{ github.event.inputs.version }}

.github/workflows/main.yml

@@ -1,75 +0,0 @@
-name: build
-
-on: [push, pull_request]
-
-jobs:
-  build:
-
-    runs-on: ${{ matrix.os }}
-
-    strategy:
-      fail-fast: false
-      matrix:
-        tox_env:
-          - "py36-pytestlatest"
-          - "py37-pytestlatest"
-          - "py38-pytestlatest"
-          - "py39-pytestlatest"
-          - "py38-pytestmain"
-          - "py38-psutil"
-
-        os: [ubuntu-latest, windows-latest]
-        include:
-          - tox_env: "py36-pytestlatest"
-            python: "3.6"
-          - tox_env: "py37-pytestlatest"
-            python: "3.7"
-          - tox_env: "py38-pytestlatest"
-            python: "3.8"
-          - tox_env: "py39-pytestlatest"
-            python: "3.9"
-          - tox_env: "py38-pytestmain"
-            python: "3.8"
-          - tox_env: "py38-psutil"
-            python: "3.8"
-
-    steps:
-    - uses: actions/checkout@v1
-    - name: Set up Python
-      uses: actions/setup-python@v1
-      with:
-        python-version: ${{ matrix.python }}
-    - name: Install tox
-      run: |
-        python -m pip install --upgrade pip
-        pip install tox
-    - name: Test
-      run: |
-        tox -e ${{ matrix.tox_env }}
-
-  deploy:
-
-    if: github.event_name == 'push' && startsWith(github.event.ref, 'refs/tags')
-
-    runs-on: ubuntu-latest
-
-    needs: build
-
-    steps:
-    - uses: actions/checkout@v1
-    - name: Set up Python
-      uses: actions/setup-python@v1
-      with:
-        python-version: "3.7"
-    - name: Install wheel
-      run: |
-        python -m pip install --upgrade pip
-        pip install wheel
-    - name: Build package
-      run: |
-        python setup.py sdist bdist_wheel
-    - name: Publish package to PyPI
-      uses: pypa/gh-action-pypi-publish@master
-      with:
-        user: __token__
-        password: ${{ secrets.pypi_token }}

.github/workflows/test.yml

@@ -0,0 +1,93 @@
+name: test
+
+on:
+  push:
+    branches:
+      - master
+      - "test-me-*"
+
+  pull_request:
+    branches:
+      - "*"
+
+# Cancel running jobs for the same workflow and branch.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+
+  package:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+    - name: Build and Check Package
+      uses: hynek/build-and-inspect-python-package@v2.13
+
+  test:
+
+    needs: [package]
+
+    runs-on: ${{ matrix.os }}
+
+    strategy:
+      fail-fast: false
+      matrix:
+        tox_env:
+          - "py39-pytestmin"
+          - "py39-pytestlatest"
+          - "py310-pytestlatest"
+          - "py311-pytestlatest"
+          - "py311-pytestmain"
+          - "py312-pytestlatest"
+          - "py313-pytestlatest"
+          - "py310-psutil"
+          - "py310-setproctitle"
+
+        os: [ubuntu-latest, windows-latest]
+        include:
+          - tox_env: "py39-pytestmin"
+            python: "3.9"
+          - tox_env: "py39-pytestlatest"
+            python: "3.9"
+          - tox_env: "py310-pytestlatest"
+            python: "3.10"
+          - tox_env: "py311-pytestlatest"
+            python: "3.11"
+          - tox_env: "py311-pytestmain"
+            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"
+            python: "3.10"
+
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        # Needed to fetch tags, which are required by setuptools-scm.
+        fetch-depth: 0
+
+    - name: Download Package
+      uses: actions/download-artifact@v4
+      with:
+        name: Packages
+        path: dist
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python }}
+
+    - name: Install tox
+      run: |
+        python -m pip install --upgrade pip
+        pip install tox
+
+    - name: Test
+      shell: bash
+      run: |
+        tox run -e ${{ matrix.tox_env }} --installpkg `find dist/*.tar.gz`

.pre-commit-config.yaml

@@ -1,26 +1,19 @@
 repos:
--   repo: https://github.com/psf/black
+- repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: 21.6b0
+  rev: "v0.12.3"
+  hooks:
+    - id: ruff
+      args: ["--fix"]
+    - id: ruff-format
+-   repo: https://github.com/asottile/blacken-docs
+    rev: 1.19.1
     hooks:
-    -   id: black
+    -   id: blacken-docs
-        args: [--safe, --quiet, --target-version, py35]
+        additional_dependencies: [black==23.1.0]
-        language_version: python3.7
 -   repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.0.1
+    rev: v5.0.0
     hooks:
-    -   id: trailing-whitespace
-    -   id: end-of-file-fixer
     -   id: check-yaml
-    -   id: debug-statements
--   repo: https://github.com/PyCQA/flake8
-    rev: 3.9.2
-    hooks:
-    -   id: flake8
--   repo: https://github.com/asottile/pyupgrade
-    rev: v2.19.4
-    hooks:
-    -   id: pyupgrade
-        args: [--py3-plus]
 -   repo: local
     hooks:
     -   id: rst
@@ -29,4 +22,14 @@ repos:
         files: ^(CHANGELOG.rst|HOWTORELEASE.rst|README.rst|changelog/.*)$
         language: python
         additional_dependencies: [pygments, restructuredtext_lint]
-        language_version: python3.7
+-   repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.16.1
+    hooks:
+    -   id: mypy
+        files: ^(src/|testing/)
+        args: []
+        additional_dependencies:
+          - pytest>=7.0.0
+          - execnet>=2.1.0
+          - types-psutil
+          - setproctitle

.readthedocs.yaml

@@ -0,0 +1,14 @@
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+
+sphinx:
+  configuration: docs/conf.py
+
+python:
+  install:
+    - path: .
+    - requirements: docs/requirements.txt

CHANGELOG.rst

@@ -1,3 +1,325 @@
+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
+--------
+
+- `#1027 <https://github.com/pytest-dev/pytest-xdist/pull/1027>`_:``pytest-xdist`` workers now always execute the tests in the main thread.
+  Previously some tests might end up executing in a separate thread other than ``main`` in the workers, due to some internal `execnet`` details. This can cause problems specially with async frameworks where the event loop is running in the ``main`` thread (for example `#620 <https://github.com/pytest-dev/pytest-xdist/issues/620>`__).
+
+Bug Fixes
+---------
+
+- `#1024 <https://github.com/pytest-dev/pytest-xdist/issues/1024>`_: Added proper handling of ``shouldstop`` (such as set by ``--max-fail``) and ``shouldfail`` conditions in workers.
+  Previously, a worker might have continued executing further tests before the controller could terminate the session.
+
+- `#1028 <https://github.com/pytest-dev/pytest-xdist/issues/1028>`_: Fixed compatibility issue between `looponfail` and editable installs.
+
+- `#620 <https://github.com/pytest-dev/pytest-xdist/issues/620>`_: Use the new ``main_thread_only`` ``execnet`` "execmodel" so that code which expects to only run in the main thread will now work as expected.
+
+- `#937 <https://github.com/pytest-dev/pytest-xdist/issues/937>`_: Fixed a bug where plugin would raise an incompatibility error with ``--pdb`` despite using ``-n0``.
+
+
+Removals
+--------
+
+- `#1053 <https://github.com/pytest-dev/pytest-xdist/issues/1053>`_: Dropped support for Python 3.7.
+
+- `#1057 <https://github.com/pytest-dev/pytest-xdist/issues/1057>`_: pytest>=7.0.0 is now required.
+
+  execnet>=2.1.0 is now required.
+
+
+Trivial Changes
+---------------
+
+- `#1020 <https://github.com/pytest-dev/pytest-xdist/issues/1020>`_: pytest-xdist's ``setup.py`` file is removed.
+
+  If you relied on this file, e.g. to install pytest using ``setup.py install``,
+  please see `Why you shouldn't invoke setup.py directly <https://blog.ganssle.io/articles/2021/10/setup-py-deprecated.html#summary>`_ for alternatives.
+
+- `#1057 <https://github.com/pytest-dev/pytest-xdist/issues/1057>`_: The internals of pytest-xdist are now fully typed. The typing is not exposed yet.
+
+- `#996 <https://github.com/pytest-dev/pytest-xdist/issues/996>`_: Adjusted license file format and content to ensure security scanners will identity the license.
+
+pytest-xdist 3.5.0 (2023-11-21)
+===============================
+
+Features
+--------
+
+- `#632 <https://github.com/pytest-dev/pytest-xdist/issues/632>`_: ``--dist=loadscope`` now sorts scopes by number of tests to assign largest scopes early -- in many cases this should improve overall test session running time, as there is less chance of a large scope being left to be processed near the end of the session, leaving other workers idle.
+
+
+pytest-xdist 3.4.0 (2023-11-11)
+===============================
+
+Features
+--------
+
+- `#963 <https://github.com/pytest-dev/pytest-xdist/issues/963>`_: Wait for workers to finish reporting when test run stops early.
+
+  This makes sure that the results of in-progress tests are displayed.
+  Previously these reports were being discarded, losing information about the
+  test run.
+
+- `#965 <https://github.com/pytest-dev/pytest-xdist/issues/965>`_: Added support for Python 3.12.
+
+
+pytest-xdist 3.3.1 (2023-05-19)
+===============================
+
+Bug Fixes
+---------
+
+- `#907 <https://github.com/pytest-dev/pytest-xdist/issues/907>`_: Avoid remote calls during startup as ``execnet`` by default does not ensure remote affinity with the
+  main thread and might accidentally schedule the pytest worker into a non-main thread, which breaks numerous frameworks,
+  for example ``asyncio``, ``anyio``, ``PyQt/PySide``, etc.
+
+  A more safe correction will require thread affinity in ``execnet`` (`pytest-dev/execnet#96 <https://github.com/pytest-dev/execnet/issues/96>`__).
+
+
+pytest-xdist 3.3.0 (2023-05-12)
+===============================
+
+Features
+--------
+
+- `#555 <https://github.com/pytest-dev/pytest-xdist/issues/555>`_: Improved progress output when collecting nodes to be less verbose.
+
+
+pytest-xdist 3.2.1 (2023-03-12)
+===============================
+
+Bug Fixes
+---------
+
+- `#884 <https://github.com/pytest-dev/pytest-xdist/issues/884>`_: Fixed hang in ``worksteal`` scheduler.
+
+
+pytest-xdist 3.2.0 (2023-02-07)
+===============================
+
+Improved Documentation
+----------------------
+
+- `#863 <https://github.com/pytest-dev/pytest-xdist/issues/863>`_: Document limitations for debugging due to standard I/O of workers not being forwarded. Also, mention remote debugging as a possible workaround.
+
+
+Features
+--------
+
+- `#855 <https://github.com/pytest-dev/pytest-xdist/issues/855>`_: Users can now configure ``load`` scheduling precision using ``--maxschedchunk`` command
+  line option.
+
+- `#858 <https://github.com/pytest-dev/pytest-xdist/issues/858>`_: New ``worksteal`` scheduler, based on the idea of `work stealing <https://en.wikipedia.org/wiki/Work_stealing>`_. It's similar to ``load`` scheduler, but it should handle tests with significantly differing duration better, and, at the same time, it should provide similar or better reuse of fixtures.
+
+
+Trivial Changes
+---------------
+
+- `#870 <https://github.com/pytest-dev/pytest-xdist/issues/870>`_: Make the tests pass even when ``$PYTEST_XDIST_AUTO_NUM_WORKERS`` is set.
+
+
+pytest-xdist 3.1.0 (2022-12-01)
+===============================
+
+Features
+--------
+
+- `#789 <https://github.com/pytest-dev/pytest-xdist/issues/789>`_: Users can now set a default distribution mode in their configuration file:
+
+  .. code-block:: ini
+
+      [pytest]
+      addopts = --dist loadscope
+
+- `#842 <https://github.com/pytest-dev/pytest-xdist/issues/842>`_: Python 3.11 is now officially supported.
+
+
+Removals
+--------
+
+- `#842 <https://github.com/pytest-dev/pytest-xdist/issues/842>`_: Python 3.6 is no longer supported.
+
+
+pytest-xdist 3.0.2 (2022-10-25)
+===============================
+
+Bug Fixes
+---------
+
+- `#813 <https://github.com/pytest-dev/pytest-xdist/issues/813>`_: Cancel shutdown when a crashed worker is restarted.
+
+
+Deprecations
+------------
+
+- `#825 <https://github.com/pytest-dev/pytest-xdist/issues/825>`_: The ``--rsyncdir`` command line argument and ``rsyncdirs`` config variable are deprecated.
+
+  The rsync feature will be removed in pytest-xdist 4.0.
+
+- `#826 <https://github.com/pytest-dev/pytest-xdist/issues/826>`_: The ``--looponfail`` command line argument and ``looponfailroots`` config variable are deprecated.
+
+  The loop-on-fail feature will be removed in pytest-xdist 4.0.
+
+
+Improved Documentation
+----------------------
+
+- `#791 <https://github.com/pytest-dev/pytest-xdist/issues/791>`_: Document the ``pytest_xdist_auto_num_workers`` hook.
+
+- `#796 <https://github.com/pytest-dev/pytest-xdist/issues/796>`_: Added known limitations section to documentation.
+
+- `#829 <https://github.com/pytest-dev/pytest-xdist/issues/829>`_: Document the ``-n logical`` option.
+
+
+Features
+--------
+
+- `#792 <https://github.com/pytest-dev/pytest-xdist/issues/792>`_: The environment variable ``PYTEST_XDIST_AUTO_NUM_WORKERS`` can now be used to
+  specify the default for ``-n auto`` and ``-n logical``.
+
+- `#812 <https://github.com/pytest-dev/pytest-xdist/issues/812>`_: Partially restore old initial batch distribution algorithm in ``LoadScheduling``.
+
+  pytest orders tests for optimal sequential execution - i. e. avoiding
+  unnecessary setup and teardown of fixtures. So executing tests in consecutive
+  chunks is important for optimal performance.
+
+  In v1.14, initial test distribution in ``LoadScheduling`` was changed to
+  round-robin, optimized for the corner case, when the number of tests is less
+  than ``2 * number of nodes``. At the same time, it became worse for all other
+  cases.
+
+  For example: if some tests use some "heavy" fixture, and these tests fit into
+  the initial batch, with round-robin distribution the fixture will be created
+  ``min(n_tests, n_workers)`` times, no matter how many other tests there are.
+
+  With the old algorithm (before v1.14), if there are enough tests not using
+  the fixture, the fixture was created only once.
+
+  So restore the old behavior for typical cases where the number of tests is
+  much greater than the number of workers (or, strictly speaking, when there
+  are at least 2 tests for every node).
+
+
+Removals
+--------
+
+- `#468 <https://github.com/pytest-dev/pytest-xdist/issues/468>`_: The ``--boxed`` command-line option has been removed. If you still need this functionality, install `pytest-forked <https://pypi.org/project/pytest-forked>`__ separately.
+
+
+Trivial Changes
+---------------
+
+- `#468 <https://github.com/pytest-dev/pytest-xdist/issues/468>`_: The ``py`` dependency has been dropped.
+
+- `#822 <https://github.com/pytest-dev/pytest-xdist/issues/822>`_: Replace internal usage of ``py.log`` with a custom solution (but with the same interface).
+
+- `#823 <https://github.com/pytest-dev/pytest-xdist/issues/823>`_: Remove usage of ``py._pydir`` as an rsync candidate.
+
+- `#824 <https://github.com/pytest-dev/pytest-xdist/issues/824>`_: Replace internal usages of ``py.path.local`` by ``pathlib.Path``.
+
+
+pytest-xdist 2.5.0 (2021-12-10)
+===============================
+
+Deprecations and Removals
+-------------------------
+
+- `#468 <https://github.com/pytest-dev/pytest-xdist/issues/468>`_: The ``--boxed`` command line argument is deprecated. Install `pytest-forked <https://pypi.org/project/pytest-forked>`__ and use ``--forked`` instead. pytest-xdist 3.0.0 will remove the ``--boxed`` argument and ``pytest-forked`` dependency.
+
+
+Features
+--------
+
+- `#722 <https://github.com/pytest-dev/pytest-xdist/issues/722>`_: Full compatibility with pytest 7 - no deprecation warnings or use of legacy features.
+
+- `#733 <https://github.com/pytest-dev/pytest-xdist/issues/733>`_: New ``--dist=loadgroup`` option, which ensures all tests marked with ``@pytest.mark.xdist_group`` run in the same session/worker. Other tests run distributed as in ``--dist=load``.
+
+
+Trivial Changes
+---------------
+
+- `#708 <https://github.com/pytest-dev/pytest-xdist/issues/708>`_: Use ``@pytest.hookspec`` decorator to declare hook options in ``newhooks.py`` to avoid warnings in ``pytest 7.0``.
+
+- `#719 <https://github.com/pytest-dev/pytest-xdist/issues/719>`_: Use up-to-date ``setup.cfg``/``pyproject.toml`` packaging setup.
+
+- `#720 <https://github.com/pytest-dev/pytest-xdist/issues/720>`_: Require pytest>=6.2.0.
+
+- `#721 <https://github.com/pytest-dev/pytest-xdist/issues/721>`_: Started using type annotations and mypy checking internally. The types are incomplete and not published.
+
+
+pytest-xdist 2.4.0 (2021-09-20)
+===============================
+
+Features
+--------
+
+- `#696 <https://github.com/pytest-dev/pytest-xdist/issues/696>`_: On Linux, the process title now changes to indicate the current worker state (running/idle).
+
+  Depends on the `setproctitle <https://pypi.org/project/setproctitle/>`__ package, which can be installed with ``pip install pytest-xdist[setproctitle]``.
+
+- `#704 <https://github.com/pytest-dev/pytest-xdist/issues/704>`_: Add support for Python 3.10.
+
+
 pytest-xdist 2.3.0 (2021-06-16)
 ===============================
 

LICENSE

@@ -1,18 +1,21 @@
+MIT License
 
-  Permission is hereby granted, free of charge, to any person obtaining a copy
+Copyright (c) 2010 Holger Krekel and contributors.
-  of this software and associated documentation files (the "Software"), to deal
-  in the Software without restriction, including without limitation the rights
-  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-  copies of the Software, and to permit persons to whom the Software is
-  furnished to do so, subject to the following conditions:
 
-  The above copyright notice and this permission notice shall be included in all
+Permission is hereby granted, free of charge, to any person obtaining a copy
-  copies or substantial portions of the Software.
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
 
-  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+The above copyright notice and this permission notice shall be included in all
-  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+copies or substantial portions of the Software.
-  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+
-  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-  SOFTWARE.
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

MANIFEST.in

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

OVERVIEW.md

@@ -1,76 +0,0 @@
-# Overview #
-
-`xdist` works by spawning one or more **workers**, which are controlled
-by the **master**. Each **worker** is responsible for performing
-a full test collection and afterwards running tests as dictated by the **master**.
-
-The execution flow is:
-
-1. **master** spawns one or more **workers** at the beginning of
-   the test session. The communication between **master** and **worker** nodes makes use of
-   [execnet](http://codespeak.net/execnet/) and its [gateways](http://codespeak.net/execnet/basics.html#gateways-bootstrapping-python-interpreters).
-   The actual interpreters executing the code for the **workers** might
-   be remote or local.
-
-1. Each **worker** itself is a mini pytest runner. **workers** at this
-   point perform a full test collection, sending back the collected
-   test-ids back to the **master** which does not
-   perform any collection itself.
-
-1. The **master** receives the result of the collection from all nodes.
-   At this point the **master** performs some sanity check to ensure that
-   all **workers** collected the same tests (including order), bailing out otherwise.
-   If all is well, it converts the list of test-ids into a list of simple
-   indexes, where each index corresponds to the position of that test in the
-   original collection list. This works because all nodes have the same
-   collection list, and saves bandwidth because the **master** can now tell
-   one of the workers to just *execute test index 3* index of passing the
-   full test id.
-
-1. If **dist-mode** is **each**: the **master** just sends the full list
-   of test indexes to each node at this moment.
-
-1. If **dist-mode** is **load**: the **master** takes around 25% of the
-   tests and sends them one by one to each **worker** in a round robin
-   fashion. The rest of the tests will be distributed later as **workers**
-   finish tests (see below).
-
-1. Note that `pytest_xdist_make_scheduler` hook can be used to implement custom tests distribution logic.
-
-1. **workers** re-implement `pytest_runtestloop`: pytest's default implementation
-   basically loops over all collected items in the `session` object and executes
-   the `pytest_runtest_protocol` for each test item, but in xdist **workers** sit idly
-   waiting for **master** to send tests for execution. As tests are
-   received by **workers**, `pytest_runtest_protocol` is executed for each test.
-   Here it worth noting an implementation detail: **workers** always must keep at
-   least one test item on their queue due to how the `pytest_runtest_protocol(item, nextitem)`
-   hook is defined: in order to pass the `nextitem` to the hook, the worker must wait for more
-   instructions from master before executing that remaining test. If it receives more tests,
-   then it can safely call `pytest_runtest_protocol` because it knows what the `nextitem` parameter will be.
-   If it receives a "shutdown" signal, then it can execute the hook passing `nextitem` as `None`.
-
-1. As tests are started and completed at the **workers**, the results are sent
-   back to the **master**, which then just forwards the results to
-   the appropriate pytest hooks: `pytest_runtest_logstart` and
-   `pytest_runtest_logreport`. This way other plugins (for example `junitxml`)
-   can work normally. The **master** (when in dist-mode **load**)
-   decides to send more tests to a node when a test completes, using
-   some heuristics such as test durations and how many tests each **worker**
-   still has to run.
-
-1. When the **master** has no more pending tests it will
-   send a "shutdown" signal to all **workers**, which will then run their
-   remaining tests to completion and shut down. At this point the
-   **master** will sit waiting for **workers** to shut down, still
-   processing events such as `pytest_runtest_logreport`.
-
-## FAQ ##
-
-> Why does each worker do its own collection, as opposed to having
-the master collect once and distribute from that collection to the workers?
-
-If collection was performed by master then it would have to
-serialize collected items to send them through the wire, as workers live in another process.
-The problem is that test items are not easily (impossible?) to serialize, as they contain references to
-the test functions, fixture managers, config objects, etc. Even if one manages to serialize it,
-it seems it would be very hard to get it right and easy to break by any small change in pytest.

README.rst

@@ -1,4 +1,6 @@
-
+============
+pytest-xdist
+============
 
 .. image:: http://img.shields.io/pypi/v/pytest-xdist.svg
     :alt: PyPI version
@@ -11,393 +13,21 @@
     :alt: Python versions
     :target: https://pypi.python.org/pypi/pytest-xdist
 
-.. image:: https://github.com/pytest-dev/pytest-xdist/workflows/build/badge.svg
+.. image:: https://github.com/pytest-dev/pytest-xdist/workflows/test/badge.svg
     :target: https://github.com/pytest-dev/pytest-xdist/actions
 
 .. image:: https://img.shields.io/badge/code%20style-black-000000.svg
     :target: https://github.com/ambv/black
 
-xdist: pytest distributed testing plugin
+The `pytest-xdist`_ plugin extends pytest with new test execution modes, the most used being distributing
-========================================
+tests across multiple CPUs to speed up test execution::
 
-The `pytest-xdist`_ plugin extends pytest with some unique
+    pytest -n auto
-test execution modes:
 
-* test run parallelization_: if you have multiple CPUs or hosts you can use
+With this call, pytest will spawn a number of workers processes equal to the number of available CPUs, and distribute
-  those for a combined test run.  This allows to speed up
+the tests randomly across them.
-  development or to use special resources of `remote machines`_.
 
+Documentation
+=============
 
-* ``--looponfail``: run your tests repeatedly in a subprocess.  After each run
+Documentation is available at `Read The Docs <https://pytest-xdist.readthedocs.io>`__.
-  pytest waits until a file in your project changes and then re-runs
-  the previously failing tests.  This is repeated until all tests pass
-  after which again a full run is performed.
-
-* `Multi-Platform`_ coverage: you can specify different Python interpreters
-  or different platforms and run tests in parallel on all of them.
-
-Before running tests remotely, ``pytest`` efficiently "rsyncs" your
-program source code to the remote place.  All test results
-are reported back and displayed to your local terminal.
-You may specify different Python versions and interpreters.
-
-If you would like to know how pytest-xdist works under the covers, checkout
-`OVERVIEW <https://github.com/pytest-dev/pytest-xdist/blob/master/OVERVIEW.md>`_.
-
-
-**NOTE**: due to how pytest-xdist is implemented, the ``-s/--capture=no`` option does not work.
-
-
-Installation
-------------
-
-Install the plugin with::
-
-    pip install pytest-xdist
-
-
-To use ``psutil`` for detection of the number of CPUs available, install the ``psutil`` extra::
-
-    pip install pytest-xdist[psutil]
-
-
-.. _parallelization:
-
-Speed up test runs by sending tests to multiple CPUs
-----------------------------------------------------
-
-To send tests to multiple CPUs, use the ``-n`` (or ``--numprocesses``) option::
-
-    pytest -n NUMCPUS
-
-Pass ``-n auto`` to use as many processes as your computer has CPU cores. This
-can lead to considerable speed ups, especially if your test suite takes a
-noticeable amount of time.
-
-If a test crashes a worker, pytest-xdist will automatically restart that worker
-and report the test’s failure. You can use the ``--max-worker-restart`` option
-to limit the number of worker restarts that are allowed, or disable restarting
-altogether using ``--max-worker-restart 0``.
-
-By default, using ``--numprocesses`` will send pending tests to any worker that
-is available, without any guaranteed order. You can change the test
-distribution algorithm this with the ``--dist`` option. It takes these values:
-
-* ``--dist no``: The default algorithm, distributing one test at a time.
-
-* ``--dist loadscope``: Tests are grouped by **module** for *test functions*
-  and by **class** for *test methods*. Groups are distributed to available
-  workers as whole units. This guarantees that all tests in a group run in the
-  same process. This can be useful if you have expensive module-level or
-  class-level fixtures. Grouping by class takes priority over grouping by
-  module.
-
-* ``--dist loadfile``: Tests are grouped by their containing file. Groups are
-  distributed to available workers as whole units. This guarantees that all
-  tests in a file run in the same worker.
-
-Making session-scoped fixtures execute only once
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-``pytest-xdist`` is designed so that each worker process will perform its own collection and execute
-a subset of all tests. This means that tests in different processes requesting a high-level
-scoped fixture (for example ``session``) will execute the fixture code more than once, which
-breaks expectations and might be undesired in certain situations.
-
-While ``pytest-xdist`` does not have a builtin support for ensuring a session-scoped fixture is
-executed exactly once, this can be achieved by using a lock file for inter-process communication.
-
-The example below needs to execute the fixture ``session_data`` only once (because it is
-resource intensive, or needs to execute only once to define configuration options, etc), so it makes
-use of a `FileLock <https://pypi.org/project/filelock/>`_ to produce the fixture data only once
-when the first process requests the fixture, while the other processes will then read
-the data from a file.
-
-Here is the code:
-
-.. code-block:: python
-
-    import json
-
-    import pytest
-    from filelock import FileLock
-
-
-    @pytest.fixture(scope="session")
-    def session_data(tmp_path_factory, worker_id):
-        if worker_id == "master":
-            # not executing in with multiple workers, just produce the data and let
-            # pytest's fixture caching do its job
-            return produce_expensive_data()
-
-        # get the temp directory shared by all workers
-        root_tmp_dir = tmp_path_factory.getbasetemp().parent
-
-        fn = root_tmp_dir / "data.json"
-        with FileLock(str(fn) + ".lock"):
-            if fn.is_file():
-                data = json.loads(fn.read_text())
-            else:
-                data = produce_expensive_data()
-                fn.write_text(json.dumps(data))
-        return data
-
-
-The example above can also be use in cases a fixture needs to execute exactly once per test session, like
-initializing a database service and populating initial tables.
-
-This technique might not work for every case, but should be a starting point for many situations
-where executing a high-scope fixture exactly once is important.
-
-Running tests in a Python subprocess
-------------------------------------
-
-To instantiate a python3.9 subprocess and send tests to it, you may type::
-
-    pytest -d --tx popen//python=python3.9
-
-This will start a subprocess which is run with the ``python3.9``
-Python interpreter, found in your system binary lookup path.
-
-If you prefix the --tx option value like this::
-
-    --tx 3*popen//python=python3.9
-
-then three subprocesses would be created and tests
-will be load-balanced across these three processes.
-
-.. _boxed:
-
-Running tests in a boxed subprocess
------------------------------------
-
-This functionality has been moved to the
-`pytest-forked <https://github.com/pytest-dev/pytest-forked>`_ plugin, but the ``--boxed`` option
-is still kept for backward compatibility.
-
-.. _`remote machines`:
-
-Sending tests to remote SSH accounts
-------------------------------------
-
-Suppose you have a package ``mypkg`` which contains some
-tests that you can successfully run locally. And you
-have a ssh-reachable machine ``myhost``.  Then
-you can ad-hoc distribute your tests by typing::
-
-    pytest -d --tx ssh=myhostpopen --rsyncdir mypkg mypkg
-
-This will synchronize your :code:`mypkg` package directory
-to a remote ssh account and then locally collect tests
-and send them to remote places for execution.
-
-You can specify multiple :code:`--rsyncdir` directories
-to be sent to the remote side.
-
-.. note::
-
-  For pytest to collect and send tests correctly
-  you not only need to make sure all code and tests
-  directories are rsynced, but that any test (sub) directory
-  also has an :code:`__init__.py` file because internally
-  pytest references tests as a fully qualified python
-  module path.  **You will otherwise get strange errors**
-  during setup of the remote side.
-
-
-You can specify multiple :code:`--rsyncignore` glob patterns
-to be ignored when file are sent to the remote side.
-There are also internal ignores: :code:`.*, *.pyc, *.pyo, *~`
-Those you cannot override using rsyncignore command-line or
-ini-file option(s).
-
-
-Sending tests to remote Socket Servers
---------------------------------------
-
-Download the single-module `socketserver.py`_ Python program
-and run it like this::
-
-    python socketserver.py
-
-It will tell you that it starts listening on the default
-port.  You can now on your home machine specify this
-new socket host with something like this::
-
-    pytest -d --tx socket=192.168.1.102:8888 --rsyncdir mypkg mypkg
-
-
-.. _`atonce`:
-.. _`Multi-Platform`:
-
-
-Running tests on many platforms at once
----------------------------------------
-
-The basic command to run tests on multiple platforms is::
-
-    pytest --dist=each --tx=spec1 --tx=spec2
-
-If you specify a windows host, an OSX host and a Linux
-environment this command will send each tests to all
-platforms - and report back failures from all platforms
-at once. The specifications strings use the `xspec syntax`_.
-
-.. _`xspec syntax`: http://codespeak.net/execnet/basics.html#xspec
-
-.. _`socketserver.py`: https://raw.githubusercontent.com/pytest-dev/execnet/master/execnet/script/socketserver.py
-
-.. _`execnet`: http://codespeak.net/execnet
-
-Identifying the worker process during a test
---------------------------------------------
-
-*New in version 1.15.*
-
-If you need to determine the identity of a worker process in
-a test or fixture, you may use the ``worker_id`` fixture to do so:
-
-.. code-block:: python
-
-    @pytest.fixture()
-    def user_account(worker_id):
-        """ use a different account in each xdist worker """
-        return "account_%s" % worker_id
-
-When ``xdist`` is disabled (running with ``-n0`` for example), then
-``worker_id`` will return ``"master"``.
-
-Worker processes also have the following environment variables
-defined:
-
-* ``PYTEST_XDIST_WORKER``: the name of the worker, e.g., ``"gw2"``.
-* ``PYTEST_XDIST_WORKER_COUNT``: the total number of workers in this session,
-  e.g., ``"4"`` when ``-n 4`` is given in the command-line.
-
-The information about the worker_id in a test is stored in the ``TestReport`` as
-well, under the ``worker_id`` attribute.
-
-Since version 2.0, the following functions are also available in the ``xdist`` module:
-
-.. code-block:: python
-
-    def is_xdist_worker(request_or_session) -> bool:
-        """Return `True` if this is an xdist worker, `False` otherwise
-
-        :param request_or_session: the `pytest` `request` or `session` object
-        """
-
-    def is_xdist_master(request_or_session) -> bool:
-        """Return `True` if this is the xdist controller, `False` otherwise
-
-        Note: this method also returns `False` when distribution has not been
-        activated at all.
-
-        deprecated alias for is_xdist_controller
-
-        :param request_or_session: the `pytest` `request` or `session` object
-        """
-
-     def is_xdist_controller(request_or_session) -> bool:
-        """Return `True` if this is the xdist controller, `False` otherwise
-
-        Note: this method also returns `False` when distribution has not been
-        activated at all.
-
-        :param request_or_session: the `pytest` `request` or `session` object
-        """
-
-    def get_xdist_worker_id(request_or_session) -> str:
-        """Return the id of the current worker ('gw0', 'gw1', etc) or 'master'
-        if running on the controller node.
-
-        If not distributing tests (for example passing `-n0` or not passing `-n` at all) also return 'master'.
-
-        :param request_or_session: the `pytest` `request` or `session` object
-        """
-
-
-Uniquely identifying the current test run
------------------------------------------
-
-*New in version 1.32.*
-
-If you need to globally distinguish one test run from others in your
-workers, you can use the ``testrun_uid`` fixture. For instance, let's say you
-wanted to create a separate database for each test run:
-
-.. code-block:: python
-
-    import pytest
-    from posix_ipc import Semaphore, O_CREAT
-
-    @pytest.fixture(scope="session", autouse=True)
-    def create_unique_database(testrun_uid):
-        """ create a unique database for this particular test run """
-        database_url = f"psql://myapp-{testrun_uid}"
-
-        with Semaphore(f"/{testrun_uid}-lock", flags=O_CREAT, initial_value=1):
-            if not database_exists(database_url):
-                create_database(database_url)
-
-    @pytest.fixture()
-    def db(testrun_uid):
-        """ retrieve unique database """
-        database_url = f"psql://myapp-{testrun_uid}"
-        return database_get_instance(database_url)
-
-
-Additionally, during a test run, the following environment variable is defined:
-
-* ``PYTEST_XDIST_TESTRUNUID``: the unique id of the test run.
-
-Accessing ``sys.argv`` from the master node in workers
-------------------------------------------------------
-
-To access the ``sys.argv`` passed to the command-line of the master node, use
-``request.config.workerinput["mainargv"]``.
-
-
-Specifying test exec environments in an ini file
-------------------------------------------------
-
-You can use pytest's ini file configuration to avoid typing common options.
-You can for example make running with three subprocesses your default like this:
-
-.. code-block:: ini
-
-    [pytest]
-    addopts = -n3
-
-You can also add default environments like this:
-
-.. code-block:: ini
-
-    [pytest]
-    addopts = --tx ssh=myhost//python=python3.9 --tx ssh=myhost//python=python3.6
-
-and then just type::
-
-    pytest --dist=each
-
-to run tests in each of the environments.
-
-
-Specifying "rsync" dirs in an ini-file
---------------------------------------
-
-In a ``tox.ini`` or ``setup.cfg`` file in your root project directory
-you may specify directories to include or to exclude in synchronisation:
-
-.. code-block:: ini
-
-    [pytest]
-    rsyncdirs = . mypkg helperpkg
-    rsyncignore = .hg
-
-These directory specifications are relative to the directory
-where the configuration file was found.
-
-.. _`pytest-xdist`: http://pypi.python.org/pypi/pytest-xdist
-.. _`pytest-xdist repository`: https://github.com/pytest-dev/pytest-xdist
-.. _`pytest`: http://pytest.org

RELEASING.rst

@@ -32,12 +32,10 @@ To publish a new release ``X.Y.Z``, the steps are as follows:
 
     $ tox -e release -- X.Y.Z
 
-#. Commit and push the branch for review.
+#. Commit and push the branch to ``upstream`` and open a PR.
 
-#. Once PR is **green** and **approved**, create and push a tag::
+#. Once the PR is **green** and **approved**, start the ``deploy`` workflow manually from the branch ``release-VERSION``, passing ``VERSION`` as parameter, or execute::
 
-    $ export VERSION=X.Y.Z
+   gh workflow run deploy.yml -R pytest-dev/pytest-xdist --ref release-X.Y.Z --field version=X.Y.Z
-    $ git tag v$VERSION release-$VERSION
-    $ git push git@github.com:pytest-dev/pytest-xdist.git v$VERSION
 
-That will build the package and publish it on ``PyPI`` automatically.
+#. Merge the release PR to ``master``.

docs/.gitignore

@@ -0,0 +1 @@
+_build/

docs/changelog.rst

@@ -0,0 +1,5 @@
+=========
+Changelog
+=========
+
+.. include:: ../CHANGELOG.rst

docs/conf.py

@@ -0,0 +1,55 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+
+# -- Project information -----------------------------------------------------
+
+project = "pytest-xdist"
+copyright = "2010, holger krekel and contributors"
+author = "holger krekel and contributors"
+
+master_doc = "index"
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    "sphinx_rtd_theme",
+    "sphinx.ext.autodoc",
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ["_templates"]
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = "sphinx_rtd_theme"
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+# html_static_path = ['_static']

docs/crash.rst

@@ -0,0 +1,7 @@
+When tests crash
+================
+
+If a test crashes a worker, pytest-xdist will automatically restart that worker
+and report the test’s failure. You can use the ``--max-worker-restart`` option
+to limit the number of worker restarts that are allowed, or disable restarting
+altogether using ``--max-worker-restart 0``.

docs/distribution.rst

@@ -0,0 +1,130 @@
+.. _parallelization:
+
+Running tests across multiple CPUs
+==================================
+
+To send tests to multiple CPUs, use the ``-n`` (or ``--numprocesses``) option::
+
+    pytest -n auto
+
+This can lead to considerable speed ups, especially if your test suite takes a
+noticeable amount of time.
+
+With ``-n auto``, pytest-xdist will use as many processes as your computer
+has physical CPU cores.
+
+Use ``-n logical`` to use the number of *logical* CPU cores rather than
+physical ones. This currently requires the `psutil <https://pypi.org/project/psutil/>`__ package to be installed;
+if it is not or if it fails to determine the number of logical CPUs, fall back to ``-n auto`` behavior.
+
+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:
+
+* Set the environment variable ``PYTEST_XDIST_AUTO_NUM_WORKERS`` to the
+  desired number of processes.
+
+* Implement the ``pytest_xdist_auto_num_workers``
+  `pytest hook <https://docs.pytest.org/en/latest/how-to/writing_plugins.html>`__
+  (a ``pytest_xdist_auto_num_workers(config)`` function in e.g. ``conftest.py``)
+  that returns the number of processes to use.
+  The hook can use ``config.option.numprocesses`` to determine if the user
+  asked for ``"auto"`` or ``"logical"``, and it can return ``None`` to fall
+  back to the default.
+
+If both the hook and environment variable are specified, the hook takes
+priority.
+
+
+Parallelization can be configured further with these options:
+
+* ``--maxprocesses=maxprocesses``: limit the maximum number of workers to
+  process the tests.
+
+* ``--max-worker-restart``: maximum number of workers that can be restarted
+  when crashed (set to zero to disable this feature).
+
+The test distribution algorithm is configured with the ``--dist`` command-line option:
+
+.. _distribution modes:
+
+* ``--dist load`` **(default)**: Sends pending tests to any worker that is
+  available, without any guaranteed order. Scheduling can be fine-tuned with
+  the `--maxschedchunk` option, see output of `pytest --help`.
+
+* ``--dist loadscope``: Tests are grouped by **module** for *test functions*
+  and by **class** for *test methods*. Groups are distributed to available
+  workers as whole units. This guarantees that all tests in a group run in the
+  same process. This can be useful if you have expensive module-level or
+  class-level fixtures. Grouping by class takes priority over grouping by
+  module.
+
+* ``--dist loadfile``: Tests are grouped by their containing file. Groups are
+  distributed to available workers as whole units. This guarantees that all
+  tests in a file run in the same worker.
+
+* ``--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. 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
+
+      @pytest.mark.xdist_group(name="group1")
+      def test1():
+          pass
+
+
+      class TestA:
+          @pytest.mark.xdist_group("group1")
+          def test2():
+              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
+  available workers. When a worker completes most of its assigned tests and
+  doesn't have enough tests to continue (currently, every worker needs at least
+  two tests in its queue), an attempt is made to reassign ("steal") a portion
+  of tests from some other worker's queue. The results should be similar to
+  the ``load`` method, but ``worksteal`` should handle tests with significantly
+  differing duration better, and, at the same time, it should provide similar
+  or better reuse of fixtures.
+
+* ``--dist no``: The normal pytest execution mode, runs one test at a time (no distribution at all).

docs/how-it-works.rst

@@ -0,0 +1,90 @@
+How it works?
+=============
+
+``xdist`` works by spawning one or more **workers**, which are
+controlled by the **controller**. Each **worker** is responsible for
+performing a full test collection and afterwards running tests as
+dictated by the **controller**.
+
+The execution flow is:
+
+1. **controller** spawns one or more **workers** at the beginning of the
+   test session. The communication between **controller** and **worker**
+   nodes makes use of `execnet <https://codespeak.net/execnet/>`__ and
+   its
+   `gateways <https://codespeak.net/execnet/basics.html#gateways-bootstrapping-python-interpreters>`__.
+   The actual interpreters executing the code for the **workers** might
+   be remote or local.
+
+2. Each **worker** itself is a mini pytest runner. **workers** at this
+   point perform a full test collection, sending back the collected
+   test-ids back to the **controller** which does not perform any
+   collection itself.
+
+3. The **controller** receives the result of the collection from all
+   nodes. At this point the **controller** performs some sanity check to
+   ensure that all **workers** collected the same tests (including
+   order), bailing out otherwise. If all is well, it converts the list
+   of test-ids into a list of simple indexes, where each index
+   corresponds to the position of that test in the original collection
+   list. This works because all nodes have the same collection list, and
+   saves bandwidth because the **controller** can now tell one of the
+   workers to just *execute test index 3* instead of passing the full
+   test id.
+
+4. If **dist-mode** is **each**: the **controller** just sends the full
+   list of test indexes to each node at this moment.
+
+5. If **dist-mode** is **load**: the **controller** takes around 25% of
+   the tests and sends them one by one to each **worker** in a round
+   robin fashion. The rest of the tests will be distributed later as
+   **workers** finish tests (see below).
+
+6. Note that ``pytest_xdist_make_scheduler`` hook can be used to
+   implement custom tests distribution logic.
+
+7. **workers** re-implement ``pytest_runtestloop``: pytest’s default
+   implementation basically loops over all collected items in the
+   ``session`` object and executes the ``pytest_runtest_protocol`` for
+   each test item, but in xdist **workers** sit idly waiting for
+   **controller** to send tests for execution. As tests are received by
+   **workers**, ``pytest_runtest_protocol`` is executed for each test.
+   Here it worth noting an implementation detail: **workers** always
+   must keep at least one test item on their queue due to how the
+   ``pytest_runtest_protocol(item, nextitem)`` hook is defined: in order
+   to pass the ``nextitem`` to the hook, the worker must wait for more
+   instructions from controller before executing that remaining test. If
+   it receives more tests, then it can safely call
+   ``pytest_runtest_protocol`` because it knows what the ``nextitem``
+   parameter will be. If it receives a “shutdown” signal, then it can
+   execute the hook passing ``nextitem`` as ``None``.
+
+8. As tests are started and completed at the **workers**, the results
+   are sent back to the **controller**, which then just forwards the
+   results to the appropriate pytest hooks: ``pytest_runtest_logstart``
+   and ``pytest_runtest_logreport``. This way other plugins (for example
+   ``junitxml``) can work normally. The **controller** (when in
+   dist-mode **load**) decides to send more tests to a node when a test
+   completes, using some heuristics such as test durations and how many
+   tests each **worker** still has to run.
+
+9. When the **controller** has no more pending tests it will send a
+   “shutdown” signal to all **workers**, which will then run their
+   remaining tests to completion and shut down. At this point the
+   **controller** will sit waiting for **workers** to shut down, still
+   processing events such as ``pytest_runtest_logreport``.
+
+FAQ
+---
+
+**Question**: Why does each worker do its own collection, as opposed to having the
+controller collect once and distribute from that collection to the
+workers?
+
+If collection was performed by controller then it would have to
+serialize collected items to send them through the wire, as workers live
+in another process. The problem is that test items are not easily
+(impossible?) to serialize, as they contain references to the test
+functions, fixture managers, config objects, etc. Even if one manages to
+serialize it, it seems it would be very hard to get it right and easy to
+break by any small change in pytest.

docs/how-to.rst

@@ -0,0 +1,232 @@
+How-tos
+-------
+
+This section show cases how to accomplish some specialized tasks with ``pytest-xdist``.
+
+Identifying the worker process during a test
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+*New in version 1.15.*
+
+If you need to determine the identity of a worker process in
+a test or fixture, you may use the ``worker_id`` fixture to do so:
+
+.. code-block:: python
+
+    @pytest.fixture()
+    def user_account(worker_id):
+        """use a different account in each xdist worker"""
+        return "account_%s" % worker_id
+
+When ``xdist`` is disabled (running with ``-n0`` for example), then
+``worker_id`` will return ``"master"``.
+
+Worker processes also have the following environment variables
+defined:
+
+.. envvar:: PYTEST_XDIST_WORKER
+
+The name of the worker, e.g., ``"gw2"``.
+
+.. envvar:: PYTEST_XDIST_WORKER_COUNT
+
+The total number of workers in this session, e.g., ``"4"`` when ``-n 4`` is given in the command-line.
+
+The information about the worker_id in a test is stored in the ``TestReport`` as
+well, under the ``worker_id`` attribute.
+
+Since version 2.0, the following functions are also available in the ``xdist`` module:
+
+
+.. autofunction:: xdist.is_xdist_worker
+.. autofunction:: xdist.is_xdist_controller
+.. autofunction:: xdist.is_xdist_master
+.. autofunction:: xdist.get_xdist_worker_id
+
+Identifying workers from the system environment
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+*New in version 2.4*
+
+If the `setproctitle`_ package is installed, ``pytest-xdist`` will use it to
+update the process title (command line) on its workers to show their current
+state.  The titles used are ``[pytest-xdist running] file.py/node::id`` and
+``[pytest-xdist idle]``, visible in standard tools like ``ps`` and ``top`` on
+Linux, Mac OS X and BSD systems.  For Windows, please follow `setproctitle`_'s
+pointer regarding the Process Explorer tool.
+
+This is intended purely as an UX enhancement, e.g. to track down issues with
+long-running or CPU intensive tests.  Errors in changing the title are ignored
+silently.  Please try not to rely on the title format or title changes in
+external scripts.
+
+.. _`setproctitle`: https://pypi.org/project/setproctitle/
+
+
+Uniquely identifying the current test run
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+*New in version 1.32.*
+
+If you need to globally distinguish one test run from others in your
+workers, you can use the ``testrun_uid`` fixture. For instance, let's say you
+wanted to create a separate database for each test run:
+
+.. code-block:: python
+
+    import pytest
+    from posix_ipc import Semaphore, O_CREAT
+
+
+    @pytest.fixture(scope="session", autouse=True)
+    def create_unique_database(testrun_uid):
+        """create a unique database for this particular test run"""
+        database_url = f"psql://myapp-{testrun_uid}"
+
+        with Semaphore(f"/{testrun_uid}-lock", flags=O_CREAT, initial_value=1):
+            if not database_exists(database_url):
+                create_database(database_url)
+
+
+    @pytest.fixture()
+    def db(testrun_uid):
+        """retrieve unique database"""
+        database_url = f"psql://myapp-{testrun_uid}"
+        return database_get_instance(database_url)
+
+
+Additionally, during a test run, the following environment variable is defined:
+
+.. envvar:: PYTEST_XDIST_TESTRUNUID
+
+The unique id of the test run.
+
+Accessing ``sys.argv`` from the controller node in workers
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To access the ``sys.argv`` passed to the command-line of the controller node, use
+``request.config.workerinput["mainargv"]``.
+
+
+Specifying test exec environments in an ini file
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+You can use pytest's ini file configuration to avoid typing common options.
+You can for example make running with three subprocesses your default like this:
+
+.. code-block:: ini
+
+    [pytest]
+    addopts = -n3
+
+You can also add default environments like this:
+
+.. code-block:: ini
+
+    [pytest]
+    addopts = --tx ssh=myhost//python=python3.9 --tx ssh=myhost//python=python3.6
+
+and then just type::
+
+    pytest --dist=each
+
+to run tests in each of the environments.
+
+
+Specifying "rsync" dirs in an ini-file
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+In a ``tox.ini`` or ``setup.cfg`` file in your root project directory
+you may specify directories to include or to exclude in synchronisation:
+
+.. code-block:: ini
+
+    [pytest]
+    rsyncdirs = . mypkg helperpkg
+    rsyncignore = .hg
+
+These directory specifications are relative to the directory
+where the configuration file was found.
+
+.. _`pytest-xdist`: http://pypi.python.org/pypi/pytest-xdist
+.. _`pytest-xdist repository`: https://github.com/pytest-dev/pytest-xdist
+.. _`pytest`: http://pytest.org
+
+
+Making session-scoped fixtures execute only once
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+``pytest-xdist`` is designed so that each worker process will perform its own collection and execute
+a subset of all tests. This means that tests in different processes requesting a high-level
+scoped fixture (for example ``session``) will execute the fixture code more than once, which
+breaks expectations and might be undesired in certain situations.
+
+While ``pytest-xdist`` does not have a builtin support for ensuring a session-scoped fixture is
+executed exactly once, this can be achieved by using a lock file for inter-process communication.
+
+The example below needs to execute the fixture ``session_data`` only once (because it is
+resource intensive, or needs to execute only once to define configuration options, etc), so it makes
+use of a `FileLock <https://pypi.org/project/filelock/>`_ to produce the fixture data only once
+when the first process requests the fixture, while the other processes will then read
+the data from a file.
+
+Here is the code:
+
+.. code-block:: python
+
+    import json
+
+    import pytest
+    from filelock import FileLock
+
+
+    @pytest.fixture(scope="session")
+    def session_data(tmp_path_factory, worker_id):
+        if worker_id == "master":
+            # not executing in with multiple workers, just produce the data and let
+            # pytest's fixture caching do its job
+            return produce_expensive_data()
+
+        # get the temp directory shared by all workers
+        root_tmp_dir = tmp_path_factory.getbasetemp().parent
+
+        fn = root_tmp_dir / "data.json"
+        with FileLock(str(fn) + ".lock"):
+            if fn.is_file():
+                data = json.loads(fn.read_text())
+            else:
+                data = produce_expensive_data()
+                fn.write_text(json.dumps(data))
+        return data
+
+
+The example above can also be use in cases a fixture needs to execute exactly once per test session, like
+initializing a database service and populating initial tables.
+
+This technique might not work for every case, but should be a starting point for many situations
+where executing a high-scope fixture exactly once is important.
+
+
+Creating one log file for each worker
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To create one log file for each worker with ``pytest-xdist``, you can leverage :envvar:`PYTEST_XDIST_WORKER`
+to generate a unique filename for each worker.
+
+Example:
+
+.. code-block:: python
+
+    # content of conftest.py
+    def pytest_configure(config):
+        worker_id = os.environ.get("PYTEST_XDIST_WORKER")
+        if worker_id is not None:
+            logging.basicConfig(
+                format=config.getini("log_file_format"),
+                filename=f"tests_{worker_id}.log",
+                level=config.getini("log_file_level"),
+            )
+
+
+When running the tests with ``-n3``, for example, three files will be created in the current directory:
+``tests_gw0.log``, ``tests_gw1.log`` and ``tests_gw2.log``.

docs/index.rst

@@ -0,0 +1,63 @@
+pytest-xdist
+============
+
+The `pytest-xdist`_ plugin extends pytest with new test execution modes, the most used being distributing
+tests across multiple CPUs to speed up test execution::
+
+    pytest -n auto
+
+With this call, pytest will spawn a number of workers processes equal to the number of available CPUs, and distribute
+the tests randomly across them.
+
+.. note::
+    Due to how pytest-xdist is implemented, the ``-s/--capture=no`` option does not work.
+
+
+Installation
+------------
+
+Install the plugin with::
+
+    pip install pytest-xdist
+
+
+To use ``psutil`` for detection of the number of CPUs available, install the ``psutil`` extra::
+
+    pip install pytest-xdist[psutil]
+
+Features
+--------
+
+* Test run :ref:`parallelization`: tests can be executed across  multiple CPUs or hosts.
+  This allows to speed up development or to use special resources of :ref:`remote machines`.
+
+* ``--looponfail``: run your tests repeatedly in a subprocess.  After each run
+  pytest waits until a file in your project changes and then re-runs
+  the previously failing tests.  This is repeated until all tests pass
+  after which again a full run is performed (DEPRECATED).
+
+* :ref:`Multi-Platform` coverage: you can specify different Python interpreters
+  or different platforms and run tests in parallel on all of them.
+
+  Before running tests remotely, ``pytest`` efficiently "rsyncs" your
+  program source code to the remote place.
+  You may specify different Python versions and interpreters. It does not
+  installs/synchronize dependencies however.
+
+  **Note**: this mode exists mostly for backward compatibility, as modern development
+  relies on continuous integration for multi-platform testing.
+
+
+
+.. toctree::
+    :maxdepth: 2
+    :caption: Contents:
+
+    distribution
+    subprocess
+    remote
+    crash
+    how-to
+    how-it-works
+    known-limitations
+    changelog

docs/known-limitations.rst

@@ -0,0 +1,71 @@
+Known limitations
+=================
+
+pytest-xdist has some limitations that may be supported in pytest but can't be supported in pytest-xdist.
+
+Order and amount of test must be consistent
+-------------------------------------------
+
+It is not possible to have tests that differ in order or their amount across workers.
+
+This is especially true with ``pytest.mark.parametrize``, when values are produced with sets or other unordered iterables/generators.
+
+
+Example:
+
+.. code-block:: python
+
+    import pytest
+
+
+    @pytest.mark.parametrize("param", {"a", "b"})
+    def test_pytest_parametrize_unordered(param):
+        pass
+
+In the example above, the fact that ``set`` are not necessarily ordered can cause different workers
+to collect tests in different order, which will throw an error.
+
+Workarounds
+~~~~~~~~~~~
+
+A solution to this is to guarantee that the parametrized values have the same order.
+
+Some solutions:
+
+* Convert your sequence to a ``list``.
+
+  .. code-block:: python
+
+    import pytest
+
+
+    @pytest.mark.parametrize("param", ["a", "b"])
+    def test_pytest_parametrize_unordered(param):
+        pass
+
+* Sort your sequence, guaranteeing order.
+
+  .. code-block:: python
+
+    import pytest
+
+
+    @pytest.mark.parametrize("param", sorted({"a", "b"}))
+    def test_pytest_parametrize_unordered(param):
+        pass
+
+Output (stdout and stderr) from workers
+---------------------------------------
+
+The ``-s``/``--capture=no`` option is meant to disable pytest capture, so users can then see stdout and stderr output in the terminal from tests and application code in real time.
+
+However, this option does not work with ``pytest-xdist`` because `execnet <https://github.com/pytest-dev/execnet>`__ the underlying library used for communication between master and workers, does not support transferring stdout/stderr from workers.
+
+Currently, there are no plans to support this in ``pytest-xdist``.
+
+Debugging
+~~~~~~~~~
+
+This also means that debugging using PDB (or any other debugger that wants to use standard I/O) will not work. The ``--pdb`` option is disabled when distributing tests with ``pytest-xdist`` for this reason.
+
+It is generally likely best to use ``pytest-xdist`` to find failing tests and then debug them without distribution; however, if you need to debug from within a worker process (for example, to address failures that only happen when running tests concurrently), remote debuggers (for example, `python-remote-pdb <https://github.com/ionelmc/python-remote-pdb>`__ or `python-web-pdb <https://github.com/romanvm/python-web-pdb>`__) have been reported to work for this purpose.

docs/remote.rst

@@ -0,0 +1,100 @@
+
+.. _`Multi-Platform`:
+.. _`remote machines`:
+
+Sending tests to remote SSH accounts
+====================================
+
+.. deprecated:: 3.0
+
+.. warning::
+
+    The ``rsync`` feature is deprecated because its implementation is faulty
+    in terms of reproducing the development environment in the remote
+    worker, and there is no clear solution moving forward.
+
+    For that reason, ``rsync`` is scheduled to be removed in release 4.0, to let the team
+    focus on a smaller set of features.
+
+    Note that SSH and socket server are not planned for removal, as they are part
+    of the ``execnet`` feature set.
+
+Suppose you have a package ``mypkg`` which contains some
+tests that you can successfully run locally. And you
+have a ssh-reachable machine ``myhost``.  Then
+you can ad-hoc distribute your tests by typing::
+
+    pytest -d  --rsyncdir mypkg --tx ssh=myhostpopen mypkg/tests/unit/test_something.py
+
+This will synchronize your :code:`mypkg` package directory
+to a remote ssh account and then locally collect tests
+and send them to remote places for execution.
+
+You can specify multiple :code:`--rsyncdir` directories
+to be sent to the remote side.
+
+.. note::
+
+  For pytest to collect and send tests correctly
+  you not only need to make sure all code and tests
+  directories are rsynced, but that any test (sub) directory
+  also has an :code:`__init__.py` file because internally
+  pytest references tests as a fully qualified python
+  module path.  **You will otherwise get strange errors**
+  during setup of the remote side.
+
+
+You can specify multiple :code:`--rsyncignore` glob patterns
+to be ignored when file are sent to the remote side.
+There are also internal ignores: :code:`.*, *.pyc, *.pyo, *~`
+Those you cannot override using rsyncignore command-line or
+ini-file option(s).
+
+
+Sending tests to remote Socket Servers
+--------------------------------------
+
+Download the single-module `socketserver.py`_ Python program
+and run it like this::
+
+    python socketserver.py
+
+It will tell you that it starts listening on the default
+port.  You can now on your home machine specify this
+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
+---------------------------------------
+
+The basic command to run tests on multiple platforms is::
+
+    pytest --dist=each --tx=spec1 --tx=spec2
+
+If you specify a windows host, an OSX host and a Linux
+environment this command will send each tests to all
+platforms - and report back failures from all platforms
+at once. The specifications strings use the `xspec syntax`_.
+
+.. _`xspec syntax`: https://codespeak.net/execnet/basics.html#xspec
+
+.. _`execnet`: https://codespeak.net/execnet
+
+.. _`socketserver.py`: https://raw.githubusercontent.com/pytest-dev/execnet/master/src/execnet/script/socketserver.py

docs/requirements.txt

@@ -0,0 +1,2 @@
+sphinx
+sphinx-rtd-theme

docs/subprocess.rst

@@ -0,0 +1,16 @@
+Running tests in a Python subprocess
+====================================
+
+To instantiate a ``python3.9`` subprocess and send tests to it, you may type::
+
+    pytest -d --tx popen//python=python3.9
+
+This will start a subprocess which is run with the ``python3.9``
+Python interpreter, found in your system binary lookup path.
+
+If you prefix the --tx option value like this::
+
+    --tx 3*popen//python=python3.9
+
+then three subprocesses would be created and tests
+will be load-balanced across these three processes.

example/boxed.txt

@@ -1,9 +1,9 @@
-.. note::
+.. warning::
 
   Since 1.19.0, the actual implementation of the ``--boxed`` option has been moved to a
   separate plugin, `pytest-forked <https://github.com/pytest-dev/pytest-forked>`_
-  which can be installed independently. The ``--boxed`` command-line options remains
+  which can be installed independently. The ``--boxed`` command-line option is deprecated
-  for backward compatibility reasons.
+  and will be removed in pytest-xdist 3.0.0; use ``--forked`` from pytest-forked instead.
 
 
 If your testing involves C or C++ libraries you might have to deal

pyproject.toml

@@ -1,3 +1,146 @@
+[build-system]
+requires = [
+  "setuptools>=77.0",
+  "setuptools-scm[toml]>=6.2.3",
+]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pytest-xdist"
+description = "pytest xdist plugin for distributed testing, most importantly across multiple CPUs"
+readme = "README.rst"
+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",
+    "Operating System :: POSIX",
+    "Operating System :: Microsoft :: Windows",
+    "Operating System :: MacOS :: MacOS X",
+    "Topic :: Software Development :: Testing",
+    "Topic :: Software Development :: Quality Assurance",
+    "Topic :: Utilities",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "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.9"
+dependencies = [
+    "execnet>=2.1",
+    "pytest>=7.0.0",
+]
+dynamic = ["version"]
+
+[project.urls]
+Homepage = "https://github.com/pytest-dev/pytest-xdist"
+Documentation = "https://pytest-xdist.readthedocs.io/en/latest"
+Changelog = "https://pytest-xdist.readthedocs.io/en/latest/changelog.html"
+Source = "https://github.com/pytest-dev/pytest-xdist"
+Tracker = "https://github.com/pytest-dev/pytest-xdist/issues"
+
+[project.entry-points.pytest11]
+xdist = "xdist.plugin"
+"xdist.looponfail" = "xdist.looponfail"
+
+[project.optional-dependencies]
+testing = ["filelock"]
+psutil = ["psutil>=3.0"]
+setproctitle = ["setproctitle"]
+
+[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"]
+
+[tool.ruff.format]
+docstring-code-format = true
+
+[tool.ruff.lint]
+select = [
+    "B",        # bugbear
+    "D",        # pydocstyle
+    "E",        # pycodestyle
+    "F",        # pyflakes
+    "I",        # isort
+    "PYI",      # flake8-pyi
+    "UP",       # pyupgrade
+    "RUF",      # ruff
+    "W",        # pycodestyle
+    "T10",      # flake8-debugger
+    "PIE",      # flake8-pie
+    "FA",       # flake8-future-annotations
+    "PGH",      # pygrep-hooks
+    "PLE",      # pylint error
+    "PLW",      # pylint warning
+    "PLR1714",  # Consider merging multiple comparisons
+]
+ignore = [
+    # bugbear ignore
+    "B011",     # Do not `assert False` (`python -O` removes these calls)
+    "B028",     # No explicit `stacklevel` keyword argument found
+    # pydocstyle ignore
+    "D100",     # Missing docstring in public module
+    "D101",     # Missing docstring in public class
+    "D102",     # Missing docstring in public method
+    "D103",     # Missing docstring in public function
+    "D104",     # Missing docstring in public package
+    "D105",     # Missing docstring in magic method
+    "D106",     # Missing docstring in public nested class
+    "D107",     # Missing docstring in `__init__`
+    "D209",     # Multi-line docstring closing quotes should be on a separate line
+    "D205",     # 1 blank line required between summary line and description
+    "D400",     # First line should end with a period
+    "D401",     # First line of docstring should be in imperative mood
+    # ruff ignore
+    "RUF012",   # Mutable class attributes should be annotated with `typing.ClassVar`
+    # pylint ignore
+    "PLW0603",  # Using the global statement
+    "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]
+# In order to be able to format for 88 char in ruff format
+max-line-length = 120
+
+[tool.ruff.lint.pydocstyle]
+convention = "pep257"
+
+[tool.ruff.lint.isort]
+force-single-line = true
+combine-as-imports = true
+force-sort-within-sections = true
+order-by-type = false
+lines-after-imports = 2
+
+[tool.ruff.lint.per-file-ignores]
+"src/xdist/_version.py" = ["I001"]
+
+[tool.mypy]
+mypy_path = ["src"]
+files = ["src", "testing"]
+strict = true
+warn_unreachable = true
+[[tool.mypy.overrides]]
+module = ["xdist._version"]
+ignore_missing_imports = true
+
+
 [tool.towncrier]
 package = "xdist"
 filename = "CHANGELOG.rst"
@@ -5,32 +148,23 @@ directory = "changelog/"
 title_format = "pytest-xdist {version} ({project_date})"
 template = "changelog/_template.rst"
 
-  [[tool.towncrier.type]]
+[tool.towncrier.fragment.removal]
-  directory = "removal"
+name = "Removals"
-  name = "Deprecations and Removals"
-  showcontent = true
 
-  [[tool.towncrier.type]]
+[tool.towncrier.fragment.deprecation]
-  directory = "feature"
+name = "Deprecations"
-  name = "Features"
-  showcontent = true
 
-  [[tool.towncrier.type]]
+[tool.towncrier.fragment.feature]
-  directory = "bugfix"
+name = "Features"
-  name = "Bug Fixes"
-  showcontent = true
 
-  [[tool.towncrier.type]]
+[tool.towncrier.fragment.bugfix]
-  directory = "vendor"
+name = "Bug Fixes"
-  name = "Vendored Libraries"
-  showcontent = true
 
-  [[tool.towncrier.type]]
+[tool.towncrier.fragment.vendor]
-  directory = "doc"
+name = "Vendored Libraries"
-  name = "Improved Documentation"
-  showcontent = true
 
-  [[tool.towncrier.type]]
+[tool.towncrier.fragment.doc]
-  directory = "trivial"
+name = "Improved Documentation"
-  name = "Trivial Changes"
+
-  showcontent = true
+[tool.towncrier.fragment.trivial]
+name = "Trivial Changes"

setup.cfg

@@ -1,5 +0,0 @@
-[metadata]
-license_file = LICENSE
-
-[flake8]
-max-line-length = 100

setup.py

@@ -1,48 +0,0 @@
-from setuptools import setup, find_packages
-
-install_requires = ["execnet>=1.1", "pytest>=6.0.0", "pytest-forked"]
-
-
-with open("README.rst") as f:
-    long_description = f.read()
-
-setup(
-    name="pytest-xdist",
-    use_scm_version={"write_to": "src/xdist/_version.py"},
-    description="pytest xdist plugin for distributed testing and loop-on-failing modes",
-    long_description=long_description,
-    license="MIT",
-    author="holger krekel and contributors",
-    author_email="pytest-dev@python.org,holger@merlinux.eu",
-    url="https://github.com/pytest-dev/pytest-xdist",
-    platforms=["linux", "osx", "win32"],
-    packages=find_packages(where="src"),
-    package_dir={"": "src"},
-    extras_require={"testing": ["filelock"], "psutil": ["psutil>=3.0"]},
-    entry_points={
-        "pytest11": ["xdist = xdist.plugin", "xdist.looponfail = xdist.looponfail"]
-    },
-    zip_safe=False,
-    python_requires=">=3.6",
-    install_requires=install_requires,
-    setup_requires=["setuptools_scm"],
-    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",
-        "Topic :: Software Development :: Testing",
-        "Topic :: Software Development :: Quality Assurance",
-        "Topic :: Utilities",
-        "Programming Language :: Python",
-        "Programming Language :: Python :: 3",
-        "Programming Language :: Python :: 3 :: Only",
-        "Programming Language :: Python :: 3.6",
-        "Programming Language :: Python :: 3.7",
-        "Programming Language :: Python :: 3.8",
-        "Programming Language :: Python :: 3.9",
-    ],
-)

src/xdist/__init__.py

@@ -1,15 +1,14 @@
-from xdist.plugin import (
-    is_xdist_worker,
-    is_xdist_master,
-    get_xdist_worker_id,
-    is_xdist_controller,
-)
 from xdist._version import version as __version__
+from xdist.plugin import get_xdist_worker_id
+from xdist.plugin import is_xdist_controller
+from xdist.plugin import is_xdist_master
+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

@@ -0,0 +1,20 @@
+from collections.abc import Iterator
+from itertools import chain
+import os
+from pathlib import Path
+from typing import Callable
+
+
+def visit_path(
+    path: Path, *, filter: Callable[[Path], bool], recurse: Callable[[Path], bool]
+) -> Iterator[Path]:
+    """
+    Implements the interface of ``py.path.local.visit()`` for Path objects,
+    to simplify porting the code over from ``py.path.local``.
+    """
+    for dirpath, dirnames, filenames in os.walk(path):
+        dirnames[:] = [x for x in dirnames if recurse(Path(dirpath, x))]
+        for name in chain(dirnames, filenames):
+            p = Path(dirpath, name)
+            if filter(p):
+                yield p

src/xdist/dsession.py

@@ -1,16 +1,28 @@
-import py
+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
+import warnings
+
+import execnet
 import pytest
 
+from xdist.remote import Producer
+from xdist.remote import WorkerInfo
+from xdist.scheduler import EachScheduling
+from xdist.scheduler import LoadFileScheduling
+from xdist.scheduler import LoadGroupScheduling
+from xdist.scheduler import LoadScheduling
+from xdist.scheduler import LoadScopeScheduling
+from xdist.scheduler import Scheduling
+from xdist.scheduler import WorkStealingScheduling
 from xdist.workermanage import NodeManager
-from xdist.scheduler import (
+from xdist.workermanage import WorkerController
-    EachScheduling,
-    LoadScheduling,
-    LoadScopeScheduling,
-    LoadFileScheduling,
-)
-
-
-from queue import Empty, Queue
 
 
 class Interrupted(KeyboardInterrupt):
@@ -18,7 +30,7 @@ class Interrupted(KeyboardInterrupt):
 
 
 class DSession:
-    """A pytest plugin which runs a distributed test session
+    """A pytest plugin which runs a distributed test session.
 
     At the beginning of the test session this creates a NodeManager
     instance which creates and starts all nodes.  Nodes then emit
@@ -31,44 +43,44 @@ class DSession:
     it will wait for instructions.
     """
 
-    def __init__(self, config):
+    shouldstop: bool | str
+
+    def __init__(self, config: pytest.Config) -> None:
         self.config = config
-        self.log = py.log.Producer("dsession")
+        self.log = Producer("dsession", enabled=config.option.debug)
-        if not config.option.debug:
+        self.nodemanager: NodeManager | None = None
-            py.log.setconsumer(self.log._keywords, None)
+        self.sched: Scheduling | None = None
-        self.nodemanager = None
-        self.sched = None
         self.shuttingdown = False
         self.countfailures = 0
-        self.maxfail = config.getvalue("maxfail")
+        self.maxfail: int = config.getvalue("maxfail")
-        self.queue = Queue()
+        self.queue: Queue[tuple[str, dict[str, Any]]] = Queue()
-        self._session = None
+        self._session: pytest.Session | None = None
-        self._failed_collection_errors = {}
+        self._failed_collection_errors: dict[object, bool] = {}
-        self._active_nodes = set()
+        self._active_nodes: set[WorkerController] = set()
         self._failed_nodes_count = 0
         self._max_worker_restart = get_default_max_worker_restart(self.config)
         # summary message to print at the end of the session
-        self._summary_report = None
+        self._summary_report: str | None = None
         self.terminal = config.pluginmanager.getplugin("terminalreporter")
         if self.terminal:
             self.trdist = TerminalDistReporter(config)
             config.pluginmanager.register(self.trdist, "terminaldistreporter")
 
     @property
-    def session_finished(self):
+    def session_finished(self) -> bool:
-        """Return True if the distributed session has finished
+        """Return True if the distributed session has finished.
 
         This means all nodes have executed all test items.  This is
         used by pytest_runtestloop to break out of its loop.
         """
         return bool(self.shuttingdown and not self._active_nodes)
 
-    def report_line(self, line):
+    def report_line(self, line: str) -> None:
         if self.terminal and self.config.option.verbose >= 0:
             self.terminal.write_line(line)
 
-    @pytest.mark.trylast
+    @pytest.hookimpl(trylast=True)
-    def pytest_sessionstart(self, session):
+    def pytest_sessionstart(self, session: pytest.Session) -> None:
         """Creates and starts the nodes.
 
         The nodes are setup to put their events onto self.queue.  As
@@ -79,43 +91,59 @@ class DSession:
         self._active_nodes.update(nodes)
         self._session = session
 
-    def pytest_sessionfinish(self, session):
+    @pytest.hookimpl
+    def pytest_sessionfinish(self) -> None:
         """Shutdown all nodes."""
         nm = getattr(self, "nodemanager", None)  # if not fully initialized
         if nm is not None:
             nm.teardown_nodes()
         self._session = None
 
-    def pytest_collection(self):
+    @pytest.hookimpl
+    def pytest_collection(self) -> bool:
         # prohibit collection of test items in controller process
         return True
 
-    @pytest.mark.trylast
+    @pytest.hookimpl(trylast=True)
-    def pytest_xdist_make_scheduler(self, config, log):
+    def pytest_xdist_make_scheduler(
+        self,
+        config: pytest.Config,
+        log: Producer,
+    ) -> Scheduling | None:
         dist = config.getvalue("dist")
-        schedulers = {
+        if dist == "each":
-            "each": EachScheduling,
+            return EachScheduling(config, log)
-            "load": LoadScheduling,
+        if dist == "load":
-            "loadscope": LoadScopeScheduling,
+            return LoadScheduling(config, log)
-            "loadfile": LoadFileScheduling,
+        if dist == "loadscope":
-        }
+            return LoadScopeScheduling(config, log)
-        return schedulers[dist](config, log)
+        if dist == "loadfile":
+            return LoadFileScheduling(config, log)
+        if dist == "loadgroup":
+            return LoadGroupScheduling(config, log)
+        if dist == "worksteal":
+            return WorkStealingScheduling(config, log)
+        return None
 
-    def pytest_runtestloop(self):
+    @pytest.hookimpl
+    def pytest_runtestloop(self) -> bool:
         self.sched = self.config.hook.pytest_xdist_make_scheduler(
             config=self.config, log=self.log
         )
         assert self.sched is not None
 
         self.shouldstop = False
+        pending_exception = None
         while not self.session_finished:
             self.loop_once()
             if self.shouldstop:
                 self.triggershutdown()
-                raise Interrupted(str(self.shouldstop))
+                pending_exception = Interrupted(str(self.shouldstop))
+        if pending_exception:
+            raise pending_exception
         return True
 
-    def loop_once(self):
+    def loop_once(self) -> None:
         """Process one callback from one of the workers."""
         while 1:
             if not self._active_nodes:
@@ -133,6 +161,7 @@ class DSession:
         call = getattr(self, method)
         self.log("calling method", method, kwargs)
         call(**kwargs)
+        assert self.sched is not None
         if self.sched.tests_finished:
             self.triggershutdown()
 
@@ -140,7 +169,11 @@ class DSession:
     # callbacks for processing events from workers
     #
 
-    def worker_workerready(self, node, workerinfo):
+    def worker_workerready(
+        self,
+        node: WorkerController,
+        workerinfo: WorkerInfo,
+    ) -> None:
         """Emitted when a node first starts up.
 
         This adds the node to the scheduler, nodes continue with
@@ -154,9 +187,10 @@ class DSession:
         if self.shuttingdown:
             node.shutdown()
         else:
+            assert self.sched is not None
             self.sched.add_node(node)
 
-    def worker_workerfinished(self, node):
+    def worker_workerfinished(self, node: WorkerController) -> None:
         """Emitted when node executes its pytest_sessionfinish hook.
 
         Removes the node from the scheduler.
@@ -166,15 +200,26 @@ class DSession:
         """
         self.config.hook.pytest_testnodedown(node=node, error=None)
         if node.workeroutput["exitstatus"] == 2:  # keyboard-interrupt
-            self.shouldstop = "{} received keyboard-interrupt".format(node)
+            self.shouldstop = f"{node} received keyboard-interrupt"
             self.worker_errordown(node, "keyboard-interrupt")
             return
-        if node in self.sched.nodes:
+        shouldfail = node.workeroutput["shouldfail"]
-            crashitem = self.sched.remove_node(node)
+        shouldstop = node.workeroutput["shouldstop"]
-            assert not crashitem, (crashitem, node)
+        for shouldx in [shouldfail, shouldstop]:
+            if shouldx:
+                if not self.shouldstop:
+                    self.shouldstop = shouldx
+                break
+        else:
+            assert self.sched is not None
+            if node in self.sched.nodes:
+                crashitem = self.sched.remove_node(node)
+                assert not crashitem, (crashitem, node)
         self._active_nodes.remove(node)
 
-    def worker_internal_error(self, node, formatted_error):
+    def worker_internal_error(
+        self, node: WorkerController, formatted_error: str
+    ) -> None:
         """
         pytest_internalerror() was called on the worker.
 
@@ -186,15 +231,14 @@ class DSession:
         try:
             assert False, formatted_error
         except AssertionError:
-            from _pytest._code import ExceptionInfo
+            excinfo = pytest.ExceptionInfo.from_current()
-
-            excinfo = ExceptionInfo.from_current()
             excrepr = excinfo.getrepr()
             self.config.hook.pytest_internalerror(excrepr=excrepr, excinfo=excinfo)
 
-    def worker_errordown(self, node, error):
+    def worker_errordown(self, node: WorkerController, error: object | None) -> None:
         """Emitted by the WorkerController when a node dies."""
         self.config.hook.pytest_testnodedown(node=node, error=error)
+        assert self.sched is not None
         try:
             crashitem = self.sched.remove_node(node)
         except KeyError:
@@ -210,25 +254,27 @@ class DSession:
         )
         if maximum_reached:
             if self._max_worker_restart == 0:
-                msg = "worker {} crashed and worker restarting disabled".format(
+                msg = f"worker {node.gateway.id} crashed and worker restarting disabled"
-                    node.gateway.id
-                )
             else:
-                msg = "maximum crashed workers reached: %d" % self._max_worker_restart
+                msg = f"maximum crashed workers reached: {self._max_worker_restart}"
             self._summary_report = msg
             self.report_line("\n" + msg)
             self.triggershutdown()
         else:
             self.report_line("\nreplacing crashed worker %s" % node.gateway.id)
+            self.shuttingdown = False
             self._clone_node(node)
         self._active_nodes.remove(node)
 
-    def pytest_terminal_summary(self, terminalreporter):
+    @pytest.hookimpl
+    def pytest_terminal_summary(self, terminalreporter: Any) -> None:
         if self.config.option.verbose >= 0 and self._summary_report:
-            terminalreporter.write_sep("=", "xdist: {}".format(self._summary_report))
+            terminalreporter.write_sep("=", f"xdist: {self._summary_report}")
 
-    def worker_collectionfinish(self, node, ids):
+    def worker_collectionfinish(
-        """worker has finished test collection.
+        self, node: WorkerController, ids: Sequence[str]
+    ) -> None:
+        """Worker has finished test collection.
 
         This adds the collection for this node to the scheduler.  If
         the scheduler indicates collection is finished (i.e. all
@@ -241,43 +287,78 @@ class DSession:
         self.config.hook.pytest_xdist_node_collection_finished(node=node, ids=ids)
         # tell session which items were effectively collected otherwise
         # the controller node will finish the session with EXIT_NOTESTSCOLLECTED
+        assert self._session is not None
         self._session.testscollected = len(ids)
+        assert self.sched is not None
         self.sched.add_node_collection(node, ids)
         if self.terminal:
-            self.trdist.setstatus(node.gateway.spec, "[%d]" % (len(ids)))
+            self.trdist.setstatus(
+                node.gateway.spec, WorkerStatus.CollectionDone, tests_collected=len(ids)
+            )
         if self.sched.collection_is_completed:
             if self.terminal and not self.sched.has_pending:
                 self.trdist.ensure_show_status()
                 self.terminal.write_line("")
                 if self.config.option.verbose > 0:
                     self.terminal.write_line(
-                        "scheduling tests via %s" % (self.sched.__class__.__name__)
+                        f"scheduling tests via {self.sched.__class__.__name__}"
                     )
             self.sched.schedule()
 
-    def worker_logstart(self, node, nodeid, location):
+    def worker_logstart(
+        self,
+        node: WorkerController,
+        nodeid: str,
+        location: tuple[str, int | None, str],
+    ) -> None:
         """Emitted when a node calls the pytest_runtest_logstart hook."""
         self.config.hook.pytest_runtest_logstart(nodeid=nodeid, location=location)
 
-    def worker_logfinish(self, node, nodeid, location):
+    def worker_logfinish(
+        self,
+        node: WorkerController,
+        nodeid: str,
+        location: tuple[str, int | None, str],
+    ) -> None:
         """Emitted when a node calls the pytest_runtest_logfinish hook."""
         self.config.hook.pytest_runtest_logfinish(nodeid=nodeid, location=location)
 
-    def worker_testreport(self, node, rep):
+    def worker_testreport(self, node: WorkerController, rep: pytest.TestReport) -> None:
         """Emitted when a node calls the pytest_runtest_logreport hook."""
-        rep.node = node
+        rep.node = node  # type: ignore[attr-defined]
         self.config.hook.pytest_runtest_logreport(report=rep)
         self._handlefailures(rep)
 
-    def worker_runtest_protocol_complete(self, node, item_index, duration):
+    def worker_runtest_protocol_complete(
+        self, node: WorkerController, item_index: int, duration: float
+    ) -> None:
         """
         Emitted when a node fires the 'runtest_protocol_complete' event,
         signalling that a test has completed the runtestprotocol and should be
         removed from the pending list in the scheduler.
         """
+        assert self.sched is not None
         self.sched.mark_test_complete(node, item_index, duration)
 
-    def worker_collectreport(self, node, rep):
+    def worker_unscheduled(
+        self, node: WorkerController, indices: Sequence[int]
+    ) -> None:
+        """
+        Emitted when a node fires the 'unscheduled' event, signalling that
+        some tests have been removed from the worker's queue and should be
+        sent to some worker again.
+
+        This should happen only in response to 'steal' command, so schedulers
+        not using 'steal' command don't have to implement it.
+        """
+        assert self.sched is not None
+        self.sched.remove_pending_tests_from_node(node, indices)
+
+    def worker_collectreport(
+        self,
+        node: WorkerController,
+        rep: pytest.CollectReport | pytest.TestReport,
+    ) -> None:
         """Emitted when a node calls the pytest_collectreport hook.
 
         Because we only need the report when there's a failure/skip, as optimization
@@ -286,19 +367,20 @@ class DSession:
         assert not rep.passed
         self._failed_worker_collectreport(node, rep)
 
-    def worker_warning_captured(self, warning_message, when, item):
+    def worker_warning_recorded(
-        """Emitted when a node calls the pytest_warning_captured hook (deprecated in 6.0)."""
+        self,
-        kwargs = dict(warning_message=warning_message, when=when, item=item)
+        warning_message: warnings.WarningMessage,
-        self.config.hook.pytest_warning_captured.call_historic(kwargs=kwargs)
+        when: str,
-
+        nodeid: str,
-    def worker_warning_recorded(self, warning_message, when, nodeid, location):
+        location: tuple[str, int, str] | None,
+    ) -> None:
         """Emitted when a node calls the pytest_warning_recorded hook."""
         kwargs = dict(
             warning_message=warning_message, when=when, nodeid=nodeid, location=location
         )
         self.config.hook.pytest_warning_recorded.call_historic(kwargs=kwargs)
 
-    def _clone_node(self, node):
+    def _clone_node(self, node: WorkerController) -> WorkerController:
         """Return new node based on an existing one.
 
         This is normally for when a node dies, this will copy the spec
@@ -308,12 +390,17 @@ class DSession:
         """
         spec = node.gateway.spec
         spec.id = None
+        assert self.nodemanager is not None
         self.nodemanager.group.allocate_id(spec)
-        node = self.nodemanager.setup_node(spec, self.queue.put)
+        clone = self.nodemanager.setup_node(spec, self.queue.put)
-        self._active_nodes.add(node)
+        self._active_nodes.add(clone)
-        return node
+        return clone
 
-    def _failed_worker_collectreport(self, node, rep):
+    def _failed_worker_collectreport(
+        self,
+        node: WorkerController,
+        rep: pytest.CollectReport | pytest.TestReport,
+    ) -> None:
         # Check we haven't already seen this report (from
         # another worker).
         if rep.longrepr not in self._failed_collection_errors:
@@ -321,28 +408,41 @@ class DSession:
             self.config.hook.pytest_collectreport(report=rep)
             self._handlefailures(rep)
 
-    def _handlefailures(self, rep):
+    def _handlefailures(
+        self,
+        rep: pytest.CollectReport | pytest.TestReport,
+    ) -> None:
         if rep.failed:
             self.countfailures += 1
-            if self.maxfail and self.countfailures >= self.maxfail:
+            if (
-                self.shouldstop = "stopping after %d failures" % (self.countfailures)
+                self.maxfail
+                and self.countfailures >= self.maxfail
+                and not self.shouldstop
+            ):
+                self.shouldstop = f"stopping after {self.countfailures} failures"
 
-    def triggershutdown(self):
+    def triggershutdown(self) -> None:
-        self.log("triggering shutdown")
+        if not self.shuttingdown:
-        self.shuttingdown = True
+            self.log("triggering shutdown")
-        for node in self.sched.nodes:
+            self.shuttingdown = True
-            node.shutdown()
+            assert self.sched is not None
+            for node in self.sched.nodes:
+                node.shutdown()
 
-    def handle_crashitem(self, nodeid, worker):
+    def handle_crashitem(self, nodeid: str, worker: WorkerController) -> None:
         # XXX get more reporting info by recording pytest_runtest_logstart?
         # XXX count no of failures and retry N times
-        runner = self.config.pluginmanager.getplugin("runner")
         fspath = nodeid.split("::")[0]
-        msg = "worker {!r} crashed while running {!r}".format(worker.gateway.id, nodeid)
+        msg = f"worker {worker.gateway.id!r} crashed while running {nodeid!r}"
-        rep = runner.TestReport(
+        rep = pytest.TestReport(
-            nodeid, (fspath, None, fspath), (), "failed", msg, "???"
+            nodeid=nodeid,
+            location=(fspath, None, fspath),
+            keywords={},
+            outcome="failed",
+            longrepr=msg,
+            when="???",  # type: ignore[arg-type]
         )
-        rep.node = worker
+        rep.node = worker  # type: ignore[attr-defined]
 
         self.config.hook.pytest_handlecrashitem(
             crashitem=nodeid,
@@ -352,36 +452,58 @@ class DSession:
         self.config.hook.pytest_runtest_logreport(report=rep)
 
 
+class WorkerStatus(Enum):
+    """Status of each worker during creation/collection."""
+
+    # Worker spec has just been created.
+    Created = auto()
+
+    # Worker has been initialized.
+    Initialized = auto()
+
+    # Worker is now ready for collection.
+    ReadyForCollection = auto()
+
+    # Worker has finished collection.
+    CollectionDone = auto()
+
+
 class TerminalDistReporter:
-    def __init__(self, config):
+    def __init__(self, config: pytest.Config) -> None:
         self.config = config
         self.tr = config.pluginmanager.getplugin("terminalreporter")
-        self._status = {}
+        self._status: dict[object, tuple[WorkerStatus, int]] = {}
         self._lastlen = 0
         self._isatty = getattr(self.tr, "isatty", self.tr.hasmarkup)
 
-    def write_line(self, msg):
+    def write_line(self, msg: str) -> None:
         self.tr.write_line(msg)
 
-    def ensure_show_status(self):
+    def ensure_show_status(self) -> None:
         if not self._isatty:
             self.write_line(self.getstatus())
 
-    def setstatus(self, spec, status, show=True):
+    def setstatus(
-        self._status[spec.id] = status
+        self,
+        spec: execnet.XSpec,
+        status: WorkerStatus,
+        *,
+        tests_collected: int,
+        show: bool = True,
+    ) -> None:
+        self._status[spec.id] = (status, tests_collected)
         if show and self._isatty:
             self.rewrite(self.getstatus())
 
-    def getstatus(self):
+    def getstatus(self) -> str:
         if self.config.option.verbose >= 0:
-            parts = [
+            line = get_workers_status_line(list(self._status.values()))
-                "{} {}".format(spec.id, self._status[spec.id]) for spec in self._specs
+            if line:
-            ]
+                return line
-            return " / ".join(parts)
-        else:
-            return "bringing up nodes..."
 
-    def rewrite(self, line, newline=False):
+        return "bringing up nodes..."
+
+    def rewrite(self, line: str, newline: bool = False) -> None:
         pline = line + " " * max(self._lastlen - len(line), 0)
         if newline:
             self._lastlen = 0
@@ -390,48 +512,90 @@ class TerminalDistReporter:
             self._lastlen = len(line)
         self.tr.rewrite(pline, bold=True)
 
-    def pytest_xdist_setupnodes(self, specs):
+    @pytest.hookimpl
+    def pytest_xdist_setupnodes(self, specs: Sequence[execnet.XSpec]) -> None:
         self._specs = specs
         for spec in specs:
-            self.setstatus(spec, "I", show=False)
+            self.setstatus(spec, WorkerStatus.Created, tests_collected=0, show=False)
-        self.setstatus(spec, "I", show=True)
+        self.setstatus(spec, WorkerStatus.Created, tests_collected=0, show=True)
         self.ensure_show_status()
 
-    def pytest_xdist_newgateway(self, gateway):
+    @pytest.hookimpl
+    def pytest_xdist_newgateway(self, gateway: execnet.Gateway) -> None:
         if self.config.option.verbose > 0:
             rinfo = gateway._rinfo()
-            version = "%s.%s.%s" % rinfo.version_info[:3]
+            different_interpreter = rinfo.executable != sys.executable
-            self.rewrite(
+            if different_interpreter:
-                "[%s] %s Python %s cwd: %s"
+                version = "{}.{}.{}".format(*rinfo.version_info[:3])
-                % (gateway.id, rinfo.platform, version, rinfo.cwd),
+                self.rewrite(
-                newline=True,
+                    f"[{gateway.id}] {rinfo.platform} Python {version} cwd: {rinfo.cwd}",
-            )
+                    newline=True,
-        self.setstatus(gateway.spec, "C")
+                )
+        self.setstatus(gateway.spec, WorkerStatus.Initialized, tests_collected=0)
 
-    def pytest_testnodeready(self, node):
+    @pytest.hookimpl
+    def pytest_testnodeready(self, node: WorkerController) -> None:
         if self.config.option.verbose > 0:
             d = node.workerinfo
-            infoline = "[{}] Python {}".format(
+            different_interpreter = d.get("executable") != sys.executable
-                d["id"], d["version"].replace("\n", " -- ")
+            if different_interpreter:
-            )
+                version = d["version"].replace("\n", " -- ")
-            self.rewrite(infoline, newline=True)
+                self.rewrite(f"[{d['id']}] Python {version}", newline=True)
-        self.setstatus(node.gateway.spec, "ok")
+        self.setstatus(
+            node.gateway.spec, WorkerStatus.ReadyForCollection, tests_collected=0
+        )
 
-    def pytest_testnodedown(self, node, error):
+    @pytest.hookimpl
+    def pytest_testnodedown(self, node: WorkerController, error: object) -> None:
         if not error:
             return
-        self.write_line("[{}] node down: {}".format(node.gateway.id, error))
+        self.write_line(f"[{node.gateway.id}] node down: {error}")
 
 
-def get_default_max_worker_restart(config):
+def get_default_max_worker_restart(config: pytest.Config) -> int | None:
-    """gets the default value of --max-worker-restart option if it is not provided.
+    """Gets the default value of --max-worker-restart option if it is not provided.
 
     Use a reasonable default to avoid workers from restarting endlessly due to crashing collections (#226).
     """
-    result = config.option.maxworkerrestart
+    result_str: str | None = config.option.maxworkerrestart
-    if result is not None:
+    if result_str is not None:
-        result = int(result)
+        result = int(result_str)
     elif config.option.numprocesses:
         # if --max-worker-restart was not provided, use a reasonable default (#226)
         result = config.option.numprocesses * 4
+    else:
+        result = None
     return result
+
+
+def get_workers_status_line(
+    status_and_items: Sequence[tuple[WorkerStatus, int]],
+) -> str:
+    """
+    Return the line to display during worker setup/collection based on the
+    status of the workers and number of tests collected for each.
+    """
+    statuses = [s for s, c in status_and_items]
+    total_workers = len(statuses)
+    workers_noun = "worker" if total_workers == 1 else "workers"
+    if status_and_items and all(s == WorkerStatus.CollectionDone for s in statuses):
+        # All workers collect the same number of items, so we grab
+        # the total number of items from the first worker.
+        first = status_and_items[0]
+        status, tests_collected = first
+        tests_noun = "item" if tests_collected == 1 else "items"
+        return f"{total_workers} {workers_noun} [{tests_collected} {tests_noun}]"
+    if WorkerStatus.CollectionDone in statuses:
+        done = sum(1 for s, c in status_and_items if c > 0)
+        return f"collecting: {done}/{total_workers} {workers_noun}"
+    if WorkerStatus.ReadyForCollection in statuses:
+        ready = statuses.count(WorkerStatus.ReadyForCollection)
+        return f"ready: {ready}/{total_workers} {workers_noun}"
+    if WorkerStatus.Initialized in statuses:
+        initialized = statuses.count(WorkerStatus.Initialized)
+        return f"initialized: {initialized}/{total_workers} {workers_noun}"
+    if WorkerStatus.Created in statuses:
+        created = statuses.count(WorkerStatus.Created)
+        return f"created: {created}/{total_workers} {workers_noun}"
+
+    return ""

src/xdist/looponfail.py

@@ -1,19 +1,30 @@
 """
-    Implement -f aka looponfailing for pytest.
+Implement -f aka looponfailing for pytest.
 
-    NOTE that we try to avoid loading and depending on application modules
+NOTE that we try to avoid loading and depending on application modules
-    within the controlling process (the one that starts repeatedly test
+within the controlling process (the one that starts repeatedly test
-    processes) otherwise changes to source code can crash
+processes) otherwise changes to source code can crash
-    the controlling process which should best never happen.
+the controlling process which should best never happen.
 """
-import py
+
-import pytest
+from __future__ import annotations
+
+from collections.abc import Sequence
+import os
+from pathlib import Path
 import sys
 import time
+from typing import Any
+
+from _pytest._io import TerminalWriter
 import execnet
+import pytest
+
+from xdist._path import visit_path
 
 
-def pytest_addoption(parser):
+@pytest.hookimpl
+def pytest_addoption(parser: pytest.Parser) -> None:
     group = parser.getgroup("xdist", "distributed and subprocess testing")
     group._addoption(
         "-f",
@@ -21,24 +32,28 @@ def pytest_addoption(parser):
         action="store_true",
         dest="looponfail",
         default=False,
-        help="run tests in subprocess, wait for modified files "
+        help="Run tests in subprocess: wait for files to be modified, then "
-        "and re-run failing test set until all pass.",
+        "re-run failing test set until all pass.",
     )
 
 
-def pytest_cmdline_main(config):
+@pytest.hookimpl
-
+def pytest_cmdline_main(config: pytest.Config) -> int | None:
     if config.getoption("looponfail"):
         usepdb = config.getoption("usepdb", False)  # a core option
         if usepdb:
             raise pytest.UsageError("--pdb is incompatible with --looponfail.")
         looponfail_main(config)
         return 2  # looponfail only can get stop with ctrl-C anyway
+    return None
 
 
-def looponfail_main(config):
+def looponfail_main(config: pytest.Config) -> None:
     remotecontrol = RemoteControl(config)
-    rootdirs = config.getini("looponfailroots")
+    config_roots = config.getini("looponfailroots")
+    if not config_roots:
+        config_roots = [Path.cwd()]
+    rootdirs = [Path(root) for root in config_roots]
     statrecorder = StatRecorder(rootdirs)
     try:
         while 1:
@@ -55,21 +70,21 @@ def looponfail_main(config):
 
 
 class RemoteControl:
-    def __init__(self, config):
+    gateway: execnet.Gateway
-        self.config = config
-        self.failures = []
 
-    def trace(self, *args):
+    def __init__(self, config: pytest.Config) -> None:
+        self.config = config
+        self.failures: list[str] = []
+
+    def trace(self, *args: object) -> None:
         if self.config.option.debug:
             msg = " ".join(str(x) for x in args)
             print("RemoteControl:", msg)
 
-    def initgateway(self):
+    def initgateway(self) -> execnet.Gateway:
-        return execnet.makegateway("popen")
+        return execnet.makegateway("execmodel=main_thread_only//popen")
 
-    def setup(self, out=None):
+    def setup(self) -> None:
-        if out is None:
-            out = py.io.TerminalWriter()
         if hasattr(self, "gateway"):
             raise ValueError("already have gateway %r" % self.gateway)
         self.trace("setting up worker session")
@@ -79,15 +94,17 @@ class RemoteControl:
             args=self.config.args,
             option_dict=vars(self.config.option),
         )
-        remote_outchannel = channel.receive()
+        remote_outchannel: execnet.Channel = channel.receive()
 
-        def write(s):
+        out = TerminalWriter()
+
+        def write(s: str) -> None:
             out._file.write(s)
             out._file.flush()
 
         remote_outchannel.setcallback(write)
 
-    def ensure_teardown(self):
+    def ensure_teardown(self) -> None:
         if hasattr(self, "channel"):
             if not self.channel.isclosed():
                 self.trace("closing", self.channel)
@@ -98,12 +115,12 @@ class RemoteControl:
             self.gateway.exit()
             del self.gateway
 
-    def runsession(self):
+    def runsession(self) -> tuple[list[str], list[str], bool]:
         try:
             self.trace("sending", self.failures)
             self.channel.send(self.failures)
             try:
-                return self.channel.receive()
+                return self.channel.receive()  # type: ignore[no-any-return]
             except self.channel.RemoteError:
                 e = sys.exc_info()[1]
                 self.trace("ERROR", e)
@@ -111,7 +128,7 @@ class RemoteControl:
         finally:
             self.ensure_teardown()
 
-    def loop_once(self):
+    def loop_once(self) -> None:
         self.setup()
         self.wasfailing = self.failures and len(self.failures)
         result = self.runsession()
@@ -126,8 +143,10 @@ class RemoteControl:
             self.failures = uniq_failures
 
 
-def repr_pytest_looponfailinfo(failreports, rootdirs):
+def repr_pytest_looponfailinfo(
-    tr = py.io.TerminalWriter()
+    failreports: Sequence[str], rootdirs: Sequence[Path]
+) -> None:
+    tr = TerminalWriter()
     if failreports:
         tr.sep("#", "LOOPONFAILING", bold=True)
         for report in failreports:
@@ -135,10 +154,14 @@ def repr_pytest_looponfailinfo(failreports, rootdirs):
                 tr.line(report, red=True)
     tr.sep("#", "waiting for changes", bold=True)
     for rootdir in rootdirs:
-        tr.line("### Watching:   {}".format(rootdir), bold=True)
+        tr.line(f"### Watching:   {rootdir}", bold=True)
 
 
-def init_worker_session(channel, args, option_dict):
+def init_worker_session(
+    channel: "execnet.Channel",  # noqa: UP037
+    args: list[str],
+    option_dict: dict[str, "Any"],  # noqa: UP037
+) -> None:
     import os
     import sys
 
@@ -149,13 +172,14 @@ def init_worker_session(channel, args, option_dict):
     newpaths = []
     for p in sys.path:
         if p:
-            if not os.path.isabs(p):
+            # Ignore path placeholders created for editable installs
+            if not os.path.isabs(p) and not p.endswith(".__path_hook__"):
                 p = os.path.abspath(p)
             newpaths.append(p)
     sys.path[:] = newpaths
 
     # fullwidth, hasmarkup = channel.receive()
-    from _pytest.config import Config
+    from pytest import Config
 
     config = Config.fromdictargs(option_dict, list(args))
     config.args = args
@@ -165,20 +189,21 @@ def init_worker_session(channel, args, option_dict):
 
 
 class WorkerFailSession:
-    def __init__(self, config, channel):
+    def __init__(self, config: pytest.Config, channel: execnet.Channel) -> None:
         self.config = config
         self.channel = channel
-        self.recorded_failures = []
+        self.recorded_failures: list[pytest.CollectReport | pytest.TestReport] = []
         self.collection_failed = False
         config.pluginmanager.register(self)
         config.option.looponfail = False
         config.option.usepdb = False
 
-    def DEBUG(self, *args):
+    def DEBUG(self, *args: object) -> None:
         if self.config.option.debug:
             print(" ".join(map(str, args)))
 
-    def pytest_collection(self, session):
+    @pytest.hookimpl
+    def pytest_collection(self, session: pytest.Session) -> bool:
         self.session = session
         self.trails = self.current_command
         hook = self.session.ihook
@@ -192,16 +217,18 @@ class WorkerFailSession:
         hook.pytest_collection_finish(session=session)
         return True
 
-    def pytest_runtest_logreport(self, report):
+    @pytest.hookimpl
+    def pytest_runtest_logreport(self, report: pytest.TestReport) -> None:
         if report.failed:
             self.recorded_failures.append(report)
 
-    def pytest_collectreport(self, report):
+    @pytest.hookimpl
+    def pytest_collectreport(self, report: pytest.CollectReport) -> None:
         if report.failed:
             self.recorded_failures.append(report)
             self.collection_failed = True
 
-    def main(self):
+    def main(self) -> None:
         self.DEBUG("WORKER: received configuration, waiting for command trails")
         try:
             command = self.channel.receive()
@@ -216,56 +243,57 @@ class WorkerFailSession:
             loc = rep.longrepr
             loc = str(getattr(loc, "reprcrash", loc))
             failreports.append(loc)
-        self.channel.send((trails, failreports, self.collection_failed))
+        result = (trails, failreports, self.collection_failed)
+        self.channel.send(result)
 
 
 class StatRecorder:
-    def __init__(self, rootdirlist):
+    def __init__(self, rootdirlist: Sequence[Path]) -> None:
         self.rootdirlist = rootdirlist
-        self.statcache = {}
+        self.statcache: dict[Path, os.stat_result] = {}
         self.check()  # snapshot state
 
-    def fil(self, p):
+    def fil(self, p: Path) -> bool:
-        return p.check(file=1, dotfile=0) and p.ext != ".pyc"
+        return p.is_file() and not p.name.startswith(".") and p.suffix != ".pyc"
 
-    def rec(self, p):
+    def rec(self, p: Path) -> bool:
-        return p.check(dotfile=0)
+        return not p.name.startswith(".") and p.exists()
 
-    def waitonchange(self, checkinterval=1.0):
+    def waitonchange(self, checkinterval: float = 1.0) -> None:
         while 1:
             changed = self.check()
             if changed:
                 return
             time.sleep(checkinterval)
 
-    def check(self, removepycfiles=True):  # noqa, too complex
+    def check(self, removepycfiles: bool = True) -> bool:
         changed = False
-        statcache = self.statcache
+        newstat: dict[Path, os.stat_result] = {}
-        newstat = {}
         for rootdir in self.rootdirlist:
-            for path in rootdir.visit(self.fil, self.rec):
+            for path in visit_path(rootdir, filter=self.fil, recurse=self.rec):
-                oldstat = statcache.pop(path, None)
+                oldstat = self.statcache.pop(path, None)
                 try:
-                    newstat[path] = curstat = path.stat()
+                    curstat = path.stat()
-                except py.error.ENOENT:
+                except OSError:
                     if oldstat:
                         changed = True
                 else:
-                    if oldstat:
+                    newstat[path] = curstat
+                    if oldstat is not None:
                         if (
-                            oldstat.mtime != curstat.mtime
+                            oldstat.st_mtime != curstat.st_mtime
-                            or oldstat.size != curstat.size
+                            or oldstat.st_size != curstat.st_size
                         ):
                             changed = True
                             print("# MODIFIED", path)
-                            if removepycfiles and path.ext == ".py":
+                            if removepycfiles and path.suffix == ".py":
-                                pycfile = path + "c"
+                                pycfile = path.with_suffix(".pyc")
-                                if pycfile.check():
+                                if pycfile.is_file():
-                                    pycfile.remove()
+                                    os.unlink(pycfile)
 
                     else:
                         changed = True
-        if statcache:
+        if self.statcache:
             changed = True
         self.statcache = newstat
         return changed

src/xdist/newhooks.py

@@ -11,63 +11,109 @@ must be taken in plugins in case ``xdist`` is not installed. Please see:
 
     http://pytest.org/en/latest/writing_plugins.html#optionally-using-hooks-from-3rd-party-plugins
 """
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+import os
+from typing import Any
+from typing import TYPE_CHECKING
+
+import execnet
 import pytest
 
 
-def pytest_xdist_setupnodes(config, specs):
+if TYPE_CHECKING:
-    """called before any remote node is set up."""
+    from xdist.remote import Producer
+    from xdist.scheduler.protocol import Scheduling
+    from xdist.workermanage import WorkerController
 
 
-def pytest_xdist_newgateway(gateway):
+@pytest.hookspec()
-    """called on new raw gateway creation."""
+def pytest_xdist_setupnodes(
+    config: pytest.Config, specs: Sequence[execnet.XSpec]
+) -> None:
+    """Called before any remote node is set up."""
 
 
-def pytest_xdist_rsyncstart(source, gateways):
+@pytest.hookspec()
-    """called before rsyncing a directory to remote gateways takes place."""
+def pytest_xdist_newgateway(gateway: execnet.Gateway) -> None:
+    """Called on new raw gateway creation."""
 
 
-def pytest_xdist_rsyncfinish(source, gateways):
+@pytest.hookspec(
-    """called after rsyncing a directory to remote gateways takes place."""
+    warn_on_impl=DeprecationWarning(
+        "rsync feature is deprecated and will be removed in pytest-xdist 4.0"
+    )
+)
+def pytest_xdist_rsyncstart(
+    source: str | os.PathLike[str],
+    gateways: Sequence[execnet.Gateway],
+) -> None:
+    """Called before rsyncing a directory to remote gateways takes place."""
 
 
-@pytest.mark.firstresult
+@pytest.hookspec(
-def pytest_xdist_getremotemodule():
+    warn_on_impl=DeprecationWarning(
-    """called when creating remote node"""
+        "rsync feature is deprecated and will be removed in pytest-xdist 4.0"
+    )
+)
+def pytest_xdist_rsyncfinish(
+    source: str | os.PathLike[str],
+    gateways: Sequence[execnet.Gateway],
+) -> None:
+    """Called after rsyncing a directory to remote gateways takes place."""
 
 
-def pytest_configure_node(node):
+@pytest.hookspec(firstresult=True)
-    """configure node information before it gets instantiated."""
+def pytest_xdist_getremotemodule() -> Any:
+    """Called when creating remote node."""
 
 
-def pytest_testnodeready(node):
+@pytest.hookspec()
+def pytest_configure_node(node: WorkerController) -> None:
+    """Configure node information before it gets instantiated."""
+
+
+@pytest.hookspec()
+def pytest_testnodeready(node: WorkerController) -> None:
     """Test Node is ready to operate."""
 
 
-def pytest_testnodedown(node, error):
+@pytest.hookspec()
+def pytest_testnodedown(node: WorkerController, error: object | None) -> None:
     """Test Node is down."""
 
 
-def pytest_xdist_node_collection_finished(node, ids):
+@pytest.hookspec()
-    """called by the controller node when a worker node finishes collecting."""
+def pytest_xdist_node_collection_finished(
+    node: WorkerController, ids: Sequence[str]
+) -> None:
+    """Called by the controller node when a worker node finishes collecting."""
 
 
-@pytest.mark.firstresult
+@pytest.hookspec(firstresult=True)
-def pytest_xdist_make_scheduler(config, log):
+def pytest_xdist_make_scheduler(
-    """return a node scheduler implementation"""
+    config: pytest.Config, log: Producer
+) -> Scheduling | None:
+    """Return a node scheduler implementation."""
 
 
-@pytest.mark.firstresult
+@pytest.hookspec(firstresult=True)
-def pytest_xdist_auto_num_workers(config):
+def pytest_xdist_auto_num_workers(config: pytest.Config) -> int:
     """
     Return the number of workers to spawn when ``--numprocesses=auto`` is given in the
     command-line.
 
     .. versionadded:: 2.1
     """
+    raise NotImplementedError()
 
 
-@pytest.mark.firstresult
+@pytest.hookspec(firstresult=True)
-def pytest_handlecrashitem(crashitem, report, sched):
+def pytest_handlecrashitem(
+    crashitem: str, report: pytest.TestReport, sched: Scheduling
+) -> None:
     """
     Handle a crashitem, modifying the report if necessary.
 

src/xdist/plugin.py

@@ -1,27 +1,41 @@
-import os
+from __future__ import annotations
-import uuid
+
-import sys
+import os
+import sys
+from typing import Literal
+import uuid
+import warnings
 
-import py
 import pytest
 
+
 _sys_path = list(sys.path)  # freeze a copy of sys.path at interpreter startup
 
 
-def pytest_xdist_auto_num_workers(config):
+@pytest.hookimpl
+def pytest_xdist_auto_num_workers(config: pytest.Config) -> int:
+    env_var = os.environ.get("PYTEST_XDIST_AUTO_NUM_WORKERS")
+    if env_var:
+        try:
+            return int(env_var)
+        except ValueError:
+            warnings.warn(
+                "PYTEST_XDIST_AUTO_NUM_WORKERS is not a number: {env_var!r}. Ignoring it."
+            )
+
     try:
         import psutil
     except ImportError:
         pass
     else:
-        use_logical = config.option.numprocesses == "logical"
+        use_logical: bool = config.option.numprocesses == "logical"
         count = psutil.cpu_count(logical=use_logical) or psutil.cpu_count()
         if count:
             return count
     try:
         from os import sched_getaffinity
 
-        def cpu_count():
+        def cpu_count() -> int:
             return len(sched_getaffinity(0))
 
     except ImportError:
@@ -29,7 +43,7 @@ def pytest_xdist_auto_num_workers(config):
             # workaround https://bitbucket.org/pypy/pypy/issues/2375
             return 2
         try:
-            from os import cpu_count
+            from os import cpu_count  # type: ignore[assignment]
         except ImportError:
             from multiprocessing import cpu_count
     try:
@@ -39,14 +53,19 @@ def pytest_xdist_auto_num_workers(config):
     return n if n else 1
 
 
-def parse_numprocesses(s):
+def parse_numprocesses(s: str) -> int | Literal["auto", "logical"]:
     if s in ("auto", "logical"):
-        return s
+        return s  # type: ignore[return-value]
     elif s is not None:
         return int(s)
 
 
-def pytest_addoption(parser):
+@pytest.hookimpl
+def pytest_addoption(parser: pytest.Parser) -> None:
+    # 'Help' formatting (same rules as pytest's):
+    # Start with capitalized letters.
+    # If a single phrase, do not end with period. If more than one phrase, all phrases end with periods.
+    # Use \n to separate logical lines.
     group = parser.getgroup("xdist", "distributed and subprocess testing")
     group._addoption(
         "-n",
@@ -55,10 +74,11 @@ def pytest_addoption(parser):
         metavar="numprocesses",
         action="store",
         type=parse_numprocesses,
-        help="Shortcut for '--dist=load --tx=NUM*popen'. With 'auto', attempt "
+        help="Shortcut for '--dist=load --tx=NUM*popen'.\n"
-        "to detect physical CPU count. With 'logical', detect logical CPU "
+        "With 'logical', attempt to detect logical CPU count (requires psutil, falls back to 'auto').\n"
-        "count. If physical CPU count cannot be found, falls back to logical "
+        "With 'auto', attempt to detect physical CPU count. If physical CPU count cannot be determined, "
-        "count. This will be 0 when used with --pdb.",
+        "falls back to 1.\n"
+        "Forced to 0 (disabled) when used with --pdb.",
     )
     group.addoption(
         "--maxprocesses",
@@ -66,33 +86,71 @@ def pytest_addoption(parser):
         metavar="maxprocesses",
         action="store",
         type=int,
-        help="limit the maximum number of workers to process the tests when using --numprocesses=auto",
+        help="Limit the maximum number of workers to process the tests when using --numprocesses "
+        "with 'auto' or 'logical'",
     )
     group.addoption(
         "--max-worker-restart",
         action="store",
         default=None,
         dest="maxworkerrestart",
-        help="maximum number of workers that can be restarted "
+        help="Maximum number of workers that can be restarted "
         "when crashed (set to zero to disable this feature)",
     )
     group.addoption(
         "--dist",
         metavar="distmode",
         action="store",
-        choices=["each", "load", "loadscope", "loadfile", "no"],
+        choices=[
+            "each",
+            "load",
+            "loadscope",
+            "loadfile",
+            "loadgroup",
+            "worksteal",
+            "no",
+        ],
         dest="dist",
         default="no",
         help=(
-            "set mode for distributing tests to exec environments.\n\n"
+            "Set mode for distributing tests to exec environments.\n\n"
-            "each: send each test to all available environments.\n\n"
+            "each: Send each test to all available environments.\n\n"
-            "load: load balance by sending any pending test to any"
+            "load: Load balance by sending any pending test to any"
             " available environment.\n\n"
-            "loadscope: load balance by sending pending groups of tests in"
+            "loadscope: Load balance by sending pending groups of tests in"
             " the same scope to any available environment.\n\n"
-            "loadfile: load balance by sending test grouped by file"
+            "loadfile: Load balance by sending test grouped by file"
             " to any available environment.\n\n"
-            "(default) no: run tests inprocess, don't distribute."
+            "loadgroup: Like 'load', but sends tests marked with 'xdist_group' to the same worker.\n\n"
+            "worksteal: Split the test suite between available environments,"
+            " then re-balance when any worker runs out of tests.\n\n"
+            "(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(
@@ -102,63 +160,83 @@ def pytest_addoption(parser):
         default=[],
         metavar="xspec",
         help=(
-            "add a test execution environment. some examples: "
+            "Add a test execution environment. Some examples:\n"
-            "--tx popen//python=python2.5 --tx socket=192.168.1.102:8888 "
+            "--tx popen//python=python2.5 --tx socket=192.168.1.102:8888\n"
             "--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",
         dest="distload",
         default=False,
-        help="load-balance tests.  shortcut for '--dist=load'",
+        help="Load-balance tests. Shortcut for '--dist=load'.",
     )
     group.addoption(
         "--rsyncdir",
         action="append",
         default=[],
         metavar="DIR",
-        help="add directory for rsyncing to remote tx nodes.",
+        help="Add directory for rsyncing to remote tx nodes",
     )
     group.addoption(
         "--rsyncignore",
         action="append",
         default=[],
         metavar="GLOB",
-        help="add expression for ignores when rsyncing to remote tx nodes.",
+        help="Add expression for ignores when rsyncing to remote tx nodes",
-    )
-    group.addoption(
-        "--boxed",
-        action="store_true",
-        help="backward compatibility alias for pytest-forked --forked",
     )
     group.addoption(
         "--testrunuid",
         action="store",
         help=(
-            "provide an identifier shared amongst all workers as the value of "
+            "Provide an identifier shared amongst all workers as the value of "
-            "the 'testrun_uid' fixture,\n\n,"
+            "the 'testrun_uid' fixture.\n"
-            "if not provided, 'testrun_uid' is filled with a new unique string "
+            "If not provided, 'testrun_uid' is filled with a new unique string "
             "on every test run."
         ),
     )
+    group.addoption(
+        "--maxschedchunk",
+        action="store",
+        type=int,
+        help=(
+            "Maximum number of tests scheduled in one step for --dist=load.\n"
+            "Setting it to 1 will force pytest to send tests to workers one by "
+            "one - might be useful for a small number of slow tests.\n"
+            "Larger numbers will allow the scheduler to submit consecutive "
+            "chunks of tests to workers - allows reusing fixtures.\n"
+            "Due to implementation reasons, at least 2 tests are scheduled per "
+            "worker at the start. Only later tests can be scheduled one by one.\n"
+            "Unlimited if not set."
+        ),
+    )
 
     parser.addini(
         "rsyncdirs",
         "list of (relative) paths to be rsynced for remote distributed testing.",
-        type="pathlist",
+        type="paths",
     )
     parser.addini(
         "rsyncignore",
         "list of (relative) glob-style paths to be ignored for rsyncing.",
-        type="pathlist",
+        type="paths",
     )
     parser.addini(
         "looponfailroots",
-        type="pathlist",
+        type="paths",
-        help="directories to check for changes",
+        help="directories to check for changes. Default: current directory.",
-        default=[py.path.local()],
     )
 
 
@@ -167,7 +245,8 @@ def pytest_addoption(parser):
 # -------------------------------------------------------------------------
 
 
-def pytest_addhooks(pluginmanager):
+@pytest.hookimpl
+def pytest_addhooks(pluginmanager: pytest.PytestPluginManager) -> None:
     from xdist import newhooks
 
     pluginmanager.add_hookspecs(newhooks)
@@ -178,9 +257,21 @@ def pytest_addhooks(pluginmanager):
 # -------------------------------------------------------------------------
 
 
-@pytest.mark.trylast
+@pytest.hookimpl(trylast=True)
-def pytest_configure(config):
+def pytest_configure(config: pytest.Config) -> None:
-    if config.getoption("dist") != "no" and not config.getvalue("collectonly"):
+    config_line = (
+        "xdist_group: specify group for tests should run in same session."
+        "in relation to one another. Provided by pytest-xdist."
+    )
+    config.addinivalue_line("markers", config_line)
+
+    # Skip this plugin entirely when only doing collection.
+    if config.getvalue("collectonly"):
+        return
+
+    # Create the distributed session in case we have a valid distribution
+    # mode and test environments.
+    if _is_distribution_mode(config):
         from xdist.dsession import DSession
 
         session = DSession(config)
@@ -188,12 +279,33 @@ def pytest_configure(config):
         tr = config.pluginmanager.getplugin("terminalreporter")
         if tr:
             tr.showfspath = False
-    if config.getoption("boxed"):
+
-        config.option.forked = True
+    # Deprecation warnings for deprecated command-line/configuration options.
+    if config.getoption("looponfail", None) or config.getini("looponfailroots"):
+        warning = DeprecationWarning(
+            "The --looponfail command line argument and looponfailroots config variable are deprecated.\n"
+            "The loop-on-fail feature will be removed in pytest-xdist 4.0."
+        )
+        config.issue_config_time_warning(warning, 2)
+
+    if config.getoption("rsyncdir", None) or config.getini("rsyncdirs"):
+        warning = DeprecationWarning(
+            "The --rsyncdir command line argument and rsyncdirs config variable are deprecated.\n"
+            "The rsync feature will be removed in pytest-xdist 4.0."
+        )
+        config.issue_config_time_warning(warning, 2)
 
 
-@pytest.mark.tryfirst
+def _is_distribution_mode(config: pytest.Config) -> bool:
-def pytest_cmdline_main(config):
+    """Whether distribution mode is on."""
+    return config.getoption("dist") != "no" and bool(config.getoption("tx"))
+
+
+@pytest.hookimpl(tryfirst=True)
+def pytest_cmdline_main(config: pytest.Config) -> None:
+    if config.option.distload:
+        config.option.dist = "load"
+
     usepdb = config.getoption("usepdb", False)  # a core option
     if config.option.numprocesses in ("auto", "logical"):
         if usepdb:
@@ -210,13 +322,16 @@ def pytest_cmdline_main(config):
         if config.option.maxprocesses:
             numprocesses = min(numprocesses, config.option.maxprocesses)
         config.option.tx = ["popen"] * numprocesses
-    if config.option.distload:
+
-        config.option.dist = "load"
+    if config.option.numprocesses == 0:
+        config.option.dist = "no"
+        config.option.tx = []
+
     val = config.getvalue
-    if not val("collectonly") and val("dist") != "no" and usepdb:
+    if not val("collectonly") and _is_distribution_mode(config) and usepdb:
         raise pytest.UsageError(
             "--pdb is incompatible with distributing tests; try using -n0 or -nauto."
-        )  # noqa: E501
+        )
 
 
 # -------------------------------------------------------------------------
@@ -224,16 +339,20 @@ def pytest_cmdline_main(config):
 # -------------------------------------------------------------------------
 
 
-def is_xdist_worker(request_or_session) -> bool:
+def is_xdist_worker(
-    """Return `True` if this is an xdist worker, `False` otherwise
+    request_or_session: pytest.FixtureRequest | pytest.Session,
+) -> bool:
+    """Return `True` if this is an xdist worker, `False` otherwise.
 
     :param request_or_session: the `pytest` `request` or `session` object
     """
     return hasattr(request_or_session.config, "workerinput")
 
 
-def is_xdist_controller(request_or_session) -> bool:
+def is_xdist_controller(
-    """Return `True` if this is the xdist controller, `False` otherwise
+    request_or_session: pytest.FixtureRequest | pytest.Session,
+) -> bool:
+    """Return `True` if this is the xdist controller, `False` otherwise.
 
     Note: this method also returns `False` when distribution has not been
     activated at all.
@@ -250,7 +369,9 @@ def is_xdist_controller(request_or_session) -> bool:
 is_xdist_master = is_xdist_controller
 
 
-def get_xdist_worker_id(request_or_session) -> str:
+def get_xdist_worker_id(
+    request_or_session: pytest.FixtureRequest | pytest.Session,
+) -> str:
     """Return the id of the current worker ('gw0', 'gw1', etc) or 'master'
     if running on the controller node.
 
@@ -260,14 +381,15 @@ def get_xdist_worker_id(request_or_session) -> str:
     :param request_or_session: the `pytest` `request` or `session` object
     """
     if hasattr(request_or_session.config, "workerinput"):
-        return request_or_session.config.workerinput["workerid"]
+        workerid: str = request_or_session.config.workerinput["workerid"]
+        return workerid
     else:
         # TODO: remove "master", ideally for a None
         return "master"
 
 
 @pytest.fixture(scope="session")
-def worker_id(request):
+def worker_id(request: pytest.FixtureRequest) -> str:
     """Return the id of the current worker ('gw0', 'gw1', etc) or 'master'
     if running on the master node.
     """
@@ -276,9 +398,10 @@ def worker_id(request):
 
 
 @pytest.fixture(scope="session")
-def testrun_uid(request):
+def testrun_uid(request: pytest.FixtureRequest) -> str:
     """Return the unique id of the current test."""
     if hasattr(request.config, "workerinput"):
-        return request.config.workerinput["testrunuid"]
+        testrunid: str = request.config.workerinput["testrunuid"]
+        return testrunid
     else:
         return uuid.uuid4().hex

src/xdist/remote.py

@@ -1,116 +1,284 @@
 """
-    This module is executed in remote subprocesses and helps to
+This module is executed in remote subprocesses and helps to
-    control a remote testing session and relay back information.
+control a remote testing session and relay back information.
-    It assumes that 'py' is importable and does not have dependencies
+It assumes that 'py' is importable and does not have dependencies
-    on the rest of the xdist code.  This means that the xdist-plugin
+on the rest of the xdist code.  This means that the xdist-plugin
-    needs not to be installed in remote environments.
+needs not to be installed in remote environments.
 """
 
-import sys
+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 Literal
+from typing import TypedDict
+from typing import Union
+import warnings
 
-import py
+from _pytest.config import _prepareconfig
+import execnet
 import pytest
-from execnet.gateway_base import dumps, DumpError
 
-from _pytest.config import _prepareconfig, Config
+
+try:
+    from setproctitle import setproctitle
+except ImportError:
+
+    def setproctitle(title: str) -> None:
+        pass
+
+
+class Producer:
+    """
+    Simplified implementation of the same interface as py.log, for backward compatibility
+    since we dropped the dependency on pylib.
+    Note: this is defined here because this module can't depend on xdist, so we need
+    to have the other way around.
+    """
+
+    def __init__(self, name: str, *, enabled: bool = True) -> None:
+        self.name = name
+        self.enabled = enabled
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}({self.name!r}, enabled={self.enabled})"
+
+    def __call__(self, *a: Any, **k: Any) -> None:
+        if self.enabled:
+            print(f"[{self.name}]", *a, **k, file=sys.stderr)
+
+    def __getattr__(self, name: str) -> Producer:
+        return type(self)(name, enabled=self.enabled)
+
+
+def worker_title(title: str) -> None:
+    try:
+        setproctitle(title)
+    except Exception:
+        # changing the process name is very optional, no errors please
+        pass
+
+
+class Marker(enum.Enum):
+    SHUTDOWN = 0
+
+
+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:
-    def __init__(self, config, channel):
+    def __init__(self, config: pytest.Config, channel: execnet.Channel) -> None:
         self.config = config
-        self.workerid = config.workerinput.get("workerid", "?")
+        workerinput: dict[str, Any] = config.workerinput  # type: ignore[attr-defined]
-        self.testrunuid = config.workerinput["testrunuid"]
+        self.workerid = workerinput.get("workerid", "?")
-        self.log = py.log.Producer("worker-%s" % self.workerid)
+        self.testrunuid = workerinput["testrunuid"]
-        if not config.option.debug:
+        self.log = Producer(f"worker-{self.workerid}", enabled=config.option.debug)
-            py.log.setconsumer(self.log._keywords, None)
         self.channel = channel
+        self.torun = TestQueue(self.channel.gateway.execmodel)
+        self.nextitem_index: int | None | Literal[Marker.SHUTDOWN] = None
         config.pluginmanager.register(self)
 
-    def sendevent(self, name, **kwargs):
+    def sendevent(self, name: str, **kwargs: object) -> None:
         self.log("sending", name, kwargs)
         self.channel.send((name, kwargs))
 
-    def pytest_internalerror(self, excrepr):
+    @pytest.hookimpl
+    def pytest_internalerror(self, excrepr: object) -> None:
         formatted_error = str(excrepr)
         for line in formatted_error.split("\n"):
             self.log("IERROR>", line)
         interactor.sendevent("internal_error", formatted_error=formatted_error)
 
-    def pytest_sessionstart(self, session):
+    @pytest.hookimpl
+    def pytest_sessionstart(self, session: pytest.Session) -> None:
         self.session = session
         workerinfo = getinfodict()
         self.sendevent("workerready", workerinfo=workerinfo)
 
     @pytest.hookimpl(hookwrapper=True)
-    def pytest_sessionfinish(self, exitstatus):
+    def pytest_sessionfinish(self, exitstatus: int) -> Generator[None, object, None]:
+        workeroutput: dict[str, Any] = self.config.workeroutput  # type: ignore[attr-defined]
         # in pytest 5.0+, exitstatus is an IntEnum object
-        self.config.workeroutput["exitstatus"] = int(exitstatus)
+        workeroutput["exitstatus"] = int(exitstatus)
+        workeroutput["shouldfail"] = self.session.shouldfail
+        workeroutput["shouldstop"] = self.session.shouldstop
         yield
-        self.sendevent("workerfinished", workeroutput=self.config.workeroutput)
+        self.sendevent("workerfinished", workeroutput=workeroutput)
 
-    def pytest_collection(self, session):
+    @pytest.hookimpl
+    def pytest_collection(self) -> None:
         self.sendevent("collectionstart")
 
-    def pytest_runtestloop(self, session):
+    def handle_command(
+        self, command: tuple[str, dict[str, Any]] | Literal[Marker.SHUTDOWN]
+    ) -> None:
+        if command is Marker.SHUTDOWN:
+            self.torun.put(Marker.SHUTDOWN)
+            return
+
+        name, kwargs = command
+
+        self.log("received command", name, kwargs)
+        if name == "runtests":
+            for i in kwargs["indices"]:
+                self.torun.put(i)
+        elif name == "runtests_all":
+            for i in range(len(self.session.items)):
+                self.torun.put(i)
+        elif name == "shutdown":
+            self.torun.put(Marker.SHUTDOWN)
+        elif name == "steal":
+            self.steal(kwargs["indices"])
+
+    def steal(self, indices: Sequence[int]) -> None:
+        """
+        Remove tests from the 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).
+
+        :param indices: indices of the tests to remove.
+        """
+        requested_set = set(indices)
+
+        with self.torun.lock() as locked_queue:
+            stolen = list(item for item in locked_queue if item in requested_set)
+
+            # 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:
+                stolen = []
+
+        self.sendevent("unscheduled", indices=stolen)
+
+    @pytest.hookimpl
+    def pytest_runtestloop(self, session: pytest.Session) -> bool:
         self.log("entering main loop")
-        torun = []
+        self.channel.setcallback(self.handle_command, endmarker=Marker.SHUTDOWN)
-        while 1:
+        self.nextitem_index = self.torun.get()
-            try:
+        while self.nextitem_index is not Marker.SHUTDOWN:
-                name, kwargs = self.channel.receive()
+            self.run_one_test()
-            except EOFError:
+            if session.shouldfail or session.shouldstop:
-                return True
-            self.log("received command", name, kwargs)
-            if name == "runtests":
-                torun.extend(kwargs["indices"])
-            elif name == "runtests_all":
-                torun.extend(range(len(session.items)))
-            self.log("items to run:", torun)
-            # only run if we have an item and a next item
-            while len(torun) >= 2:
-                self.run_one_test(torun)
-            if name == "shutdown":
-                if torun:
-                    self.run_one_test(torun)
                 break
         return True
 
-    def run_one_test(self, torun):
+    def run_one_test(self) -> None:
-        items = self.session.items
+        assert isinstance(self.nextitem_index, int)
-        self.item_index = torun.pop(0)
+        self.item_index = self.nextitem_index
-        item = items[self.item_index]
+        self.nextitem_index = self.torun.get()
-        if torun:
-            nextitem = items[torun[0]]
-        else:
-            nextitem = None
 
-        start = time.time()
+        items = self.session.items
+        item = items[self.item_index]
+        if self.nextitem_index is Marker.SHUTDOWN:
+            nextitem = None
+        else:
+            assert self.nextitem_index is not None
+            nextitem = items[self.nextitem_index]
+
+        worker_title("[pytest-xdist running] %s" % item.nodeid)
+
+        start = time.perf_counter()
         self.config.hook.pytest_runtest_protocol(item=item, nextitem=nextitem)
-        duration = time.time() - start
+        duration = time.perf_counter() - start
+
+        worker_title("[pytest-xdist idle]")
+
         self.sendevent(
             "runtest_protocol_complete", item_index=self.item_index, duration=duration
         )
 
-    def pytest_collection_finish(self, session):
+    def pytest_collection_modifyitems(
-        try:
+        self,
-            topdir = str(self.config.rootpath)
+        config: pytest.Config,
-        except AttributeError:  # pytest <= 6.1.0
+        items: list[pytest.Item],
-            topdir = str(self.config.rootdir)
+    ) -> None:
+        # add the group name to nodeid as suffix if --dist=loadgroup
+        if config.getvalue("loadgroup"):
+            for item in items:
+                gnames: set[str] = set()
+                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
+                item._nodeid = f"{item.nodeid}@{'_'.join(sorted(gnames))}"
 
+    @pytest.hookimpl
+    def pytest_collection_finish(self, session: pytest.Session) -> None:
         self.sendevent(
             "collectionfinish",
-            topdir=topdir,
+            topdir=str(self.config.rootpath),
             ids=[item.nodeid for item in session.items],
         )
 
-    def pytest_runtest_logstart(self, nodeid, location):
+    @pytest.hookimpl
+    def pytest_runtest_logstart(
+        self,
+        nodeid: str,
+        location: tuple[str, int | None, str],
+    ) -> None:
         self.sendevent("logstart", nodeid=nodeid, location=location)
 
-    def pytest_runtest_logfinish(self, nodeid, location):
+    @pytest.hookimpl
+    def pytest_runtest_logfinish(
+        self,
+        nodeid: str,
+        location: tuple[str, int | None, str],
+    ) -> None:
         self.sendevent("logfinish", nodeid=nodeid, location=location)
 
-    def pytest_runtest_logreport(self, report):
+    @pytest.hookimpl
+    def pytest_runtest_logreport(self, report: pytest.TestReport) -> None:
         data = self.config.hook.pytest_report_to_serializable(
             config=self.config, report=report
         )
@@ -120,7 +288,8 @@ class WorkerInteractor:
         assert self.session.items[self.item_index].nodeid == report.nodeid
         self.sendevent("testreport", data=data)
 
-    def pytest_collectreport(self, report):
+    @pytest.hookimpl
+    def pytest_collectreport(self, report: pytest.CollectReport) -> None:
         # send only reports that have not passed to controller as optimization (#330)
         if not report.passed:
             data = self.config.hook.pytest_report_to_serializable(
@@ -128,7 +297,14 @@ class WorkerInteractor:
             )
             self.sendevent("collectreport", data=data)
 
-    def pytest_warning_recorded(self, warning_message, when, nodeid, location):
+    @pytest.hookimpl
+    def pytest_warning_recorded(
+        self,
+        warning_message: warnings.WarningMessage,
+        when: str,
+        nodeid: str,
+        location: tuple[str, int, str] | None,
+    ) -> None:
         self.sendevent(
             "warning_recorded",
             warning_message_data=serialize_warning_message(warning_message),
@@ -138,7 +314,9 @@ class WorkerInteractor:
         )
 
 
-def serialize_warning_message(warning_message):
+def serialize_warning_message(
+    warning_message: warnings.WarningMessage,
+) -> dict[str, Any]:
     if isinstance(warning_message.message, Warning):
         message_module = type(warning_message.message).__module__
         message_class_name = type(warning_message.message).__name__
@@ -146,8 +324,8 @@ def serialize_warning_message(warning_message):
         # check now if we can serialize the warning arguments (#349)
         # if not, we will just use the exception message on the controller node
         try:
-            dumps(warning_message.message.args)
+            execnet.dumps(warning_message.message.args)
-        except DumpError:
+        except execnet.DumpError:
             message_args = None
         else:
             message_args = warning_message.message.args
@@ -172,27 +350,38 @@ def serialize_warning_message(warning_message):
         "category_class_name": category_class_name,
     }
     # access private _WARNING_DETAILS because the attributes vary between Python versions
-    for attr_name in warning_message._WARNING_DETAILS:
+    for attr_name in warning_message._WARNING_DETAILS:  # type: ignore[attr-defined]
         if attr_name in ("message", "category"):
             continue
         attr = getattr(warning_message, attr_name)
         # Check if we can serialize the warning detail, marking `None` otherwise
         # Note that we need to define the attr (even as `None`) to allow deserializing
         try:
-            dumps(attr)
+            execnet.dumps(attr)
-        except DumpError:
+        except execnet.DumpError:
             result[attr_name] = repr(attr)
         else:
             result[attr_name] = attr
     return result
 
 
-def getinfodict():
+class WorkerInfo(TypedDict):
+    version: str
+    version_info: tuple[int, int, int, str, int]
+    sysplatform: str
+    platform: str
+    executable: str
+    cwd: str
+    id: str
+    spec: execnet.XSpec
+
+
+def getinfodict() -> WorkerInfo:
     import platform
 
     return dict(
         version=sys.version,
-        version_info=tuple(sys.version_info),
+        version_info=tuple(sys.version_info),  # type: ignore[typeddict-item]
         sysplatform=sys.platform,
         platform=platform.platform(),
         executable=sys.executable,
@@ -200,12 +389,8 @@ def getinfodict():
     )
 
 
-def remote_initconfig(option_dict, args):
+def setup_config(config: pytest.Config, basetemp: str | None) -> None:
-    option_dict["plugins"].append("no:terminal")
+    config.option.loadgroup = config.getvalue("dist") == "loadgroup"
-    return Config.fromdictargs(option_dict, args)
-
-
-def setup_config(config, basetemp):
     config.option.looponfail = False
     config.option.usepdb = False
     config.option.dist = "no"
@@ -216,8 +401,8 @@ def setup_config(config, basetemp):
 
 
 if __name__ == "__channelexec__":
-    channel = channel  # noqa
+    channel: execnet.Channel = channel  # type: ignore[name-defined] # noqa: F821, PLW0127
-    workerinput, args, option_dict, change_sys_path = channel.receive()
+    workerinput, args, option_dict, change_sys_path = channel.receive()  # type: ignore[name-defined]
 
     if change_sys_path is None:
         importpath = os.getcwd()
@@ -232,15 +417,11 @@ if __name__ == "__channelexec__":
     os.environ["PYTEST_XDIST_WORKER"] = workerinput["workerid"]
     os.environ["PYTEST_XDIST_WORKER_COUNT"] = str(workerinput["workercount"])
 
-    if hasattr(Config, "InvocationParams"):
+    config = _prepareconfig(args, None)
-        config = _prepareconfig(args, None)
-    else:
-        config = remote_initconfig(option_dict, args)
-        config.args = args
 
     setup_config(config, option_dict.get("basetemp"))
     config._parser.prog = os.path.basename(workerinput["mainargv"][0])
-    config.workerinput = workerinput
+    config.workerinput = workerinput  # type: ignore[attr-defined]
-    config.workeroutput = {}
+    config.workeroutput = {}  # type: ignore[attr-defined]
-    interactor = WorkerInteractor(config, channel)
+    interactor = WorkerInteractor(config, channel)  # type: ignore[name-defined]
     config.hook.pytest_cmdline_main(config=config)

src/xdist/report.py

@@ -1,7 +1,15 @@
+from __future__ import annotations
+
+from collections.abc import Sequence
 from difflib import unified_diff
 
 
-def report_collection_diff(from_collection, to_collection, from_id, to_id):
+def report_collection_diff(
+    from_collection: Sequence[str],
+    to_collection: Sequence[str],
+    from_id: str,
+    to_id: str,
+) -> str | None:
     """Report the collected test difference between two nodes.
 
     :returns: detailed message describing the difference between the given
@@ -14,7 +22,9 @@ def report_collection_diff(from_collection, to_collection, from_id, to_id):
     error_message = (
         "Different tests were collected between {from_id} and {to_id}. "
         "The difference is:\n"
-        "{diff}"
+        "{diff}\n"
+        "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/__init__.py

@@ -1,4 +1,7 @@
-from xdist.scheduler.each import EachScheduling  # noqa
+from xdist.scheduler.each import EachScheduling as EachScheduling
-from xdist.scheduler.load import LoadScheduling  # noqa
+from xdist.scheduler.load import LoadScheduling as LoadScheduling
-from xdist.scheduler.loadfile import LoadFileScheduling  # noqa
+from xdist.scheduler.loadfile import LoadFileScheduling as LoadFileScheduling
-from xdist.scheduler.loadscope import LoadScopeScheduling  # noqa
+from xdist.scheduler.loadgroup import LoadGroupScheduling as LoadGroupScheduling
+from xdist.scheduler.loadscope import LoadScopeScheduling as LoadScopeScheduling
+from xdist.scheduler.protocol import Scheduling as Scheduling
+from xdist.scheduler.worksteal import WorkStealingScheduling as WorkStealingScheduling

src/xdist/scheduler/each.py

@@ -1,11 +1,17 @@
-from py.log import Producer
+from __future__ import annotations
 
-from xdist.workermanage import parse_spec_config
+from collections.abc import Sequence
+
+import pytest
+
+from xdist.remote import Producer
 from xdist.report import report_collection_diff
+from xdist.workermanage import parse_tx_spec_config
+from xdist.workermanage import WorkerController
 
 
 class EachScheduling:
-    """Implement scheduling of test items on all nodes
+    """Implement scheduling of test items on all nodes.
 
     If a node gets added after the test run is started then it is
     assumed to replace a node which got removed before it finished
@@ -18,13 +24,13 @@ class EachScheduling:
     assigned the remaining items from the removed node.
     """
 
-    def __init__(self, config, log=None):
+    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 = {}
+        self.node2collection: dict[WorkerController, list[str]] = {}
-        self.node2pending = {}
+        self.node2pending: dict[WorkerController, list[int]] = {}
-        self._started = []
+        self._started: list[WorkerController] = []
-        self._removed2pending = {}
+        self._removed2pending: dict[WorkerController, list[int]] = {}
         if log is None:
             self.log = Producer("eachsched")
         else:
@@ -32,12 +38,12 @@ class EachScheduling:
         self.collection_is_completed = False
 
     @property
-    def nodes(self):
+    def nodes(self) -> list[WorkerController]:
         """A list of all nodes in the scheduler."""
         return list(self.node2pending.keys())
 
     @property
-    def tests_finished(self):
+    def tests_finished(self) -> bool:
         if not self.collection_is_completed:
             return False
         if self._removed2pending:
@@ -48,8 +54,8 @@ class EachScheduling:
         return True
 
     @property
-    def has_pending(self):
+    def has_pending(self) -> bool:
-        """Return True if there are pending test items
+        """Return True if there are pending test items.
 
         This indicates that collection has finished and nodes are
         still processing test items, so this can be thought of as
@@ -60,12 +66,14 @@ class EachScheduling:
                 return True
         return False
 
-    def add_node(self, node):
+    def add_node(self, node: WorkerController) -> None:
         assert node not in self.node2pending
         self.node2pending[node] = []
 
-    def add_node_collection(self, node, collection):
+    def add_node_collection(
-        """Add the collected test items from a node
+        self, node: WorkerController, collection: Sequence[str]
+    ) -> None:
+        """Add the collected test items from a node.
 
         Collection is complete once all nodes have submitted their
         collection.  In this case its pending list is set to an empty
@@ -98,29 +106,33 @@ class EachScheduling:
                     self.node2pending[node] = pending
                     break
 
-    def mark_test_complete(self, node, item_index, duration=0):
+    def mark_test_complete(
+        self, node: WorkerController, item_index: int, duration: float = 0
+    ) -> None:
         self.node2pending[node].remove(item_index)
 
-    def mark_test_pending(self, item):
+    def mark_test_pending(self, item: str) -> None:
-        self.pending.insert(
+        raise NotImplementedError()
-            0,
-            self.collection.index(item),
-        )
-        for node in self.node2pending:
-            self.check_schedule(node)
 
-    def remove_node(self, node):
+    def remove_pending_tests_from_node(
+        self,
+        node: WorkerController,
+        indices: Sequence[int],
+    ) -> None:
+        raise NotImplementedError()
+
+    def remove_node(self, node: WorkerController) -> str | None:
         # KeyError if we didn't get an add_node() yet
         pending = self.node2pending.pop(node)
         if not pending:
-            return
+            return None
         crashitem = self.node2collection[node][pending.pop(0)]
         if pending:
             self._removed2pending[node] = pending
         return crashitem
 
-    def schedule(self):
+    def schedule(self) -> None:
-        """Schedule the test items on the nodes
+        """Schedule the test items on the nodes.
 
         If the node's pending list is empty it is a new node which
         needs to run all the tests.  If the pending list is already

src/xdist/scheduler/load.py

@@ -1,10 +1,14 @@
+from __future__ import annotations
+
+from collections.abc import Sequence
 from itertools import cycle
 
-from py.log import Producer
+import pytest
-from _pytest.runner import CollectReport
 
-from xdist.workermanage import parse_spec_config
+from xdist.remote import Producer
 from xdist.report import report_collection_diff
+from xdist.workermanage import parse_tx_spec_config
+from xdist.workermanage import WorkerController
 
 
 class LoadScheduling:
@@ -23,7 +27,7 @@ class LoadScheduling:
     submit a collection. This is used to know when all nodes have
     finished collection or how large the chunks need to be created.
 
-    Attributes:
+    Attributes::
 
     :numnodes: The expected number of nodes taking part.  The actual
        number of nodes will vary during the scheduler's lifetime as
@@ -53,25 +57,26 @@ class LoadScheduling:
     :config: Config object, used for handling hooks.
     """
 
-    def __init__(self, config, log=None):
+    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 = {}
+        self.node2collection: dict[WorkerController, list[str]] = {}
-        self.node2pending = {}
+        self.node2pending: dict[WorkerController, list[int]] = {}
-        self.pending = []
+        self.pending: list[int] = []
-        self.collection = None
+        self.collection: list[str] | None = None
         if log is None:
             self.log = Producer("loadsched")
         else:
             self.log = log.loadsched
         self.config = config
+        self.maxschedchunk = self.config.getoption("maxschedchunk")
 
     @property
-    def nodes(self):
+    def nodes(self) -> list[WorkerController]:
         """A list of all nodes in the scheduler."""
         return list(self.node2pending.keys())
 
     @property
-    def collection_is_completed(self):
+    def collection_is_completed(self) -> bool:
         """Boolean indication initial test collection is complete.
 
         This is a boolean indicating all initial participating nodes
@@ -81,7 +86,7 @@ class LoadScheduling:
         return len(self.node2collection) >= self.numnodes
 
     @property
-    def tests_finished(self):
+    def tests_finished(self) -> bool:
         """Return True if all tests have been executed by the nodes."""
         if not self.collection_is_completed:
             return False
@@ -93,8 +98,8 @@ class LoadScheduling:
         return True
 
     @property
-    def has_pending(self):
+    def has_pending(self) -> bool:
-        """Return True if there are pending test items
+        """Return True if there are pending test items.
 
         This indicates that collection has finished and nodes are
         still processing test items, so this can be thought of as
@@ -107,7 +112,7 @@ class LoadScheduling:
                 return True
         return False
 
-    def add_node(self, node):
+    def add_node(self, node: WorkerController) -> None:
         """Add a new node to the scheduler.
 
         From now on the node will be allocated chunks of tests to
@@ -119,8 +124,10 @@ class LoadScheduling:
         assert node not in self.node2pending
         self.node2pending[node] = []
 
-    def add_node_collection(self, node, collection):
+    def add_node_collection(
-        """Add the collected test items from a node
+        self, node: WorkerController, collection: Sequence[str]
+    ) -> None:
+        """Add the collected test items from a node.
 
         The collection is stored in the ``.node2collection`` map.
         Called by the ``DSession.worker_collectionfinish`` hook.
@@ -140,8 +147,10 @@ class LoadScheduling:
                 return
         self.node2collection[node] = list(collection)
 
-    def mark_test_complete(self, node, item_index, duration=0):
+    def mark_test_complete(
-        """Mark test item as completed by node
+        self, node: WorkerController, item_index: int, duration: float = 0
+    ) -> None:
+        """Mark test item as completed by node.
 
         The duration it took to execute the item is used as a hint to
         the scheduler.
@@ -151,7 +160,8 @@ class LoadScheduling:
         self.node2pending[node].remove(item_index)
         self.check_schedule(node, duration=duration)
 
-    def mark_test_pending(self, item):
+    def mark_test_pending(self, item: str) -> None:
+        assert self.collection is not None
         self.pending.insert(
             0,
             self.collection.index(item),
@@ -159,8 +169,15 @@ class LoadScheduling:
         for node in self.node2pending:
             self.check_schedule(node)
 
-    def check_schedule(self, node, duration=0):
+    def remove_pending_tests_from_node(
-        """Maybe schedule new items on the node
+        self,
+        node: WorkerController,
+        indices: Sequence[int],
+    ) -> None:
+        raise NotImplementedError()
+
+    def check_schedule(self, node: WorkerController, duration: float = 0) -> None:
+        """Maybe schedule new items on the node.
 
         If there are any globally pending nodes left then this will
         check if the given node should be given any more tests.  The
@@ -185,14 +202,16 @@ class LoadScheduling:
                     # so let's rather wait with sending new items
                     return
                 num_send = items_per_node_max - len(node_pending)
-                self._send_tests(node, num_send)
+                # keep at least 2 tests pending even if --maxschedchunk=1
+                maxschedchunk = max(2 - len(node_pending), self.maxschedchunk)
+                self._send_tests(node, min(num_send, maxschedchunk))
         else:
             node.shutdown()
 
         self.log("num items waiting for node:", len(self.pending))
 
-    def remove_node(self, node):
+    def remove_node(self, node: WorkerController) -> str | None:
-        """Remove a node from the scheduler
+        """Remove a node from the scheduler.
 
         This should be called either when the node crashed or at
         shutdown time.  In the former case any pending items assigned
@@ -206,17 +225,18 @@ class LoadScheduling:
         """
         pending = self.node2pending.pop(node)
         if not pending:
-            return
+            return None
 
         # The node crashed, reassing pending items
+        assert self.collection is not None
         crashitem = self.collection[pending.pop(0)]
         self.pending.extend(pending)
         for node in self.node2pending:
             self.check_schedule(node)
         return crashitem
 
-    def schedule(self):
+    def schedule(self) -> None:
-        """Initiate distribution of the test collection
+        """Initiate distribution of the test collection.
 
         Initiate scheduling of the items across the nodes.  If this
         gets called again later it behaves the same as calling
@@ -240,35 +260,53 @@ class LoadScheduling:
             return
 
         # Collections are identical, create the index of pending items.
-        self.collection = list(self.node2collection.values())[0]
+        self.collection = next(iter(self.node2collection.values()))
         self.pending[:] = range(len(self.collection))
         if not self.collection:
             return
 
+        if self.maxschedchunk is None:
+            self.maxschedchunk = len(self.collection)
+
         # Send a batch of tests to run. If we don't have at least two
         # tests per node, we have to send them all so that we can send
         # shutdown signals and get all nodes working.
-        initial_batch = max(len(self.pending) // 4, 2 * len(self.nodes))
+        if len(self.pending) < 2 * len(self.nodes):
+            # Distribute tests round-robin. Try to load all nodes if there are
+            # enough tests. The other branch tries sends at least 2 tests
+            # to each node - which is suboptimal when you have less than
+            # 2 * len(nodes) tests.
+            nodes = cycle(self.nodes)
+            for _ in range(len(self.pending)):
+                self._send_tests(next(nodes), 1)
+        else:
+            # Send batches of consecutive tests. By default, pytest sorts tests
+            # in order for optimal single-threaded execution, minimizing the
+            # number of necessary fixture setup/teardown. Try to keep that
+            # optimal order for every worker.
 
-        # distribute tests round-robin up to the batch size
+            # how many items per node do we have about?
-        # (or until we run out)
+            items_per_node = len(self.collection) // len(self.node2pending)
-        nodes = cycle(self.nodes)
+            # take a fraction of tests for initial distribution
-        for i in range(initial_batch):
+            node_chunksize = min(items_per_node // 4, self.maxschedchunk)
-            self._send_tests(next(nodes), 1)
+            node_chunksize = max(node_chunksize, 2)
+            # and initialize each node with a chunk of tests
+            for node in self.nodes:
+                self._send_tests(node, node_chunksize)
 
         if not self.pending:
             # initial distribution sent all tests, start node shutdown
             for node in self.nodes:
                 node.shutdown()
 
-    def _send_tests(self, node, num):
+    def _send_tests(self, node: WorkerController, num: int) -> None:
         tests_per_node = self.pending[:num]
         if tests_per_node:
             del self.pending[:num]
             self.node2pending[node].extend(tests_per_node)
             node.send_runtest_some(tests_per_node)
 
-    def _check_nodes_have_same_collection(self):
+    def _check_nodes_have_same_collection(self) -> bool:
         """Return True if all nodes have collected the same items.
 
         If collections differ, this method returns False while logging
@@ -286,8 +324,11 @@ class LoadScheduling:
                 same_collection = False
                 self.log(msg)
                 if self.config is not None:
-                    rep = CollectReport(
+                    rep = pytest.CollectReport(
-                        node.gateway.id, "failed", longrepr=msg, result=[]
+                        nodeid=node.gateway.id,
+                        outcome="failed",
+                        longrepr=msg,
+                        result=[],
                     )
                     self.config.hook.pytest_collectreport(report=rep)
 

src/xdist/scheduler/loadfile.py

@@ -1,5 +1,10 @@
+from __future__ import annotations
+
+import pytest
+
+from xdist.remote import Producer
+
 from .loadscope import LoadScopeScheduling
-from py.log import Producer
 
 
 class LoadFileScheduling(LoadScopeScheduling):
@@ -20,14 +25,14 @@ class LoadFileScheduling(LoadScopeScheduling):
     This class behaves very much like LoadScopeScheduling, but with a file-level scope.
     """
 
-    def __init__(self, config, log=None):
+    def __init__(self, config: pytest.Config, log: Producer | None = None) -> None:
         super().__init__(config, log)
         if log is None:
             self.log = Producer("loadfilesched")
         else:
             self.log = log.loadfilesched
 
-    def _split_scope(self, nodeid):
+    def _split_scope(self, nodeid: str) -> str:
         """Determine the scope (grouping) of a nodeid.
 
         There are usually 3 cases for a nodeid::
@@ -43,7 +48,10 @@ class LoadFileScheduling(LoadScopeScheduling):
         This function will group tests with the scope determined by splitting
         the first ``::`` from the left. That is, test will be grouped in a
         single work unit when they reside in the same file.
-         In the above example, scopes will be::
+
+        In the above example, scopes will be::
+
+        .. code-block:: text
 
             example/loadsuite/test/test_beta.py
             example/loadsuite/test/test_delta.py

src/xdist/scheduler/loadgroup.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+import pytest
+
+from xdist.remote import Producer
+
+from .loadscope import LoadScopeScheduling
+
+
+class LoadGroupScheduling(LoadScopeScheduling):
+    """Implement load scheduling across nodes, but grouping test by xdist_group mark.
+
+    This class behaves very much like LoadScopeScheduling, but it groups tests by xdist_group mark
+    instead of the module or class to which they belong to.
+    """
+
+    def __init__(self, config: pytest.Config, log: Producer | None = None) -> None:
+        super().__init__(config, log)
+        if log is None:
+            self.log = Producer("loadgroupsched")
+        else:
+            self.log = log.loadgroupsched
+
+    def _split_scope(self, nodeid: str) -> str:
+        """Determine the scope (grouping) of a nodeid.
+
+        There are usually 3 cases for a nodeid::
+
+            example/loadsuite/test/test_beta.py::test_beta0
+            example/loadsuite/test/test_delta.py::Delta1::test_delta0
+            example/loadsuite/epsilon/__init__.py::epsilon.epsilon
+
+        #. Function in a test module.
+        #. Method of a class in a test module.
+        #. Doctest in a function in a package.
+
+        With loadgroup, two cases are added::
+
+            example/loadsuite/test/test_beta.py::test_beta0
+            example/loadsuite/test/test_delta.py::Delta1::test_delta0
+            example/loadsuite/epsilon/__init__.py::epsilon.epsilon
+            example/loadsuite/test/test_gamma.py::test_beta0@gname
+            example/loadsuite/test/test_delta.py::Gamma1::test_gamma0@gname
+
+        This function will group tests with the scope determined by splitting the first ``@``
+        from the right. That is, test will be grouped in a single work unit when they have
+        same group name. In the above example, scopes will be::
+
+            example/loadsuite/test/test_beta.py::test_beta0
+            example/loadsuite/test/test_delta.py::Delta1::test_delta0
+            example/loadsuite/epsilon/__init__.py::epsilon.epsilon
+            gname
+            gname
+        """
+        if nodeid.rfind("@") > nodeid.rfind("]"):
+            # check the index of ']' to avoid the case: parametrize mark value has '@'
+            return nodeid.split("@")[-1]
+        else:
+            return nodeid

src/xdist/scheduler/loadscope.py

@@ -1,9 +1,15 @@
-from collections import OrderedDict
+from __future__ import annotations
 
-from _pytest.runner import CollectReport
+from collections import OrderedDict
-from py.log import Producer
+from collections.abc import Sequence
+from typing import NoReturn
+
+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
 
 
 class LoadScopeScheduling:
@@ -21,7 +27,7 @@ class LoadScopeScheduling:
     When created, ``numnodes`` defines how many nodes are expected to submit a
     collection. This is used to know when all nodes have finished collection.
 
-    Attributes:
+    Attributes::
 
     :numnodes: The expected number of nodes taking part.  The actual number of
        nodes will vary during the scheduler's lifetime as nodes are added by
@@ -84,13 +90,13 @@ class LoadScopeScheduling:
     :config: Config object, used for handling hooks.
     """
 
-    def __init__(self, config, log=None):
+    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 = None
+        self.collection: list[str] | None = None
 
-        self.workqueue = OrderedDict()
+        self.workqueue: OrderedDict[str, dict[str, bool]] = OrderedDict()
-        self.assigned_work = OrderedDict()
+        self.assigned_work: dict[WorkerController, dict[str, dict[str, bool]]] = {}
-        self.registered_collections = OrderedDict()
+        self.registered_collections: dict[WorkerController, list[str]] = {}
 
         if log is None:
             self.log = Producer("loadscopesched")
@@ -100,12 +106,12 @@ class LoadScopeScheduling:
         self.config = config
 
     @property
-    def nodes(self):
+    def nodes(self) -> list[WorkerController]:
         """A list of all active nodes in the scheduler."""
         return list(self.assigned_work.keys())
 
     @property
-    def collection_is_completed(self):
+    def collection_is_completed(self) -> bool:
         """Boolean indication initial test collection is complete.
 
         This is a boolean indicating all initial participating nodes have
@@ -115,7 +121,7 @@ class LoadScopeScheduling:
         return len(self.registered_collections) >= self.numnodes
 
     @property
-    def tests_finished(self):
+    def tests_finished(self) -> bool:
         """Return True if all tests have been executed by the nodes."""
         if not self.collection_is_completed:
             return False
@@ -130,7 +136,7 @@ class LoadScopeScheduling:
         return True
 
     @property
-    def has_pending(self):
+    def has_pending(self) -> bool:
         """Return True if there are pending test items.
 
         This indicates that collection has finished and nodes are still
@@ -146,7 +152,7 @@ class LoadScopeScheduling:
 
         return False
 
-    def add_node(self, node):
+    def add_node(self, node: WorkerController) -> None:
         """Add a new node to the scheduler.
 
         From now on the node will be assigned work units to be executed.
@@ -155,9 +161,9 @@ class LoadScopeScheduling:
         bootstraps a new node.
         """
         assert node not in self.assigned_work
-        self.assigned_work[node] = OrderedDict()
+        self.assigned_work[node] = {}
 
-    def remove_node(self, node):
+    def remove_node(self, node: WorkerController) -> str | None:
         """Remove a node from the scheduler.
 
         This should be called either when the node crashed or at shutdown time.
@@ -198,7 +204,9 @@ class LoadScopeScheduling:
 
         return crashitem
 
-    def add_node_collection(self, node, collection):
+    def add_node_collection(
+        self, node: WorkerController, collection: Sequence[str]
+    ) -> None:
         """Add the collected test items from a node.
 
         The collection is stored in the ``.registered_collections`` dictionary.
@@ -207,19 +215,16 @@ class LoadScopeScheduling:
 
         - ``DSession.worker_collectionfinish``.
         """
-
         # Check that add_node() was called on the node before
         assert node in self.assigned_work
 
         # A new node has been added later, perhaps an original one died.
         if self.collection_is_completed:
-
             # Assert that .schedule() should have been called by now
             assert self.collection
 
             # Check that the new collection matches the official collection
             if collection != self.collection:
-
                 other_node = next(iter(self.registered_collections.keys()))
 
                 msg = report_collection_diff(
@@ -230,7 +235,9 @@ class LoadScopeScheduling:
 
         self.registered_collections[node] = list(collection)
 
-    def mark_test_complete(self, node, item_index, duration=0):
+    def mark_test_complete(
+        self, node: WorkerController, item_index: int, duration: float = 0
+    ) -> None:
         """Mark test item as completed by node.
 
         Called by the hook:
@@ -243,10 +250,17 @@ class LoadScopeScheduling:
         self.assigned_work[node][scope][nodeid] = True
         self._reschedule(node)
 
-    def mark_test_pending(self, item):
+    def mark_test_pending(self, item: str) -> NoReturn:
         raise NotImplementedError()
 
-    def _assign_work_unit(self, node):
+    def remove_pending_tests_from_node(
+        self,
+        node: WorkerController,
+        indices: Sequence[int],
+    ) -> None:
+        raise NotImplementedError()
+
+    def _assign_work_unit(self, node: WorkerController) -> None:
         """Assign a work unit to a node."""
         assert self.workqueue
 
@@ -254,7 +268,7 @@ class LoadScopeScheduling:
         scope, work_unit = self.workqueue.popitem(last=False)
 
         # Keep track of the assigned work
-        assigned_to_node = self.assigned_work.setdefault(node, default=OrderedDict())
+        assigned_to_node = self.assigned_work.setdefault(node, {})
         assigned_to_node[scope] = work_unit
 
         # Ask the node to execute the workload
@@ -267,7 +281,7 @@ class LoadScopeScheduling:
 
         node.send_runtest_some(nodeids_indexes)
 
-    def _split_scope(self, nodeid):
+    def _split_scope(self, nodeid: str) -> str:
         """Determine the scope (grouping) of a nodeid.
 
         There are usually 3 cases for a nodeid::
@@ -291,18 +305,17 @@ class LoadScopeScheduling:
         """
         return nodeid.rsplit("::", 1)[0]
 
-    def _pending_of(self, workload):
+    def _pending_of(self, workload: dict[str, dict[str, bool]]) -> int:
         """Return the number of pending tests in a workload."""
         pending = sum(list(scope.values()).count(False) for scope in workload.values())
         return pending
 
-    def _reschedule(self, node):
+    def _reschedule(self, node: WorkerController) -> None:
         """Maybe schedule new items on the node.
 
         If there are any globally pending work units left then this will check
         if the given node should be given any more tests.
         """
-
         # Do not add more work to a node shutting down
         if node.shutting_down:
             return
@@ -322,7 +335,7 @@ class LoadScopeScheduling:
         # Pop one unit of work and assign it
         self._assign_work_unit(node)
 
-    def schedule(self):
+    def schedule(self) -> None:
         """Initiate distribution of the test collection.
 
         Initiate scheduling of the items across the nodes.  If this gets called
@@ -352,21 +365,32 @@ class LoadScopeScheduling:
             return
 
         # Determine chunks of work (scopes)
+        unsorted_workqueue: dict[str, dict[str, bool]] = {}
         for nodeid in self.collection:
             scope = self._split_scope(nodeid)
-            work_unit = self.workqueue.setdefault(scope, default=OrderedDict())
+            work_unit = unsorted_workqueue.setdefault(scope, {})
             work_unit[nodeid] = False
 
+        if self.config.option.loadscopereorder:
+            # Insert tests scopes into work queue ordered by number of tests.
+            for scope, nodeids in sorted(
+                unsorted_workqueue.items(), key=lambda item: -len(item[1])
+            ):
+                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)
 
         if extra_nodes > 0:
-            self.log("Shuting down {} nodes".format(extra_nodes))
+            self.log(f"Shutting down {extra_nodes} nodes")
 
             for _ in range(extra_nodes):
-                unused_node, assigned = self.assigned_work.popitem(last=True)
+                unused_node, assigned = self.assigned_work.popitem()
 
-                self.log("Shuting down unused node {}".format(unused_node))
+                self.log(f"Shutting down unused node {unused_node}")
                 unused_node.shutdown()
 
         # Assign initial workload
@@ -382,7 +406,7 @@ class LoadScopeScheduling:
             for node in self.nodes:
                 node.shutdown()
 
-    def _check_nodes_have_same_collection(self):
+    def _check_nodes_have_same_collection(self) -> bool:
         """Return True if all nodes have collected the same items.
 
         If collections differ, this method returns False while logging
@@ -403,10 +427,12 @@ class LoadScopeScheduling:
             same_collection = False
             self.log(msg)
 
-            if self.config is None:
+            rep = pytest.CollectReport(
-                continue
+                nodeid=node.gateway.id,
-
+                outcome="failed",
-            rep = CollectReport(node.gateway.id, "failed", longrepr=msg, result=[])
+                longrepr=msg,
+                result=[],
+            )
             self.config.hook.pytest_collectreport(report=rep)
 
         return same_collection

src/xdist/scheduler/protocol.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Protocol
+
+from xdist.workermanage import WorkerController
+
+
+class Scheduling(Protocol):
+    @property
+    def nodes(self) -> list[WorkerController]: ...
+
+    @property
+    def collection_is_completed(self) -> bool: ...
+
+    @property
+    def tests_finished(self) -> bool: ...
+
+    @property
+    def has_pending(self) -> bool: ...
+
+    def add_node(self, node: WorkerController) -> None: ...
+
+    def add_node_collection(
+        self,
+        node: WorkerController,
+        collection: Sequence[str],
+    ) -> None: ...
+
+    def mark_test_complete(
+        self,
+        node: WorkerController,
+        item_index: int,
+        duration: float = 0,
+    ) -> None: ...
+
+    def mark_test_pending(self, item: str) -> None: ...
+
+    def remove_pending_tests_from_node(
+        self,
+        node: WorkerController,
+        indices: Sequence[int],
+    ) -> None: ...
+
+    def remove_node(self, node: WorkerController) -> str | None: ...
+
+    def schedule(self) -> None: ...

src/xdist/scheduler/worksteal.py

@@ -0,0 +1,345 @@
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import NamedTuple
+
+import pytest
+
+from xdist.remote import Producer
+from xdist.report import report_collection_diff
+from xdist.workermanage import parse_tx_spec_config
+from xdist.workermanage import WorkerController
+
+
+class NodePending(NamedTuple):
+    node: WorkerController
+    pending: list[int]
+
+
+# Every worker needs at least 2 tests in queue - the current and the next one.
+MIN_PENDING = 2
+
+
+class WorkStealingScheduling:
+    """Implement work-stealing scheduling.
+
+    Initially, tests are distributed evenly among all nodes.
+
+    When some node completes most of its assigned tests (when only one pending
+    test remains), an attempt is made to reassign ("steal") some tests from
+    other nodes to this node.
+
+    Attributes::
+
+    :numnodes: The expected number of nodes taking part.  The actual
+       number of nodes will vary during the scheduler's lifetime as
+       nodes are added by the DSession as they are brought up and
+       removed either because of a dead node or normal shutdown.  This
+       number is primarily used to know when the initial collection is
+       completed.
+
+    :node2collection: Map of nodes and their test collection.  All
+       collections should always be identical.
+
+    :node2pending: Map of nodes and the indices of their pending
+       tests.  The indices are an index into ``.pending`` (which is
+       identical to their own collection stored in
+       ``.node2collection``).
+
+    :collection: The one collection once it is validated to be
+       identical between all the nodes.  It is initialised to None
+       until ``.schedule()`` is called.
+
+    :pending: List of indices of globally pending tests.  These are
+       tests which have not yet been allocated to a chunk for a node
+       to process.
+
+    :log: A py.log.Producer instance.
+
+    :config: Config object, used for handling hooks.
+
+    :steal_requested_from_node: The node to which the current "steal" request
+       was sent. ``None`` if there is no request in progress. Only one request
+       can be in progress at any time, the scheduler doesn't send multiple
+       simultaneous requests.
+    """
+
+    def __init__(self, config: pytest.Config, log: Producer | None = None) -> None:
+        self.numnodes = len(parse_tx_spec_config(config))
+        self.node2collection: dict[WorkerController, list[str]] = {}
+        self.node2pending: dict[WorkerController, list[int]] = {}
+        self.pending: list[int] = []
+        self.collection: list[str] | None = None
+        if log is None:
+            self.log = Producer("workstealsched")
+        else:
+            self.log = log.workstealsched
+        self.config = config
+        self.steal_requested_from_node: WorkerController | None = None
+
+    @property
+    def nodes(self) -> list[WorkerController]:
+        """A list of all nodes in the scheduler."""
+        return list(self.node2pending.keys())
+
+    @property
+    def collection_is_completed(self) -> bool:
+        """Boolean indication initial test collection is complete.
+
+        This is a boolean indicating all initial participating nodes
+        have finished collection.  The required number of initial
+        nodes is defined by ``.numnodes``.
+        """
+        return len(self.node2collection) >= self.numnodes
+
+    @property
+    def tests_finished(self) -> bool:
+        """Return True if all tests have been executed by the nodes."""
+        if not self.collection_is_completed:
+            return False
+        if self.pending:
+            return False
+        if self.steal_requested_from_node is not None:
+            return False
+        for pending in self.node2pending.values():
+            if len(pending) >= MIN_PENDING:
+                return False
+        return True
+
+    @property
+    def has_pending(self) -> bool:
+        """Return True if there are pending test items.
+
+        This indicates that collection has finished and nodes are
+        still processing test items, so this can be thought of as
+        "the scheduler is active".
+        """
+        if self.pending:
+            return True
+        for pending in self.node2pending.values():
+            if pending:
+                return True
+        return False
+
+    def add_node(self, node: WorkerController) -> None:
+        """Add a new node to the scheduler.
+
+        From now on the node will be allocated chunks of tests to
+        execute.
+
+        Called by the ``DSession.worker_workerready`` hook when it
+        successfully bootstraps a new node.
+        """
+        assert node not in self.node2pending
+        self.node2pending[node] = []
+
+    def add_node_collection(
+        self, node: WorkerController, collection: Sequence[str]
+    ) -> None:
+        """Add the collected test items from a node.
+
+        The collection is stored in the ``.node2collection`` map.
+        Called by the ``DSession.worker_collectionfinish`` hook.
+        """
+        assert node in self.node2pending
+        if self.collection_is_completed:
+            # A new node has been added later, perhaps an original one died.
+            # .schedule() should have
+            # been called by now
+            assert self.collection
+            if collection != self.collection:
+                other_node = next(iter(self.node2collection.keys()))
+                msg = report_collection_diff(
+                    self.collection, collection, other_node.gateway.id, node.gateway.id
+                )
+                self.log(msg)
+                return
+        self.node2collection[node] = list(collection)
+
+    def mark_test_complete(
+        self, node: WorkerController, item_index: int, duration: float | None = None
+    ) -> None:
+        """Mark test item as completed by node.
+
+        This is called by the ``DSession.worker_testreport`` hook.
+        """
+        self.node2pending[node].remove(item_index)
+        self.check_schedule()
+
+    def mark_test_pending(self, item: str) -> None:
+        assert self.collection is not None
+        self.pending.insert(
+            0,
+            self.collection.index(item),
+        )
+        self.check_schedule()
+
+    def remove_pending_tests_from_node(
+        self,
+        node: WorkerController,
+        indices: Sequence[int],
+    ) -> None:
+        """Node returned some test indices back in response to 'steal' command.
+
+        This is called by ``DSession.worker_unscheduled``.
+        """
+        assert node is self.steal_requested_from_node
+        self.steal_requested_from_node = None
+
+        indices_set = set(indices)
+        self.node2pending[node] = [
+            i for i in self.node2pending[node] if i not in indices_set
+        ]
+        self.pending.extend(indices)
+        self.check_schedule()
+
+    def check_schedule(self) -> None:
+        """Reschedule tests/perform load balancing."""
+        nodes_up = [
+            NodePending(node, pending)
+            for node, pending in self.node2pending.items()
+            if not node.shutting_down
+        ]
+
+        def get_idle_nodes() -> list[WorkerController]:
+            return [node for node, pending in nodes_up if len(pending) < MIN_PENDING]
+
+        idle_nodes = get_idle_nodes()
+        if not idle_nodes:
+            return
+
+        if self.pending:
+            # Distribute pending tests evenly among idle nodes
+            for i, node in enumerate(idle_nodes):
+                nodes_remaining = len(idle_nodes) - i
+                num_send = len(self.pending) // nodes_remaining
+                self._send_tests(node, num_send)
+
+            idle_nodes = get_idle_nodes()
+            # No need to steal anything if all nodes have enough work to continue
+            if not idle_nodes:
+                return
+
+        # Only one active stealing request is allowed
+        if self.steal_requested_from_node is not None:
+            return
+
+        # Find the node that has the longest test queue
+        steal_from = max(
+            nodes_up, key=lambda node_pending: len(node_pending.pending), default=None
+        )
+
+        if steal_from is None:
+            num_steal = 0
+        else:
+            # Steal half of the test queue - but keep that node running too.
+            # If the node has 2 or less tests queued, stealing will fail
+            # anyway.
+            max_steal = max(0, len(steal_from.pending) - MIN_PENDING)
+            num_steal = min(len(steal_from.pending) // 2, max_steal)
+
+        if num_steal == 0:
+            # Can't get more work - shutdown idle nodes. This will force them
+            # to run the last test now instead of waiting for more tests.
+            for node in idle_nodes:
+                node.shutdown()
+            return
+
+        assert steal_from is not None
+        steal_from.node.send_steal(steal_from.pending[-num_steal:])
+        self.steal_requested_from_node = steal_from.node
+
+    def remove_node(self, node: WorkerController) -> str | None:
+        """Remove a node from the scheduler.
+
+        This should be called either when the node crashed or at
+        shutdown time.  In the former case any pending items assigned
+        to the node will be re-scheduled.  Called by the
+        ``DSession.worker_workerfinished`` and
+        ``DSession.worker_errordown`` hooks.
+
+        Return the item which was being executing while the node
+        crashed or None if the node has no more pending items.
+        """
+        pending = self.node2pending.pop(node)
+
+        # If node was removed without completing its assigned tests - it crashed
+        if pending:
+            assert self.collection is not None
+            crashitem = self.collection[pending.pop(0)]
+        else:
+            crashitem = None
+
+        self.pending.extend(pending)
+
+        # Dead node won't respond to "steal" request
+        if self.steal_requested_from_node is node:
+            self.steal_requested_from_node = None
+
+        self.check_schedule()
+        return crashitem
+
+    def schedule(self) -> None:
+        """Initiate distribution of the test collection.
+
+        Initiate scheduling of the items across the nodes.  If this
+        gets called again later it behaves the same as calling
+        ``.check_schedule()`` on all nodes so that newly added nodes
+        will start to be used.
+
+        This is called by the ``DSession.worker_collectionfinish`` hook
+        if ``.collection_is_completed`` is True.
+        """
+        assert self.collection_is_completed
+
+        # Initial distribution already happened, reschedule on all nodes
+        if self.collection is not None:
+            self.check_schedule()
+            return
+
+        if not self._check_nodes_have_same_collection():
+            self.log("**Different tests collected, aborting run**")
+            return
+
+        # Collections are identical, create the index of pending items.
+        self.collection = next(iter(self.node2collection.values()))
+        self.pending[:] = range(len(self.collection))
+        if not self.collection:
+            return
+
+        self.check_schedule()
+
+    def _send_tests(self, node: WorkerController, num: int) -> None:
+        tests_per_node = self.pending[:num]
+        if tests_per_node:
+            del self.pending[:num]
+            self.node2pending[node].extend(tests_per_node)
+            node.send_runtest_some(tests_per_node)
+
+    def _check_nodes_have_same_collection(self) -> bool:
+        """Return True if all nodes have collected the same items.
+
+        If collections differ, this method returns False while logging
+        the collection differences and posting collection errors to
+        pytest_collectreport hook.
+        """
+        node_collection_items = list(self.node2collection.items())
+        first_node, col = node_collection_items[0]
+        same_collection = True
+        for node, collection in node_collection_items[1:]:
+            msg = report_collection_diff(
+                col, collection, first_node.gateway.id, node.gateway.id
+            )
+            if msg:
+                same_collection = False
+                self.log(msg)
+                if self.config is not None:
+                    rep = pytest.CollectReport(
+                        nodeid=node.gateway.id,
+                        outcome="failed",
+                        longrepr=msg,
+                        result=[],
+                    )
+                    self.config.hook.pytest_collectreport(report=rep)
+
+        return same_collection

src/xdist/workermanage.py

@@ -1,20 +1,33 @@
+from __future__ import annotations
+
+from collections.abc import Sequence
+from concurrent.futures import ThreadPoolExecutor
+import enum
 import fnmatch
 import os
+from pathlib import Path
 import re
 import sys
+from typing import Any
+from typing import Callable
+from typing import Literal
+from typing import Union
 import uuid
+import warnings
 
-import py
-import pytest
 import execnet
+import pytest
 
-import xdist.remote
 from xdist.plugin import _sys_path
+import xdist.remote
+from xdist.remote import Producer
+from xdist.remote import WorkerInfo
 
 
-def parse_spec_config(config):
+def parse_tx_spec_config(config: pytest.Config) -> list[str]:
     xspeclist = []
-    for xspec in config.getvalue("tx"):
+    tx: list[str] = config.getvalue("tx")
+    for xspec in tx:
         i = xspec.find("*")
         try:
             num = int(xspec[:i])
@@ -33,64 +46,101 @@ class NodeManager:
     EXIT_TIMEOUT = 10
     DEFAULT_IGNORES = [".*", "*.pyc", "*.pyo", "*~"]
 
-    def __init__(self, config, specs=None, defaultchdir="pyexecnetcache"):
+    def __init__(
+        self,
+        config: pytest.Config,
+        specs: Sequence[execnet.XSpec | str] | None = None,
+        defaultchdir: str = "pyexecnetcache",
+    ) -> None:
         self.config = config
         self.trace = self.config.trace.get("nodemanager")
         self.testrunuid = self.config.getoption("testrunuid")
         if self.testrunuid is None:
             self.testrunuid = uuid.uuid4().hex
-        self.group = execnet.Group()
+        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 = []
+        self.specs: list[execnet.XSpec] = []
         for spec in specs:
             if not isinstance(spec, execnet.XSpec):
                 spec = execnet.XSpec(spec)
+            if getattr(spec, "execmodel", None) != "main_thread_only":
+                spec = execnet.XSpec(f"execmodel=main_thread_only//{spec}")
             if not spec.chdir and not spec.popen:
                 spec.chdir = defaultchdir
             self.group.allocate_id(spec)
             self.specs.append(spec)
         self.roots = self._getrsyncdirs()
         self.rsyncoptions = self._getrsyncoptions()
-        self._rsynced_specs = set()
+        self._rsynced_specs: set[tuple[Any, Any]] = set()
 
-    def rsync_roots(self, gateway):
+    def rsync_roots(self, gateway: execnet.Gateway) -> None:
         """Rsync the set of roots to the node's gateway cwd."""
         if self.roots:
             for root in self.roots:
                 self.rsync(gateway, root, **self.rsyncoptions)
 
-    def setup_nodes(self, putevent):
+    def setup_nodes(
+        self,
+        putevent: Callable[[tuple[str, dict[str, Any]]], None],
+    ) -> 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, putevent):
+    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)
         node = WorkerController(self, gw, self.config, putevent)
-        gw.node = node  # keep the node alive
+        # Keep the node alive.
+        gw.node = node  # type: ignore[attr-defined]
         node.setup()
         self.trace("started node %r" % node)
         return node
 
-    def teardown_nodes(self):
+    def teardown_nodes(self) -> None:
         self.group.terminate(self.EXIT_TIMEOUT)
 
-    def _getxspecs(self):
+    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 _getrsyncdirs(self):
+    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:
             if not spec.popen or spec.chdir:
                 break
         else:
             return []
-        import pytest
         import _pytest
+        import pytest
 
-        def get_dir(p):
+        def get_dir(p: str) -> str:
             """Return the directory path if p is a package or the path to the .py file otherwise."""
             stripped = p.rstrip("co")
             if os.path.basename(stripped) == "__init__.py":
@@ -101,37 +151,46 @@ class NodeManager:
         pytestpath = get_dir(pytest.__file__)
         pytestdir = get_dir(_pytest.__file__)
         config = self.config
-        candidates = [py._pydir, pytestpath, pytestdir]
+        candidates = [pytestpath, pytestdir]
         candidates += config.option.rsyncdir
         rsyncroots = config.getini("rsyncdirs")
         if rsyncroots:
             candidates.extend(rsyncroots)
         roots = []
         for root in candidates:
-            root = py.path.local(root).realpath()
+            root_path = Path(root).resolve()
-            if not root.check():
+            if not root_path.exists():
-                raise pytest.UsageError("rsyncdir doesn't exist: {!r}".format(root))
+                raise pytest.UsageError(f"rsyncdir doesn't exist: {root!r}")
-            if root not in roots:
+            if root_path not in roots:
-                roots.append(root)
+                roots.append(root_path)
         return roots
 
-    def _getrsyncoptions(self):
+    def _getrsyncoptions(self) -> dict[str, Any]:
         """Get options to be passed for rsync."""
         ignores = list(self.DEFAULT_IGNORES)
-        ignores += self.config.option.rsyncignore
+        ignores += [str(path) for path in self.config.option.rsyncignore]
-        ignores += self.config.getini("rsyncignore")
+        ignores += [str(path) for path in self.config.getini("rsyncignore")]
 
         return {
             "ignores": ignores,
             "verbose": getattr(self.config.option, "verbose", 0),
         }
 
-    def rsync(self, gateway, source, notify=None, verbose=False, ignores=None):
+    def rsync(
+        self,
+        gateway: execnet.Gateway,
+        source: str | os.PathLike[str],
+        notify: (
+            Callable[[str, execnet.XSpec, str | os.PathLike[str]], Any] | None
+        ) = None,
+        verbose: int = False,
+        ignores: Sequence[str] | None = None,
+    ) -> None:
         """Perform rsync to remote hosts for node."""
         # XXX This changes the calling behaviour of
         #     pytest_xdist_rsyncstart and pytest_xdist_rsyncfinish to
         #     be called once per rsync target.
-        rsync = HostRSync(source, verbose=verbose, ignores=ignores)
+        rsync = HostRSync(source, verbose=verbose > 0, ignores=ignores)
         spec = gateway.spec
         if spec.popen and not spec.chdir:
             # XXX This assumes that sources are python-packages
@@ -146,7 +205,7 @@ class NodeManager:
         if (spec, source) in self._rsynced_specs:
             return
 
-        def finished():
+        def finished() -> None:
             if notify:
                 notify("rsyncrootready", spec, source)
 
@@ -158,65 +217,98 @@ class NodeManager:
 
 
 class HostRSync(execnet.RSync):
-    """RSyncer that filters out common files"""
+    """RSyncer that filters out common files."""
 
-    def __init__(self, sourcedir, *args, **kwargs):
+    PathLike = Union[str, "os.PathLike[str]"]
-        self._synced = {}
-        ignores = kwargs.pop("ignores", None) or []
-        self._ignores = [
-            re.compile(fnmatch.translate(getattr(x, "strpath", x))) for x in ignores
-        ]
-        super().__init__(sourcedir=sourcedir, **kwargs)
 
-    def filter(self, path):
+    def __init__(
-        path = py.path.local(path)
+        self,
+        sourcedir: PathLike,
+        *,
+        ignores: Sequence[PathLike] | None = None,
+        verbose: bool = True,
+    ) -> None:
+        if ignores is None:
+            ignores = []
+        self._ignores = [re.compile(fnmatch.translate(os.fspath(x))) for x in ignores]
+        super().__init__(sourcedir=Path(sourcedir), verbose=verbose)
+
+    def filter(self, path: PathLike) -> bool:
+        path = Path(path)
         for cre in self._ignores:
-            if cre.match(path.basename) or cre.match(path.strpath):
+            if cre.match(path.name) or cre.match(str(path)):
                 return False
         else:
             return True
 
-    def add_target_host(self, gateway, finished=None):
+    def add_target_host(
+        self,
+        gateway: execnet.Gateway,
+        finished: Callable[[], None] | None = None,
+    ) -> None:
         remotepath = os.path.basename(self._sourcedir)
         super().add_target(gateway, remotepath, finishedcallback=finished, delete=True)
 
-    def _report_send_file(self, gateway, modified_rel_path):
+    def _report_send_file(
+        self,
+        gateway: execnet.Gateway,  # type: ignore[override]
+        modified_rel_path: str,
+    ) -> None:
         if self._verbose > 0:
             path = os.path.basename(self._sourcedir) + "/" + modified_rel_path
             remotepath = gateway.spec.chdir
-            print("{}:{} <= {}".format(gateway.spec, remotepath, path))
+            print(f"{gateway.spec}:{remotepath} <= {path}")
 
 
-def make_reltoroot(roots, args):
+def make_reltoroot(roots: Sequence[Path], args: list[str]) -> list[str]:
     # XXX introduce/use public API for splitting pytest args
     splitcode = "::"
     result = []
     for arg in args:
         parts = arg.split(splitcode)
-        fspath = py.path.local(parts[0])
+        fspath = Path(parts[0])
-        if not fspath.exists():
+        try:
+            exists = fspath.exists()
+        except OSError:
+            exists = False
+        if not exists:
             result.append(arg)
             continue
         for root in roots:
-            x = fspath.relto(root)
+            x: Path | None
+            try:
+                x = fspath.relative_to(root)
+            except ValueError:
+                x = None
             if x or fspath == root:
-                parts[0] = root.basename + "/" + x
+                parts[0] = root.name + "/" + str(x)
                 break
         else:
-            raise ValueError("arg {} not relative to an rsync root".format(arg))
+            raise ValueError(f"arg {arg} not relative to an rsync root")
         result.append(splitcode.join(parts))
     return result
 
 
+class Marker(enum.Enum):
+    END = -1
+
+
 class WorkerController:
-    ENDMARK = -1
+    # Set when the worker is ready.
+    workerinfo: WorkerInfo
 
     class RemoteHook:
-        @pytest.mark.trylast
+        @pytest.hookimpl(trylast=True)
-        def pytest_xdist_getremotemodule(self):
+        def pytest_xdist_getremotemodule(self) -> Any:
             return xdist.remote
 
-    def __init__(self, nodemanager, gateway, config, putevent):
+    def __init__(
+        self,
+        nodemanager: NodeManager,
+        gateway: execnet.Gateway,
+        config: pytest.Config,
+        putevent: Callable[[tuple[str, dict[str, Any]]], None],
+    ) -> None:
         config.pluginmanager.register(self.RemoteHook())
         self.nodemanager = nodemanager
         self.putevent = putevent
@@ -230,33 +322,32 @@ class WorkerController:
         }
         self._down = False
         self._shutdown_sent = False
-        self.log = py.log.Producer("workerctl-%s" % gateway.id)
+        self.log = Producer(f"workerctl-{gateway.id}", enabled=config.option.debug)
-        if not self.config.option.debug:
-            py.log.setconsumer(self.log._keywords, None)
 
-    def __repr__(self):
+    def __repr__(self) -> str:
-        return "<{} {}>".format(self.__class__.__name__, self.gateway.id)
+        return f"<{self.__class__.__name__} {self.gateway.id}>"
 
     @property
-    def shutting_down(self):
+    def shutting_down(self) -> bool:
         return self._down or self._shutdown_sent
 
-    def setup(self):
+    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
-        if hasattr(self.config, "invocation_params"):
+        args = [str(x) for x in self.config.invocation_params.args or ()]
-            args = [str(x) for x in self.config.invocation_params.args or ()]
+        option_dict = {}
-            option_dict = {}
-        else:
-            args = self.config.args
-            option_dict = vars(self.config.option)
         if not spec.popen or spec.chdir:
             args = make_reltoroot(self.nodemanager.roots, args)
         if spec.popen:
             name = "popen-%s" % self.gateway.id
-            if hasattr(self.config, "_tmpdirhandler"):
+            if hasattr(self.config, "_tmp_path_factory"):
-                basetemp = self.config._tmpdirhandler.getbasetemp()
+                basetemp = self.config._tmp_path_factory.getbasetemp()
-                option_dict["basetemp"] = str(basetemp.join(name))
+                option_dict["basetemp"] = str(basetemp / name)
         self.config.hook.pytest_configure_node(node=self)
 
         remote_module = self.config.hook.pytest_xdist_getremotemodule()
@@ -266,10 +357,11 @@ class WorkerController:
         change_sys_path = _sys_path if self.gateway.spec.popen else None
         self.channel.send((self.workerinput, args, option_dict, change_sys_path))
 
-        if self.putevent:
+        # putevent is only None in a test.
-            self.channel.setcallback(self.process_from_remote, endmarker=self.ENDMARK)
+        if self.putevent:  # type: ignore[truthy-function]
+            self.channel.setcallback(self.process_from_remote, endmarker=Marker.END)
 
-    def ensure_teardown(self):
+    def ensure_teardown(self) -> None:
         if hasattr(self, "channel"):
             if not self.channel.isclosed():
                 self.log("closing", self.channel)
@@ -280,13 +372,16 @@ class WorkerController:
             self.gateway.exit()
             # del self.gateway
 
-    def send_runtest_some(self, indices):
+    def send_runtest_some(self, indices: Sequence[int]) -> None:
         self.sendcommand("runtests", indices=indices)
 
-    def send_runtest_all(self):
+    def send_runtest_all(self) -> None:
         self.sendcommand("runtests_all")
 
-    def shutdown(self):
+    def send_steal(self, indices: Sequence[int]) -> None:
+        self.sendcommand("steal", indices=indices)
+
+    def shutdown(self) -> None:
         if not self._down:
             try:
                 self.sendcommand("shutdown")
@@ -294,17 +389,19 @@ class WorkerController:
                 pass
             self._shutdown_sent = True
 
-    def sendcommand(self, name, **kwargs):
+    def sendcommand(self, name: str, **kwargs: object) -> None:
-        """send a named parametrized command to the other side."""
+        """Send a named parametrized command to the other side."""
-        self.log("sending command {}(**{})".format(name, kwargs))
+        self.log(f"sending command {name}(**{kwargs})")
         self.channel.send((name, kwargs))
 
-    def notify_inproc(self, eventname, **kwargs):
+    def notify_inproc(self, eventname: str, **kwargs: object) -> None:
-        self.log("queuing {}(**{})".format(eventname, kwargs))
+        self.log(f"queuing {eventname}(**{kwargs})")
         self.putevent((eventname, kwargs))
 
-    def process_from_remote(self, eventcall):  # noqa too complex
+    def process_from_remote(
-        """this gets called for each object we receive from
+        self, eventcall: tuple[str, dict[str, Any]] | Literal[Marker.END]
+    ) -> None:
+        """This gets called for each object we receive from
         the other side and if the channel closes.
 
         Note that channel callbacks run in the receiver
@@ -312,8 +409,8 @@ class WorkerController:
         avoid raising exceptions or doing heavy work.
         """
         try:
-            if eventcall == self.ENDMARK:
+            if eventcall is Marker.END:
-                err = self.channel._getremoteerror()
+                err: object | None = self.channel._getremoteerror()  # type: ignore[no-untyped-call]
                 if not self._down:
                     if not err or isinstance(err, EOFError):
                         err = "Not properly terminated"  # lost connection?
@@ -322,7 +419,7 @@ class WorkerController:
                 return
             eventname, kwargs = eventcall
             if eventname in ("collectionstart",):
-                self.log("ignoring {}({})".format(eventname, kwargs))
+                self.log(f"ignoring {eventname}({kwargs})")
             elif eventname == "workerready":
                 self.notify_inproc(eventname, node=self, **kwargs)
             elif eventname == "internal_error":
@@ -345,6 +442,8 @@ class WorkerController:
                 self.notify_inproc(eventname, node=self, ids=kwargs["ids"])
             elif eventname == "runtest_protocol_complete":
                 self.notify_inproc(eventname, node=self, **kwargs)
+            elif eventname == "unscheduled":
+                self.notify_inproc(eventname, node=self, **kwargs)
             elif eventname == "logwarning":
                 self.notify_inproc(
                     eventname,
@@ -353,16 +452,6 @@ class WorkerController:
                     nodeid=kwargs["nodeid"],
                     fslocation=kwargs["nodeid"],
                 )
-            elif eventname == "warning_captured":
-                warning_message = unserialize_warning_message(
-                    kwargs["warning_message_data"]
-                )
-                self.notify_inproc(
-                    eventname,
-                    warning_message=warning_message,
-                    when=kwargs["when"],
-                    item=kwargs["item"],
-                )
             elif eventname == "warning_recorded":
                 warning_message = unserialize_warning_message(
                     kwargs["warning_message_data"]
@@ -375,22 +464,19 @@ class WorkerController:
                     location=kwargs["location"],
                 )
             else:
-                raise ValueError("unknown event: {}".format(eventname))
+                raise ValueError(f"unknown event: {eventname}")
         except KeyboardInterrupt:
             # should not land in receiver-thread
             raise
-        except:  # noqa
+        except BaseException:
-            from _pytest._code import ExceptionInfo
+            excinfo = pytest.ExceptionInfo.from_current()
-
-            excinfo = ExceptionInfo.from_current()
             print("!" * 20, excinfo)
             self.config.notify_exception(excinfo)
             self.shutdown()
             self.notify_inproc("errordown", node=self, error=excinfo)
 
 
-def unserialize_warning_message(data):
+def unserialize_warning_message(data: dict[str, Any]) -> warnings.WarningMessage:
-    import warnings
     import importlib
 
     if data["message_module"]:
@@ -423,7 +509,7 @@ def unserialize_warning_message(data):
 
     kwargs = {"message": message, "category": category}
     # access private _WARNING_DETAILS because the attributes vary between Python versions
-    for attr_name in warnings.WarningMessage._WARNING_DETAILS:
+    for attr_name in warnings.WarningMessage._WARNING_DETAILS:  # type: ignore[attr-defined]
         if attr_name in ("message", "category"):
             continue
         kwargs[attr_name] = data[attr_name]

testing/conftest.py

@@ -1,17 +1,25 @@
-import py
+from __future__ import annotations
-import pytest
+
+from collections.abc import Generator
+import shutil
+from typing import Callable
+
 import execnet
+import pytest
+
 
 pytest_plugins = "pytester"
 
 
 @pytest.fixture(autouse=True)
-def _divert_atexit(request, monkeypatch):
+def _divert_atexit(monkeypatch: pytest.MonkeyPatch) -> Generator[None]:
     import atexit
 
     finalizers = []
 
-    def fake_register(func, *args, **kwargs):
+    def fake_register(
+        func: Callable[..., object], *args: object, **kwargs: object
+    ) -> None:
         finalizers.append((func, args, kwargs))
 
     monkeypatch.setattr(atexit, "register", fake_register)
@@ -23,7 +31,7 @@ def _divert_atexit(request, monkeypatch):
         func(*args, **kwargs)
 
 
-def pytest_addoption(parser):
+def pytest_addoption(parser: pytest.Parser) -> None:
     parser.addoption(
         "--gx",
         action="append",
@@ -33,28 +41,28 @@ def pytest_addoption(parser):
 
 
 @pytest.fixture
-def specssh(request):
+def specssh(request: pytest.FixtureRequest) -> str:
     return getspecssh(request.config)
 
 
 # configuration information for tests
-def getgspecs(config):
+def getgspecs(config: pytest.Config) -> list[execnet.XSpec]:
     return [execnet.XSpec(spec) for spec in config.getvalueorskip("gspecs")]
 
 
-def getspecssh(config):
+def getspecssh(config: pytest.Config) -> str:
     xspecs = getgspecs(config)
     for spec in xspecs:
         if spec.ssh:
-            if not py.path.local.sysfind("ssh"):
+            if not shutil.which("ssh"):
-                py.test.skip("command not found: ssh")
+                pytest.skip("command not found: ssh")
             return str(spec)
-    py.test.skip("need '--gx ssh=...'")
+    pytest.skip("need '--gx ssh=...'")
 
 
-def getsocketspec(config):
+def getsocketspec(config: pytest.Config) -> execnet.XSpec:
     xspecs = getgspecs(config)
     for spec in xspecs:
         if spec.socket:
             return spec
-    py.test.skip("need '--gx socket=...'")
+    pytest.skip("need '--gx socket=...'")

testing/test_dsession.py

@@ -1,60 +1,68 @@
-from xdist.dsession import DSession, get_default_max_worker_restart
+from __future__ import annotations
-from xdist.report import report_collection_diff
+
-from xdist.scheduler import EachScheduling, LoadScheduling
+from collections.abc import Sequence
+from typing import Any
+from typing import cast
+from typing import TYPE_CHECKING
 
-import py
-import pytest
 import execnet
+import pytest
 
-XSpec = execnet.XSpec
+from xdist.dsession import DSession
+from xdist.dsession import get_default_max_worker_restart
+from xdist.dsession import get_workers_status_line
+from xdist.dsession import WorkerStatus
+from xdist.report import report_collection_diff
+from xdist.scheduler import EachScheduling
+from xdist.scheduler import LoadScheduling
+from xdist.scheduler import WorkStealingScheduling
+from xdist.workermanage import WorkerController
 
 
-def run(item, node, excinfo=None):
+if TYPE_CHECKING:
-    runner = item.config.pluginmanager.getplugin("runner")
+    BaseOfMockGateway = execnet.Gateway
-    rep = runner.ItemTestReport(item=item, excinfo=excinfo, when="call")
+    BaseOfMockNode = WorkerController
-    rep.node = node
+else:
-    return rep
+    BaseOfMockGateway = object
+    BaseOfMockNode = object
 
 
-class MockGateway:
+class MockGateway(BaseOfMockGateway):
-    _count = 0
+    def __init__(self) -> None:
-
+        self._count = 0
-    def __init__(self):
         self.id = str(self._count)
         self._count += 1
 
 
-class MockNode:
+class MockNode(BaseOfMockNode):
-    def __init__(self):
+    def __init__(self) -> None:
-        self.sent = []
+        self.sent: list[int | str] = []
+        self.stolen: list[int] = []
         self.gateway = MockGateway()
         self._shutdown = False
 
-    def send_runtest_some(self, indices):
+    def send_runtest_some(self, indices: Sequence[int]) -> None:
         self.sent.extend(indices)
 
-    def send_runtest_all(self):
+    def send_runtest_all(self) -> None:
         self.sent.append("ALL")
 
-    def shutdown(self):
+    def send_steal(self, indices: Sequence[int]) -> None:
+        self.stolen.extend(indices)
+
+    def shutdown(self) -> None:
         self._shutdown = True
 
     @property
-    def shutting_down(self):
+    def shutting_down(self) -> bool:
         return self._shutdown
 
 
-def dumpqueue(queue):
-    while queue.qsize():
-        print(queue.get())
-
-
 class TestEachScheduling:
-    def test_schedule_load_simple(self, testdir):
+    def test_schedule_load_simple(self, pytester: pytest.Pytester) -> None:
-        node1 = MockNode()
+        config = pytester.parseconfig("--tx=2*popen")
-        node2 = MockNode()
-        config = testdir.parseconfig("--tx=2*popen")
         sched = EachScheduling(config)
+        node1, node2 = MockNode(), MockNode()
         sched.add_node(node1)
         sched.add_node(node2)
         collection = ["a.py::test_1"]
@@ -62,7 +70,7 @@ class TestEachScheduling:
         sched.add_node_collection(node1, collection)
         assert not sched.collection_is_completed
         sched.add_node_collection(node2, collection)
-        assert sched.collection_is_completed
+        assert bool(sched.collection_is_completed)
         assert sched.node2collection[node1] == collection
         assert sched.node2collection[node2] == collection
         sched.schedule()
@@ -74,15 +82,15 @@ class TestEachScheduling:
         sched.mark_test_complete(node2, 0)
         assert sched.tests_finished
 
-    def test_schedule_remove_node(self, testdir):
+    def test_schedule_remove_node(self, pytester: pytest.Pytester) -> None:
-        node1 = MockNode()
+        config = pytester.parseconfig("--tx=popen")
-        config = testdir.parseconfig("--tx=popen")
         sched = EachScheduling(config)
+        node1 = MockNode()
         sched.add_node(node1)
         collection = ["a.py::test_1"]
         assert not sched.collection_is_completed
         sched.add_node_collection(node1, collection)
-        assert sched.collection_is_completed
+        assert bool(sched.collection_is_completed)
         assert sched.node2collection[node1] == collection
         sched.schedule()
         assert sched.tests_finished
@@ -93,18 +101,18 @@ class TestEachScheduling:
 
 
 class TestLoadScheduling:
-    def test_schedule_load_simple(self, testdir):
+    def test_schedule_load_simple(self, pytester: pytest.Pytester) -> None:
-        config = testdir.parseconfig("--tx=2*popen")
+        config = pytester.parseconfig("--tx=2*popen")
         sched = LoadScheduling(config)
-        sched.add_node(MockNode())
+        node1, node2 = MockNode(), MockNode()
-        sched.add_node(MockNode())
+        sched.add_node(node1)
-        node1, node2 = sched.nodes
+        sched.add_node(node2)
         collection = ["a.py::test_1", "a.py::test_2"]
         assert not sched.collection_is_completed
         sched.add_node_collection(node1, collection)
         assert not sched.collection_is_completed
         sched.add_node_collection(node2, collection)
-        assert sched.collection_is_completed
+        assert bool(sched.collection_is_completed)
         assert sched.node2collection[node1] == collection
         assert sched.node2collection[node2] == collection
         sched.schedule()
@@ -114,15 +122,17 @@ class TestLoadScheduling:
         assert len(node2.sent) == 1
         assert node1.sent == [0]
         assert node2.sent == [1]
-        sched.mark_test_complete(node1, node1.sent[0])
+        sent10 = node1.sent[0]
+        assert isinstance(sent10, int)
+        sched.mark_test_complete(node1, sent10)
         assert sched.tests_finished
 
-    def test_schedule_batch_size(self, testdir):
+    def test_schedule_batch_size(self, pytester: pytest.Pytester) -> None:
-        config = testdir.parseconfig("--tx=2*popen")
+        config = pytester.parseconfig("--tx=2*popen")
         sched = LoadScheduling(config)
-        sched.add_node(MockNode())
+        node1, node2 = MockNode(), MockNode()
-        sched.add_node(MockNode())
+        sched.add_node(node1)
-        node1, node2 = sched.nodes
+        sched.add_node(node2)
         col = ["xyz"] * 6
         sched.add_node_collection(node1, col)
         sched.add_node_collection(node2, col)
@@ -130,64 +140,116 @@ class TestLoadScheduling:
         # assert not sched.tests_finished
         sent1 = node1.sent
         sent2 = node2.sent
-        assert sent1 == [0, 2]
+        assert sent1 == [0, 1]
-        assert sent2 == [1, 3]
+        assert sent2 == [2, 3]
         assert sched.pending == [4, 5]
         assert sched.node2pending[node1] == sent1
         assert sched.node2pending[node2] == sent2
         assert len(sched.pending) == 2
         sched.mark_test_complete(node1, 0)
-        assert node1.sent == [0, 2, 4]
+        assert node1.sent == [0, 1, 4]
         assert sched.pending == [5]
-        assert node2.sent == [1, 3]
+        assert node2.sent == [2, 3]
-        sched.mark_test_complete(node1, 2)
+        sched.mark_test_complete(node1, 1)
-        assert node1.sent == [0, 2, 4, 5]
+        assert node1.sent == [0, 1, 4, 5]
         assert not sched.pending
 
-    def test_schedule_fewer_tests_than_nodes(self, testdir):
+    def test_schedule_maxchunk_none(self, pytester: pytest.Pytester) -> None:
-        config = testdir.parseconfig("--tx=2*popen")
+        config = pytester.parseconfig("--tx=2*popen")
         sched = LoadScheduling(config)
-        sched.add_node(MockNode())
+        node1, node2 = MockNode(), MockNode()
-        sched.add_node(MockNode())
+        sched.add_node(node1)
-        sched.add_node(MockNode())
+        sched.add_node(node2)
-        node1, node2, node3 = sched.nodes
+        col = [f"test{i}" for i in range(16)]
+        sched.add_node_collection(node1, col)
+        sched.add_node_collection(node2, col)
+        sched.schedule()
+        assert node1.sent == [0, 1]
+        assert node2.sent == [2, 3]
+        assert sched.pending == list(range(4, 16))
+        assert sched.node2pending[node1] == node1.sent
+        assert sched.node2pending[node2] == node2.sent
+        sched.mark_test_complete(node1, 0)
+        assert node1.sent == [0, 1, 4, 5]
+        assert sched.pending == list(range(6, 16))
+        sched.mark_test_complete(node1, 1)
+        assert node1.sent == [0, 1, 4, 5]
+        assert sched.pending == list(range(6, 16))
+
+        for i in range(7, 16):
+            sched.mark_test_complete(node1, i - 3)
+            assert node1.sent == [0, 1, *range(4, i)]
+            assert node2.sent == [2, 3]
+            assert sched.pending == list(range(i, 16))
+
+    def test_schedule_maxchunk_1(self, pytester: pytest.Pytester) -> None:
+        config = pytester.parseconfig("--tx=2*popen", "--maxschedchunk=1")
+        sched = LoadScheduling(config)
+        node1, node2 = MockNode(), MockNode()
+        sched.add_node(node1)
+        sched.add_node(node2)
+        col = [f"test{i}" for i in range(16)]
+        sched.add_node_collection(node1, col)
+        sched.add_node_collection(node2, col)
+        sched.schedule()
+        assert node1.sent == [0, 1]
+        assert node2.sent == [2, 3]
+        assert sched.pending == list(range(4, 16))
+        assert sched.node2pending[node1] == node1.sent
+        assert sched.node2pending[node2] == node2.sent
+
+        for complete_index, first_pending in enumerate(range(5, 16)):
+            sent_index = node1.sent[complete_index]
+            assert isinstance(sent_index, int)
+            sched.mark_test_complete(node1, sent_index)
+            assert node1.sent == [0, 1, *range(4, first_pending)]
+            assert node2.sent == [2, 3]
+            assert sched.pending == list(range(first_pending, 16))
+
+    def test_schedule_fewer_tests_than_nodes(self, pytester: pytest.Pytester) -> None:
+        config = pytester.parseconfig("--tx=3*popen")
+        sched = LoadScheduling(config)
+        node1, node2, node3 = MockNode(), MockNode(), MockNode()
+        sched.add_node(node1)
+        sched.add_node(node2)
+        sched.add_node(node3)
         col = ["xyz"] * 2
         sched.add_node_collection(node1, col)
         sched.add_node_collection(node2, col)
+        sched.add_node_collection(node3, col)
+        assert sched.collection_is_completed
         sched.schedule()
         # assert not sched.tests_finished
-        sent1 = node1.sent
+        assert node1.sent == [0]
-        sent2 = node2.sent
+        assert node2.sent == [1]
-        sent3 = node3.sent
+        assert node3.sent == []
-        assert sent1 == [0]
-        assert sent2 == [1]
-        assert sent3 == []
         assert not sched.pending
 
-    def test_schedule_fewer_than_two_tests_per_node(self, testdir):
+    def test_schedule_fewer_than_two_tests_per_node(
-        config = testdir.parseconfig("--tx=2*popen")
+        self, pytester: pytest.Pytester
+    ) -> None:
+        config = pytester.parseconfig("--tx=3*popen")
         sched = LoadScheduling(config)
-        sched.add_node(MockNode())
+        node1, node2, node3 = MockNode(), MockNode(), MockNode()
-        sched.add_node(MockNode())
+        sched.add_node(node1)
-        sched.add_node(MockNode())
+        sched.add_node(node2)
-        node1, node2, node3 = sched.nodes
+        sched.add_node(node3)
         col = ["xyz"] * 5
         sched.add_node_collection(node1, col)
         sched.add_node_collection(node2, col)
+        sched.add_node_collection(node3, col)
+        assert sched.collection_is_completed
         sched.schedule()
         # assert not sched.tests_finished
-        sent1 = node1.sent
+        assert node1.sent == [0, 3]
-        sent2 = node2.sent
+        assert node2.sent == [1, 4]
-        sent3 = node3.sent
+        assert node3.sent == [2]
-        assert sent1 == [0, 3]
-        assert sent2 == [1, 4]
-        assert sent3 == [2]
         assert not sched.pending
 
-    def test_add_remove_node(self, testdir):
+    def test_add_remove_node(self, pytester: pytest.Pytester) -> None:
-        node = MockNode()
+        config = pytester.parseconfig("--tx=popen")
-        config = testdir.parseconfig("--tx=popen")
         sched = LoadScheduling(config)
+        node = MockNode()
         sched.add_node(node)
         collection = ["test_file.py::test_func"]
         sched.add_node_collection(node, collection)
@@ -197,29 +259,26 @@ class TestLoadScheduling:
         crashitem = sched.remove_node(node)
         assert crashitem == collection[0]
 
-    def test_different_tests_collected(self, testdir):
+    def test_different_tests_collected(self, pytester: pytest.Pytester) -> None:
         """
         Test that LoadScheduling is reporting collection errors when
         different test ids are collected by workers.
         """
 
         class CollectHook:
-            """
+            """Dummy hook that stores collection reports."""
-            Dummy hook that stores collection reports.
-            """
 
-            def __init__(self):
+            def __init__(self) -> None:
-                self.reports = []
+                self.reports: list[pytest.CollectReport] = []
 
-            def pytest_collectreport(self, report):
+            def pytest_collectreport(self, report: pytest.CollectReport) -> None:
                 self.reports.append(report)
 
         collect_hook = CollectHook()
-        config = testdir.parseconfig("--tx=2*popen")
+        config = pytester.parseconfig("--tx=2*popen")
         config.pluginmanager.register(collect_hook, "collect_hook")
-        node1 = MockNode()
-        node2 = MockNode()
         sched = LoadScheduling(config)
+        node1, node2 = MockNode(), MockNode()
         sched.add_node(node1)
         sched.add_node(node2)
         sched.add_node_collection(node1, ["a.py::test_1"])
@@ -227,14 +286,192 @@ class TestLoadScheduling:
         sched.schedule()
         assert len(collect_hook.reports) == 1
         rep = collect_hook.reports[0]
+        assert isinstance(rep.longrepr, str)
+        assert "Different tests were collected between" in rep.longrepr
+
+
+class TestWorkStealingScheduling:
+    def test_ideal_case(self, pytester: pytest.Pytester) -> None:
+        config = pytester.parseconfig("--tx=2*popen")
+        sched = WorkStealingScheduling(config)
+        node1, node2 = MockNode(), MockNode()
+        sched.add_node(node1)
+        sched.add_node(node2)
+        collection = [f"test_workstealing.py::test_{i}" for i in range(16)]
+        assert not sched.collection_is_completed
+        sched.add_node_collection(node1, collection)
+        assert not sched.collection_is_completed
+        sched.add_node_collection(node2, collection)
+        assert bool(sched.collection_is_completed)
+        assert sched.node2collection[node1] == collection
+        assert sched.node2collection[node2] == collection
+        sched.schedule()
+        assert not sched.pending
+        assert not sched.tests_finished
+        assert node1.sent == list(range(8))
+        assert node2.sent == list(range(8, 16))
+        for i in range(8):
+            sent1, sent2 = node1.sent[i], node2.sent[i]
+            assert isinstance(sent1, int) and isinstance(sent2, int)
+            sched.mark_test_complete(node1, sent1)
+            sched.mark_test_complete(node2, sent2)
+        assert bool(sched.tests_finished)
+        assert node1.stolen == []
+        assert node2.stolen == []
+
+    def test_stealing(self, pytester: pytest.Pytester) -> None:
+        config = pytester.parseconfig("--tx=2*popen")
+        sched = WorkStealingScheduling(config)
+        node1, node2 = MockNode(), MockNode()
+        sched.add_node(node1)
+        sched.add_node(node2)
+        collection = [f"test_workstealing.py::test_{i}" for i in range(16)]
+        sched.add_node_collection(node1, collection)
+        sched.add_node_collection(node2, collection)
+        assert sched.collection_is_completed
+        sched.schedule()
+        assert node1.sent == list(range(8))
+        assert node2.sent == list(range(8, 16))
+        for i in range(8):
+            sent = node1.sent[i]
+            assert isinstance(sent, int)
+            sched.mark_test_complete(node1, sent)
+        assert node2.stolen == list(range(12, 16))
+        sched.remove_pending_tests_from_node(node2, node2.stolen)
+        for i in range(4):
+            sent = node2.sent[i]
+            assert isinstance(sent, int)
+            sched.mark_test_complete(node2, sent)
+        assert node1.stolen == [14, 15]
+        sched.remove_pending_tests_from_node(node1, node1.stolen)
+        sched.mark_test_complete(node1, 12)
+        sched.mark_test_complete(node2, 14)
+        assert node2.stolen == list(range(12, 16))
+        assert node1.stolen == [14, 15]
+        assert sched.tests_finished
+
+    def test_steal_on_add_node(self, pytester: pytest.Pytester) -> None:
+        node = MockNode()
+        config = pytester.parseconfig("--tx=popen")
+        sched = WorkStealingScheduling(config)
+        sched.add_node(node)
+        collection = [f"test_workstealing.py::test_{i}" for i in range(5)]
+        sched.add_node_collection(node, collection)
+        assert sched.collection_is_completed
+        sched.schedule()
+        assert not sched.pending
+        sched.mark_test_complete(node, 0)
+        node2 = MockNode()
+        sched.add_node(node2)
+        sched.add_node_collection(node2, collection)
+        assert sched.collection_is_completed
+        sched.schedule()
+        assert node.stolen == [3, 4]
+        sched.remove_pending_tests_from_node(node, node.stolen)
+        sched.mark_test_complete(node, 1)
+        sched.mark_test_complete(node2, 3)
+        assert sched.tests_finished
+        assert node2.stolen == []
+
+    def test_schedule_fewer_tests_than_nodes(self, pytester: pytest.Pytester) -> None:
+        config = pytester.parseconfig("--tx=3*popen")
+        sched = WorkStealingScheduling(config)
+        node1, node2, node3 = MockNode(), MockNode(), MockNode()
+        sched.add_node(node1)
+        sched.add_node(node2)
+        sched.add_node(node3)
+        col = ["xyz"] * 2
+        sched.add_node_collection(node1, col)
+        sched.add_node_collection(node2, col)
+        sched.add_node_collection(node3, col)
+        sched.schedule()
+        assert node1.sent == []
+        assert node1.stolen == []
+        assert node2.sent == [0]
+        assert node2.stolen == []
+        assert node3.sent == [1]
+        assert node3.stolen == []
+        assert not sched.pending
+        assert sched.tests_finished
+
+    def test_schedule_fewer_than_two_tests_per_node(
+        self, pytester: pytest.Pytester
+    ) -> None:
+        config = pytester.parseconfig("--tx=3*popen")
+        sched = WorkStealingScheduling(config)
+        node1, node2, node3 = MockNode(), MockNode(), MockNode()
+        sched.add_node(node1)
+        sched.add_node(node2)
+        sched.add_node(node3)
+        col = ["xyz"] * 5
+        sched.add_node_collection(node1, col)
+        sched.add_node_collection(node2, col)
+        sched.add_node_collection(node3, col)
+        sched.schedule()
+        assert node1.sent == [0]
+        assert node2.sent == [1, 2]
+        assert node3.sent == [3, 4]
+        assert not sched.pending
+        assert not sched.tests_finished
+        sent10 = node1.sent[0]
+        assert isinstance(sent10, int)
+        sent20 = node2.sent[0]
+        assert isinstance(sent20, int)
+        sent30 = node3.sent[0]
+        assert isinstance(sent30, int)
+        sent31 = node3.sent[1]
+        assert isinstance(sent31, int)
+        sched.mark_test_complete(node1, sent10)
+        sched.mark_test_complete(node2, sent20)
+        sched.mark_test_complete(node3, sent30)
+        sched.mark_test_complete(node3, sent31)
+        assert bool(sched.tests_finished)
+        assert node1.stolen == []
+        assert node2.stolen == []
+        assert node3.stolen == []
+
+    def test_add_remove_node(self, pytester: pytest.Pytester) -> None:
+        node = MockNode()
+        config = pytester.parseconfig("--tx=popen")
+        sched = WorkStealingScheduling(config)
+        sched.add_node(node)
+        collection = ["test_file.py::test_func"]
+        sched.add_node_collection(node, collection)
+        assert sched.collection_is_completed
+        sched.schedule()
+        assert not sched.pending
+        crashitem = sched.remove_node(node)
+        assert crashitem == collection[0]
+
+    def test_different_tests_collected(self, pytester: pytest.Pytester) -> None:
+        class CollectHook:
+            def __init__(self) -> None:
+                self.reports: list[pytest.CollectReport] = []
+
+            def pytest_collectreport(self, report: pytest.CollectReport) -> None:
+                self.reports.append(report)
+
+        collect_hook = CollectHook()
+        config = pytester.parseconfig("--tx=2*popen")
+        config.pluginmanager.register(collect_hook, "collect_hook")
+        sched = WorkStealingScheduling(config)
+        node1, node2 = MockNode(), MockNode()
+        sched.add_node(node1)
+        sched.add_node(node2)
+        sched.add_node_collection(node1, ["a.py::test_1"])
+        sched.add_node_collection(node2, ["a.py::test_2"])
+        sched.schedule()
+        assert len(collect_hook.reports) == 1
+        rep = collect_hook.reports[0]
+        assert isinstance(rep.longrepr, str)
         assert "Different tests were collected between" in rep.longrepr
 
 
 class TestDistReporter:
-    @py.test.mark.xfail
+    @pytest.mark.xfail
-    def test_rsync_printing(self, testdir, linecomp):
+    def test_rsync_printing(self, pytester: pytest.Pytester, linecomp: Any) -> None:
-        config = testdir.parseconfig()
+        config = pytester.parseconfig()
-        from _pytest.pytest_terminal import TerminalReporter
+        from _pytest.terminal import TerminalReporter
 
         rep = TerminalReporter(config, file=linecomp.stringio)
         config.pluginmanager.register(rep, "terminalreporter")
@@ -258,21 +495,23 @@ class TestDistReporter:
         # linecomp.assert_contains_lines([
         #     "*X1*popen*xyz*2.5*"
         # ])
-        dsession.pytest_xdist_rsyncstart(source="hello", gateways=[gw1, gw2])
+        dsession.pytest_xdist_rsyncstart(source="hello", gateways=[gw1, gw2])  # type: ignore[attr-defined]
         linecomp.assert_contains_lines(["[X1,X2] rsyncing: hello"])
 
 
-def test_report_collection_diff_equal():
+def test_report_collection_diff_equal() -> None:
     """Test reporting of equal collections."""
     from_collection = to_collection = ["aaa", "bbb", "ccc"]
-    assert report_collection_diff(from_collection, to_collection, 1, 2) is None
+    assert report_collection_diff(from_collection, to_collection, "1", "2") is None
 
 
-def test_default_max_worker_restart():
+def test_default_max_worker_restart() -> None:
-    class config:
+    class MockConfig:
         class option:
-            maxworkerrestart = None
+            maxworkerrestart: str | None = None
-            numprocesses = 0
+            numprocesses: int = 0
+
+    config = cast(pytest.Config, MockConfig)
 
     assert get_default_max_worker_restart(config) is None
 
@@ -286,7 +525,7 @@ def test_default_max_worker_restart():
     assert get_default_max_worker_restart(config) == 0
 
 
-def test_report_collection_diff_different():
+def test_report_collection_diff_different() -> None:
     """Test reporting of different collections."""
     from_collection = ["aaa", "bbb", "ccc", "YYY"]
     to_collection = ["aZa", "bbb", "XXX", "ccc"]
@@ -303,7 +542,9 @@ def test_report_collection_diff_different():
         " bbb\n"
         "+XXX\n"
         " ccc\n"
-        "-YYY"
+        "-YYY\n"
+        "To see why this happens see 'Known limitations' in documentation "
+        "for pytest-xdist"
     )
 
     msg = report_collection_diff(from_collection, to_collection, "1", "2")
@@ -311,8 +552,8 @@ def test_report_collection_diff_different():
 
 
 @pytest.mark.xfail(reason="duplicate test ids not supported yet")
-def test_pytest_issue419(testdir):
+def test_pytest_issue419(pytester: pytest.Pytester) -> None:
-    testdir.makepyfile(
+    pytester.makepyfile(
         """
         import pytest
 
@@ -321,6 +562,73 @@ def test_pytest_issue419(testdir):
             pass
     """
     )
-    reprec = testdir.inline_run("-n1")
+    reprec = pytester.inline_run("-n1")
     reprec.assertoutcome(passed=2)
     assert 0
+
+
+Created = WorkerStatus.Created
+Initialized = WorkerStatus.Initialized
+ReadyForCollection = WorkerStatus.ReadyForCollection
+CollectionDone = WorkerStatus.CollectionDone
+
+
+@pytest.mark.parametrize(
+    "status_and_items, expected",
+    [
+        (
+            [],
+            "",
+        ),
+        (
+            [(Created, 0)],
+            "created: 1/1 worker",
+        ),
+        (
+            [(Created, 0), (Created, 0)],
+            "created: 2/2 workers",
+        ),
+        (
+            [(Initialized, 0), (Created, 0)],
+            "initialized: 1/2 workers",
+        ),
+        (
+            [(Initialized, 0), (Initialized, 0)],
+            "initialized: 2/2 workers",
+        ),
+        (
+            [(ReadyForCollection, 0), (Created, 0)],
+            "ready: 1/2 workers",
+        ),
+        (
+            [(ReadyForCollection, 0), (ReadyForCollection, 0)],
+            "ready: 2/2 workers",
+        ),
+        (
+            [(CollectionDone, 12), (Created, 0)],
+            "collecting: 1/2 workers",
+        ),
+        (
+            [(CollectionDone, 12), (CollectionDone, 12)],
+            "2 workers [12 items]",
+        ),
+        (
+            [(CollectionDone, 1), (CollectionDone, 1)],
+            "2 workers [1 item]",
+        ),
+        (
+            [(CollectionDone, 1)],
+            "1 worker [1 item]",
+        ),
+        # Different number of tests collected will raise an error and should not happen in practice,
+        # but we test for it anyway.
+        (
+            [(CollectionDone, 1), (CollectionDone, 12)],
+            "2 workers [1 item]",
+        ),
+    ],
+)
+def test_get_workers_status_line(
+    status_and_items: Sequence[tuple[WorkerStatus, int]], expected: str
+) -> None:
+    assert get_workers_status_line(status_and_items) == expected

testing/test_looponfail.py

@@ -1,89 +1,108 @@
-import py
+from __future__ import annotations
+
+import pathlib
+from pathlib import Path
+import shutil
+import tempfile
+import textwrap
+import unittest.mock
+
 import pytest
-from pkg_resources import parse_version
 
 from xdist.looponfail import RemoteControl
 from xdist.looponfail import StatRecorder
 
 
 class TestStatRecorder:
-    def test_filechange(self, tmpdir):
+    def test_filechange(self, tmp_path: Path) -> None:
-        tmp = tmpdir
+        tmp = tmp_path
-        hello = tmp.ensure("hello.py")
+        hello = tmp / "hello.py"
+        hello.touch()
         sd = StatRecorder([tmp])
         changed = sd.check()
         assert not changed
 
-        hello.write("world")
+        hello.write_text("world")
         changed = sd.check()
         assert changed
 
-        (hello + "c").write("hello")
+        hello.with_suffix(".pyc").write_text("hello")
         changed = sd.check()
         assert not changed
 
-        p = tmp.ensure("new.py")
+        p = tmp / "new.py"
+        p.touch()
         changed = sd.check()
         assert changed
 
-        p.remove()
+        p.unlink()
         changed = sd.check()
         assert changed
 
-        tmp.join("a", "b", "c.py").ensure()
+        tmp.joinpath("a", "b").mkdir(parents=True)
+        tmp.joinpath("a", "b", "c.py").touch()
         changed = sd.check()
         assert changed
 
-        tmp.join("a", "c.txt").ensure()
+        tmp.joinpath("a", "c.txt").touch()
         changed = sd.check()
         assert changed
         changed = sd.check()
         assert not changed
 
-        tmp.join("a").remove()
+        shutil.rmtree(str(tmp.joinpath("a")))
         changed = sd.check()
         assert changed
 
-    def test_dirchange(self, tmpdir):
+    def test_dirchange(self, tmp_path: Path) -> None:
-        tmp = tmpdir
+        tmp = tmp_path
-        tmp.ensure("dir", "hello.py")
+        tmp.joinpath("dir").mkdir()
+        tmp.joinpath("dir", "hello.py").touch()
         sd = StatRecorder([tmp])
-        assert not sd.fil(tmp.join("dir"))
+        assert not sd.fil(tmp / "dir")
 
-    def test_filechange_deletion_race(self, tmpdir, monkeypatch):
+    def test_filechange_deletion_race(self, tmp_path: Path) -> None:
-        tmp = tmpdir
+        tmp = tmp_path
         sd = StatRecorder([tmp])
         changed = sd.check()
         assert not changed
 
-        p = tmp.ensure("new.py")
+        p = tmp.joinpath("new.py")
+        p.touch()
         changed = sd.check()
         assert changed
 
-        p.remove()
+        p.unlink()
         # make check()'s visit() call return our just removed
         # path as if we were in a race condition
-        monkeypatch.setattr(tmp, "visit", lambda *args: [p])
+        dirname = str(tmp)
-
+        dirnames: list[str] = []
-        changed = sd.check()
+        filenames = [str(p)]
+        with unittest.mock.patch(
+            "os.walk", return_value=[(dirname, dirnames, filenames)], autospec=True
+        ):
+            changed = sd.check()
         assert changed
 
-    def test_pycremoval(self, tmpdir):
+    def test_pycremoval(self, tmp_path: Path) -> None:
-        tmp = tmpdir
+        tmp = tmp_path
-        hello = tmp.ensure("hello.py")
+        hello = tmp / "hello.py"
+        hello.touch()
         sd = StatRecorder([tmp])
         changed = sd.check()
         assert not changed
 
-        pycfile = hello + "c"
+        pycfile = hello.with_suffix(".pyc")
-        pycfile.ensure()
+        pycfile.touch()
-        hello.write("world")
+        hello.write_text("world")
         changed = sd.check()
         assert changed
-        assert not pycfile.check()
+        assert not pycfile.exists()
 
-    def test_waitonchange(self, tmpdir, monkeypatch):
+    def test_waitonchange(
-        tmp = tmpdir
+        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        tmp = tmp_path
         sd = StatRecorder([tmp])
 
         ret_values = [True, False]
@@ -93,63 +112,71 @@ class TestStatRecorder:
 
 
 class TestRemoteControl:
-    def test_nofailures(self, testdir):
+    def test_nofailures(self, pytester: pytest.Pytester) -> None:
-        item = testdir.getitem("def test_func(): pass\n")
+        item = pytester.getitem("def test_func(): pass\n")
         control = RemoteControl(item.config)
         control.setup()
         topdir, failures = control.runsession()[:2]
         assert not failures
 
-    def test_failures_somewhere(self, testdir):
+    def test_failures_somewhere(self, pytester: pytest.Pytester) -> None:
-        item = testdir.getitem("def test_func():\n assert 0\n")
+        item = pytester.getitem("def test_func():\n assert 0\n")
         control = RemoteControl(item.config)
         control.setup()
-        failures = control.runsession()
+        failures = control.runsession()[0]
         assert failures
         control.setup()
-        item.fspath.write("def test_func():\n assert 1\n")
+        item.path.write_text("def test_func():\n assert 1\n")
-        removepyc(item.fspath)
+        removepyc(item.path)
         topdir, failures = control.runsession()[:2]
         assert not failures
 
-    def test_failure_change(self, testdir):
+    def test_failure_change(self, pytester: pytest.Pytester) -> None:
-        modcol = testdir.getitem(
+        modcol = pytester.getitem(
-            """
+            textwrap.dedent(
-            def test_func():
+                """
-                assert 0
+                def test_func():
-        """
+                    assert 0
+                """
+            )
         )
         control = RemoteControl(modcol.config)
         control.loop_once()
         assert control.failures
-        modcol.fspath.write(
+        modcol_path = modcol.path
-            py.code.Source(
+
+        modcol_path.write_text(
+            textwrap.dedent(
+                """
+                def test_func():
+                    assert 1
+                def test_new():
+                    assert 0
                 """
-            def test_func():
-                assert 1
-            def test_new():
-                assert 0
-        """
             )
         )
-        removepyc(modcol.fspath)
+        removepyc(modcol_path)
         control.loop_once()
         assert not control.failures
         control.loop_once()
         assert control.failures
         assert str(control.failures).find("test_new") != -1
 
-    def test_failure_subdir_no_init(self, testdir):
+    def test_failure_subdir_no_init(
-        modcol = testdir.getitem(
+        self, pytester: pytest.Pytester, monkeypatch: pytest.MonkeyPatch
-            """
+    ) -> None:
-            def test_func():
+        modcol = pytester.getitem(
-                assert 0
+            textwrap.dedent(
-        """
+                """
+                def test_func():
+                    assert 0
+                """
+            )
         )
-        parent = modcol.fspath.dirpath().dirpath()
+        parent = modcol.path.parent.parent
-        parent.chdir()
+        monkeypatch.chdir(parent)
         modcol.config.args = [
-            py.path.local(x).relto(parent) for x in modcol.config.args
+            str(Path(x).relative_to(parent)) for x in modcol.config.args
         ]
         control = RemoteControl(modcol.config)
         control.loop_once()
@@ -157,59 +184,100 @@ class TestRemoteControl:
         control.loop_once()
         assert control.failures
 
+    def test_ignore_sys_path_hook_entry(
+        self, pytester: pytest.Pytester, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        # Modifying sys.path as seen by the worker process is a bit tricky,
+        # because any changes made in the current process do not carry over.
+        # However, we can leverage the `sitecustomize` behavior to run arbitrary
+        # code when the subprocess interpreter is starting up. We just need to
+        # install our module in the search path, which we can accomplish by
+        # adding a temporary directory to PYTHONPATH.
+        tmpdir = tempfile.TemporaryDirectory()
+        with open(pathlib.Path(tmpdir.name) / "sitecustomize.py", "w") as custom:
+            print(
+                textwrap.dedent(
+                    """
+                    import sys
+                    sys.path.append('dummy.__path_hook__')
+                    """
+                ),
+                file=custom,
+            )
+
+        monkeypatch.setenv("PYTHONPATH", tmpdir.name, prepend=":")
+
+        item = pytester.getitem(
+            textwrap.dedent(
+                """
+                def test_func():
+                    import sys
+                    assert "dummy.__path_hook__" in sys.path
+                """
+            )
+        )
+        control = RemoteControl(item.config)
+        control.setup()
+        topdir, failures = control.runsession()[:2]
+        assert not failures
+
 
 class TestLooponFailing:
-    def test_looponfail_from_fail_to_ok(self, testdir):
+    def test_looponfail_from_fail_to_ok(self, pytester: pytest.Pytester) -> None:
-        modcol = testdir.getmodulecol(
+        modcol = pytester.getmodulecol(
-            """
+            textwrap.dedent(
-            def test_one():
+                """
-                x = 0
+                def test_one():
-                assert x == 1
+                    x = 0
-            def test_two():
+                    assert x == 1
-                assert 1
+                def test_two():
-        """
+                    assert 1
+                """
+            )
         )
         remotecontrol = RemoteControl(modcol.config)
         remotecontrol.loop_once()
         assert len(remotecontrol.failures) == 1
 
-        modcol.fspath.write(
+        modcol.path.write_text(
-            py.code.Source(
+            textwrap.dedent(
+                """
+                def test_one():
+                    assert 1
+                def test_two():
+                    assert 1
                 """
-            def test_one():
-                assert 1
-            def test_two():
-                assert 1
-        """
             )
         )
-        removepyc(modcol.fspath)
+        removepyc(modcol.path)
         remotecontrol.loop_once()
         assert not remotecontrol.failures
 
-    def test_looponfail_from_one_to_two_tests(self, testdir):
+    def test_looponfail_from_one_to_two_tests(self, pytester: pytest.Pytester) -> None:
-        modcol = testdir.getmodulecol(
+        modcol = pytester.getmodulecol(
-            """
+            textwrap.dedent(
-            def test_one():
+                """
-                assert 0
+                def test_one():
-        """
+                    assert 0
+                """
+            )
         )
         remotecontrol = RemoteControl(modcol.config)
         remotecontrol.loop_once()
         assert len(remotecontrol.failures) == 1
         assert "test_one" in remotecontrol.failures[0]
 
-        modcol.fspath.write(
+        modcol.path.write_text(
-            py.code.Source(
+            textwrap.dedent(
+                """
+                def test_one():
+                    assert 1 # passes now
+                def test_two():
+                    assert 0 # new and fails
                 """
-            def test_one():
-                assert 1 # passes now
-            def test_two():
-                assert 0 # new and fails
-        """
             )
         )
-        removepyc(modcol.fspath)
+        removepyc(modcol.path)
         remotecontrol.loop_once()
         assert len(remotecontrol.failures) == 0
         remotecontrol.loop_once()
@@ -217,52 +285,54 @@ class TestLooponFailing:
         assert "test_one" not in remotecontrol.failures[0]
         assert "test_two" in remotecontrol.failures[0]
 
-    @pytest.mark.xfail(
+    @pytest.mark.xfail(reason="broken by pytest 3.1+", strict=True)
-        parse_version(pytest.__version__) >= parse_version("3.1"),
+    def test_looponfail_removed_test(self, pytester: pytest.Pytester) -> None:
-        reason="broken by pytest 3.1+",
+        modcol = pytester.getmodulecol(
-        strict=True,
+            textwrap.dedent(
-    )
+                """
-    def test_looponfail_removed_test(self, testdir):
+                def test_one():
-        modcol = testdir.getmodulecol(
+                    assert 0
-            """
+                def test_two():
-            def test_one():
+                    assert 0
-                assert 0
+                """
-            def test_two():
+            )
-                assert 0
-        """
         )
         remotecontrol = RemoteControl(modcol.config)
         remotecontrol.loop_once()
         assert len(remotecontrol.failures) == 2
 
-        modcol.fspath.write(
+        modcol.path.write_text(
-            py.code.Source(
+            textwrap.dedent(
+                """
+                def test_xxx(): # renamed test
+                    assert 0
+                def test_two():
+                    assert 1 # pass now
                 """
-            def test_xxx(): # renamed test
-                assert 0
-            def test_two():
-                assert 1 # pass now
-        """
             )
         )
-        removepyc(modcol.fspath)
+        removepyc(modcol.path)
         remotecontrol.loop_once()
         assert len(remotecontrol.failures) == 0
 
         remotecontrol.loop_once()
         assert len(remotecontrol.failures) == 1
 
-    def test_looponfail_multiple_errors(self, testdir, monkeypatch):
+    def test_looponfail_multiple_errors(
-        modcol = testdir.getmodulecol(
+        self, pytester: pytest.Pytester, monkeypatch: pytest.MonkeyPatch
-            """
+    ) -> None:
-            def test_one():
+        modcol = pytester.getmodulecol(
-                assert 0
+            textwrap.dedent(
-        """
+                """
+                def test_one():
+                    assert 0
+                """
+            )
         )
         remotecontrol = RemoteControl(modcol.config)
         orig_runsession = remotecontrol.runsession
 
-        def runsession_dups():
+        def runsession_dups() -> tuple[list[str], list[str], bool]:
             # twisted.trial test cases may report multiple errors.
             failures, reports, collection_failed = orig_runsession()
             print(failures)
@@ -274,55 +344,59 @@ class TestLooponFailing:
 
 
 class TestFunctional:
-    def test_fail_to_ok(self, testdir):
+    def test_fail_to_ok(self, pytester: pytest.Pytester) -> None:
-        p = testdir.makepyfile(
+        p = pytester.makepyfile(
-            """
+            textwrap.dedent(
-            def test_one():
+                """
-                x = 0
+                def test_one():
-                assert x == 1
+                    x = 0
-        """
+                    assert x == 1
+                """
+            )
         )
-        # p = testdir.mkdir("sub").join(p1.basename)
+        # p = pytester.mkdir("sub").join(p1.basename)
         # p1.move(p)
-        child = testdir.spawn_pytest("-f %s --traceconfig" % p, expect_timeout=30.0)
+        child = pytester.spawn_pytest("-f %s --traceconfig" % p, expect_timeout=30.0)
         child.expect("def test_one")
         child.expect("x == 1")
         child.expect("1 failed")
         child.expect("### LOOPONFAILING ####")
         child.expect("waiting for changes")
-        p.write(
+        p.write_text(
-            py.code.Source(
+            textwrap.dedent(
                 """
-            def test_one():
+                def test_one():
-                x = 1
+                    x = 1
-                assert x == 1
+                    assert x == 1
-        """
+                """
-            )
+            ),
         )
         child.expect(".*1 passed.*")
         child.kill(15)
 
-    def test_xfail_passes(self, testdir):
+    def test_xfail_passes(self, pytester: pytest.Pytester) -> None:
-        p = testdir.makepyfile(
+        p = pytester.makepyfile(
-            """
+            textwrap.dedent(
-            import py
+                """
-            @py.test.mark.xfail
+                import pytest
-            def test_one():
+                @pytest.mark.xfail
-                pass
+                def test_one():
-        """
+                    pass
+                """
+            )
         )
-        child = testdir.spawn_pytest("-f %s" % p, expect_timeout=30.0)
+        child = pytester.spawn_pytest("-f %s" % p, expect_timeout=30.0)
         child.expect("1 xpass")
         # child.expect("### LOOPONFAILING ####")
         child.expect("waiting for changes")
         child.kill(15)
 
 
-def removepyc(path):
+def removepyc(path: Path) -> None:
     # XXX damn those pyc files
-    pyc = path + "c"
+    pyc = path.with_suffix(".pyc")
-    if pyc.check():
+    if pyc.exists():
-        pyc.remove()
+        pyc.unlink()
-    c = path.dirpath("__pycache__")
+    c = path.parent / "__pycache__"
-    if c.check():
+    if c.exists():
-        c.remove()
+        shutil.rmtree(c)

testing/test_newhooks.py

@@ -3,8 +3,8 @@ import pytest
 
 class TestHooks:
     @pytest.fixture(autouse=True)
-    def create_test_file(self, testdir):
+    def create_test_file(self, pytester: pytest.Pytester) -> None:
-        testdir.makepyfile(
+        pytester.makepyfile(
             """
             import os
             def test_a(): pass
@@ -13,11 +13,11 @@ class TestHooks:
         """
         )
 
-    def test_runtest_logreport(self, testdir):
+    def test_runtest_logreport(self, pytester: pytest.Pytester) -> None:
-        """Test that log reports from pytest_runtest_logreport when running
+        """Test that log reports from pytest_runtest_logreport when running with
-        with xdist contain "node", "nodeid", "worker_id", and "testrun_uid" attributes. (#8)
+        xdist contain "node", "nodeid", "worker_id", and "testrun_uid"
-        """
+        attributes (#8)."""
-        testdir.makeconftest(
+        pytester.makeconftest(
             """
             def pytest_runtest_logreport(report):
                 if hasattr(report, 'node'):
@@ -35,7 +35,7 @@ class TestHooks:
                                    % (report.nodeid, report.worker_id, report.testrun_uid))
         """
         )
-        res = testdir.runpytest("-n1", "-s")
+        res = pytester.runpytest("-n1", "-s")
         res.stdout.fnmatch_lines(
             [
                 "*HOOK: test_runtest_logreport.py::test_a gw0 *",
@@ -45,9 +45,9 @@ class TestHooks:
             ]
         )
 
-    def test_node_collection_finished(self, testdir):
+    def test_node_collection_finished(self, pytester: pytest.Pytester) -> None:
         """Test pytest_xdist_node_collection_finished hook (#8)."""
-        testdir.makeconftest(
+        pytester.makeconftest(
             """
             def pytest_xdist_node_collection_finished(node, ids):
                 workerid = node.workerinput['workerid']
@@ -55,7 +55,7 @@ class TestHooks:
                 print("HOOK: %s %s" % (workerid, ', '.join(stripped_ids)))
         """
         )
-        res = testdir.runpytest("-n2", "-s")
+        res = pytester.runpytest("-n2", "-s")
         res.stdout.fnmatch_lines_random(
             ["*HOOK: gw0 test_a, test_b, test_c", "*HOOK: gw1 test_a, test_b, test_c"]
         )
@@ -64,8 +64,8 @@ class TestHooks:
 
 class TestCrashItem:
     @pytest.fixture(autouse=True)
-    def create_test_file(self, testdir):
+    def create_test_file(self, pytester: pytest.Pytester) -> None:
-        testdir.makepyfile(
+        pytester.makepyfile(
             """
             import os
             def test_a(): pass
@@ -75,9 +75,9 @@ class TestCrashItem:
         """
         )
 
-    def test_handlecrashitem(self, testdir):
+    def test_handlecrashitem(self, pytester: pytest.Pytester) -> None:
         """Test pytest_handlecrashitem hook."""
-        testdir.makeconftest(
+        pytester.makeconftest(
             """
             test_runs = 0
 
@@ -91,6 +91,31 @@ class TestCrashItem:
                     print("HOOK: pytest_handlecrashitem")
         """
         )
-        res = testdir.runpytest("-n2", "-s")
+        res = pytester.runpytest("-n2", "-s")
         res.stdout.fnmatch_lines_random(["*HOOK: pytest_handlecrashitem"])
         res.stdout.fnmatch_lines(["*3 passed*"])
+
+    def test_handlecrashitem_one(self, pytester: pytest.Pytester) -> None:
+        """Test pytest_handlecrashitem hook with just one test."""
+        pytester.makeconftest(
+            """
+            test_runs = 0
+
+            def pytest_handlecrashitem(crashitem, report, sched):
+                global test_runs
+
+                if test_runs == 0:
+                    sched.mark_test_pending(crashitem)
+                    test_runs = 1
+                else:
+                    print("HOOK: pytest_handlecrashitem")
+        """
+        )
+        res = pytester.runpytest("-n1", "-s", "-k", "test_b")
+        res.stdout.fnmatch_lines_random(["*HOOK: pytest_handlecrashitem"])
+        res.stdout.fnmatch_lines(
+            [
+                "FAILED test_handlecrashitem_one.py::test_b",
+                "FAILED test_handlecrashitem_one.py::test_b",
+            ]
+        )

testing/test_plugin.py

@@ -1,47 +1,78 @@
 from contextlib import suppress
+import os
+from pathlib import Path
+import sys
 
-import py
 import execnet
-from xdist.workermanage import NodeManager
-
 import pytest
 
+from xdist.workermanage import NodeManager
 
-def test_dist_incompatibility_messages(testdir):
+
-    result = testdir.runpytest("--pdb", "--looponfail")
+@pytest.fixture
+def monkeypatch_3_cpus(monkeypatch: pytest.MonkeyPatch) -> None:
+    """Make pytest-xdist believe the system has 3 CPUs."""
+    # block import
+    monkeypatch.setitem(sys.modules, "psutil", None)
+    monkeypatch.delattr(os, "sched_getaffinity", raising=False)
+    monkeypatch.setattr(os, "cpu_count", lambda: 3)
+
+
+def test_dist_incompatibility_messages(pytester: pytest.Pytester) -> None:
+    result = pytester.runpytest("--pdb", "--looponfail")
     assert result.ret != 0
-    result = testdir.runpytest("--pdb", "-n", "3")
+    result = pytester.runpytest("--pdb", "-n", "3")
     assert result.ret != 0
     assert "incompatible" in result.stderr.str()
-    result = testdir.runpytest("--pdb", "-d", "--tx", "popen")
+    result = pytester.runpytest("--pdb", "-d", "--tx", "popen")
     assert result.ret != 0
     assert "incompatible" in result.stderr.str()
 
 
-def test_dist_options(testdir):
+def test_dist_options(pytester: pytest.Pytester) -> None:
     from xdist.plugin import pytest_cmdline_main as check_options
 
-    config = testdir.parseconfigure("-n 2")
+    config = pytester.parseconfigure("-n 2")
     check_options(config)
     assert config.option.dist == "load"
     assert config.option.tx == ["popen"] * 2
-    config = testdir.parseconfigure("--numprocesses", "2")
+    config = pytester.parseconfigure("--numprocesses", "2")
     check_options(config)
     assert config.option.dist == "load"
     assert config.option.tx == ["popen"] * 2
-    config = testdir.parseconfigure("--numprocesses", "3", "--maxprocesses", "2")
+    config = pytester.parseconfigure("--numprocesses", "3", "--maxprocesses", "2")
     check_options(config)
     assert config.option.dist == "load"
     assert config.option.tx == ["popen"] * 2
-    config = testdir.parseconfigure("-d")
+    config = pytester.parseconfigure("-d")
     check_options(config)
     assert config.option.dist == "load"
 
+    config = pytester.parseconfigure("--numprocesses", "0")
+    check_options(config)
+    assert config.option.dist == "no"
+    assert config.option.tx == []
 
-def test_auto_detect_cpus(testdir, monkeypatch):
+    config = pytester.parseconfigure("--numprocesses", "0", "-d")
-    import os
+    check_options(config)
+    assert config.option.dist == "no"
+    assert config.option.tx == []
+
+    config = pytester.parseconfigure(
+        "--numprocesses", "0", "--dist", "each", "--tx", "2*popen"
+    )
+    check_options(config)
+    assert config.option.dist == "no"
+    assert config.option.tx == []
+
+
+def test_auto_detect_cpus(
+    pytester: pytest.Pytester, monkeypatch: pytest.MonkeyPatch
+) -> None:
     from xdist.plugin import pytest_cmdline_main as check_options
 
+    monkeypatch.delenv("PYTEST_XDIST_AUTO_NUM_WORKERS", raising=False)
+
     with suppress(ImportError):
         import psutil
 
@@ -56,152 +87,253 @@ def test_auto_detect_cpus(testdir, monkeypatch):
 
         monkeypatch.setattr(multiprocessing, "cpu_count", lambda: 99)
 
-    config = testdir.parseconfigure("-n2")
+    config = pytester.parseconfigure("-n2")
     assert config.getoption("numprocesses") == 2
 
-    config = testdir.parseconfigure("-nauto")
+    config = pytester.parseconfigure("-nauto")
     check_options(config)
     assert config.getoption("numprocesses") == 99
 
-    config = testdir.parseconfigure("-nauto", "--pdb")
+    for numprocesses in (0, "auto", "logical"):
-    check_options(config)
+        config = pytester.parseconfigure(f"-n{numprocesses}", "--pdb")
-    assert config.getoption("usepdb")
+        check_options(config)
-    assert config.getoption("numprocesses") == 0
+        assert config.getoption("usepdb")
-    assert config.getoption("dist") == "no"
+        assert config.getoption("numprocesses") == 0
-
+        assert config.getoption("dist") == "no"
-    config = testdir.parseconfigure("-nlogical", "--pdb")
-    check_options(config)
-    assert config.getoption("usepdb")
-    assert config.getoption("numprocesses") == 0
-    assert config.getoption("dist") == "no"
 
     monkeypatch.delattr(os, "sched_getaffinity", raising=False)
     monkeypatch.setenv("TRAVIS", "true")
-    config = testdir.parseconfigure("-nauto")
+    config = pytester.parseconfigure("-nauto")
     check_options(config)
     assert config.getoption("numprocesses") == 2
 
 
-def test_auto_detect_cpus_psutil(testdir, monkeypatch):
+def test_auto_detect_cpus_psutil(
+    pytester: pytest.Pytester, monkeypatch: pytest.MonkeyPatch
+) -> None:
     from xdist.plugin import pytest_cmdline_main as check_options
 
     psutil = pytest.importorskip("psutil")
 
+    monkeypatch.delenv("PYTEST_XDIST_AUTO_NUM_WORKERS", raising=False)
     monkeypatch.setattr(psutil, "cpu_count", lambda logical=True: 84 if logical else 42)
 
-    config = testdir.parseconfigure("-nauto")
+    config = pytester.parseconfigure("-nauto")
     check_options(config)
     assert config.getoption("numprocesses") == 42
 
-    config = testdir.parseconfigure("-nlogical")
+    config = pytester.parseconfigure("-nlogical")
     check_options(config)
     assert config.getoption("numprocesses") == 84
 
 
-def test_hook_auto_num_workers(testdir, monkeypatch):
+def test_auto_detect_cpus_os(
+    pytester: pytest.Pytester, monkeypatch: pytest.MonkeyPatch, monkeypatch_3_cpus: None
+) -> None:
     from xdist.plugin import pytest_cmdline_main as check_options
 
-    testdir.makeconftest(
+    monkeypatch.delenv("PYTEST_XDIST_AUTO_NUM_WORKERS", raising=False)
+
+    config = pytester.parseconfigure("-nauto")
+    check_options(config)
+    assert config.getoption("numprocesses") == 3
+
+    config = pytester.parseconfigure("-nlogical")
+    check_options(config)
+    assert config.getoption("numprocesses") == 3
+
+
+def test_hook_auto_num_workers(
+    pytester: pytest.Pytester, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    from xdist.plugin import pytest_cmdline_main as check_options
+
+    pytester.makeconftest(
         """
         def pytest_xdist_auto_num_workers():
             return 42
     """
     )
-    config = testdir.parseconfigure("-nauto")
+    config = pytester.parseconfigure("-nauto")
     check_options(config)
     assert config.getoption("numprocesses") == 42
 
-    config = testdir.parseconfigure("-nlogical")
+    config = pytester.parseconfigure("-nlogical")
     check_options(config)
     assert config.getoption("numprocesses") == 42
 
 
-def test_boxed_with_collect_only(testdir):
+def test_hook_auto_num_workers_arg(
+    pytester: pytest.Pytester, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    # config.option.numprocesses is a pytest feature,
+    # but we document it so let's test it.
     from xdist.plugin import pytest_cmdline_main as check_options
 
-    config = testdir.parseconfigure("-n1", "--boxed")
+    pytester.makeconftest(
+        """
+        def pytest_xdist_auto_num_workers(config):
+            if config.option.numprocesses == 'auto':
+                return 42
+            if config.option.numprocesses == 'logical':
+                return 8
+    """
+    )
+    config = pytester.parseconfigure("-nauto")
     check_options(config)
-    assert config.option.forked
+    assert config.getoption("numprocesses") == 42
 
-    config = testdir.parseconfigure("-n1", "--collect-only")
+    config = pytester.parseconfigure("-nlogical")
     check_options(config)
-    assert not config.option.forked
+    assert config.getoption("numprocesses") == 8
 
-    config = testdir.parseconfigure("-n1", "--boxed", "--collect-only")
+
+def test_hook_auto_num_workers_none(
+    pytester: pytest.Pytester, monkeypatch: pytest.MonkeyPatch, monkeypatch_3_cpus: None
+) -> None:
+    # Returning None from a hook to skip it is pytest behavior,
+    # but we document it so let's test it.
+    from xdist.plugin import pytest_cmdline_main as check_options
+
+    monkeypatch.delenv("PYTEST_XDIST_AUTO_NUM_WORKERS", raising=False)
+
+    pytester.makeconftest(
+        """
+        def pytest_xdist_auto_num_workers():
+            return None
+    """
+    )
+    config = pytester.parseconfigure("-nauto")
     check_options(config)
-    assert config.option.forked
+    assert config.getoption("numprocesses") == 3
+
+    monkeypatch.setenv("PYTEST_XDIST_AUTO_NUM_WORKERS", "5")
+
+    config = pytester.parseconfigure("-nauto")
+    check_options(config)
+    assert config.getoption("numprocesses") == 5
 
 
-def test_dsession_with_collect_only(testdir):
+def test_envvar_auto_num_workers(
+    pytester: pytest.Pytester, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    from xdist.plugin import pytest_cmdline_main as check_options
+
+    monkeypatch.setenv("PYTEST_XDIST_AUTO_NUM_WORKERS", "7")
+
+    config = pytester.parseconfigure("-nauto")
+    check_options(config)
+    assert config.getoption("numprocesses") == 7
+
+    config = pytester.parseconfigure("-nlogical")
+    check_options(config)
+    assert config.getoption("numprocesses") == 7
+
+
+def test_envvar_auto_num_workers_warn(
+    pytester: pytest.Pytester, monkeypatch: pytest.MonkeyPatch, monkeypatch_3_cpus: None
+) -> None:
+    from xdist.plugin import pytest_cmdline_main as check_options
+
+    monkeypatch.setenv("PYTEST_XDIST_AUTO_NUM_WORKERS", "fourscore")
+
+    config = pytester.parseconfigure("-nauto")
+    with pytest.warns(UserWarning):
+        check_options(config)
+    assert config.getoption("numprocesses") == 3
+
+
+def test_auto_num_workers_hook_overrides_envvar(
+    pytester: pytest.Pytester, monkeypatch: pytest.MonkeyPatch, monkeypatch_3_cpus: None
+) -> None:
+    from xdist.plugin import pytest_cmdline_main as check_options
+
+    monkeypatch.setenv("PYTEST_XDIST_AUTO_NUM_WORKERS", "987")
+    pytester.makeconftest(
+        """
+        def pytest_xdist_auto_num_workers():
+            return 2
+    """
+    )
+    config = pytester.parseconfigure("-nauto")
+    check_options(config)
+    assert config.getoption("numprocesses") == 2
+
+    config = pytester.parseconfigure("-nauto")
+    check_options(config)
+    assert config.getoption("numprocesses") == 2
+
+
+def test_dsession_with_collect_only(pytester: pytest.Pytester) -> None:
     from xdist.plugin import pytest_cmdline_main as check_options
     from xdist.plugin import pytest_configure as configure
 
-    config = testdir.parseconfigure("-n1")
+    config = pytester.parseconfigure("-n1")
     check_options(config)
     configure(config)
     assert config.pluginmanager.hasplugin("dsession")
 
-    config = testdir.parseconfigure("-n1", "--collect-only")
+    config = pytester.parseconfigure("-n1", "--collect-only")
     check_options(config)
     configure(config)
     assert not config.pluginmanager.hasplugin("dsession")
 
 
-def test_testrunuid_provided(testdir):
+def test_testrunuid_provided(pytester: pytest.Pytester) -> None:
-    config = testdir.parseconfigure("--testrunuid", "test123", "--tx=popen")
+    config = pytester.parseconfigure("--testrunuid", "test123", "--tx=popen")
     nm = NodeManager(config)
     assert nm.testrunuid == "test123"
 
 
-def test_testrunuid_generated(testdir):
+def test_testrunuid_generated(pytester: pytest.Pytester) -> None:
-    config = testdir.parseconfigure("--tx=popen")
+    config = pytester.parseconfigure("--tx=popen")
     nm = NodeManager(config)
     assert len(nm.testrunuid) == 32
 
 
 class TestDistOptions:
-    def test_getxspecs(self, testdir):
+    def test_getxspecs(self, pytester: pytest.Pytester) -> None:
-        config = testdir.parseconfigure("--tx=popen", "--tx", "ssh=xyz")
+        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
         assert xspecs[1].ssh == "xyz"
 
-    def test_xspecs_multiplied(self, testdir):
+    def test_xspecs_multiplied(self, pytester: pytest.Pytester) -> None:
-        config = testdir.parseconfigure("--tx=3*popen")
+        config = pytester.parseconfigure("--tx=3*popen")
-        xspecs = NodeManager(config)._getxspecs()
+        xspecs = NodeManager(config)._gettxspecs()
         assert len(xspecs) == 3
         assert xspecs[1].popen
 
-    def test_getrsyncdirs(self, testdir):
+    def test_getrsyncdirs(self, pytester: pytest.Pytester) -> None:
-        config = testdir.parseconfigure("--rsyncdir=" + str(testdir.tmpdir))
+        config = pytester.parseconfigure("--rsyncdir=" + str(pytester.path))
         nm = NodeManager(config, specs=[execnet.XSpec("popen")])
         assert not nm._getrsyncdirs()
         nm = NodeManager(config, specs=[execnet.XSpec("popen//chdir=qwe")])
         assert nm.roots
-        assert testdir.tmpdir in nm.roots
+        assert pytester.path in nm.roots
 
-    def test_getrsyncignore(self, testdir):
+    def test_getrsyncignore(self, pytester: pytest.Pytester) -> None:
-        config = testdir.parseconfigure("--rsyncignore=fo*")
+        config = pytester.parseconfigure("--rsyncignore=fo*")
         nm = NodeManager(config, specs=[execnet.XSpec("popen//chdir=qwe")])
         assert "fo*" in nm.rsyncoptions["ignores"]
 
-    def test_getrsyncdirs_with_conftest(self, testdir):
+    def test_getrsyncdirs_with_conftest(self, pytester: pytest.Pytester) -> None:
-        p = py.path.local()
+        p = Path.cwd()
-        for bn in "x y z".split():
+        for bn in ("x", "y", "z"):
-            p.mkdir(bn)
+            p.joinpath(bn).mkdir()
-        testdir.makeini(
+        pytester.makeini(
             """
             [pytest]
             rsyncdirs= x
         """
         )
-        config = testdir.parseconfigure(testdir.tmpdir, "--rsyncdir=y", "--rsyncdir=z")
+        config = pytester.parseconfigure(pytester.path, "--rsyncdir=y", "--rsyncdir=z")
         nm = NodeManager(config, specs=[execnet.XSpec("popen//chdir=xyz")])
         roots = nm._getrsyncdirs()
         # assert len(roots) == 3 + 1 # pylib
-        assert py.path.local("y") in roots
+        assert Path("y").resolve() in roots
-        assert py.path.local("z") in roots
+        assert Path("z").resolve() in roots
-        assert testdir.tmpdir.join("x") in roots
+        assert pytester.path.joinpath("x") in roots

testing/test_remote.py

@@ -1,60 +1,73 @@
-import py
+from __future__ import annotations
+
+import marshal
 import pprint
-import pytest
+from queue import Queue
 import sys
+from typing import Any
+from typing import Callable
+from typing import cast
+from typing import Union
 import uuid
 
-from xdist.workermanage import WorkerController
 import execnet
-import marshal
+import pytest
+
+from xdist.workermanage import NodeManager
+from xdist.workermanage import WorkerController
 
-from queue import Queue
 
 WAIT_TIMEOUT = 10.0
 
 
-def check_marshallable(d):
+def check_marshallable(d: object) -> None:
     try:
-        marshal.dumps(d)
+        marshal.dumps(d)  # type: ignore[arg-type]
-    except ValueError:
+    except ValueError as e:
         pprint.pprint(d)
-        raise ValueError("not marshallable")
+        raise ValueError("not marshallable") from e
 
 
 class EventCall:
-    def __init__(self, eventcall):
+    def __init__(self, eventcall: tuple[str, dict[str, Any]]) -> None:
         self.name, self.kwargs = eventcall
 
-    def __str__(self):
+    def __str__(self) -> str:
-        return "<EventCall {}(**{})>".format(self.name, self.kwargs)
+        return f"<EventCall {self.name}(**{self.kwargs})>"
 
 
 class WorkerSetup:
-    use_callback = False
+    def __init__(
-
+        self, request: pytest.FixtureRequest, pytester: pytest.Pytester
-    def __init__(self, request, testdir):
+    ) -> None:
         self.request = request
-        self.testdir = testdir
+        self.pytester = pytester
-        self.events = Queue()
+        self.use_callback = False
+        self.events = Queue()  # type: ignore[var-annotated]
 
-    def setup(
+    def setup(self) -> None:
-        self,
+        self.pytester.chdir()
-    ):
-        self.testdir.chdir()
         # import os ; os.environ['EXECNET_DEBUG'] = "2"
-        self.gateway = execnet.makegateway()
+        self.gateway = execnet.makegateway("execmodel=main_thread_only//popen")
-        self.config = config = self.testdir.parseconfigure()
+        self.config = config = self.pytester.parseconfigure()
-        putevent = self.use_callback and self.events.put or None
+        putevent = self.events.put if self.use_callback else None
 
         class DummyMananger:
             testrunuid = uuid.uuid4().hex
             specs = [0, 1]
 
-        self.slp = WorkerController(DummyMananger, self.gateway, config, putevent)
+        nodemanager = cast(NodeManager, DummyMananger)
+
+        self.slp = WorkerController(
+            nodemanager=nodemanager,
+            gateway=self.gateway,
+            config=config,
+            putevent=putevent,  # type: ignore[arg-type]
+        )
         self.request.addfinalizer(self.slp.ensure_teardown)
         self.slp.setup()
 
-    def popevent(self, name=None):
+    def popevent(self, name: str | None = None) -> EventCall:
         while 1:
             if self.use_callback:
                 data = self.events.get(timeout=WAIT_TIMEOUT)
@@ -63,39 +76,37 @@ class WorkerSetup:
             ev = EventCall(data)
             if name is None or ev.name == name:
                 return ev
-            print("skipping {}".format(ev))
+            print(f"skipping {ev}")
 
-    def sendcommand(self, name, **kwargs):
+    def sendcommand(self, name: str, **kwargs: Any) -> None:
         self.slp.sendcommand(name, **kwargs)
 
 
 @pytest.fixture
-def worker(request, testdir):
+def worker(request: pytest.FixtureRequest, pytester: pytest.Pytester) -> WorkerSetup:
-    return WorkerSetup(request, testdir)
+    return WorkerSetup(request, pytester)
-
-
-@pytest.mark.xfail(reason="#59")
-def test_remoteinitconfig(testdir):
-    from xdist.remote import remote_initconfig
-
-    config1 = testdir.parseconfig()
-    config2 = remote_initconfig(config1.option.__dict__, config1.args)
-    assert config2.option.__dict__ == config1.option.__dict__
-    assert config2.pluginmanager.getplugin("terminal") in (-1, None)
 
 
 class TestWorkerInteractor:
+    UnserializerReport = Callable[
+        [dict[str, Any]], Union[pytest.CollectReport, pytest.TestReport]
+    ]
+
     @pytest.fixture
-    def unserialize_report(self, pytestconfig):
+    def unserialize_report(self, pytestconfig: pytest.Config) -> UnserializerReport:
-        def unserialize(data):
+        def unserialize(
-            return pytestconfig.hook.pytest_report_from_serializable(
+            data: dict[str, Any],
+        ) -> pytest.CollectReport | pytest.TestReport:
+            return pytestconfig.hook.pytest_report_from_serializable(  # type: ignore[no-any-return]
                 config=pytestconfig, data=data
             )
 
         return unserialize
 
-    def test_basic_collect_and_runtests(self, worker, unserialize_report):
+    def test_basic_collect_and_runtests(
-        worker.testdir.makepyfile(
+        self, worker: WorkerSetup, unserialize_report: UnserializerReport
+    ) -> None:
+        worker.pytester.makepyfile(
             """
             def test_func():
                 pass
@@ -108,7 +119,7 @@ class TestWorkerInteractor:
         assert ev.name == "collectionstart"
         assert not ev.kwargs
         ev = worker.popevent("collectionfinish")
-        assert ev.kwargs["topdir"] == worker.testdir.tmpdir
+        assert ev.kwargs["topdir"] == str(worker.pytester.path)
         ids = ev.kwargs["ids"]
         assert len(ids) == 1
         worker.sendcommand("runtests", indices=list(range(len(ids))))
@@ -126,8 +137,10 @@ class TestWorkerInteractor:
         ev = worker.popevent("workerfinished")
         assert "workeroutput" in ev.kwargs
 
-    def test_remote_collect_skip(self, worker, unserialize_report):
+    def test_remote_collect_skip(
-        worker.testdir.makepyfile(
+        self, worker: WorkerSetup, unserialize_report: UnserializerReport
+    ) -> None:
+        worker.pytester.makepyfile(
             """
             import pytest
             pytest.skip("hello", allow_module_level=True)
@@ -140,12 +153,15 @@ class TestWorkerInteractor:
         assert ev.name == "collectreport"
         rep = unserialize_report(ev.kwargs["data"])
         assert rep.skipped
+        assert isinstance(rep.longrepr, tuple)
         assert rep.longrepr[2] == "Skipped: hello"
         ev = worker.popevent("collectionfinish")
         assert not ev.kwargs["ids"]
 
-    def test_remote_collect_fail(self, worker, unserialize_report):
+    def test_remote_collect_fail(
-        worker.testdir.makepyfile("""aasd qwe""")
+        self, worker: WorkerSetup, unserialize_report: UnserializerReport
+    ) -> None:
+        worker.pytester.makepyfile("""aasd qwe""")
         worker.setup()
         ev = worker.popevent("collectionstart")
         assert not ev.kwargs
@@ -156,8 +172,10 @@ class TestWorkerInteractor:
         ev = worker.popevent("collectionfinish")
         assert not ev.kwargs["ids"]
 
-    def test_runtests_all(self, worker, unserialize_report):
+    def test_runtests_all(
-        worker.testdir.makepyfile(
+        self, worker: WorkerSetup, unserialize_report: UnserializerReport
+    ) -> None:
+        worker.pytester.makepyfile(
             """
             def test_func(): pass
             def test_func2(): pass
@@ -175,7 +193,7 @@ class TestWorkerInteractor:
         worker.sendcommand("runtests_all")
         worker.sendcommand("shutdown")
         for func in "::test_func", "::test_func2":
-            for i in range(3):  # setup/call/teardown
+            for _ in range(3):  # setup/call/teardown
                 ev = worker.popevent("testreport")
                 assert ev.name == "testreport"
                 rep = unserialize_report(ev.kwargs["data"])
@@ -183,17 +201,19 @@ class TestWorkerInteractor:
         ev = worker.popevent("workerfinished")
         assert "workeroutput" in ev.kwargs
 
-    def test_happy_run_events_converted(self, testdir, worker):
+    def test_happy_run_events_converted(
-        py.test.xfail("implement a simple test for event production")
+        self, pytester: pytest.Pytester, worker: WorkerSetup
-        assert not worker.use_callback
+    ) -> None:
-        worker.testdir.makepyfile(
+        pytest.xfail("implement a simple test for event production")
+        assert not worker.use_callback  # type: ignore[unreachable]
+        worker.pytester.makepyfile(
             """
             def test_func():
                 pass
         """
         )
         worker.setup()
-        hookrec = testdir.getreportrecorder(worker.config)
+        hookrec = pytester.getreportrecorder(worker.config)
         for data in worker.slp.channel:
             worker.slp.process_from_remote(data)
         worker.slp.process_from_remote(worker.slp.ENDMARK)
@@ -209,18 +229,115 @@ class TestWorkerInteractor:
             ]
         )
 
-    def test_process_from_remote_error_handling(self, worker, capsys):
+    def test_process_from_remote_error_handling(
+        self, worker: WorkerSetup, capsys: pytest.CaptureFixture[str]
+    ) -> None:
         worker.use_callback = True
         worker.setup()
-        worker.slp.process_from_remote(("<nonono>", ()))
+        worker.slp.process_from_remote(("<nonono>", {}))
         out, err = capsys.readouterr()
         assert "INTERNALERROR> ValueError: unknown event: <nonono>" in out
         ev = worker.popevent()
         assert ev.name == "errordown"
 
+    def test_steal_work(
+        self, worker: WorkerSetup, unserialize_report: UnserializerReport
+    ) -> None:
+        worker.pytester.makepyfile(
+            """
+            import time
+            def test_func(): time.sleep(1)
+            def test_func2(): pass
+            def test_func3(): pass
+            def test_func4(): pass
+        """
+        )
+        worker.setup()
+        ev = worker.popevent("collectionfinish")
+        ids = ev.kwargs["ids"]
+        assert len(ids) == 4
+        worker.sendcommand("runtests_all")
 
-def test_remote_env_vars(testdir):
+        # wait for test_func setup
-    testdir.makepyfile(
+        ev = worker.popevent("testreport")
+        rep = unserialize_report(ev.kwargs["data"])
+        assert rep.nodeid.endswith("::test_func")
+        assert rep.when == "setup"
+
+        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 = [
+            ("test_func", "call"),
+            ("test_func", "teardown"),
+            ("test_func2", "setup"),
+            ("test_func2", "call"),
+            ("test_func2", "teardown"),
+        ]
+
+        for func, when in reports:
+            ev = worker.popevent("testreport")
+            rep = unserialize_report(ev.kwargs["data"])
+            assert rep.nodeid.endswith(f"::{func}")
+            assert rep.when == when
+
+        worker.sendcommand("shutdown")
+
+        for when in ["setup", "call", "teardown"]:
+            ev = worker.popevent("testreport")
+            rep = unserialize_report(ev.kwargs["data"])
+            assert rep.nodeid.endswith("::test_func4")
+            assert rep.when == when
+
+        ev = worker.popevent("workerfinished")
+        assert "workeroutput" in ev.kwargs
+
+    def test_steal_empty_queue(
+        self, worker: WorkerSetup, unserialize_report: UnserializerReport
+    ) -> None:
+        worker.pytester.makepyfile(
+            """
+            def test_func(): pass
+            def test_func2(): pass
+        """
+        )
+        worker.setup()
+        ev = worker.popevent("collectionfinish")
+        ids = ev.kwargs["ids"]
+        assert len(ids) == 2
+        worker.sendcommand("runtests_all")
+
+        for when in ["setup", "call", "teardown"]:
+            ev = worker.popevent("testreport")
+            rep = unserialize_report(ev.kwargs["data"])
+            assert rep.nodeid.endswith("::test_func")
+            assert rep.when == when
+
+        worker.sendcommand("steal", indices=[0, 1])
+        ev = worker.popevent("unscheduled")
+        assert ev.kwargs["indices"] == []
+
+        worker.sendcommand("shutdown")
+
+        for when in ["setup", "call", "teardown"]:
+            ev = worker.popevent("testreport")
+            rep = unserialize_report(ev.kwargs["data"])
+            assert rep.nodeid.endswith("::test_func2")
+            assert rep.when == when
+
+        ev = worker.popevent("workerfinished")
+        assert "workeroutput" in ev.kwargs
+
+
+def test_remote_env_vars(pytester: pytest.Pytester) -> None:
+    pytester.makepyfile(
         """
         import os
         def test():
@@ -229,13 +346,13 @@ def test_remote_env_vars(testdir):
             assert os.environ['PYTEST_XDIST_WORKER_COUNT'] == '2'
     """
     )
-    result = testdir.runpytest("-n2", "--max-worker-restart=0")
+    result = pytester.runpytest("-n2", "--max-worker-restart=0")
     assert result.ret == 0
 
 
-def test_remote_inner_argv(testdir):
+def test_remote_inner_argv(pytester: pytest.Pytester) -> None:
     """Test/document the behavior due to execnet using `python -c`."""
-    testdir.makepyfile(
+    pytester.makepyfile(
         """
         import sys
 
@@ -243,29 +360,25 @@ def test_remote_inner_argv(testdir):
             assert sys.argv == ["-c"]
         """
     )
-    result = testdir.runpytest("-n1")
+    result = pytester.runpytest("-n1")
     assert result.ret == 0
 
 
-def test_remote_mainargv(testdir):
+def test_remote_mainargv(pytester: pytest.Pytester) -> None:
     outer_argv = sys.argv
 
-    testdir.makepyfile(
+    pytester.makepyfile(
-        """
+        f"""
         def test_mainargv(request):
-            assert request.config.workerinput["mainargv"] == {!r}
+            assert request.config.workerinput["mainargv"] == {outer_argv!r}
-        """.format(
+        """
-            outer_argv
-        )
     )
-    result = testdir.runpytest("-n1")
+    result = pytester.runpytest("-n1")
     assert result.ret == 0
 
 
-def test_remote_usage_prog(testdir, request):
+def test_remote_usage_prog(pytester: pytest.Pytester) -> None:
-    if not hasattr(request.config._parser, "prog"):
+    pytester.makeconftest(
-        pytest.skip("prog not available in config parser")
-    testdir.makeconftest(
         """
         import pytest
 
@@ -280,7 +393,7 @@ def test_remote_usage_prog(testdir, request):
             config_parser = config._parser
     """
     )
-    testdir.makepyfile(
+    pytester.makepyfile(
         """
         import sys
 
@@ -289,14 +402,14 @@ def test_remote_usage_prog(testdir, request):
     """
     )
 
-    result = testdir.runpytest_subprocess("-n1")
+    result = pytester.runpytest_subprocess("-n1")
     assert result.ret == 1
     result.stdout.fnmatch_lines(["*usage: *", "*error: my_usage_error"])
 
 
-def test_remote_sys_path(testdir):
+def test_remote_sys_path(pytester: pytest.Pytester) -> None:
     """Work around sys.path differences due to execnet using `python -c`."""
-    testdir.makepyfile(
+    pytester.makepyfile(
         """
         import sys
 
@@ -304,5 +417,5 @@ def test_remote_sys_path(testdir):
             assert "" not in sys.path
         """
     )
-    result = testdir.runpytest("-n1")
+    result = pytester.runpytest("-n1")
     assert result.ret == 0

testing/test_workermanage.py

@@ -1,126 +1,165 @@
-import py
+from __future__ import annotations
-import pytest
+
+from pathlib import Path
+import shutil
 import textwrap
+import warnings
+
 import execnet
-from _pytest.pytester import HookRecorder
+import pytest
-from xdist import workermanage, newhooks
+from util import generate_warning
-from xdist.workermanage import HostRSync, NodeManager
+
+from xdist import workermanage
+from xdist._path import visit_path
+from xdist.remote import serialize_warning_message
+from xdist.workermanage import HostRSync
+from xdist.workermanage import NodeManager
+from xdist.workermanage import unserialize_warning_message
+
 
 pytest_plugins = "pytester"
 
 
 @pytest.fixture
-def hookrecorder(request, config):
+def hookrecorder(
-    hookrecorder = HookRecorder(config.pluginmanager)
+    config: pytest.Config, pytester: pytest.Pytester
-    if hasattr(hookrecorder, "start_recording"):
+) -> pytest.HookRecorder:
-        hookrecorder.start_recording(newhooks)
+    hookrecorder = pytester.make_hook_recorder(config.pluginmanager)
-    request.addfinalizer(hookrecorder.finish_recording)
     return hookrecorder
 
 
 @pytest.fixture
-def config(testdir):
+def config(pytester: pytest.Pytester) -> pytest.Config:
-    return testdir.parseconfig()
+    return pytester.parseconfig()
 
 
 @pytest.fixture
-def mysetup(tmpdir):
+def source(tmp_path: Path) -> Path:
-    class mysetup:
+    source = tmp_path / "source"
-        source = tmpdir.mkdir("source")
+    source.mkdir()
-        dest = tmpdir.mkdir("dest")
+    return source
-
-    return mysetup()
 
 
 @pytest.fixture
-def workercontroller(monkeypatch):
+def dest(tmp_path: Path) -> Path:
+    dest = tmp_path / "dest"
+    dest.mkdir()
+    return dest
+
+
+@pytest.fixture
+def workercontroller(monkeypatch: pytest.MonkeyPatch) -> None:
     class MockController:
-        def __init__(self, *args):
+        def __init__(self, *args: object) -> None:
             pass
 
-        def setup(self):
+        def setup(self) -> None:
             pass
 
     monkeypatch.setattr(workermanage, "WorkerController", MockController)
-    return MockController
 
 
 class TestNodeManagerPopen:
-    def test_popen_no_default_chdir(self, config):
+    def test_popen_no_default_chdir(self, config: pytest.Config) -> None:
         gm = NodeManager(config, ["popen"])
         assert gm.specs[0].chdir is None
 
-    def test_default_chdir(self, config):
+    def test_default_chdir(self, config: pytest.Config) -> None:
         specs = ["ssh=noco", "socket=xyz"]
         for spec in NodeManager(config, specs).specs:
             assert spec.chdir == "pyexecnetcache"
         for spec in NodeManager(config, specs, defaultchdir="abc").specs:
             assert spec.chdir == "abc"
 
-    def test_popen_makegateway_events(self, config, hookrecorder, workercontroller):
+    def test_popen_makegateway_events(
+        self,
+        config: pytest.Config,
+        hookrecorder: pytest.HookRecorder,
+        workercontroller: None,
+    ) -> None:
         hm = NodeManager(config, ["popen"] * 2)
-        hm.setup_nodes(None)
+        hm.setup_nodes(None)  # type: ignore[arg-type]
         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("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)
 
-    def test_popens_rsync(self, config, mysetup, workercontroller):
+    def test_popens_rsync(
-        source = mysetup.source
+        self,
+        config: pytest.Config,
+        source: Path,
+        dest: Path,
+        workercontroller: None,
+    ) -> None:
         hm = NodeManager(config, ["popen"] * 2)
-        hm.setup_nodes(None)
+        hm.setup_nodes(None)  # type: ignore[arg-type]
         assert len(hm.group) == 2
         for gw in hm.group:
 
             class pseudoexec:
-                args = []
+                args = []  # type: ignore[var-annotated]
 
-                def __init__(self, *args):
+                def __init__(self, *args: object) -> None:
                     self.args.extend(args)
 
-                def waitclose(self):
+                def waitclose(self) -> None:
                     pass
 
-            gw.remote_exec = pseudoexec
+            gw.remote_exec = pseudoexec  # type: ignore[assignment]
         notifications = []
         for gw in hm.group:
             hm.rsync(gw, source, notify=lambda *args: notifications.append(args))
         assert not notifications
         hm.teardown_nodes()
         assert not len(hm.group)
-        assert "sys.path.insert" in gw.remote_exec.args[0]
+        assert "sys.path.insert" in gw.remote_exec.args[0]  # type: ignore[attr-defined]
 
-    def test_rsync_popen_with_path(self, config, mysetup, workercontroller):
+    def test_rsync_popen_with_path(
-        source, dest = mysetup.source, mysetup.dest
+        self, config: pytest.Config, source: Path, dest: Path, workercontroller: None
+    ) -> None:
         hm = NodeManager(config, ["popen//chdir=%s" % dest] * 1)
-        hm.setup_nodes(None)
+        hm.setup_nodes(None)  # type: ignore[arg-type]
-        source.ensure("dir1", "dir2", "hello")
+        source.joinpath("dir1", "dir2").mkdir(parents=True)
+        source.joinpath("dir1", "dir2", "hello").touch()
         notifications = []
         for gw in hm.group:
             hm.rsync(gw, source, notify=lambda *args: notifications.append(args))
         assert len(notifications) == 1
         assert notifications[0] == ("rsyncrootready", hm.group["gw0"].spec, source)
         hm.teardown_nodes()
-        dest = dest.join(source.basename)
+        dest = dest.joinpath(source.name)
-        assert dest.join("dir1").check()
+        assert dest.joinpath("dir1").exists()
-        assert dest.join("dir1", "dir2").check()
+        assert dest.joinpath("dir1", "dir2").exists()
-        assert dest.join("dir1", "dir2", "hello").check()
+        assert dest.joinpath("dir1", "dir2", "hello").exists()
 
     def test_rsync_same_popen_twice(
-        self, config, mysetup, hookrecorder, workercontroller
+        self,
-    ):
+        config: pytest.Config,
-        source, dest = mysetup.source, mysetup.dest
+        source: Path,
+        dest: Path,
+        hookrecorder: pytest.HookRecorder,
+        workercontroller: None,
+    ) -> None:
         hm = NodeManager(config, ["popen//chdir=%s" % dest] * 2)
         hm.roots = []
-        hm.setup_nodes(None)
+        hm.setup_nodes(None)  # type: ignore[arg-type]
-        source.ensure("dir1", "dir2", "hello")
+        source.joinpath("dir1", "dir2").mkdir(parents=True)
+        source.joinpath("dir1", "dir2", "hello").touch()
         gw = hm.group[0]
         hm.rsync(gw, source)
         call = hookrecorder.popcall("pytest_xdist_rsyncstart")
@@ -131,161 +170,311 @@ class TestNodeManagerPopen:
 
 
 class TestHRSync:
-    def test_hrsync_filter(self, mysetup):
+    def test_hrsync_filter(self, source: Path, dest: Path) -> None:
-        source, _ = mysetup.source, mysetup.dest  # noqa
+        source.joinpath("dir").mkdir()
-        source.ensure("dir", "file.txt")
+        source.joinpath("dir", "file.txt").touch()
-        source.ensure(".svn", "entries")
+        source.joinpath(".svn").mkdir()
-        source.ensure(".somedotfile", "moreentries")
+        source.joinpath(".svn", "entries").touch()
-        source.ensure("somedir", "editfile~")
+        source.joinpath(".somedotfile").mkdir()
+        source.joinpath(".somedotfile", "moreentries").touch()
+        source.joinpath("somedir").mkdir()
+        source.joinpath("somedir", "editfile~").touch()
         syncer = HostRSync(source, ignores=NodeManager.DEFAULT_IGNORES)
-        files = list(source.visit(rec=syncer.filter, fil=syncer.filter))
+        files = list(visit_path(source, recurse=syncer.filter, filter=syncer.filter))
-        assert len(files) == 3
+        names = {x.name for x in files}
-        basenames = [x.basename for x in files]
+        assert names == {"dir", "file.txt", "somedir"}
-        assert "dir" in basenames
-        assert "file.txt" in basenames
-        assert "somedir" in basenames
 
-    def test_hrsync_one_host(self, mysetup):
+    def test_hrsync_one_host(self, source: Path, dest: Path) -> None:
-        source, dest = mysetup.source, mysetup.dest
+        gw = execnet.makegateway("execmodel=main_thread_only//popen//chdir=%s" % dest)
-        gw = execnet.makegateway("popen//chdir=%s" % dest)
         finished = []
         rsync = HostRSync(source)
         rsync.add_target_host(gw, finished=lambda: finished.append(1))
-        source.join("hello.py").write("world")
+        source.joinpath("hello.py").write_text("world")
         rsync.send()
         gw.exit()
-        assert dest.join(source.basename, "hello.py").check()
+        assert dest.joinpath(source.name, "hello.py").exists()
         assert len(finished) == 1
 
 
 class TestNodeManager:
-    @py.test.mark.xfail(run=False)
+    @pytest.mark.xfail(run=False)
-    def test_rsync_roots_no_roots(self, testdir, mysetup):
+    def test_rsync_roots_no_roots(
-        mysetup.source.ensure("dir1", "file1").write("hello")
+        self, pytester: pytest.Pytester, source: Path, dest: Path
-        config = testdir.parseconfig(mysetup.source)
+    ) -> None:
-        nodemanager = NodeManager(config, ["popen//chdir=%s" % mysetup.dest])
+        source.joinpath("dir1").mkdir()
+        source.joinpath("dir1", "file1").write_text("hello")
+        config = pytester.parseconfig(source)
+        nodemanager = NodeManager(config, ["popen//chdir=%s" % dest])
         # assert nodemanager.config.topdir == source == config.topdir
-        nodemanager.makegateways()
+        nodemanager.makegateways()  # type: ignore[attr-defined]
-        nodemanager.rsync_roots()
+        nodemanager.rsync_roots()  # type: ignore[call-arg]
-        (p,) = nodemanager.gwmanager.multi_exec(
+        (p,) = nodemanager.gwmanager.multi_exec(  # type: ignore[attr-defined]
             "import os ; channel.send(os.getcwd())"
         ).receive_each()
-        p = py.path.local(p)
+        p = Path(p)
         print("remote curdir", p)
-        assert p == mysetup.dest.join(config.topdir.basename)
+        assert p == dest.joinpath(config.rootpath.name)
-        assert p.join("dir1").check()
+        assert p.joinpath("dir1").is_dir()
-        assert p.join("dir1", "file1").check()
+        assert p.joinpath("dir1", "file1").is_file()
 
-    def test_popen_rsync_subdir(self, testdir, mysetup, workercontroller):
+    def test_popen_rsync_subdir(
-        source, dest = mysetup.source, mysetup.dest
+        self,
-        dir1 = mysetup.source.mkdir("dir1")
+        pytester: pytest.Pytester,
-        dir2 = dir1.mkdir("dir2")
+        source: Path,
-        dir2.ensure("hello")
+        dest: Path,
+        workercontroller: None,
+    ) -> None:
+        dir1 = source / "dir1"
+        dir1.mkdir()
+        dir2 = dir1 / "dir2"
+        dir2.mkdir()
+        dir2.joinpath("hello").touch()
         for rsyncroot in (dir1, source):
-            dest.remove()
+            shutil.rmtree(str(dest), ignore_errors=True)
             nodemanager = NodeManager(
-                testdir.parseconfig(
+                pytester.parseconfig(
                     "--tx", "popen//chdir=%s" % dest, "--rsyncdir", rsyncroot, source
                 )
             )
-            nodemanager.setup_nodes(None)  # calls .rsync_roots()
+            # calls .rsync_roots()
+            nodemanager.setup_nodes(None)  # type: ignore[arg-type]
             if rsyncroot == source:
-                dest = dest.join("source")
+                dest = dest.joinpath("source")
-            assert dest.join("dir1").check()
+            assert dest.joinpath("dir1").exists()
-            assert dest.join("dir1", "dir2").check()
+            assert dest.joinpath("dir1", "dir2").exists()
-            assert dest.join("dir1", "dir2", "hello").check()
+            assert dest.joinpath("dir1", "dir2", "hello").exists()
             nodemanager.teardown_nodes()
 
     @pytest.mark.parametrize(
-        "flag, expects_report", [("-q", False), ("", False), ("-v", True)]
+        ["flag", "expects_report"],
+        [
+            ("-q", False),
+            ("", False),
+            ("-v", True),
+        ],
     )
     def test_rsync_report(
-        self, testdir, mysetup, workercontroller, capsys, flag, expects_report
+        self,
-    ):
+        pytester: pytest.Pytester,
-        source, dest = mysetup.source, mysetup.dest
+        source: Path,
-        dir1 = mysetup.source.mkdir("dir1")
+        dest: Path,
-        args = "--tx", "popen//chdir=%s" % dest, "--rsyncdir", dir1, source
+        workercontroller: None,
+        capsys: pytest.CaptureFixture[str],
+        flag: str,
+        expects_report: bool,
+    ) -> None:
+        dir1 = source / "dir1"
+        dir1.mkdir()
+        args = ["--tx", "popen//chdir=%s" % dest, "--rsyncdir", str(dir1), str(source)]
         if flag:
-            args += (flag,)
+            args.append(flag)
-        nodemanager = NodeManager(testdir.parseconfig(*args))
+        nodemanager = NodeManager(pytester.parseconfig(*args))
-        nodemanager.setup_nodes(None)  # calls .rsync_roots()
+        # calls .rsync_roots()
+        nodemanager.setup_nodes(None)  # type: ignore[arg-type]
         out, _ = capsys.readouterr()
         if expects_report:
             assert "<= pytest/__init__.py" in out
         else:
             assert "<= pytest/__init__.py" not in out
 
-    def test_init_rsync_roots(self, testdir, mysetup, workercontroller):
+    def test_init_rsync_roots(
-        source, dest = mysetup.source, mysetup.dest
+        self,
-        dir2 = source.ensure("dir1", "dir2", dir=1)
+        pytester: pytest.Pytester,
-        source.ensure("dir1", "somefile", dir=1)
+        source: Path,
-        dir2.ensure("hello")
+        dest: Path,
-        source.ensure("bogusdir", "file")
+        workercontroller: None,
-        source.join("tox.ini").write(
+    ) -> None:
+        dir2 = source.joinpath("dir1", "dir2")
+        dir2.mkdir(parents=True)
+        source.joinpath("dir1", "somefile").mkdir()
+        dir2.joinpath("hello").touch()
+        source.joinpath("bogusdir").mkdir()
+        source.joinpath("bogusdir", "file").touch()
+        source.joinpath("tox.ini").write_text(
             textwrap.dedent(
                 """
-            [pytest]
+                [pytest]
-            rsyncdirs=dir1/dir2
+                rsyncdirs=dir1/dir2
-        """
+                """
             )
         )
-        config = testdir.parseconfig(source)
+        config = pytester.parseconfig(source)
         nodemanager = NodeManager(config, ["popen//chdir=%s" % dest])
-        nodemanager.setup_nodes(None)  # calls .rsync_roots()
+        # calls .rsync_roots()
-        assert dest.join("dir2").check()
+        nodemanager.setup_nodes(None)  # type: ignore[arg-type]
-        assert not dest.join("dir1").check()
+        assert dest.joinpath("dir2").exists()
-        assert not dest.join("bogus").check()
+        assert not dest.joinpath("dir1").exists()
+        assert not dest.joinpath("bogus").exists()
 
-    def test_rsyncignore(self, testdir, mysetup, workercontroller):
+    def test_rsyncignore(
-        source, dest = mysetup.source, mysetup.dest
+        self,
-        dir2 = source.ensure("dir1", "dir2", dir=1)
+        pytester: pytest.Pytester,
-        source.ensure("dir5", "dir6", "bogus")
+        source: Path,
-        source.ensure("dir5", "file")
+        dest: Path,
-        dir2.ensure("hello")
+        workercontroller: None,
-        source.ensure("foo", "bar")
+    ) -> None:
-        source.ensure("bar", "foo")
+        dir2 = source.joinpath("dir1", "dir2")
-        source.join("tox.ini").write(
+        dir2.mkdir(parents=True)
+        source.joinpath("dir5", "dir6").mkdir(parents=True)
+        source.joinpath("dir5", "dir6", "bogus").touch()
+        source.joinpath("dir5", "file").touch()
+        dir2.joinpath("hello").touch()
+        source.joinpath("foo").mkdir()
+        source.joinpath("foo", "bar").touch()
+        source.joinpath("bar").mkdir()
+        source.joinpath("bar", "foo").touch()
+        source.joinpath("tox.ini").write_text(
             textwrap.dedent(
                 """
-            [pytest]
+                [pytest]
-            rsyncdirs = dir1 dir5
+                rsyncdirs = dir1 dir5
-            rsyncignore = dir1/dir2 dir5/dir6 foo*
+                rsyncignore = dir1/dir2 dir5/dir6 foo*
-        """
+                """
             )
         )
-        config = testdir.parseconfig(source)
+        config = pytester.parseconfig(source)
         config.option.rsyncignore = ["bar"]
         nodemanager = NodeManager(config, ["popen//chdir=%s" % dest])
-        nodemanager.setup_nodes(None)  # calls .rsync_roots()
+        # calls .rsync_roots()
-        assert dest.join("dir1").check()
+        nodemanager.setup_nodes(None)  # type: ignore[arg-type]
-        assert not dest.join("dir1", "dir2").check()
+        assert dest.joinpath("dir1").exists()
-        assert dest.join("dir5", "file").check()
+        assert not dest.joinpath("dir1", "dir2").exists()
-        assert not dest.join("dir6").check()
+        assert dest.joinpath("dir5", "file").exists()
-        assert not dest.join("foo").check()
+        assert not dest.joinpath("dir6").exists()
-        assert not dest.join("bar").check()
+        assert not dest.joinpath("foo").exists()
+        assert not dest.joinpath("bar").exists()
 
-    def test_optimise_popen(self, testdir, mysetup, workercontroller):
+    def test_optimise_popen(
-        source = mysetup.source
+        self,
+        pytester: pytest.Pytester,
+        source: Path,
+        dest: Path,
+        workercontroller: None,
+    ) -> None:
         specs = ["popen"] * 3
-        source.join("conftest.py").write("rsyncdirs = ['a']")
+        source.joinpath("conftest.py").write_text("rsyncdirs = ['a']")
-        source.ensure("a", dir=1)
+        source.joinpath("a").mkdir()
-        config = testdir.parseconfig(source)
+        config = pytester.parseconfig(source)
         nodemanager = NodeManager(config, specs)
-        nodemanager.setup_nodes(None)  # calls .rysnc_roots()
+        # calls .rysnc_roots()
+        nodemanager.setup_nodes(None)  # type: ignore[arg-type]
         for gwspec in nodemanager.specs:
             assert gwspec._samefilesystem()
             assert not gwspec.chdir
 
-    def test_ssh_setup_nodes(self, specssh, testdir):
+    def test_ssh_setup_nodes(self, specssh: str, pytester: pytest.Pytester) -> None:
-        testdir.makepyfile(
+        pytester.makepyfile(
             __init__="",
             test_x="""
             def test_one():
                 pass
         """,
         )
-        reprec = testdir.inline_run(
+        reprec = pytester.inline_run(
-            "-d", "--rsyncdir=%s" % testdir.tmpdir, "--tx", specssh, testdir.tmpdir
+            "-d", "--rsyncdir=%s" % pytester.path, "--tx", specssh, pytester.path
         )
         (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
+
+
+@pytest.mark.parametrize(
+    "w_cls",
+    [
+        UserWarning,
+        MyWarning,
+        "Imported",
+        pytest.param(
+            "Nested",
+            marks=pytest.mark.xfail(reason="Nested warning classes are not supported."),
+        ),
+    ],
+)
+def test_unserialize_warning_msg(w_cls: type[Warning] | str) -> None:
+    """Test that warning serialization process works well."""
+    # Create a test warning message
+    with pytest.warns(UserWarning) as w:
+        if not isinstance(w_cls, str):
+            warnings.warn("hello", w_cls)
+        elif w_cls == "Imported":
+            generate_warning()
+        elif w_cls == "Nested":
+            # dynamic creation
+            class MyWarning2(UserWarning):
+                pass
+
+            warnings.warn("hello", MyWarning2)
+
+    # Unpack
+    assert len(w) == 1
+    w_msg = w[0]
+
+    # Serialize and deserialize
+    data = serialize_warning_message(w_msg)
+    w_msg2 = unserialize_warning_message(data)
+
+    # Compare the two objects
+    all_keys = set(vars(w_msg).keys()).union(set(vars(w_msg2).keys()))
+    for k in all_keys:
+        v1 = getattr(w_msg, k)
+        v2 = getattr(w_msg2, k)
+        if k == "message":
+            assert type(v1) is type(v2)
+            assert v1.args == v2.args
+        else:
+            assert v1 == v2
+
+
+class MyWarningUnknown(UserWarning):
+    # Changing the __module__ attribute is only safe if class can be imported
+    # from there
+    __module__ = "unknown"
+
+
+def test_warning_serialization_tweaked_module() -> None:
+    """Test for GH#404."""
+    # Create a test warning message
+    with pytest.warns(UserWarning) as w:
+        warnings.warn("hello", MyWarningUnknown)
+
+    # Unpack
+    assert len(w) == 1
+    w_msg = w[0]
+
+    # Serialize and deserialize
+    data = serialize_warning_message(w_msg)
+
+    # __module__ cannot be found!
+    with pytest.raises(ModuleNotFoundError):
+        unserialize_warning_message(data)

testing/util.py

@@ -0,0 +1,9 @@
+import warnings
+
+
+class MyWarning2(UserWarning):
+    pass
+
+
+def generate_warning() -> None:
+    warnings.warn(MyWarning2("hello"))

tox.ini

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