Release 3.5.0

Follow up to # 632.

---------

Co-authored-by: Jörg Kohlsdorf <joerg@cornershopapp.com>

.github/workflows/deploy.yml

@@ -0,0 +1,55 @@
+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@v3
+
+    - name: Build and Check Package
+      uses: hynek/build-and-inspect-python-package@v1.5
+
+  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@v3
+
+    - name: Download Package
+      uses: actions/download-artifact@v3
+      with:
+        name: Packages
+        path: dist
+
+    - name: Publish package to PyPI
+      uses: pypa/gh-action-pypi-publish@v1.8.5
+
+    - 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@v1
+      with:
+        files: dist/*
+        tag_name: v${{ github.event.inputs.version }}

.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@v3
+    - name: Build and Check Package
+      uses: hynek/build-and-inspect-python-package@v1.5
+
+  test:
+
+    needs: [package]
+
+    runs-on: ${{ matrix.os }}
+
+    strategy:
+      fail-fast: false
+      matrix:
+        tox_env:
+          - "py37-pytestlatest"
+          - "py38-pytestlatest"
+          - "py39-pytestlatest"
+          - "py310-pytestlatest"
+          - "py311-pytestlatest"
+          - "py311-pytestmain"
+          - "py312-pytestlatest"
+          - "py310-psutil"
+          - "py310-setproctitle"
+
+        os: [ubuntu-latest, windows-latest]
+        include:
+          - tox_env: "py37-pytestlatest"
+            python: "3.7"
+          - tox_env: "py38-pytestlatest"
+            python: "3.8"
+          - 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: "py310-psutil"
+            python: "3.10"
+          - tox_env: "py310-setproctitle"
+            python: "3.10"
+
+    steps:
+    - uses: actions/checkout@v3
+      with:
+        # Needed to fetch tags, which are required by setuptools-scm.
+        fetch-depth: 0
+
+    - name: Download Package
+      uses: actions/download-artifact@v3
+      with:
+        name: Packages
+        path: dist
+
+    - name: Set up Python
+      uses: actions/setup-python@v2
+      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`

.gitignore

@@ -23,7 +23,7 @@ include/
 lib/
 bin/
 env/
-xdist/_version.py*
+src/xdist/_version.py*
 pytest_xdist.egg-info
 issue/
 3rdparty/

.pre-commit-config.yaml

@@ -1,18 +1,35 @@
 repos:
--   repo: https://github.com/ambv/black
+-   repo: https://github.com/PyCQA/autoflake
-    rev: 18.6b4
+    rev: v2.2.1
+    hooks:
+    -   id: autoflake
+        args: ["--in-place", "--remove-unused-variables", "--remove-all-unused-imports"]
+-   repo: https://github.com/psf/black
+    rev: 23.11.0
     hooks:
     -   id: black
-        args: [--safe, --quiet]
+        args: [--safe, --quiet, --target-version, py35]
-        language_version: python3.6
+-   repo: https://github.com/asottile/blacken-docs
+    rev: 1.16.0
+    hooks:
+    -   id: blacken-docs
+        additional_dependencies: [black==23.1.0]
 -   repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v1.3.0
+    rev: v4.5.0
     hooks:
     -   id: trailing-whitespace
     -   id: end-of-file-fixer
     -   id: check-yaml
     -   id: debug-statements
+-   repo: https://github.com/PyCQA/flake8
+    rev: 6.1.0
+    hooks:
     -   id: flake8
+-   repo: https://github.com/asottile/pyupgrade
+    rev: v3.15.0
+    hooks:
+    -   id: pyupgrade
+        args: [--py3-plus]
 -   repo: local
     hooks:
     -   id: rst
@@ -21,4 +38,12 @@ repos:
         files: ^(CHANGELOG.rst|HOWTORELEASE.rst|README.rst|changelog/.*)$
         language: python
         additional_dependencies: [pygments, restructuredtext_lint]
-        python_version: python3.6
+-   repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.7.0
+    hooks:
+    -   id: mypy
+        files: ^(src/|testing/)
+        args: []
+        additional_dependencies:
+          - pytest>=6.2.0
+          - py>=1.10.0

.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

.travis.yml

@@ -1,66 +0,0 @@
-sudo: false
-language: python
-
-notifications:
-  irc:
-    channels:
-    - 'chat.freenode.net#pytest'
-    on_success: change
-    on_failure: change
-    skip_join: true
-  email:
-  - pytest-commit@python.org
-
-python:
-- '2.7'
-- '3.4'
-- '3.5'
-- '3.6'
-env:
-- TOXENV=py-pytest30
-- TOXENV=py-pytest31
-- TOXENV=py-pytest32
-- TOXENV=py-pytest33
-- TOXENV=py-pytest36
-
-install: pip install tox setuptools_scm
-script: tox
-
-stages:
-- linting
-- test
-- name: deploy
-  if: repo = pytest-dev/pytest-xdist AND tag IS present
-
-jobs:
-  include:
-    - stage: linting
-      python: '3.6'
-      script:
-      - tox -e linting
-    - stage: test
-    # python x env above are already included into this stage
-    - python: "2.7"
-      env: TOXENV=py27-pytestmaster
-    - python: "2.7"
-      env: TOXENV=py27-pytestfeatures
-    - python: "3.6"
-      env: TOXENV=py36-pytestmaster
-    - python: "3.6"
-      env: TOXENV=py36-pytestfeatures
-
-    - stage: deploy
-      python: '3.6'
-      env:
-      install: pip install -U setuptools setuptools_scm
-      script: skip
-      deploy:
-        provider: pypi
-        user: ronny
-        distributions: sdist bdist_wheel
-        skip_upload_docs: true
-        password:
-          secure: cxmSDho5d+PYKEM4ZCg8ms1P4lzhYkrw6fEOm2HtTcsuCyY6aZMSgImWAnEYbJHSkdzgcxlXK9UKJ9B0YenXmBCkAr7UjdnpNXNmkySr0sYzlH/sfqt/dDATCHFaRKxnkOSOVywaDYhT9n8YudbXI77pXwD12i/CeSSJDbHhsu0JYUfAcb+D6YjRYoA2SEGCnzSzg+gDDfwXZx4ZiODCGLVwieNp1klCg88YROUE1BaYYNuUOONvfXX8+TWowbCF6ChH1WL/bZ49OStEYQNuYxZQZr4yClIqu9VJbchrU8j860K9ott2kkGTgfB/dDrQB/XncBubyIX9ikzCQAmmBXWAI3eyvWLPDk2Jz7kW2l2RT7syct80tCq3JhvQ1qdwr5ap7siocTLgnBW0tF4tkHSTFN3510fkc43npnp6FThebESQpnI24vqpwJ9hI/kW5mYi014Og2E/cpCXnz2XO8iZPDbqAMQpDsqEQoyhfGNgPTGp4K30TxRtwZBI5hHhDKnnR16fXtRgt1gYPvz/peUQvvpOm4JzIzGXPzluuutpnCBy75v5+oiwT3YRrLL/Meims9FtDDXL3qQubAE/ezIOOpm0N5XXV8DxIom8EN71yq5ab1tqhM+tBX7owRjy4FR4If2Q8feBdmTuh26DIQt/y+qSG8VkB9Sw/JCjc7c=
-        on:
-          tags: true
-          repo: pytest-dev/pytest-xdist

CHANGELOG.rst

@@ -1,3 +1,559 @@
+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)
+===============================
+
+Deprecations and Removals
+-------------------------
+
+- `#654 <https://github.com/pytest-dev/pytest-xdist/issues/654>`_: Python 3.5 is no longer supported.
+
+
+Features
+--------
+
+- `#646 <https://github.com/pytest-dev/pytest-xdist/issues/646>`_: Add ``--numprocesses=logical`` flag, which automatically uses the number of logical CPUs available, instead of physical CPUs with ``auto``.
+
+  This is very useful for test suites which are not CPU-bound.
+
+- `#650 <https://github.com/pytest-dev/pytest-xdist/issues/650>`_: Added new ``pytest_handlecrashitem`` hook to allow handling and rescheduling crashed items.
+
+
+Bug Fixes
+---------
+
+- `#421 <https://github.com/pytest-dev/pytest-xdist/issues/421>`_: Copy the parent process sys.path into local workers, to work around execnet's python -c adding the current directory to sys.path.
+
+- `#638 <https://github.com/pytest-dev/pytest-xdist/issues/638>`_: Fix issue caused by changing the branch name of the pytest repository.
+
+
+Trivial Changes
+---------------
+
+- `#592 <https://github.com/pytest-dev/pytest-xdist/issues/592>`_: Replace master with controller where ever possible.
+
+- `#643 <https://github.com/pytest-dev/pytest-xdist/issues/643>`_: Use 'main' to refer to pytest default branch in tox env names.
+
+
+pytest-xdist 2.2.1 (2021-02-09)
+===============================
+
+Bug Fixes
+---------
+
+- `#623 <https://github.com/pytest-dev/pytest-xdist/issues/623>`_: Gracefully handle the pending deprecation of Node.fspath by using config.rootpath for topdir.
+
+
+pytest-xdist 2.2.0 (2020-12-14)
+===============================
+
+Features
+--------
+
+- `#608 <https://github.com/pytest-dev/pytest-xdist/issues/608>`_: Internal errors in workers are now propagated to the master node.
+
+
+pytest-xdist 2.1.0 (2020-08-25)
+===============================
+
+Features
+--------
+
+- `#585 <https://github.com/pytest-dev/pytest-xdist/issues/585>`_: New ``pytest_xdist_auto_num_workers`` hook can be implemented by plugins or ``conftest.py`` files to control the number of workers when ``--numprocesses=auto`` is given in the command-line.
+
+
+Trivial Changes
+---------------
+
+- `#585 <https://github.com/pytest-dev/pytest-xdist/issues/585>`_: ``psutil`` has proven to make ``pytest-xdist`` installation in certain platforms and containers problematic, so to use it for automatic number of CPUs detection users need to install the ``psutil`` extra::
+
+      pip install pytest-xdist[psutil]
+
+
+pytest-xdist 2.0.0 (2020-08-12)
+===============================
+
+Deprecations and Removals
+-------------------------
+
+- `#541 <https://github.com/pytest-dev/pytest-xdist/issues/541>`_: Drop backward-compatibility "slave" aliases related to worker nodes.  We deliberately moved away from this terminology years ago, and it seems like the right time to finish the deprecation and removal process.
+
+- `#569 <https://github.com/pytest-dev/pytest-xdist/issues/569>`_: ``pytest-xdist`` no longer supports Python 2.7.
+
+
+Features
+--------
+
+- `#504 <https://github.com/pytest-dev/pytest-xdist/issues/504>`_: New functions ``xdist.is_xdist_worker``, ``xdist.is_xdist_master``, ``xdist.get_xdist_worker_id``, to easily identify the current node.
+
+
+Bug Fixes
+---------
+
+- `#471 <https://github.com/pytest-dev/pytest-xdist/issues/471>`_: Fix issue with Rsync reporting in quiet mode.
+
+- `#553 <https://github.com/pytest-dev/pytest-xdist/issues/553>`_: When using ``-n auto``, count the number of physical CPU cores instead of logical ones.
+
+
+Trivial Changes
+---------------
+
+- `#541 <https://github.com/pytest-dev/pytest-xdist/issues/541>`_: ``pytest-xdist`` now requires ``pytest>=6.0``.
+
+
+pytest-xdist 1.34.0 (2020-07-27)
+================================
+
+Features
+--------
+
+- `#549 <https://github.com/pytest-dev/pytest-xdist/issues/549>`_: Make ``--pdb`` imply ``--dist no``, as the two options cannot really work together at the moment.
+
+
+Bug Fixes
+---------
+
+- `#478 <https://github.com/pytest-dev/pytest-xdist/issues/478>`_: Fix regression with duplicated arguments via $PYTEST_ADDOPTS in 1.30.0.
+
+- `#558 <https://github.com/pytest-dev/pytest-xdist/issues/558>`_: Fix ``rsyncdirs`` usage with pytest 6.0.
+
+- `#562 <https://github.com/pytest-dev/pytest-xdist/issues/562>`_: Do not trigger the deprecated ``pytest_warning_captured`` in pytest 6.0+.
+
+
+pytest-xdist 1.33.0 (2020-07-09)
+================================
+
+Features
+--------
+
+- `#554 <https://github.com/pytest-dev/pytest-xdist/issues/554>`_: Fix warnings support for upcoming pytest 6.0.
+
+
+Trivial Changes
+---------------
+
+- `#548 <https://github.com/pytest-dev/pytest-xdist/issues/548>`_: SCM and CI files are no longer included in the source distribution.
+
+
+pytest-xdist 1.32.0 (2020-05-03)
+================================
+
+Deprecations and Removals
+-------------------------
+
+- `#475 <https://github.com/pytest-dev/pytest-xdist/issues/475>`_: Drop support for EOL Python 3.4.
+
+
+Features
+--------
+
+- `#524 <https://github.com/pytest-dev/pytest-xdist/issues/524>`_: Add `testrun_uid` fixture. This is a shared value that uniquely identifies a test run among all workers.
+  This also adds a `PYTEST_XDIST_TESTRUNUID` environment variable that is accessible within a test as well as a command line option `--testrunuid` to manually set the value from outside.
+
+
+pytest-xdist 1.31.0 (2019-12-19)
+================================
+
+Features
+--------
+
+- `#486 <https://github.com/pytest-dev/pytest-xdist/issues/486>`_: Add support for Python 3.8.
+
+
+Bug Fixes
+---------
+
+- `#491 <https://github.com/pytest-dev/pytest-xdist/issues/491>`_: Fix regression that caused custom plugin command-line arguments to be discarded when using ``--tx`` mode.
+
+
+
+pytest-xdist 1.30.0 (2019-10-01)
+================================
+
+Features
+--------
+
+- `#448 <https://github.com/pytest-dev/pytest-xdist/issues/448>`_: Initialization between workers and master nodes is now more consistent, which fixes a number of
+  long-standing issues related to startup with the ``-c`` option.
+
+  Issues:
+
+  * `#6 <https://github.com/pytest-dev/pytest-xdist/issues/6>`__: Poor interaction between ``-n#`` and ``-c X.cfg``
+  * `#445 <https://github.com/pytest-dev/pytest-xdist/issues/445>`__: pytest-xdist is not reporting the same nodeid as pytest does
+
+  This however only works with **pytest 5.1 or later**, as it required changes in pytest itself.
+
+
+Bug Fixes
+---------
+
+- `#467 <https://github.com/pytest-dev/pytest-xdist/issues/467>`_: Fix crash issues related to running xdist with the terminal plugin disabled.
+
+
+pytest-xdist 1.29.0 (2019-06-14)
+================================
+
+Features
+--------
+
+- `#226 <https://github.com/pytest-dev/pytest-xdist/issues/226>`_: ``--max-worker-restart`` now assumes a more reasonable value (4 times the number of
+  nodes) when not given explicitly. This prevents test suites from running forever when the suite crashes during collection.
+
+- `#435 <https://github.com/pytest-dev/pytest-xdist/issues/435>`_: When the test session is interrupted due to running out of workers, the reason is shown in the test summary
+  for easier viewing.
+
+- `#442 <https://github.com/pytest-dev/pytest-xdist/issues/442>`_: Compatibility fix for upcoming pytest 5.0: ``session.exitstatus`` is now an ``IntEnum`` object.
+
+
+Bug Fixes
+---------
+
+- `#435 <https://github.com/pytest-dev/pytest-xdist/issues/435>`_: No longer show an internal error when we run out of workers due to crashes.
+
+
+pytest-xdist 1.28.0 (2019-04-02)
+================================
+
+Features
+--------
+
+- `#426 <https://github.com/pytest-dev/pytest-xdist/issues/426>`_: ``pytest-xdist`` now uses the new ``pytest_report_to_serializable`` and ``pytest_report_from_serializable``
+  hooks from ``pytest 4.4`` (still experimental). This will make report serialization more reliable and
+  extensible.
+
+  This also means that ``pytest-xdist`` now requires ``pytest>=4.4``.
+
+
+pytest-xdist 1.27.0 (2019-02-15)
+================================
+
+Features
+--------
+
+- `#374 <https://github.com/pytest-dev/pytest-xdist/issues/374>`_: The new ``pytest_xdist_getremotemodule`` hook allows overriding the module run on remote nodes.
+
+- `#415 <https://github.com/pytest-dev/pytest-xdist/issues/415>`_: Improve behavior of ``--numprocesses=auto`` to work well with ``--pdb`` option.
+
+
+pytest-xdist 1.26.1 (2019-01-28)
+================================
+
+Bug Fixes
+---------
+
+- `#406 <https://github.com/pytest-dev/pytest-xdist/issues/406>`_: Do not implement deprecated ``pytest_logwarning`` hook in pytest versions where it is deprecated.
+
+
+pytest-xdist 1.26.0 (2019-01-11)
+================================
+
+Features
+--------
+
+- `#376 <https://github.com/pytest-dev/pytest-xdist/issues/376>`_: The current directory is no longer added ``sys.path`` for local workers, only for remote connections.
+
+  This behavior is surprising because it makes xdist runs and non-xdist runs to potentially behave differently.
+
+
+Bug Fixes
+---------
+
+- `#379 <https://github.com/pytest-dev/pytest-xdist/issues/379>`_: Warning attributes are checked to make sure they can be dumped prior to
+  serializing the warning for submission to the master node.
+
+
+pytest-xdist 1.25.0 (2018-12-12)
+================================
+
+Deprecations and Removals
+-------------------------
+
+- `#372 <https://github.com/pytest-dev/pytest-xdist/issues/372>`_: Pytest versions older than 3.6 are no longer supported.
+
+
+Features
+--------
+
+- `#373 <https://github.com/pytest-dev/pytest-xdist/issues/373>`_: Node setup information is hidden when pytest is run in quiet mode to reduce noise on many-core machines.
+
+- `#388 <https://github.com/pytest-dev/pytest-xdist/issues/388>`_: ``mainargv`` is made available in ``workerinput`` from the host's ``sys.argv``.
+
+  This can be used via ``request.config.workerinput["mainargv"]``.
+
+
+Bug Fixes
+---------
+
+- `#332 <https://github.com/pytest-dev/pytest-xdist/issues/332>`_: Fix report of module-level skips (``pytest.skip(reason, allow_module_level=True)``).
+
+- `#378 <https://github.com/pytest-dev/pytest-xdist/issues/378>`_: Fix support for gevent monkeypatching
+
+- `#384 <https://github.com/pytest-dev/pytest-xdist/issues/384>`_: pytest 4.1 support: ``ExceptionInfo`` API changes.
+
+- `#390 <https://github.com/pytest-dev/pytest-xdist/issues/390>`_: pytest 4.1 support: ``pytest_logwarning`` hook removed.
+
+
+pytest-xdist 1.24.1 (2018-11-09)
+================================
+
+Bug Fixes
+---------
+
+- `#349 <https://github.com/pytest-dev/pytest-xdist/issues/349>`_: Correctly handle warnings created with arguments that can't be serialized during the transfer from workers to master node.
+
+
+pytest-xdist 1.24.0 (2018-10-18)
+================================
+
+Features
+--------
+
+- `#337 <https://github.com/pytest-dev/pytest-xdist/issues/337>`_: New ``--maxprocesses`` command-line option that limits the maximum number of workers when using ``--numprocesses=auto``.
+
+
+Bug Fixes
+---------
+
+- `#351 <https://github.com/pytest-dev/pytest-xdist/issues/351>`_: Fix scheduling deadlock in case of inter-test locking.
+
+
+pytest-xdist 1.23.2 (2018-09-28)
+================================
+
+Bug Fixes
+---------
+
+- `#344 <https://github.com/pytest-dev/pytest-xdist/issues/344>`_: Fix issue where Warnings could cause pytest to fail if they do not set the args attribute correctly.
+
+
+pytest-xdist 1.23.1 (2018-09-25)
+================================
+
+Bug Fixes
+---------
+
+- `#341 <https://github.com/pytest-dev/pytest-xdist/issues/341>`_: Fix warnings transfer between workers and master node with pytest >= 3.8.
+
+
 pytest-xdist 1.23.0 (2018-08-23)
 ================================
 
@@ -256,17 +812,6 @@ Improved Documentation
 - Added ``HOWTORELEASE`` documentation. (#155)
 
 
-..
-    You should *NOT* be adding new change log entries to this file, this
-    file is managed by towncrier. You *may* edit previous change logs to
-    fix problems like typo corrections or such.
-    To add a new change log entry, please see
-    https://pip.pypa.io/en/latest/development/#adding-a-news-entry
-    We named the news folder ``changelog``
-
-.. towncrier release notes start
-
-
 1.17.0
 ------
 

ISSUES.txt

@@ -1,31 +0,0 @@
-next release critical
------------------------------------------------
-tag: bug
-
-miserably fails: --dist=each --tx popen --tx socket=...
-
-
-rename / hooks
------------------------------------------------
-tag: bug
-
-node -> slave
-transition for hooks?
-configure_node -> configure_slave
-
-allow to remotely run xdist tests with xdist
------------------------------------------------
-tag: feature
-
-allow to run xdist own tests using its own mechanism.
-currently this doesn't work because the remote side
-has no pytest plugin.   How to configure/do
-register "xdist.plugin" on the remote side?
-
-see to avoid any "from _pytest" internal imports
------------------------------------------------
-tag: feature
-
-currently tests and even xdist core code imports
-names from the internal _pytest namespace.
-See to avoid it.

MANIFEST.in

@@ -0,0 +1,5 @@
+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,259 +13,21 @@
     :alt: Python versions
     :target: https://pypi.python.org/pypi/pytest-xdist
 
-.. image:: https://travis-ci.org/pytest-dev/pytest-xdist.svg?branch=master
+.. image:: https://github.com/pytest-dev/pytest-xdist/workflows/test/badge.svg
-    :alt: Travis CI build status
+    :target: https://github.com/pytest-dev/pytest-xdist/actions
-    :target: https://travis-ci.org/pytest-dev/pytest-xdist
-
-.. image:: https://ci.appveyor.com/api/projects/status/56eq1a1avd4sdd7e/branch/master?svg=true
-    :alt: AppVeyor build status
-    :target: https://ci.appveyor.com/project/pytestbot/pytest-xdist
 
 .. 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>`_.
-
-
-Installation
-------------
-
-Install the plugin with::
-
-    pip install pytest-xdist
-
-or use the package in develop/in-place mode with
-a checkout of the `pytest-xdist repository`_ ::
-
-    pip install --editable .
-
-.. _parallelization:
-
-Speed up test runs by sending tests to multiple CPUs
-----------------------------------------------------
-
-To send tests to multiple CPUs, type::
-
-    pytest -n NUM
-
-Especially for longer running tests or tests requiring
-a lot of I/O this can lead to considerable speed ups. This option can
-also be set to ``auto`` for automatic detection of the number of CPUs.
-
-If a test crashes the interpreter, pytest-xdist will automatically restart
-that worker and report the failure as usual. You can use the
-``--max-worker-restart`` option to limit the number of workers that can
-be restarted, or disable restarting altogether using ``--max-worker-restart=0``.
-
-By default, the ``-n`` option will send pending tests to any worker that is available, without
-any guaranteed order, but you can control this with these options:
-
-* ``--dist=loadscope``: tests will be grouped by **module** for *test functions* and
-  by **class** for *test methods*, then each group will be sent to an available worker,
-  guaranteeing 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. Currently the groupings can't be customized,
-  with grouping by class takes priority over grouping by module.
-  This feature was added in version ``1.19``.
-
-* ``--dist=loadfile``: tests will be grouped by file name, and then will be sent to an available
-  worker, guaranteeing that all tests in a group run in the same worker. This feature was added
-  in version ``1.21``.
-
-
-Running tests in a Python subprocess
-------------------------------------
-
-To instantiate a python3.5 subprocess and send tests to it, you may type::
-
-    pytest -d --tx popen//python=python3.5
-
-This will start a subprocess which is run with the ``python3.5``
-Python interpreter, found in your system binary lookup path.
-
-If you prefix the --tx option value like this::
-
-    --tx 3*popen//python=python3.5
-
-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`: http://bitbucket.org/hpk42/execnet/raw/2af991418160/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"``.
-
-Additionally, worker processes 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.
-
-
-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.5 --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,8 @@ 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.
 
-    $ export VERSION=X.Y.Z
+#. Merge the release PR to ``master``.
-    $ 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.

appveyor.yml

@@ -1,22 +0,0 @@
-environment:
-  matrix:
-  # note: please use "tox --listenvs" to populate the build matrix
-  - TOXENV: "py27-pytest33"
-  - TOXENV: "py34-pytest33"
-  - TOXENV: "py35-pytest33"
-  - TOXENV: "py36-pytest33"
-  - TOXENV: "py36-pytest36"
-  - TOXENV: "py27-pytest33-pexpect"
-  - TOXENV: "py36-pytest33-pexpect"
-
-install:
-  - C:\Python36\python -m pip install -U tox setuptools_scm pip
-
-build: false  # Not a C# project, build stuff at the test step instead.
-
-test_script:
-  - C:\Python36\python -m tox
-
-# We don't deploy anything on tags with AppVeyor, we use Travis instead, so we
-# might as well save resources
-skip_tags: true

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 = "2022, 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,95 @@
+.. _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 CPU cores.
+
+Use ``-n logical`` to use the number of *logical* CPU cores rather than
+physical ones. This currently requires the ``psutil`` package to be installed;
+if it is not, pytest-xdist will fall back to ``-n auto`` behavior.
+
+Pass a number, e.g. ``-n 8``, to specify the number of processes explicitly.
+
+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.
+
+  .. 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.
+  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,86 @@
+
+.. _`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
+
+
+
+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/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,14 @@
+[build-system]
+requires = [
+  "setuptools>=45.0",
+  "setuptools-scm[toml]>=6.2.3",
+  "wheel",
+]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools_scm]
+write_to = "src/xdist/_version.py"
+
 [tool.towncrier]
 package = "xdist"
 filename = "CHANGELOG.rst"
@@ -5,32 +16,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,8 +1,83 @@
-[bdist_wheel]
-universal = 1
-
 [metadata]
+name = pytest-xdist
+description = pytest xdist plugin for distributed testing, most importantly across multiple CPUs
+long_description = file: README.rst
+long_description_content_type = text/x-rst
+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
+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.7
+    Programming Language :: Python :: 3.8
+    Programming Language :: Python :: 3.9
+    Programming Language :: Python :: 3.10
+    Programming Language :: Python :: 3.11
+    Programming Language :: Python :: 3.12
 license_file = LICENSE
+project_urls =
+    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
+
+[options]
+packages = find:
+package_dir = =src
+zip_safe = False
+python_requires = >=3.7
+install_requires =
+    execnet>=1.1
+    pytest>=6.2.0
+
+[options.packages.find]
+where = src
+
+[options.entry_points]
+pytest11 =
+    xdist = xdist.plugin
+    xdist.looponfail = xdist.looponfail
+
+[options.extras_require]
+testing =
+    filelock
+psutil = psutil>=3.0
+setproctitle = setproctitle
 
 [flake8]
+# Ignore any errors related to formatting, let black worry/fix them.
+ignore = E501, W503, E203
 max-line-length = 100
+
+[mypy]
+mypy_path = src
+# TODO: Enable this & fix errors.
+# check_untyped_defs = True
+disallow_any_generics = True
+ignore_missing_imports = True
+no_implicit_optional = True
+show_error_codes = True
+strict_equality = True
+warn_redundant_casts = True
+warn_return_any = True
+warn_unreachable = True
+warn_unused_configs = True
+# TODO: Enable this & fix errors.
+# no_implicit_reexport = True

setup.py

@@ -1,44 +0,0 @@
-from setuptools import setup, find_packages
-
-install_requires = ["execnet>=1.1", "pytest>=3.0.0", "pytest-forked", "six"]
-
-
-setup(
-    name="pytest-xdist",
-    use_scm_version={"write_to": "xdist/_version.py"},
-    description="pytest xdist plugin for distributed testing"
-    " and loop-on-failing modes",
-    long_description=open("README.rst").read(),
-    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(exclude=["testing", "example"]),
-    entry_points={
-        "pytest11": ["xdist = xdist.plugin", "xdist.looponfail = xdist.looponfail"]
-    },
-    zip_safe=False,
-    python_requires=">=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*",
-    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 :: 2",
-        "Programming Language :: Python :: 2.7",
-        "Programming Language :: Python :: 3",
-        "Programming Language :: Python :: 3.4",
-        "Programming Language :: Python :: 3.5",
-        "Programming Language :: Python :: 3.6",
-    ],
-)

src/xdist/__init__.py

@@ -0,0 +1,15 @@
+from xdist.plugin import (
+    is_xdist_worker,
+    is_xdist_master,
+    get_xdist_worker_id,
+    is_xdist_controller,
+)
+from xdist._version import version as __version__
+
+__all__ = [
+    "__version__",
+    "is_xdist_worker",
+    "is_xdist_master",
+    "is_xdist_controller",
+    "get_xdist_worker_id",
+]

src/xdist/_path.py

@@ -0,0 +1,19 @@
+import os
+from itertools import chain
+from pathlib import Path
+from typing import Callable, Iterator
+
+
+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,23 +1,30 @@
-import py
+from __future__ import annotations
+import sys
+from enum import Enum, auto
+from typing import Sequence
+
 import pytest
 
+from xdist.remote import Producer
 from xdist.workermanage import NodeManager
 from xdist.scheduler import (
     EachScheduling,
     LoadScheduling,
     LoadScopeScheduling,
     LoadFileScheduling,
+    LoadGroupScheduling,
+    WorkStealingScheduling,
 )
 
 
-from six.moves.queue import Empty, Queue
+from queue import Empty, Queue
 
 
 class Interrupted(KeyboardInterrupt):
-    """ signals an immediate interruption. """
+    """signals an immediate interruption."""
 
 
-class DSession(object):
+class DSession:
     """A pytest plugin which runs a distributed test session
 
     At the beginning of the test session this creates a NodeManager
@@ -33,9 +40,7 @@ class DSession(object):
 
     def __init__(self, config):
         self.config = config
-        self.log = py.log.Producer("dsession")
+        self.log = Producer("dsession", enabled=config.option.debug)
-        if not config.option.debug:
-            py.log.setconsumer(self.log._keywords, None)
         self.nodemanager = None
         self.sched = None
         self.shuttingdown = False
@@ -46,14 +51,11 @@ class DSession(object):
         self._failed_collection_errors = {}
         self._active_nodes = set()
         self._failed_nodes_count = 0
-        self._max_worker_restart = self.config.option.maxworkerrestart
+        self._max_worker_restart = get_default_max_worker_restart(self.config)
-        if self._max_worker_restart is not None:
+        # summary message to print at the end of the session
-            self._max_worker_restart = int(self._max_worker_restart)
+        self._summary_report = None
-        try:
         self.terminal = config.pluginmanager.getplugin("terminalreporter")
-        except KeyError:
+        if self.terminal:
-            self.terminal = None
-        else:
             self.trdist = TerminalDistReporter(config)
             config.pluginmanager.register(self.trdist, "terminaldistreporter")
 
@@ -70,7 +72,7 @@ class DSession(object):
         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):
         """Creates and starts the nodes.
 
@@ -82,6 +84,7 @@ class DSession(object):
         self._active_nodes.update(nodes)
         self._session = session
 
+    @pytest.hookimpl
     def pytest_sessionfinish(self, session):
         """Shutdown all nodes."""
         nm = getattr(self, "nodemanager", None)  # if not fully initialized
@@ -89,11 +92,12 @@ class DSession(object):
             nm.teardown_nodes()
         self._session = None
 
+    @pytest.hookimpl
     def pytest_collection(self):
-        # prohibit collection of test items in master process
+        # 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):
         dist = config.getvalue("dist")
         schedulers = {
@@ -101,9 +105,12 @@ class DSession(object):
             "load": LoadScheduling,
             "loadscope": LoadScopeScheduling,
             "loadfile": LoadFileScheduling,
+            "loadgroup": LoadGroupScheduling,
+            "worksteal": WorkStealingScheduling,
         }
         return schedulers[dist](config, log)
 
+    @pytest.hookimpl
     def pytest_runtestloop(self):
         self.sched = self.config.hook.pytest_xdist_make_scheduler(
             config=self.config, log=self.log
@@ -111,11 +118,14 @@ class DSession(object):
         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):
@@ -153,9 +163,6 @@ class DSession(object):
         node.workerinfo["id"] = node.gateway.id
         node.workerinfo["spec"] = node.gateway.spec
 
-        # TODO: (#234 task) needs this for pytest. Remove when refactor in pytest repo
-        node.slaveinfo = node.workerinfo
-
         self.config.hook.pytest_testnodeready(node=node)
         if self.shuttingdown:
             node.shutdown()
@@ -172,7 +179,7 @@ class DSession(object):
         """
         self.config.hook.pytest_testnodedown(node=node, error=None)
         if node.workeroutput["exitstatus"] == 2:  # keyboard-interrupt
-            self.shouldstop = "%s received keyboard-interrupt" % (node,)
+            self.shouldstop = f"{node} received keyboard-interrupt"
             self.worker_errordown(node, "keyboard-interrupt")
             return
         if node in self.sched.nodes:
@@ -180,6 +187,24 @@ class DSession(object):
             assert not crashitem, (crashitem, node)
         self._active_nodes.remove(node)
 
+    def worker_internal_error(self, node, formatted_error):
+        """
+        pytest_internalerror() was called on the worker.
+
+        pytest_internalerror() arguments are an excinfo and an excrepr, which can't
+        be serialized, so we go with a poor man's solution of raising an exception
+        here ourselves using the formatted message.
+        """
+        self._active_nodes.remove(node)
+        try:
+            assert False, formatted_error
+        except AssertionError:
+            from _pytest._code import ExceptionInfo
+
+            excinfo = ExceptionInfo.from_current()
+            excrepr = excinfo.getrepr()
+            self.config.hook.pytest_internalerror(excrepr=excrepr, excinfo=excinfo)
+
     def worker_errordown(self, node, error):
         """Emitted by the WorkerController when a node dies."""
         self.config.hook.pytest_testnodedown(node=node, error=error)
@@ -198,15 +223,25 @@ class DSession(object):
         )
         if maximum_reached:
             if self._max_worker_restart == 0:
-                msg = "Worker restarting disabled"
+                msg = "worker {} crashed and worker restarting disabled".format(
+                    node.gateway.id
+                )
             else:
-                msg = "Maximum crashed workers reached: %d" % self._max_worker_restart
+                msg = "maximum crashed workers reached: %d" % self._max_worker_restart
-            self.report_line(msg)
+            self._summary_report = msg
+            self.report_line("\n" + msg)
+            self.triggershutdown()
         else:
-            self.report_line("Replacing crashed worker %s" % node.gateway.id)
+            self.report_line("\nreplacing crashed worker %s" % node.gateway.id)
+            self.shuttingdown = False
             self._clone_node(node)
         self._active_nodes.remove(node)
 
+    @pytest.hookimpl
+    def pytest_terminal_summary(self, terminalreporter):
+        if self.config.option.verbose >= 0 and self._summary_report:
+            terminalreporter.write_sep("=", f"xdist: {self._summary_report}")
+
     def worker_collectionfinish(self, node, ids):
         """worker has finished test collection.
 
@@ -220,17 +255,20 @@ class DSession(object):
             return
         self.config.hook.pytest_xdist_node_collection_finished(node=node, ids=ids)
         # tell session which items were effectively collected otherwise
-        # the master node will finish the session with EXIT_NOTESTSCOLLECTED
+        # the controller node will finish the session with EXIT_NOTESTSCOLLECTED
         self._session.testscollected = len(ids)
         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()
 
@@ -256,19 +294,39 @@ class DSession(object):
         """
         self.sched.mark_test_complete(node, item_index, duration)
 
+    def worker_unscheduled(self, node, indices):
+        """
+        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.
+        """
+        self.sched.remove_pending_tests_from_node(node, indices)
+
     def worker_collectreport(self, node, rep):
         """Emitted when a node calls the pytest_collectreport hook.
 
-        Because we only need the report when there's a failure, as optimization
+        Because we only need the report when there's a failure/skip, as optimization
-        we only expect to receive failed reports from workers (#330).
+        we only expect to receive failed/skipped reports from workers (#330).
         """
-        assert rep.failed
+        assert not rep.passed
         self._failed_worker_collectreport(node, rep)
 
-    def worker_logwarning(self, message, code, nodeid, fslocation):
+    def worker_warning_captured(self, warning_message, when, item):
-        """Emitted when a node calls the pytest_logwarning hook."""
+        """Emitted when a node calls the pytest_warning_captured hook (deprecated in 6.0)."""
-        kwargs = dict(message=message, code=code, nodeid=nodeid, fslocation=fslocation)
+        # This hook as been removed in pytest 7.1, and we can remove support once we only
-        self.config.hook.pytest_logwarning.call_historic(kwargs=kwargs)
+        # support pytest >=7.1.
+        kwargs = dict(warning_message=warning_message, when=when, item=item)
+        self.config.hook.pytest_warning_captured.call_historic(kwargs=kwargs)
+
+    def worker_warning_recorded(self, warning_message, when, nodeid, location):
+        """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):
         """Return new node based on an existing one.
@@ -296,10 +354,15 @@ class DSession(object):
     def _handlefailures(self, rep):
         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):
+        if not self.shuttingdown:
             self.log("triggering shutdown")
             self.shuttingdown = True
             for node in self.sched.nodes:
@@ -310,37 +373,65 @@ class DSession(object):
         # 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" % (worker.gateway.id, nodeid)
+        msg = f"worker {worker.gateway.id!r} crashed while running {nodeid!r}"
         rep = runner.TestReport(
             nodeid, (fspath, None, fspath), (), "failed", msg, "???"
         )
         rep.node = worker
+
+        self.config.hook.pytest_handlecrashitem(
+            crashitem=nodeid,
+            report=rep,
+            sched=self.sched,
+        )
         self.config.hook.pytest_runtest_logreport(report=rep)
 
 
-class TerminalDistReporter(object):
+class WorkerStatus(Enum):
-    def __init__(self, config):
+    """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) -> None:
         self.config = config
         self.tr = config.pluginmanager.getplugin("terminalreporter")
-        self._status = {}
+        self._status: dict[str, 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, 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:
-        parts = ["%s %s" % (spec.id, self._status[spec.id]) for spec in self._specs]
+        if self.config.option.verbose >= 0:
-        return " / ".join(parts)
+            line = get_workers_status_line(list(self._status.values()))
+            if line:
+                return line
+
+        return "bringing up nodes..."
 
     def rewrite(self, line, newline=False):
         pline = line + " " * max(self._lastlen - len(line), 0)
@@ -351,40 +442,88 @@ class TerminalDistReporter(object):
             self._lastlen = len(line)
         self.tr.rewrite(pline, bold=True)
 
-    def pytest_xdist_setupnodes(self, specs):
+    @pytest.hookimpl
+    def pytest_xdist_setupnodes(self, specs) -> 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) -> None:
         if self.config.option.verbose > 0:
             rinfo = gateway._rinfo()
+            different_interpreter = rinfo.executable != sys.executable
+            if different_interpreter:
                 version = "%s.%s.%s" % rinfo.version_info[:3]
                 self.rewrite(
-                "[%s] %s Python %s cwd: %s"
+                    f"[{gateway.id}] {rinfo.platform} Python {version} cwd: {rinfo.cwd}",
-                % (gateway.id, rinfo.platform, version, 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) -> None:
         if self.config.option.verbose > 0:
             d = node.workerinfo
-            infoline = "[%s] Python %s" % (d["id"], d["version"].replace("\n", " -- "))
+            different_interpreter = d.get("executable") != sys.executable
-            self.rewrite(infoline, newline=True)
+            if different_interpreter:
-        self.setstatus(node.gateway.spec, "ok")
+                version = d["version"].replace("\n", " -- ")
+                self.rewrite(f"[{d['id']}] Python {version}", newline=True)
+        self.setstatus(
+            node.gateway.spec, WorkerStatus.ReadyForCollection, tests_collected=0
+        )
 
-    def pytest_testnodedown(self, node, error):
+    @pytest.hookimpl
+    def pytest_testnodedown(self, node, error) -> None:
         if not error:
             return
-        self.write_line("[%s] node down: %s" % (node.gateway.id, error))
+        self.write_line(f"[{node.gateway.id}] node down: {error}")
 
-    # def pytest_xdist_rsyncstart(self, source, gateways):
+
-    #    targets = ",".join([gw.id for gw in gateways])
+def get_default_max_worker_restart(config):
-    #    msg = "[%s] rsyncing: %s" %(targets, source)
+    """gets the default value of --max-worker-restart option if it is not provided.
-    #    self.write_line(msg)
+
-    # def pytest_xdist_rsyncfinish(self, source, gateways):
+    Use a reasonable default to avoid workers from restarting endlessly due to crashing collections (#226).
-    #    targets = ", ".join(["[%s]" % gw.id for gw in gateways])
+    """
-    #    self.write_line("rsyncfinish: %s -> %s" %(source, targets))
+    result = config.option.maxworkerrestart
+    if result is not None:
+        result = int(result)
+    elif config.option.numprocesses:
+        # if --max-worker-restart was not provided, use a reasonable default (#226)
+        result = config.option.numprocesses * 4
+    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

@@ -6,14 +6,20 @@
     processes) otherwise changes to source code can crash
     the controlling process which should best never happen.
 """
-from __future__ import print_function
+import os
-import py
+from pathlib import Path
+from typing import Dict, Sequence
+
 import pytest
 import sys
 import time
 import execnet
+from _pytest._io import TerminalWriter
+
+from xdist._path import visit_path
 
 
+@pytest.hookimpl
 def pytest_addoption(parser):
     group = parser.getgroup("xdist", "distributed and subprocess testing")
     group._addoption(
@@ -27,19 +33,22 @@ def pytest_addoption(parser):
     )
 
 
+@pytest.hookimpl
 def pytest_cmdline_main(config):
-
     if config.getoption("looponfail"):
-        usepdb = config.getoption("usepdb")  # a core option
+        usepdb = config.getoption("usepdb", False)  # a core option
         if usepdb:
-            raise pytest.UsageError("--pdb incompatible with --looponfail.")
+            raise pytest.UsageError("--pdb is incompatible with --looponfail.")
         looponfail_main(config)
         return 2  # looponfail only can get stop with ctrl-C anyway
 
 
-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,14 +64,14 @@ def looponfail_main(config):
         print()
 
 
-class RemoteControl(object):
+class RemoteControl:
     def __init__(self, config):
         self.config = config
         self.failures = []
 
     def trace(self, *args):
         if self.config.option.debug:
-            msg = " ".join([str(x) for x in args])
+            msg = " ".join(str(x) for x in args)
             print("RemoteControl:", msg)
 
     def initgateway(self):
@@ -70,7 +79,7 @@ class RemoteControl(object):
 
     def setup(self, out=None):
         if out is None:
-            out = py.io.TerminalWriter()
+            out = TerminalWriter()
         if hasattr(self, "gateway"):
             raise ValueError("already have gateway %r" % self.gateway)
         self.trace("setting up worker session")
@@ -128,7 +137,7 @@ class RemoteControl(object):
 
 
 def repr_pytest_looponfailinfo(failreports, rootdirs):
-    tr = py.io.TerminalWriter()
+    tr = TerminalWriter()
     if failreports:
         tr.sep("#", "LOOPONFAILING", bold=True)
         for report in failreports:
@@ -136,7 +145,7 @@ 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:   %s" % (rootdir,), bold=True)
+        tr.line(f"### Watching:   {rootdir}", bold=True)
 
 
 def init_worker_session(channel, args, option_dict):
@@ -165,7 +174,7 @@ def init_worker_session(channel, args, option_dict):
     WorkerFailSession(config, channel).main()
 
 
-class WorkerFailSession(object):
+class WorkerFailSession:
     def __init__(self, config, channel):
         self.config = config
         self.channel = channel
@@ -179,6 +188,7 @@ class WorkerFailSession(object):
         if self.config.option.debug:
             print(" ".join(map(str, args)))
 
+    @pytest.hookimpl
     def pytest_collection(self, session):
         self.session = session
         self.trails = self.current_command
@@ -193,10 +203,12 @@ class WorkerFailSession(object):
         hook.pytest_collection_finish(session=session)
         return True
 
+    @pytest.hookimpl
     def pytest_runtest_logreport(self, report):
         if report.failed:
             self.recorded_failures.append(report)
 
+    @pytest.hookimpl
     def pytest_collectreport(self, report):
         if report.failed:
             self.recorded_failures.append(report)
@@ -220,17 +232,17 @@ class WorkerFailSession(object):
         self.channel.send((trails, failreports, self.collection_failed))
 
 
-class StatRecorder(object):
+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):
         while 1:
@@ -239,34 +251,34 @@ class StatRecorder(object):
                 return
             time.sleep(checkinterval)
 
-    def check(self, removepycfiles=True):  # noqa, too complex
+    def check(self, removepycfiles: bool = True) -> bool:  # noqa, too complex
         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

@@ -0,0 +1,99 @@
+"""
+xdist hooks.
+
+Additionally, pytest-xdist will also decorate a few other hooks
+with the worker instance that executed the hook originally:
+
+``pytest_runtest_logreport``: ``rep`` parameter has a ``node`` attribute.
+
+You can use this hooks just as you would use normal pytest hooks, but some care
+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
+"""
+import pytest
+
+
+@pytest.hookspec()
+def pytest_xdist_setupnodes(config, specs):
+    """called before any remote node is set up."""
+
+
+@pytest.hookspec()
+def pytest_xdist_newgateway(gateway):
+    """called on new raw gateway creation."""
+
+
+@pytest.hookspec(
+    warn_on_impl=DeprecationWarning(
+        "rsync feature is deprecated and will be removed in pytest-xdist 4.0"
+    )
+)
+def pytest_xdist_rsyncstart(source, gateways):
+    """called before rsyncing a directory to remote gateways takes place."""
+
+
+@pytest.hookspec(
+    warn_on_impl=DeprecationWarning(
+        "rsync feature is deprecated and will be removed in pytest-xdist 4.0"
+    )
+)
+def pytest_xdist_rsyncfinish(source, gateways):
+    """called after rsyncing a directory to remote gateways takes place."""
+
+
+@pytest.hookspec(firstresult=True)
+def pytest_xdist_getremotemodule():
+    """called when creating remote node"""
+
+
+@pytest.hookspec()
+def pytest_configure_node(node):
+    """configure node information before it gets instantiated."""
+
+
+@pytest.hookspec()
+def pytest_testnodeready(node):
+    """Test Node is ready to operate."""
+
+
+@pytest.hookspec()
+def pytest_testnodedown(node, error):
+    """Test Node is down."""
+
+
+@pytest.hookspec()
+def pytest_xdist_node_collection_finished(node, ids):
+    """called by the controller node when a worker node finishes collecting."""
+
+
+@pytest.hookspec(firstresult=True)
+def pytest_xdist_make_scheduler(config, log):
+    """return a node scheduler implementation"""
+
+
+@pytest.hookspec(firstresult=True)
+def pytest_xdist_auto_num_workers(config):
+    """
+    Return the number of workers to spawn when ``--numprocesses=auto`` is given in the
+    command-line.
+
+    .. versionadded:: 2.1
+    """
+
+
+@pytest.hookspec(firstresult=True)
+def pytest_handlecrashitem(crashitem, report, sched):
+    """
+    Handle a crashitem, modifying the report if necessary.
+
+    The scheduler is provided as a parameter to reschedule the test if desired with
+    `sched.mark_test_pending`.
+
+    def pytest_handlecrashitem(crashitem, report, sched):
+        if should_rerun(crashitem):
+            sched.mark_test_pending(crashitem)
+            report.outcome = "rerun"
+
+    .. versionadded:: 2.2.1
+    """

src/xdist/plugin.py

@@ -0,0 +1,344 @@
+import os
+import uuid
+import sys
+import warnings
+
+import pytest
+
+
+PYTEST_GTE_7 = hasattr(pytest, "version_tuple") and pytest.version_tuple >= (7, 0)  # type: ignore[attr-defined]
+
+_sys_path = list(sys.path)  # freeze a copy of sys.path at interpreter startup
+
+
+@pytest.hookimpl
+def pytest_xdist_auto_num_workers(config):
+    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"
+        count = psutil.cpu_count(logical=use_logical) or psutil.cpu_count()
+        if count:
+            return count
+    try:
+        from os import sched_getaffinity
+
+        def cpu_count():
+            return len(sched_getaffinity(0))
+
+    except ImportError:
+        if os.environ.get("TRAVIS") == "true":
+            # workaround https://bitbucket.org/pypy/pypy/issues/2375
+            return 2
+        try:
+            from os import cpu_count
+        except ImportError:
+            from multiprocessing import cpu_count
+    try:
+        n = cpu_count()
+    except NotImplementedError:
+        return 1
+    return n if n else 1
+
+
+def parse_numprocesses(s):
+    if s in ("auto", "logical"):
+        return s
+    elif s is not None:
+        return int(s)
+
+
+@pytest.hookimpl
+def pytest_addoption(parser):
+    group = parser.getgroup("xdist", "distributed and subprocess testing")
+    group._addoption(
+        "-n",
+        "--numprocesses",
+        dest="numprocesses",
+        metavar="numprocesses",
+        action="store",
+        type=parse_numprocesses,
+        help="Shortcut for '--dist=load --tx=NUM*popen'. With 'auto', attempt "
+        "to detect physical CPU count. With 'logical', detect logical CPU "
+        "count. If physical CPU count cannot be found, falls back to logical "
+        "count. This will be 0 when used with --pdb.",
+    )
+    group.addoption(
+        "--maxprocesses",
+        dest="maxprocesses",
+        metavar="maxprocesses",
+        action="store",
+        type=int,
+        help="limit the maximum number of workers to process the tests when using --numprocesses=auto",
+    )
+    group.addoption(
+        "--max-worker-restart",
+        action="store",
+        default=None,
+        dest="maxworkerrestart",
+        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",
+            "loadgroup",
+            "worksteal",
+            "no",
+        ],
+        dest="dist",
+        default="no",
+        help=(
+            "set mode for distributing tests to exec environments.\n\n"
+            "each: send each test to all available environments.\n\n"
+            "load: load balance by sending any pending test to any"
+            " available environment.\n\n"
+            "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"
+            " to any available environment.\n\n"
+            "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 rebalance when any worker runs out of tests.\n\n"
+            "(default) no: run tests inprocess, don't distribute."
+        ),
+    )
+    group.addoption(
+        "--tx",
+        dest="tx",
+        action="append",
+        default=[],
+        metavar="xspec",
+        help=(
+            "add a test execution environment. some examples: "
+            "--tx popen//python=python2.5 --tx socket=192.168.1.102:8888 "
+            "--tx ssh=user@codespeak.net//chdir=testcache"
+        ),
+    )
+    group._addoption(
+        "-d",
+        action="store_true",
+        dest="distload",
+        default=False,
+        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.",
+    )
+    group.addoption(
+        "--rsyncignore",
+        action="append",
+        default=[],
+        metavar="GLOB",
+        help="add expression for ignores when rsyncing to remote tx nodes.",
+    )
+    group.addoption(
+        "--testrunuid",
+        action="store",
+        help=(
+            "provide an identifier shared amongst all workers as the value of "
+            "the 'testrun_uid' fixture,\n\n,"
+            "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. "
+            "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. "
+            "Larger numbers will allow the scheduler to submit consecutive "
+            "chunks of tests to workers - allows reusing fixtures. "
+            "Due to implementation reasons, at least 2 tests are scheduled per "
+            "worker at the start. Only later tests can be scheduled one by one. "
+            "Unlimited if not set."
+        ),
+    )
+
+    parser.addini(
+        "rsyncdirs",
+        "list of (relative) paths to be rsynced for remote distributed testing.",
+        type="paths" if PYTEST_GTE_7 else "pathlist",
+    )
+    parser.addini(
+        "rsyncignore",
+        "list of (relative) glob-style paths to be ignored for rsyncing.",
+        type="paths" if PYTEST_GTE_7 else "pathlist",
+    )
+    parser.addini(
+        "looponfailroots",
+        type="paths" if PYTEST_GTE_7 else "pathlist",
+        help="directories to check for changes. Default: current directory.",
+    )
+
+
+# -------------------------------------------------------------------------
+# distributed testing hooks
+# -------------------------------------------------------------------------
+
+
+@pytest.hookimpl
+def pytest_addhooks(pluginmanager):
+    from xdist import newhooks
+
+    pluginmanager.add_hookspecs(newhooks)
+
+
+# -------------------------------------------------------------------------
+# distributed testing initialization
+# -------------------------------------------------------------------------
+
+
+@pytest.hookimpl(trylast=True)
+def pytest_configure(config):
+    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 config.getoption("dist") != "no" and config.getoption("tx"):
+        from xdist.dsession import DSession
+
+        session = DSession(config)
+        config.pluginmanager.register(session, "dsession")
+        tr = config.pluginmanager.getplugin("terminalreporter")
+        if tr:
+            tr.showfspath = False
+
+    # 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.hookimpl(tryfirst=True)
+def pytest_cmdline_main(config):
+    usepdb = config.getoption("usepdb", False)  # a core option
+    if config.option.numprocesses in ("auto", "logical"):
+        if usepdb:
+            config.option.numprocesses = 0
+            config.option.dist = "no"
+        else:
+            auto_num_cpus = config.hook.pytest_xdist_auto_num_workers(config=config)
+            config.option.numprocesses = auto_num_cpus
+
+    if config.option.numprocesses:
+        if config.option.dist == "no":
+            config.option.dist = "load"
+        numprocesses = config.option.numprocesses
+        if config.option.maxprocesses:
+            numprocesses = min(numprocesses, config.option.maxprocesses)
+        config.option.tx = ["popen"] * numprocesses
+    if config.option.distload:
+        config.option.dist = "load"
+    val = config.getvalue
+    if not val("collectonly") and val("dist") != "no" and usepdb:
+        raise pytest.UsageError(
+            "--pdb is incompatible with distributing tests; try using -n0 or -nauto."
+        )  # noqa: E501
+
+
+# -------------------------------------------------------------------------
+# fixtures and API to easily know the role of current node
+# -------------------------------------------------------------------------
+
+
+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
+    """
+    return hasattr(request_or_session.config, "workerinput")
+
+
+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
+    """
+    return (
+        not is_xdist_worker(request_or_session)
+        and request_or_session.config.option.dist != "no"
+    )
+
+
+# ALIAS: TODO, deprecate (#592)
+is_xdist_master = is_xdist_controller
+
+
+def get_xdist_worker_id(request_or_session):
+    """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
+    """
+    if hasattr(request_or_session.config, "workerinput"):
+        return request_or_session.config.workerinput["workerid"]
+    else:
+        # TODO: remove "master", ideally for a None
+        return "master"
+
+
+@pytest.fixture(scope="session")
+def worker_id(request):
+    """Return the id of the current worker ('gw0', 'gw1', etc) or 'master'
+    if running on the master node.
+    """
+    # TODO: remove "master", ideally for a None
+    return get_xdist_worker_id(request)
+
+
+@pytest.fixture(scope="session")
+def testrun_uid(request):
+    """Return the unique id of the current test."""
+    if hasattr(request.config, "workerinput"):
+        return request.config.workerinput["testrunuid"]
+    else:
+        return uuid.uuid4().hex

src/xdist/remote.py

@@ -0,0 +1,355 @@
+"""
+    This module is executed in remote subprocesses and helps to
+    control a remote testing session and relay back information.
+    It assumes that 'py' is importable and does not have dependencies
+    on the rest of the xdist code.  This means that the xdist-plugin
+    needs not to be installed in remote environments.
+"""
+
+import contextlib
+import sys
+import os
+import time
+from typing import Any
+
+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):
+        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):
+        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):
+    try:
+        setproctitle(title)
+    except Exception:
+        # changing the process name is very optional, no errors please
+        pass
+
+
+class WorkerInteractor:
+    SHUTDOWN_MARK = object()
+    QUEUE_REPLACED_MARK = object()
+
+    def __init__(self, config, channel):
+        self.config = config
+        self.workerid = config.workerinput.get("workerid", "?")
+        self.testrunuid = config.workerinput["testrunuid"]
+        self.log = Producer(f"worker-{self.workerid}", enabled=config.option.debug)
+        self.channel = channel
+        self.torun = self._make_queue()
+        self.nextitem_index = None
+        config.pluginmanager.register(self)
+
+    def _make_queue(self):
+        return self.channel.gateway.execmodel.queue.Queue()
+
+    def _get_next_item_index(self):
+        """Gets the next item from test queue. Handles the case when the queue
+        is replaced concurrently in another thread.
+        """
+        result = self.torun.get()
+        while result is self.QUEUE_REPLACED_MARK:
+            result = self.torun.get()
+        return result
+
+    def sendevent(self, name, **kwargs):
+        self.log("sending", name, kwargs)
+        self.channel.send((name, kwargs))
+
+    @pytest.hookimpl
+    def pytest_internalerror(self, excrepr):
+        formatted_error = str(excrepr)
+        for line in formatted_error.split("\n"):
+            self.log("IERROR>", line)
+        interactor.sendevent("internal_error", formatted_error=formatted_error)
+
+    @pytest.hookimpl
+    def pytest_sessionstart(self, session):
+        self.session = session
+        workerinfo = getinfodict()
+        self.sendevent("workerready", workerinfo=workerinfo)
+
+    @pytest.hookimpl(hookwrapper=True)
+    def pytest_sessionfinish(self, exitstatus):
+        # in pytest 5.0+, exitstatus is an IntEnum object
+        self.config.workeroutput["exitstatus"] = int(exitstatus)
+        yield
+        self.sendevent("workerfinished", workeroutput=self.config.workeroutput)
+
+    @pytest.hookimpl
+    def pytest_collection(self, session):
+        self.sendevent("collectionstart")
+
+    def handle_command(self, command):
+        if command is self.SHUTDOWN_MARK:
+            self.torun.put(self.SHUTDOWN_MARK)
+            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(self.SHUTDOWN_MARK)
+        elif name == "steal":
+            self.steal(kwargs["indices"])
+
+    def steal(self, indices):
+        indices = set(indices)
+        stolen = []
+
+        old_queue, self.torun = self.torun, self._make_queue()
+
+        def old_queue_get_nowait_noraise():
+            with contextlib.suppress(self.channel.gateway.execmodel.queue.Empty):
+                return old_queue.get_nowait()
+
+        for i in iter(old_queue_get_nowait_noraise, None):
+            if i in indices:
+                stolen.append(i)
+            else:
+                self.torun.put(i)
+
+        self.sendevent("unscheduled", indices=stolen)
+        old_queue.put(self.QUEUE_REPLACED_MARK)
+
+    @pytest.hookimpl
+    def pytest_runtestloop(self, session):
+        self.log("entering main loop")
+        self.channel.setcallback(self.handle_command, endmarker=self.SHUTDOWN_MARK)
+        self.nextitem_index = self._get_next_item_index()
+        while self.nextitem_index is not self.SHUTDOWN_MARK:
+            self.run_one_test()
+        return True
+
+    def run_one_test(self):
+        self.item_index = self.nextitem_index
+        self.nextitem_index = self._get_next_item_index()
+
+        items = self.session.items
+        item = items[self.item_index]
+        if self.nextitem_index is self.SHUTDOWN_MARK:
+            nextitem = None
+        else:
+            nextitem = items[self.nextitem_index]
+
+        worker_title("[pytest-xdist running] %s" % item.nodeid)
+
+        start = time.time()
+        self.config.hook.pytest_runtest_protocol(item=item, nextitem=nextitem)
+        duration = time.time() - start
+
+        worker_title("[pytest-xdist idle]")
+
+        self.sendevent(
+            "runtest_protocol_complete", item_index=self.item_index, duration=duration
+        )
+
+    def pytest_collection_modifyitems(self, session, config, items):
+        # add the group name to nodeid as suffix if --dist=loadgroup
+        if config.getvalue("loadgroup"):
+            for item in items:
+                mark = item.get_closest_marker("xdist_group")
+                if not mark:
+                    continue
+                gname = (
+                    mark.args[0]
+                    if len(mark.args) > 0
+                    else mark.kwargs.get("name", "default")
+                )
+                item._nodeid = f"{item.nodeid}@{gname}"
+
+    @pytest.hookimpl
+    def pytest_collection_finish(self, session):
+        try:
+            topdir = str(self.config.rootpath)
+        except AttributeError:  # pytest <= 6.1.0
+            topdir = str(self.config.rootdir)
+
+        self.sendevent(
+            "collectionfinish",
+            topdir=topdir,
+            ids=[item.nodeid for item in session.items],
+        )
+
+    @pytest.hookimpl
+    def pytest_runtest_logstart(self, nodeid, location):
+        self.sendevent("logstart", nodeid=nodeid, location=location)
+
+    @pytest.hookimpl
+    def pytest_runtest_logfinish(self, nodeid, location):
+        self.sendevent("logfinish", nodeid=nodeid, location=location)
+
+    @pytest.hookimpl
+    def pytest_runtest_logreport(self, report):
+        data = self.config.hook.pytest_report_to_serializable(
+            config=self.config, report=report
+        )
+        data["item_index"] = self.item_index
+        data["worker_id"] = self.workerid
+        data["testrun_uid"] = self.testrunuid
+        assert self.session.items[self.item_index].nodeid == report.nodeid
+        self.sendevent("testreport", data=data)
+
+    @pytest.hookimpl
+    def pytest_collectreport(self, report):
+        # send only reports that have not passed to controller as optimization (#330)
+        if not report.passed:
+            data = self.config.hook.pytest_report_to_serializable(
+                config=self.config, report=report
+            )
+            self.sendevent("collectreport", data=data)
+
+    @pytest.hookimpl
+    def pytest_warning_recorded(self, warning_message, when, nodeid, location):
+        self.sendevent(
+            "warning_recorded",
+            warning_message_data=serialize_warning_message(warning_message),
+            when=when,
+            nodeid=nodeid,
+            location=location,
+        )
+
+
+def serialize_warning_message(warning_message):
+    if isinstance(warning_message.message, Warning):
+        message_module = type(warning_message.message).__module__
+        message_class_name = type(warning_message.message).__name__
+        message_str = str(warning_message.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)
+        except DumpError:
+            message_args = None
+        else:
+            message_args = warning_message.message.args
+    else:
+        message_str = warning_message.message
+        message_module = None
+        message_class_name = None
+        message_args = None
+    if warning_message.category:
+        category_module = warning_message.category.__module__
+        category_class_name = warning_message.category.__name__
+    else:
+        category_module = None
+        category_class_name = None
+
+    result = {
+        "message_str": message_str,
+        "message_module": message_module,
+        "message_class_name": message_class_name,
+        "message_args": message_args,
+        "category_module": category_module,
+        "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:
+        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)
+        except DumpError:
+            result[attr_name] = repr(attr)
+        else:
+            result[attr_name] = attr
+    return result
+
+
+def getinfodict():
+    import platform
+
+    return dict(
+        version=sys.version,
+        version_info=tuple(sys.version_info),
+        sysplatform=sys.platform,
+        platform=platform.platform(),
+        executable=sys.executable,
+        cwd=os.getcwd(),
+    )
+
+
+def remote_initconfig(option_dict, args):
+    option_dict["plugins"].append("no:terminal")
+    return Config.fromdictargs(option_dict, args)
+
+
+def setup_config(config, basetemp):
+    config.option.loadgroup = config.getvalue("dist") == "loadgroup"
+    config.option.looponfail = False
+    config.option.usepdb = False
+    config.option.dist = "no"
+    config.option.distload = False
+    config.option.numprocesses = None
+    config.option.maxprocesses = None
+    config.option.basetemp = basetemp
+
+
+if __name__ == "__channelexec__":
+    channel = channel  # type: ignore[name-defined] # noqa: F821
+    workerinput, args, option_dict, change_sys_path = channel.receive()  # type: ignore[name-defined]
+
+    if change_sys_path is None:
+        importpath = os.getcwd()
+        sys.path.insert(0, importpath)
+        os.environ["PYTHONPATH"] = (
+            importpath + os.pathsep + os.environ.get("PYTHONPATH", "")
+        )
+    else:
+        sys.path = change_sys_path
+
+    os.environ["PYTEST_XDIST_TESTRUNUID"] = workerinput["testrunuid"]
+    os.environ["PYTEST_XDIST_WORKER"] = workerinput["workerid"]
+    os.environ["PYTEST_XDIST_WORKER_COUNT"] = str(workerinput["workercount"])
+
+    if hasattr(Config, "InvocationParams"):
+        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  # type: ignore[attr-defined]
+    config.workeroutput = {}  # type: ignore[attr-defined]
+    interactor = WorkerInteractor(config, channel)  # type: ignore[name-defined]
+    config.hook.pytest_cmdline_main(config=config)

src/xdist/report.py

@@ -1,4 +1,3 @@
-from __future__ import print_function
 from difflib import unified_diff
 
 
@@ -13,9 +12,10 @@ def report_collection_diff(from_collection, to_collection, from_id, to_id):
 
     diff = unified_diff(from_collection, to_collection, fromfile=from_id, tofile=to_id)
     error_message = (
-        u"Different tests were collected between {from_id} and {to_id}. "
+        "Different tests were collected between {from_id} and {to_id}. "
-        u"The difference is:\n"
+        "The difference is:\n"
-        u"{diff}"
+        "{diff}\n"
+        "To see why this happens see Known limitations in documentation"
     ).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")])
+    msg = "\n".join(x.rstrip() for x in error_message.split("\n"))
     return msg

src/xdist/scheduler/__init__.py

@@ -0,0 +1,6 @@
+from xdist.scheduler.each import EachScheduling  # noqa
+from xdist.scheduler.load import LoadScheduling  # noqa
+from xdist.scheduler.loadfile import LoadFileScheduling  # noqa
+from xdist.scheduler.loadscope import LoadScopeScheduling  # noqa
+from xdist.scheduler.loadgroup import LoadGroupScheduling  # noqa
+from xdist.scheduler.worksteal import WorkStealingScheduling  # noqa

src/xdist/scheduler/each.py

@@ -1,10 +1,9 @@
-from py.log import Producer
+from xdist.remote import Producer
-
 from xdist.workermanage import parse_spec_config
 from xdist.report import report_collection_diff
 
 
-class EachScheduling(object):
+class EachScheduling:
     """Implement scheduling of test items on all nodes
 
     If a node gets added after the test run is started then it is
@@ -101,6 +100,14 @@ class EachScheduling(object):
     def mark_test_complete(self, node, item_index, duration=0):
         self.node2pending[node].remove(item_index)
 
+    def mark_test_pending(self, item):
+        self.pending.insert(
+            0,
+            self.collection.index(item),
+        )
+        for node in self.node2pending:
+            self.check_schedule(node)
+
     def remove_node(self, node):
         # KeyError if we didn't get an add_node() yet
         pending = self.node2pending.pop(node)
@@ -126,6 +133,7 @@ class EachScheduling(object):
             if not pending:
                 pending[:] = range(len(self.node2collection[node]))
                 node.send_runtest_all()
+                node.shutdown()
             else:
                 node.send_runtest_some(pending)
             self._started.append(node)

src/xdist/scheduler/load.py

@@ -1,13 +1,13 @@
 from itertools import cycle
 
-from py.log import Producer
 from _pytest.runner import CollectReport
 
+from xdist.remote import Producer
 from xdist.workermanage import parse_spec_config
 from xdist.report import report_collection_diff
 
 
-class LoadScheduling(object):
+class LoadScheduling:
     """Implement load scheduling across nodes.
 
     This distributes the tests collected across all nodes so each test
@@ -64,6 +64,7 @@ class LoadScheduling(object):
         else:
             self.log = log.loadsched
         self.config = config
+        self.maxschedchunk = self.config.getoption("maxschedchunk")
 
     @property
     def nodes(self):
@@ -151,6 +152,14 @@ class LoadScheduling(object):
         self.node2pending[node].remove(item_index)
         self.check_schedule(node, duration=duration)
 
+    def mark_test_pending(self, item):
+        self.pending.insert(
+            0,
+            self.collection.index(item),
+        )
+        for node in self.node2pending:
+            self.check_schedule(node)
+
     def check_schedule(self, node, duration=0):
         """Maybe schedule new items on the node
 
@@ -177,7 +186,12 @@ class LoadScheduling(object):
                     # 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):
@@ -234,16 +248,34 @@ class LoadScheduling(object):
         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
-        # distribute tests round-robin up to the batch size
+            # enough tests. The other branch tries sends at least 2 tests
-        # (or until we run out)
+            # to each node - which is suboptimal when you have less than
+            # 2 * len(nodes) tests.
             nodes = cycle(self.nodes)
-        for i in range(initial_batch):
+            for i 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.
+
+            # how many items per node do we have about?
+            items_per_node = len(self.collection) // len(self.node2pending)
+            # take a fraction of tests for initial distribution
+            node_chunksize = min(items_per_node // 4, self.maxschedchunk)
+            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

src/xdist/scheduler/loadfile.py

@@ -1,5 +1,5 @@
-from . import LoadScopeScheduling
+from .loadscope import LoadScopeScheduling
-from py.log import Producer
+from xdist.remote import Producer
 
 
 class LoadFileScheduling(LoadScopeScheduling):
@@ -21,7 +21,7 @@ class LoadFileScheduling(LoadScopeScheduling):
     """
 
     def __init__(self, config, log=None):
-        super(LoadFileScheduling, self).__init__(config, log)
+        super().__init__(config, log)
         if log is None:
             self.log = Producer("loadfilesched")
         else:

src/xdist/scheduler/loadgroup.py

@@ -0,0 +1,54 @@
+from .loadscope import LoadScopeScheduling
+from xdist.remote import Producer
+
+
+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, log=None):
+        super().__init__(config, log)
+        if log is None:
+            self.log = Producer("loadgroupsched")
+        else:
+            self.log = log.loadgroupsched
+
+    def _split_scope(self, nodeid):
+        """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,12 +1,12 @@
 from collections import OrderedDict
 
 from _pytest.runner import CollectReport
-from py.log import Producer
+from xdist.remote import Producer
 from xdist.report import report_collection_diff
 from xdist.workermanage import parse_spec_config
 
 
-class LoadScopeScheduling(object):
+class LoadScopeScheduling:
     """Implement load scheduling across nodes, but grouping test by scope.
 
     This distributes the tests collected across all nodes so each test is run
@@ -187,7 +187,7 @@ class LoadScopeScheduling(object):
             break
         else:
             raise RuntimeError(
-                "Unable to identify crashitem on a workload with " "pending items"
+                "Unable to identify crashitem on a workload with pending items"
             )
 
         # Made uncompleted work unit available again
@@ -213,13 +213,11 @@ class LoadScopeScheduling(object):
 
         # 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(
@@ -243,6 +241,9 @@ class LoadScopeScheduling(object):
         self.assigned_work[node][scope][nodeid] = True
         self._reschedule(node)
 
+    def mark_test_pending(self, item):
+        raise NotImplementedError()
+
     def _assign_work_unit(self, node):
         """Assign a work unit to a node."""
         assert self.workqueue
@@ -306,6 +307,7 @@ class LoadScopeScheduling(object):
 
         # Check that more work is available
         if not self.workqueue:
+            node.shutdown()
             return
 
         self.log("Number of units waiting for node:", len(self.workqueue))
@@ -348,21 +350,28 @@ class LoadScopeScheduling(object):
             return
 
         # Determine chunks of work (scopes)
+        unsorted_workqueue = OrderedDict()
         for nodeid in self.collection:
             scope = self._split_scope(nodeid)
-            work_unit = self.workqueue.setdefault(scope, default=OrderedDict())
+            work_unit = unsorted_workqueue.setdefault(scope, default=OrderedDict())
             work_unit[nodeid] = False
 
+        # 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
+
         # Avoid having more workers than work
         extra_nodes = len(self.nodes) - len(self.workqueue)
 
         if extra_nodes > 0:
-            self.log("Shuting down {0} 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)
 
-                self.log("Shuting down unused node {0}".format(unused_node))
+                self.log(f"Shutting down unused node {unused_node}")
                 unused_node.shutdown()
 
         # Assign initial workload

src/xdist/scheduler/worksteal.py

@@ -0,0 +1,325 @@
+from collections import namedtuple
+
+from _pytest.runner import CollectReport
+
+from xdist.remote import Producer
+from xdist.workermanage import parse_spec_config
+from xdist.report import report_collection_diff
+
+
+NodePending = namedtuple("NodePending", ["node", "pending"])
+
+# 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, log=None):
+        self.numnodes = len(parse_spec_config(config))
+        self.node2collection = {}
+        self.node2pending = {}
+        self.pending = []
+        self.collection = None
+        if log is None:
+            self.log = Producer("workstealsched")
+        else:
+            self.log = log.workstealsched
+        self.config = config
+        self.steal_requested_from_node = None
+
+    @property
+    def nodes(self):
+        """A list of all nodes in the scheduler."""
+        return list(self.node2pending.keys())
+
+    @property
+    def collection_is_completed(self):
+        """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):
+        """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):
+        """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):
+        """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, collection):
+        """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, item_index, duration=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):
+        self.pending.insert(
+            0,
+            self.collection.index(item),
+        )
+        self.check_schedule()
+
+    def remove_pending_tests_from_node(self, node, indices):
+        """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):
+        """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():
+            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
+
+        steal_from.node.send_steal(steal_from.pending[-num_steal:])
+        self.steal_requested_from_node = steal_from.node
+
+    def remove_node(self, node):
+        """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:
+            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):
+        """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 = list(self.node2collection.values())[0]
+        self.pending[:] = range(len(self.collection))
+        if not self.collection:
+            return
+
+        self.check_schedule()
+
+    def _send_tests(self, node, num):
+        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):
+        """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 = CollectReport(
+                        node.gateway.id, "failed", longrepr=msg, result=[]
+                    )
+                    self.config.hook.pytest_collectreport(report=rep)
+
+        return same_collection

src/xdist/workermanage.py

@@ -1,16 +1,17 @@
-from __future__ import print_function
 import fnmatch
 import os
 import re
-import threading
+import sys
+import uuid
+from pathlib import Path
+from typing import List, Union, Sequence, Optional, Any, Tuple, Set
 
-import py
 import pytest
 import execnet
 
 import xdist.remote
-
+from xdist.remote import Producer
-from _pytest import runner  # XXX load dynamically
+from xdist.plugin import _sys_path
 
 
 def parse_spec_config(config):
@@ -30,14 +31,16 @@ def parse_spec_config(config):
     return xspeclist
 
 
-class NodeManager(object):
+class NodeManager:
     EXIT_TIMEOUT = 10
     DEFAULT_IGNORES = [".*", "*.pyc", "*.pyo", "*~"]
 
-    def __init__(self, config, specs=None, defaultchdir="pyexecnetcache"):
+    def __init__(self, config, specs=None, defaultchdir="pyexecnetcache") -> None:
         self.config = config
-        self._nodesready = threading.Event()
         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()
         if specs is None:
             specs = self._getxspecs()
@@ -51,7 +54,7 @@ class NodeManager(object):
             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):
         """Rsync the set of roots to the node's gateway cwd."""
@@ -62,10 +65,7 @@ class NodeManager(object):
     def setup_nodes(self, putevent):
         self.config.hook.pytest_xdist_setupnodes(config=self.config, specs=self.specs)
         self.trace("setting up nodes")
-        nodes = []
+        return [self.setup_node(spec, putevent) for spec in self.specs]
-        for spec in self.specs:
-            nodes.append(self.setup_node(spec, putevent))
-        return nodes
 
     def setup_node(self, spec, putevent):
         gw = self.group.makegateway(spec)
@@ -83,7 +83,7 @@ class NodeManager(object):
     def _getxspecs(self):
         return [execnet.XSpec(x) for x in parse_spec_config(self.config)]
 
-    def _getrsyncdirs(self):
+    def _getrsyncdirs(self) -> List[Path]:
         for spec in self.specs:
             if not spec.popen or spec.chdir:
                 break
@@ -92,19 +92,27 @@ class NodeManager(object):
         import pytest
         import _pytest
 
-        pytestpath = pytest.__file__.rstrip("co")
+        def get_dir(p):
-        pytestdir = py.path.local(_pytest.__file__).dirpath()
+            """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":
+                return os.path.dirname(p)
+            else:
+                return stripped
+
+        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(root).resolve()
-            if not root.check():
+            if not root.exists():
-                raise pytest.UsageError("rsyncdir doesn't exist: %r" % (root,))
+                raise pytest.UsageError(f"rsyncdir doesn't exist: {root!r}")
             if root not in roots:
                 roots.append(root)
         return roots
@@ -112,10 +120,13 @@ class NodeManager(object):
     def _getrsyncoptions(self):
         """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": self.config.option.verbose}
+        return {
+            "ignores": ignores,
+            "verbose": getattr(self.config.option, "verbose", 0),
+        }
 
     def rsync(self, gateway, source, notify=None, verbose=False, ignores=None):
         """Perform rsync to remote hosts for node."""
@@ -149,61 +160,80 @@ class NodeManager(object):
 
 
 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 = {}
-        self._ignores = []
-        ignores = kwargs.pop("ignores", None) or []
-        for x in ignores:
-            x = getattr(x, "strpath", x)
-            self._ignores.append(re.compile(fnmatch.translate(x)))
-        super(HostRSync, self).__init__(sourcedir=sourcedir, **kwargs)
 
-    def filter(self, path):
+    def __init__(
-        path = py.path.local(path)
+        self,
+        sourcedir: PathLike,
+        *,
+        ignores: Optional[Sequence[PathLike]] = None,
+        **kwargs: object
+    ) -> None:
+        if ignores is None:
+            ignores = []
+        self._ignores = [re.compile(fnmatch.translate(os.fspath(x))) for x in ignores]
+        super().__init__(sourcedir=Path(sourcedir), **kwargs)
+
+    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):
         remotepath = os.path.basename(self._sourcedir)
-        super(HostRSync, self).add_target(
+        super().add_target(gateway, remotepath, finishedcallback=finished, delete=True)
-            gateway, remotepath, finishedcallback=finished, delete=True
-        )
 
     def _report_send_file(self, gateway, modified_rel_path):
-        if self._verbose:
+        if self._verbose > 0:
             path = os.path.basename(self._sourcedir) + "/" + modified_rel_path
             remotepath = gateway.spec.chdir
-            print("%s:%s <= %s" % (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])
+        try:
+            exists = fspath.exists()
+        except OSError:
+            exists = False
+        if not exists:
+            result.append(arg)
+            continue
         for root in roots:
-            x = fspath.relto(root)
+            x: Optional[Path]
+            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 %s not relative to an rsync root" % (arg,))
+            raise ValueError(f"arg {arg} not relative to an rsync root")
         result.append(splitcode.join(parts))
     return result
 
 
-class WorkerController(object):
+class WorkerController:
     ENDMARK = -1
 
+    class RemoteHook:
+        @pytest.hookimpl(trylast=True)
+        def pytest_xdist_getremotemodule(self):
+            return xdist.remote
+
     def __init__(self, nodemanager, gateway, config, putevent):
+        config.pluginmanager.register(self.RemoteHook())
         self.nodemanager = nodemanager
         self.putevent = putevent
         self.gateway = gateway
@@ -211,19 +241,15 @@ class WorkerController(object):
         self.workerinput = {
             "workerid": gateway.id,
             "workercount": len(nodemanager.specs),
-            "slaveid": gateway.id,
+            "testrunuid": nodemanager.testrunuid,
-            "slavecount": len(nodemanager.specs),
+            "mainargv": sys.argv,
         }
-        # TODO: deprecated name, backward compatibility only. Remove it in future
-        self.slaveinput = self.workerinput
         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):
-        return "<%s %s>" % (self.__class__.__name__, self.gateway.id)
+        return f"<{self.__class__.__name__} {self.gateway.id}>"
 
     @property
     def shutting_down(self):
@@ -232,18 +258,28 @@ class WorkerController(object):
     def setup(self):
         self.log("setting up worker session")
         spec = self.gateway.spec
+        if hasattr(self.config, "invocation_params"):
+            args = [str(x) for x in self.config.invocation_params.args or ()]
+            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)
-        option_dict = vars(self.config.option)
         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)
-        self.channel = self.gateway.remote_exec(xdist.remote)
+
-        self.channel.send((self.workerinput, args, option_dict))
+        remote_module = self.config.hook.pytest_xdist_getremotemodule()
+        self.channel = self.gateway.remote_exec(remote_module)
+        # change sys.path only for remote workers
+        # restore sys.path from a frozen copy for local workers
+        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:
             self.channel.setcallback(self.process_from_remote, endmarker=self.ENDMARK)
 
@@ -264,25 +300,28 @@ class WorkerController(object):
     def send_runtest_all(self):
         self.sendcommand("runtests_all")
 
+    def send_steal(self, indices):
+        self.sendcommand("steal", indices=indices)
+
     def shutdown(self):
         if not self._down:
             try:
                 self.sendcommand("shutdown")
-            except IOError:
+            except OSError:
                 pass
             self._shutdown_sent = True
 
     def sendcommand(self, name, **kwargs):
-        """ send a named parametrized command to the other side. """
+        """send a named parametrized command to the other side."""
-        self.log("sending command %s(**%s)" % (name, kwargs))
+        self.log(f"sending command {name}(**{kwargs})")
         self.channel.send((name, kwargs))
 
     def notify_inproc(self, eventname, **kwargs):
-        self.log("queuing %s(**%s)" % (eventname, kwargs))
+        self.log(f"queuing {eventname}(**{kwargs})")
         self.putevent((eventname, kwargs))
 
     def process_from_remote(self, eventcall):  # noqa too complex
-        """ this gets called for each object we receive from
+        """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
@@ -300,18 +339,22 @@ class WorkerController(object):
                 return
             eventname, kwargs = eventcall
             if eventname in ("collectionstart",):
-                self.log("ignoring %s(%s)" % (eventname, kwargs))
+                self.log(f"ignoring {eventname}({kwargs})")
             elif eventname == "workerready":
                 self.notify_inproc(eventname, node=self, **kwargs)
+            elif eventname == "internal_error":
+                self.notify_inproc(eventname, node=self, **kwargs)
             elif eventname == "workerfinished":
                 self._down = True
-                self.workeroutput = self.slaveoutput = kwargs["workeroutput"]
+                self.workeroutput = kwargs["workeroutput"]
                 self.notify_inproc("workerfinished", node=self)
             elif eventname in ("logstart", "logfinish"):
                 self.notify_inproc(eventname, node=self, **kwargs)
             elif eventname in ("testreport", "collectreport", "teardownreport"):
                 item_index = kwargs.pop("item_index", None)
-                rep = unserialize_report(eventname, kwargs["data"])
+                rep = self.config.hook.pytest_report_from_serializable(
+                    config=self.config, data=kwargs["data"]
+                )
                 if item_index is not None:
                     rep.item_index = item_index
                 self.notify_inproc(eventname, node=self, rep=rep)
@@ -319,6 +362,8 @@ class WorkerController(object):
                 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,
@@ -327,97 +372,79 @@ class WorkerController(object):
                     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"]
+                )
+                self.notify_inproc(
+                    eventname,
+                    warning_message=warning_message,
+                    when=kwargs["when"],
+                    nodeid=kwargs["nodeid"],
+                    location=kwargs["location"],
+                )
             else:
-                raise ValueError("unknown event: %s" % (eventname,))
+                raise ValueError(f"unknown event: {eventname}")
         except KeyboardInterrupt:
             # should not land in receiver-thread
             raise
         except:  # noqa
             from _pytest._code import ExceptionInfo
 
-            excinfo = ExceptionInfo()
+            excinfo = ExceptionInfo.from_current()
             print("!" * 20, excinfo)
             self.config.notify_exception(excinfo)
             self.shutdown()
             self.notify_inproc("errordown", node=self, error=excinfo)
 
 
-def unserialize_report(name, reportdict):
+def unserialize_warning_message(data):
-    def assembled_report(reportdict):
+    import warnings
-        from _pytest._code.code import (
+    import importlib
-            ReprEntry,
+
-            ReprEntryNative,
+    if data["message_module"]:
-            ReprExceptionInfo,
+        mod = importlib.import_module(data["message_module"])
-            ReprFileLocation,
+        cls = getattr(mod, data["message_class_name"])
-            ReprFuncArgs,
+        message = None
-            ReprLocals,
+        if data["message_args"] is not None:
-            ReprTraceback,
+            try:
+                message = cls(*data["message_args"])
+            except TypeError:
+                pass
+        if message is None:
+            # could not recreate the original warning instance;
+            # create a generic Warning instance with the original
+            # message at least
+            message_text = "{mod}.{cls}: {msg}".format(
+                mod=data["message_module"],
+                cls=data["message_class_name"],
+                msg=data["message_str"],
             )
-
+            message = Warning(message_text)
-        if reportdict["longrepr"]:
-            if (
-                "reprcrash" in reportdict["longrepr"]
-                and "reprtraceback" in reportdict["longrepr"]
-            ):
-
-                reprtraceback = reportdict["longrepr"]["reprtraceback"]
-                reprcrash = reportdict["longrepr"]["reprcrash"]
-
-                unserialized_entries = []
-                reprentry = None
-                for entry_data in reprtraceback["reprentries"]:
-                    data = entry_data["data"]
-                    entry_type = entry_data["type"]
-                    if entry_type == "ReprEntry":
-                        reprfuncargs = None
-                        reprfileloc = None
-                        reprlocals = None
-                        if data["reprfuncargs"]:
-                            reprfuncargs = ReprFuncArgs(**data["reprfuncargs"])
-                        if data["reprfileloc"]:
-                            reprfileloc = ReprFileLocation(**data["reprfileloc"])
-                        if data["reprlocals"]:
-                            reprlocals = ReprLocals(data["reprlocals"]["lines"])
-
-                        reprentry = ReprEntry(
-                            lines=data["lines"],
-                            reprfuncargs=reprfuncargs,
-                            reprlocals=reprlocals,
-                            filelocrepr=reprfileloc,
-                            style=data["style"],
-                        )
-                    elif entry_type == "ReprEntryNative":
-                        reprentry = ReprEntryNative(data["lines"])
     else:
-                        report_unserialization_failure(entry_type, name, reportdict)
+        message = data["message_str"]
-                    unserialized_entries.append(reprentry)
-                reprtraceback["reprentries"] = unserialized_entries
 
-                exception_info = ReprExceptionInfo(
+    if data["category_module"]:
-                    reprtraceback=ReprTraceback(**reprtraceback),
+        mod = importlib.import_module(data["category_module"])
-                    reprcrash=ReprFileLocation(**reprcrash),
+        category = getattr(mod, data["category_class_name"])
-                )
+    else:
+        category = None
 
-                for section in reportdict["longrepr"]["sections"]:
+    kwargs = {"message": message, "category": category}
-                    exception_info.addsection(*section)
+    # access private _WARNING_DETAILS because the attributes vary between Python versions
-                reportdict["longrepr"] = exception_info
+    for attr_name in warnings.WarningMessage._WARNING_DETAILS:  # type: ignore[attr-defined]
-        return reportdict
+        if attr_name in ("message", "category"):
+            continue
+        kwargs[attr_name] = data[attr_name]
 
-    if name == "testreport":
+    return warnings.WarningMessage(**kwargs)  # type: ignore[arg-type]
-        return runner.TestReport(**assembled_report(reportdict))
-    elif name == "collectreport":
-        return runner.CollectReport(**assembled_report(reportdict))
-
-
-def report_unserialization_failure(type_name, report_name, reportdict):
-    from pprint import pprint
-
-    url = "https://github.com/pytest-dev/pytest-xdist/issues"
-    stream = py.io.TextIO()
-    pprint("-" * 100, stream=stream)
-    pprint("INTERNALERROR: Unknown entry type returned: %s" % type_name, stream=stream)
-    pprint("report_name: %s" % report_name, stream=stream)
-    pprint(reportdict, stream=stream)
-    pprint("Please report this bug at %s" % url, stream=stream)
-    pprint("-" * 100, stream=stream)
-    assert 0, stream.getvalue()

testing/conftest.py

@@ -1,37 +1,30 @@
-import py
-import pytest
 import execnet
-
+import pytest
-
+import shutil
-@pytest.fixture(scope="session", autouse=True)
+from typing import List
-def _ensure_imports():
-    # we import some modules because pytest-2.8's testdir fixture
-    # will unload all modules after each test and this cause
-    # (unknown) problems with execnet.Group()
-    execnet.Group
-    execnet.makegateway
-
 
 pytest_plugins = "pytester"
 
-# rsyncdirs = ['.', '../xdist', py.path.local(execnet.__file__).dirpath()]
-
 
 @pytest.fixture(autouse=True)
-def _divert_atexit(request, monkeypatch):
+def _divert_atexit(request, monkeypatch: pytest.MonkeyPatch):
     import atexit
 
     finalizers = []
 
-    def finish():
+    def fake_register(func, *args, **kwargs):
+        finalizers.append((func, args, kwargs))
+
+    monkeypatch.setattr(atexit, "register", fake_register)
+
+    yield
+
     while finalizers:
-            finalizers.pop()()
+        func, args, kwargs = finalizers.pop()
-
+        func(*args, **kwargs)
-    monkeypatch.setattr(atexit, "register", finalizers.append)
-    request.addfinalizer(finish)
 
 
-def pytest_addoption(parser):
+def pytest_addoption(parser) -> None:
     parser.addoption(
         "--gx",
         action="append",
@@ -41,36 +34,28 @@ def pytest_addoption(parser):
 
 
 @pytest.fixture
-def specssh(request):
+def specssh(request) -> str:
     return getspecssh(request.config)
 
 
-@pytest.fixture
-def testdir(testdir):
-    # pytest before 2.8 did not have a runpytest_subprocess
-    if not hasattr(testdir, "runpytest_subprocess"):
-        testdir.runpytest_subprocess = testdir.runpytest
-    return testdir
-
-
 # configuration information for tests
-def getgspecs(config):
+def getgspecs(config) -> List[execnet.XSpec]:
     return [execnet.XSpec(spec) for spec in config.getvalueorskip("gspecs")]
 
 
-def getspecssh(config):
+def getspecssh(config) -> str:  # type: ignore[return]
     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) -> 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,59 +1,54 @@
-from xdist.dsession import DSession
+from __future__ import annotations
+from xdist.dsession import (
+    DSession,
+    get_default_max_worker_restart,
+    get_workers_status_line,
+    WorkerStatus,
+)
 from xdist.report import report_collection_diff
-from xdist.scheduler import EachScheduling, LoadScheduling
+from xdist.scheduler import EachScheduling, LoadScheduling, WorkStealingScheduling
+from typing import Sequence
 
-import py
 import pytest
 import execnet
 
-XSpec = execnet.XSpec
-
-
-def run(item, node, excinfo=None):
-    runner = item.config.pluginmanager.getplugin("runner")
-    rep = runner.ItemTestReport(item=item, excinfo=excinfo, when="call")
-    rep.node = node
-    return rep
-
 
 class MockGateway:
-    _count = 0
+    def __init__(self) -> None:
-
+        self._count = 0
-    def __init__(self):
         self.id = str(self._count)
         self._count += 1
 
 
 class MockNode:
-    def __init__(self):
+    def __init__(self) -> None:
-        self.sent = []
+        self.sent = []  # type: ignore[var-annotated]
+        self.stolen = []  # type: ignore[var-annotated]
         self.gateway = MockGateway()
         self._shutdown = False
 
-    def send_runtest_some(self, indices):
+    def send_runtest_some(self, indices) -> 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) -> 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()
         node2 = MockNode()
-        config = testdir.parseconfig("--tx=2*popen")
+        config = pytester.parseconfig("--tx=2*popen")
         sched = EachScheduling(config)
         sched.add_node(node1)
         sched.add_node(node2)
@@ -74,9 +69,9 @@ 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 = testdir.parseconfig("--tx=popen")
+        config = pytester.parseconfig("--tx=popen")
         sched = EachScheduling(config)
         sched.add_node(node1)
         collection = ["a.py::test_1"]
@@ -93,8 +88,8 @@ 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())
         sched.add_node(MockNode())
@@ -117,8 +112,8 @@ class TestLoadScheduling:
         sched.mark_test_complete(node1, node1.sent[0])
         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())
         sched.add_node(MockNode())
@@ -130,22 +125,72 @@ 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())
+        sched.add_node(MockNode())
+        node1, node2 = 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] + list(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)
+        sched.add_node(MockNode())
+        sched.add_node(MockNode())
+        node1, node2 = 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
+
+        for complete_index, first_pending in enumerate(range(5, 16)):
+            sched.mark_test_complete(node1, node1.sent[complete_index])
+            assert node1.sent == [0, 1] + list(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)
         sched.add_node(MockNode())
         sched.add_node(MockNode())
@@ -154,18 +199,19 @@ class TestLoadScheduling:
         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())
         sched.add_node(MockNode())
@@ -174,19 +220,18 @@ class TestLoadScheduling:
         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 = testdir.parseconfig("--tx=popen")
+        config = pytester.parseconfig("--tx=popen")
         sched = LoadScheduling(config)
         sched.add_node(node)
         collection = ["test_file.py::test_func"]
@@ -197,13 +242,13 @@ 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(object):
+        class CollectHook:
             """
             Dummy hook that stores collection reports.
             """
@@ -215,7 +260,7 @@ class TestLoadScheduling:
                 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()
@@ -230,10 +275,173 @@ class TestLoadScheduling:
         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)
+        sched.add_node(MockNode())
+        sched.add_node(MockNode())
+        node1, node2 = sched.nodes
+        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 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(0, 8))
+        assert node2.sent == list(range(8, 16))
+        for i in range(8):
+            sched.mark_test_complete(node1, node1.sent[i])
+            sched.mark_test_complete(node2, node2.sent[i])
+        assert 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)
+        sched.add_node(MockNode())
+        sched.add_node(MockNode())
+        node1, node2 = sched.nodes
+        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(0, 8))
+        assert node2.sent == list(range(8, 16))
+        for i in range(8):
+            sched.mark_test_complete(node1, node1.sent[i])
+        assert node2.stolen == list(range(12, 16))
+        sched.remove_pending_tests_from_node(node2, node2.stolen)
+        for i in range(4):
+            sched.mark_test_complete(node2, node2.sent[i])
+        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)
+        sched.add_node(MockNode())
+        sched.add_node(MockNode())
+        sched.add_node(MockNode())
+        node1, node2, node3 = sched.nodes
+        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)
+        sched.add_node(MockNode())
+        sched.add_node(MockNode())
+        sched.add_node(MockNode())
+        node1, node2, node3 = sched.nodes
+        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
+        sched.mark_test_complete(node1, node1.sent[0])
+        sched.mark_test_complete(node2, node2.sent[0])
+        sched.mark_test_complete(node3, node3.sent[0])
+        sched.mark_test_complete(node3, node3.sent[1])
+        assert 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):
+                self.reports = []
+
+            def pytest_collectreport(self, report):
+                self.reports.append(report)
+
+        collect_hook = CollectHook()
+        config = pytester.parseconfig("--tx=2*popen")
+        config.pluginmanager.register(collect_hook, "collect_hook")
+        node1 = MockNode()
+        node2 = MockNode()
+        sched = WorkStealingScheduling(config)
+        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 "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) -> None:
-        config = testdir.parseconfig()
+        config = pytester.parseconfig()
         from _pytest.pytest_terminal import TerminalReporter
 
         rep = TerminalReporter(config, file=linecomp.stringio)
@@ -258,17 +466,35 @@ 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
 
 
-def test_report_collection_diff_different():
+def test_default_max_worker_restart() -> None:
+    class config:
+        class option:
+            maxworkerrestart: str | None = None
+            numprocesses: int = 0
+
+    assert get_default_max_worker_restart(config) is None
+
+    config.option.numprocesses = 2
+    assert get_default_max_worker_restart(config) == 8
+
+    config.option.maxworkerrestart = "1"
+    assert get_default_max_worker_restart(config) == 1
+
+    config.option.maxworkerrestart = "0"
+    assert get_default_max_worker_restart(config) == 0
+
+
+def test_report_collection_diff_different() -> None:
     """Test reporting of different collections."""
     from_collection = ["aaa", "bbb", "ccc", "YYY"]
     to_collection = ["aZa", "bbb", "XXX", "ccc"]
@@ -285,7 +511,8 @@ 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"
     )
 
     msg = report_collection_diff(from_collection, to_collection, "1", "2")
@@ -293,8 +520,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
 
@@ -303,6 +530,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,86 +1,108 @@
-import py
+import unittest.mock
+from typing import List
+
+import pytest
+import shutil
+import textwrap
+from pathlib import Path
+
 from xdist.looponfail import RemoteControl
 from xdist.looponfail import StatRecorder
 
 
+PYTEST_GTE_7 = hasattr(pytest, "version_tuple") and pytest.version_tuple >= (7, 0)  # type: ignore[attr-defined]
+
+
 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] = []
+        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]
@@ -90,37 +112,45 @@ 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()
         assert failures
         control.setup()
-        item.fspath.write("def test_func():\n assert 1\n")
+        item_path = item.path if PYTEST_GTE_7 else Path(str(item.fspath))  # type: ignore[attr-defined]
-        removepyc(item.fspath)
+        item_path.write_text("def test_func():\n assert 1\n")
+        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
                 """
             )
+        )
         control = RemoteControl(modcol.config)
         control.loop_once()
         assert control.failures
-        modcol.fspath.write(
+        if PYTEST_GTE_7:
-            py.code.Source(
+            modcol_path = modcol.path  # type:ignore[attr-defined]
+        else:
+            modcol_path = Path(str(modcol.fspath))
+
+        modcol_path.write_text(
+            textwrap.dedent(
                 """
                 def test_func():
                     assert 1
@@ -129,24 +159,31 @@ class TestRemoteControl:
                 """
             )
         )
-        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:
+        modcol = pytester.getitem(
+            textwrap.dedent(
                 """
                 def test_func():
                     assert 0
                 """
             )
-        parent = modcol.fspath.dirpath().dirpath()
+        )
-        parent.chdir()
+        if PYTEST_GTE_7:
+            parent = modcol.path.parent.parent  # type: ignore[attr-defined]
+        else:
+            parent = Path(modcol.fspath.dirpath().dirpath())
+        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()
@@ -156,8 +193,9 @@ class TestRemoteControl:
 
 
 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
@@ -166,12 +204,14 @@ class TestLooponFailing:
                     assert 1
                 """
             )
+        )
         remotecontrol = RemoteControl(modcol.config)
         remotecontrol.loop_once()
         assert len(remotecontrol.failures) == 1
 
-        modcol.fspath.write(
+        modcol_path = modcol.path if PYTEST_GTE_7 else Path(modcol.fspath)
-            py.code.Source(
+        modcol_path.write_text(
+            textwrap.dedent(
                 """
                 def test_one():
                     assert 1
@@ -180,24 +220,27 @@ class TestLooponFailing:
                 """
             )
         )
-        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
                 """
             )
+        )
         remotecontrol = RemoteControl(modcol.config)
         remotecontrol.loop_once()
         assert len(remotecontrol.failures) == 1
         assert "test_one" in remotecontrol.failures[0]
 
-        modcol.fspath.write(
+        modcol_path = modcol.path if PYTEST_GTE_7 else Path(modcol.fspath)
-            py.code.Source(
+        modcol_path.write_text(
+            textwrap.dedent(
                 """
                 def test_one():
                     assert 1 # passes now
@@ -206,7 +249,7 @@ class TestLooponFailing:
                 """
             )
         )
-        removepyc(modcol.fspath)
+        removepyc(modcol_path)
         remotecontrol.loop_once()
         assert len(remotecontrol.failures) == 0
         remotecontrol.loop_once()
@@ -214,9 +257,10 @@ class TestLooponFailing:
         assert "test_one" not in remotecontrol.failures[0]
         assert "test_two" in remotecontrol.failures[0]
 
-    @py.test.mark.xfail(py.test.__version__ >= "3.1", reason="broken by pytest 3.1+")
+    @pytest.mark.xfail(reason="broken by pytest 3.1+", strict=True)
-    def test_looponfail_removed_test(self, testdir):
+    def test_looponfail_removed_test(self, pytester: pytest.Pytester) -> None:
-        modcol = testdir.getmodulecol(
+        modcol = pytester.getmodulecol(
+            textwrap.dedent(
                 """
                 def test_one():
                     assert 0
@@ -224,12 +268,13 @@ class TestLooponFailing:
                     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
@@ -238,20 +283,24 @@ class TestLooponFailing:
                 """
             )
         )
-        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:
+        modcol = pytester.getmodulecol(
+            textwrap.dedent(
                 """
                 def test_one():
                     assert 0
                 """
             )
+        )
         remotecontrol = RemoteControl(modcol.config)
         orig_runsession = remotecontrol.runsession
 
@@ -267,55 +316,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
                     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)
+        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():
                     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
+                import pytest
-            @py.test.mark.xfail
+                @pytest.mark.xfail
                 def test_one():
                     pass
                 """
             )
-        child = testdir.spawn_pytest("-f %s" % p)
+        )
+        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,38 +13,41 @@ 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
-        with xdist contain "node", "nodeid" and "worker_id" attributes. (#8)
+        with xdist contain "node", "nodeid", "worker_id", and "testrun_uid" attributes. (#8)
         """
-        testdir.makeconftest(
+        pytester.makeconftest(
             """
             def pytest_runtest_logreport(report):
                 if hasattr(report, 'node'):
                     if report.when == "call":
                         workerid = report.node.workerinput['workerid']
+                        testrunuid = report.node.workerinput['testrunuid']
                         if workerid != report.worker_id:
                             print("HOOK: Worker id mismatch: %s %s"
                                    % (workerid, report.worker_id))
+                        elif testrunuid != report.testrun_uid:
+                            print("HOOK: Testrun uid mismatch: %s %s"
+                                   % (testrunuid, report.testrun_uid))
                         else:
-                            print("HOOK: %s %s"
+                            print("HOOK: %s %s %s"
-                                   % (report.nodeid, report.worker_id))
+                                   % (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*",
+                "*HOOK: test_runtest_logreport.py::test_a gw0 *",
-                "*HOOK: test_runtest_logreport.py::test_b gw0*",
+                "*HOOK: test_runtest_logreport.py::test_b gw0 *",
-                "*HOOK: test_runtest_logreport.py::test_c gw0*",
+                "*HOOK: test_runtest_logreport.py::test_c gw0 *",
                 "*3 passed*",
             ]
         )
 
-    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).
+        """Test pytest_xdist_node_collection_finished hook (#8)."""
-        """
+        pytester.makeconftest(
-        testdir.makeconftest(
             """
             def pytest_xdist_node_collection_finished(node, ids):
                 workerid = node.workerinput['workerid']
@@ -52,8 +55,67 @@ 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"]
         )
         res.stdout.fnmatch_lines(["*3 passed*"])
+
+
+class TestCrashItem:
+    @pytest.fixture(autouse=True)
+    def create_test_file(self, pytester: pytest.Pytester) -> None:
+        pytester.makepyfile(
+            """
+            import os
+            def test_a(): pass
+            def test_b(): os._exit(1)
+            def test_c(): pass
+            def test_d(): pass
+        """
+        )
+
+    def test_handlecrashitem(self, pytester: pytest.Pytester) -> None:
+        """Test pytest_handlecrashitem hook."""
+        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("-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,37 +1,65 @@
-import py
+from contextlib import suppress
+from pathlib import Path
+import sys
+import os
+
 import execnet
 from xdist.workermanage import NodeManager
 
+import pytest
 
-def test_dist_incompatibility_messages(testdir):
+
-    result = testdir.runpytest("--pdb", "--looponfail")
+@pytest.fixture
+def monkeypatch_3_cpus(monkeypatch: pytest.MonkeyPatch):
+    """Make pytest-xdist believe the system has 3 CPUs"""
+    # block import
+    monkeypatch.setitem(sys.modules, "psutil", None)  # type: ignore
+    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("-d")
+    config = pytester.parseconfigure("--numprocesses", "3", "--maxprocesses", "2")
+    check_options(config)
+    assert config.option.dist == "load"
+    assert config.option.tx == ["popen"] * 2
+    config = pytester.parseconfigure("-d")
     check_options(config)
     assert config.option.dist == "load"
 
 
-def test_auto_detect_cpus(testdir, monkeypatch):
+def test_auto_detect_cpus(
-    import os
+    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
+
+        monkeypatch.setattr(psutil, "cpu_count", lambda logical=True: None)
 
     if hasattr(os, "sched_getaffinity"):
         monkeypatch.setattr(os, "sched_getaffinity", lambda _pid: set(range(99)))
@@ -42,52 +70,218 @@ 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 = pytester.parseconfigure("-nauto", "--pdb")
+    check_options(config)
+    assert config.getoption("usepdb")
+    assert config.getoption("numprocesses") == 0
+    assert config.getoption("dist") == "no"
+
+    config = pytester.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_boxed_with_collect_only(testdir):
+def test_auto_detect_cpus_psutil(
+    pytester: pytest.Pytester, monkeypatch: pytest.MonkeyPatch
+) -> None:
     from xdist.plugin import pytest_cmdline_main as check_options
 
-    config = testdir.parseconfigure("-n1", "--boxed")
+    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 = 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") == 84
 
-    config = testdir.parseconfigure("-n1", "--boxed", "--collect-only")
+
+def test_auto_detect_cpus_os(
+    pytester: pytest.Pytester, monkeypatch: pytest.MonkeyPatch, monkeypatch_3_cpus
+) -> None:
+    from xdist.plugin import pytest_cmdline_main as check_options
+
+    monkeypatch.delenv("PYTEST_XDIST_AUTO_NUM_WORKERS", raising=False)
+
+    config = pytester.parseconfigure("-nauto")
     check_options(config)
-    assert config.option.forked
+    assert config.getoption("numprocesses") == 3
+
+    config = pytester.parseconfigure("-nlogical")
+    check_options(config)
+    assert config.getoption("numprocesses") == 3
 
 
-def test_dsession_with_collect_only(testdir):
+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 = pytester.parseconfigure("-nauto")
+    check_options(config)
+    assert config.getoption("numprocesses") == 42
+
+    config = pytester.parseconfigure("-nlogical")
+    check_options(config)
+    assert config.getoption("numprocesses") == 42
+
+
+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
+
+    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.getoption("numprocesses") == 42
+
+    config = pytester.parseconfigure("-nlogical")
+    check_options(config)
+    assert config.getoption("numprocesses") == 8
+
+
+def test_hook_auto_num_workers_none(
+    pytester: pytest.Pytester, monkeypatch: pytest.MonkeyPatch, monkeypatch_3_cpus
+) -> 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.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_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:
+    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:
+    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(pytester: pytest.Pytester) -> None:
+    config = pytester.parseconfigure("--testrunuid", "test123", "--tx=popen")
+    nm = NodeManager(config)
+    assert nm.testrunuid == "test123"
+
+
+def test_testrunuid_generated(pytester: pytest.Pytester) -> None:
+    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()
         assert len(xspecs) == 2
@@ -95,39 +289,39 @@ class TestDistOptions:
         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()
         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,12 +1,13 @@
-import py
 import pprint
 import pytest
-from xdist.workermanage import WorkerController, unserialize_report
+import sys
-from xdist.remote import serialize_report
+import uuid
+
+from xdist.workermanage import WorkerController
 import execnet
 import marshal
 
-from six.moves.queue import Queue
+from queue import Queue
 
 WAIT_TIMEOUT = 10.0
 
@@ -24,25 +25,25 @@ class EventCall:
         self.name, self.kwargs = eventcall
 
     def __str__(self):
-        return "<EventCall %s(**%s)>" % (self.name, self.kwargs)
+        return f"<EventCall {self.name}(**{self.kwargs})>"
 
 
 class WorkerSetup:
-    use_callback = False
+    def __init__(self, request, pytester: pytest.Pytester) -> None:
-
-    def __init__(self, request, testdir):
         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(self,):
+    def setup(self) -> None:
-        self.testdir.chdir()
+        self.pytester.chdir()
         # import os ; os.environ['EXECNET_DEBUG'] = "2"
         self.gateway = execnet.makegateway()
-        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)
@@ -58,210 +59,41 @@ class WorkerSetup:
             ev = EventCall(data)
             if name is None or ev.name == name:
                 return ev
-            print("skipping %s" % (ev,))
+            print(f"skipping {ev}")
 
     def sendcommand(self, name, **kwargs):
         self.slp.sendcommand(name, **kwargs)
 
 
 @pytest.fixture
-def worker(request, testdir):
+def worker(request, pytester: pytest.Pytester) -> WorkerSetup:
-    return WorkerSetup(request, testdir)
+    return WorkerSetup(request, pytester)
 
 
 @pytest.mark.xfail(reason="#59")
-def test_remoteinitconfig(testdir):
+def test_remoteinitconfig(pytester: pytest.Pytester) -> None:
     from xdist.remote import remote_initconfig
 
-    config1 = testdir.parseconfig()
+    config1 = pytester.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 TestReportSerialization:
-    def test_xdist_longrepr_to_str_issue_241(self, testdir):
-        testdir.makepyfile(
-            """
-            import os
-            def test_a(): assert False
-            def test_b(): pass
-        """
-        )
-        testdir.makeconftest(
-            """
-            def pytest_runtest_logreport(report):
-                print(report.longrepr)
-        """
-        )
-        res = testdir.runpytest("-n1", "-s")
-        res.stdout.fnmatch_lines(["*1 failed, 1 passed *"])
-
-    def test_xdist_report_longrepr_reprcrash_130(self, testdir):
-        reprec = testdir.inline_runsource(
-            """
-                    import py
-                    def test_fail(): assert False, 'Expected Message'
-                """
-        )
-        reports = reprec.getreports("pytest_runtest_logreport")
-        assert len(reports) == 3
-        rep = reports[1]
-        added_section = ("Failure Metadata", str("metadata metadata"), "*")
-        rep.longrepr.sections.append(added_section)
-        d = serialize_report(rep)
-        check_marshallable(d)
-        a = unserialize_report("testreport", d)
-        # Check assembled == rep
-        assert a.__dict__.keys() == rep.__dict__.keys()
-        for key in rep.__dict__.keys():
-            if key != "longrepr":
-                assert getattr(a, key) == getattr(rep, key)
-        assert rep.longrepr.reprcrash.lineno == a.longrepr.reprcrash.lineno
-        assert rep.longrepr.reprcrash.message == a.longrepr.reprcrash.message
-        assert rep.longrepr.reprcrash.path == a.longrepr.reprcrash.path
-        assert rep.longrepr.reprtraceback.entrysep == a.longrepr.reprtraceback.entrysep
-        assert (
-            rep.longrepr.reprtraceback.extraline == a.longrepr.reprtraceback.extraline
-        )
-        assert rep.longrepr.reprtraceback.style == a.longrepr.reprtraceback.style
-        assert rep.longrepr.sections == a.longrepr.sections
-        # Missing section attribute PR171
-        assert added_section in a.longrepr.sections
-
-    def test_reprentries_serialization_170(self, testdir):
-        from _pytest._code.code import ReprEntry
-
-        reprec = testdir.inline_runsource(
-            """
-                            def test_repr_entry():
-                                x = 0
-                                assert x
-                        """,
-            "--showlocals",
-        )
-        reports = reprec.getreports("pytest_runtest_logreport")
-        assert len(reports) == 3
-        rep = reports[1]
-        d = serialize_report(rep)
-        a = unserialize_report("testreport", d)
-
-        rep_entries = rep.longrepr.reprtraceback.reprentries
-        a_entries = a.longrepr.reprtraceback.reprentries
-        for i in range(len(a_entries)):
-            assert isinstance(rep_entries[i], ReprEntry)
-            assert rep_entries[i].lines == a_entries[i].lines
-            assert rep_entries[i].localssep == a_entries[i].localssep
-            assert rep_entries[i].reprfileloc.lineno == a_entries[i].reprfileloc.lineno
-            assert (
-                rep_entries[i].reprfileloc.message == a_entries[i].reprfileloc.message
-            )
-            assert rep_entries[i].reprfileloc.path == a_entries[i].reprfileloc.path
-            assert rep_entries[i].reprfuncargs.args == a_entries[i].reprfuncargs.args
-            assert rep_entries[i].reprlocals.lines == a_entries[i].reprlocals.lines
-            assert rep_entries[i].style == a_entries[i].style
-
-    def test_reprentries_serialization_196(self, testdir):
-        from _pytest._code.code import ReprEntryNative
-
-        reprec = testdir.inline_runsource(
-            """
-                            def test_repr_entry_native():
-                                x = 0
-                                assert x
-                        """,
-            "--tb=native",
-        )
-        reports = reprec.getreports("pytest_runtest_logreport")
-        assert len(reports) == 3
-        rep = reports[1]
-        d = serialize_report(rep)
-        a = unserialize_report("testreport", d)
-
-        rep_entries = rep.longrepr.reprtraceback.reprentries
-        a_entries = a.longrepr.reprtraceback.reprentries
-        for i in range(len(a_entries)):
-            assert isinstance(rep_entries[i], ReprEntryNative)
-            assert rep_entries[i].lines == a_entries[i].lines
-
-    def test_itemreport_outcomes(self, testdir):
-        reprec = testdir.inline_runsource(
-            """
-            import py
-            def test_pass(): pass
-            def test_fail(): 0/0
-            @py.test.mark.skipif("True")
-            def test_skip(): pass
-            def test_skip_imperative():
-                py.test.skip("hello")
-            @py.test.mark.xfail("True")
-            def test_xfail(): 0/0
-            def test_xfail_imperative():
-                py.test.xfail("hello")
-        """
-        )
-        reports = reprec.getreports("pytest_runtest_logreport")
-        assert len(reports) == 17  # with setup/teardown "passed" reports
-        for rep in reports:
-            d = serialize_report(rep)
-            check_marshallable(d)
-            newrep = unserialize_report("testreport", d)
-            assert newrep.passed == rep.passed
-            assert newrep.failed == rep.failed
-            assert newrep.skipped == rep.skipped
-            if newrep.skipped and not hasattr(newrep, "wasxfail"):
-                assert len(newrep.longrepr) == 3
-            assert newrep.outcome == rep.outcome
-            assert newrep.when == rep.when
-            assert newrep.keywords == rep.keywords
-            if rep.failed:
-                assert newrep.longreprtext == rep.longreprtext
-
-    def test_collectreport_passed(self, testdir):
-        reprec = testdir.inline_runsource("def test_func(): pass")
-        reports = reprec.getreports("pytest_collectreport")
-        for rep in reports:
-            d = serialize_report(rep)
-            check_marshallable(d)
-            newrep = unserialize_report("collectreport", d)
-            assert newrep.passed == rep.passed
-            assert newrep.failed == rep.failed
-            assert newrep.skipped == rep.skipped
-
-    def test_collectreport_fail(self, testdir):
-        reprec = testdir.inline_runsource("qwe abc")
-        reports = reprec.getreports("pytest_collectreport")
-        assert reports
-        for rep in reports:
-            d = serialize_report(rep)
-            check_marshallable(d)
-            newrep = unserialize_report("collectreport", d)
-            assert newrep.passed == rep.passed
-            assert newrep.failed == rep.failed
-            assert newrep.skipped == rep.skipped
-            if rep.failed:
-                assert newrep.longrepr == str(rep.longrepr)
-
-    def test_extended_report_deserialization(self, testdir):
-        reprec = testdir.inline_runsource("qwe abc")
-        reports = reprec.getreports("pytest_collectreport")
-        assert reports
-        for rep in reports:
-            rep.extra = True
-            d = serialize_report(rep)
-            check_marshallable(d)
-            newrep = unserialize_report("collectreport", d)
-            assert newrep.extra
-            assert newrep.passed == rep.passed
-            assert newrep.failed == rep.failed
-            assert newrep.skipped == rep.skipped
-            if rep.failed:
-                assert newrep.longrepr == str(rep.longrepr)
-
-
 class TestWorkerInteractor:
-    def test_basic_collect_and_runtests(self, worker):
+    @pytest.fixture
-        worker.testdir.makepyfile(
+    def unserialize_report(self, pytestconfig):
+        def unserialize(data):
+            return pytestconfig.hook.pytest_report_from_serializable(
+                config=pytestconfig, data=data
+            )
+
+        return unserialize
+
+    def test_basic_collect_and_runtests(
+        self, worker: WorkerSetup, unserialize_report
+    ) -> None:
+        worker.pytester.makepyfile(
             """
             def test_func():
                 pass
@@ -274,7 +106,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))))
@@ -285,21 +117,18 @@ class TestWorkerInteractor:
         ev = worker.popevent("testreport")  # setup
         ev = worker.popevent("testreport")
         assert ev.name == "testreport"
-        rep = unserialize_report(ev.name, ev.kwargs["data"])
+        rep = unserialize_report(ev.kwargs["data"])
         assert rep.nodeid.endswith("::test_func")
         assert rep.passed
         assert rep.when == "call"
         ev = worker.popevent("workerfinished")
         assert "workeroutput" in ev.kwargs
 
-    @pytest.mark.skipif(
+    def test_remote_collect_skip(self, worker: WorkerSetup, unserialize_report) -> None:
-        pytest.__version__ >= "3.0", reason="skip at module level illegal in pytest 3.0"
+        worker.pytester.makepyfile(
-    )
-    def test_remote_collect_skip(self, worker):
-        worker.testdir.makepyfile(
             """
-            import py
+            import pytest
-            py.test.skip("hello")
+            pytest.skip("hello", allow_module_level=True)
         """
         )
         worker.setup()
@@ -307,27 +136,26 @@ class TestWorkerInteractor:
         assert not ev.kwargs
         ev = worker.popevent()
         assert ev.name == "collectreport"
-        ev = worker.popevent()
+        rep = unserialize_report(ev.kwargs["data"])
-        assert ev.name == "collectreport"
-        rep = unserialize_report(ev.name, ev.kwargs["data"])
         assert rep.skipped
+        assert rep.longrepr[2] == "Skipped: hello"
         ev = worker.popevent("collectionfinish")
         assert not ev.kwargs["ids"]
 
-    def test_remote_collect_fail(self, worker):
+    def test_remote_collect_fail(self, worker: WorkerSetup, unserialize_report) -> None:
-        worker.testdir.makepyfile("""aasd qwe""")
+        worker.pytester.makepyfile("""aasd qwe""")
         worker.setup()
         ev = worker.popevent("collectionstart")
         assert not ev.kwargs
         ev = worker.popevent()
         assert ev.name == "collectreport"
-        rep = unserialize_report(ev.name, ev.kwargs["data"])
+        rep = unserialize_report(ev.kwargs["data"])
         assert rep.failed
         ev = worker.popevent("collectionfinish")
         assert not ev.kwargs["ids"]
 
-    def test_runtests_all(self, worker):
+    def test_runtests_all(self, worker: WorkerSetup, unserialize_report) -> None:
-        worker.testdir.makepyfile(
+        worker.pytester.makepyfile(
             """
             def test_func(): pass
             def test_func2(): pass
@@ -348,22 +176,24 @@ class TestWorkerInteractor:
             for i in range(3):  # setup/call/teardown
                 ev = worker.popevent("testreport")
                 assert ev.name == "testreport"
-                rep = unserialize_report(ev.name, ev.kwargs["data"])
+                rep = unserialize_report(ev.kwargs["data"])
                 assert rep.nodeid.endswith(func)
         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)
@@ -379,7 +209,9 @@ 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>", ()))
@@ -388,15 +220,176 @@ class TestWorkerInteractor:
         ev = worker.popevent()
         assert ev.name == "errordown"
 
+    def test_steal_work(self, worker: WorkerSetup, unserialize_report) -> 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")
+        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) -> 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():
+            assert len(os.environ['PYTEST_XDIST_TESTRUNUID']) == 32
             assert os.environ['PYTEST_XDIST_WORKER'] in ('gw0', 'gw1')
             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(pytester: pytest.Pytester) -> None:
+    """Test/document the behavior due to execnet using `python -c`."""
+    pytester.makepyfile(
+        """
+        import sys
+
+        def test_argv():
+            assert sys.argv == ["-c"]
+        """
+    )
+    result = pytester.runpytest("-n1")
+    assert result.ret == 0
+
+
+def test_remote_mainargv(pytester: pytest.Pytester) -> None:
+    outer_argv = sys.argv
+
+    pytester.makepyfile(
+        """
+        def test_mainargv(request):
+            assert request.config.workerinput["mainargv"] == {!r}
+        """.format(
+            outer_argv
+        )
+    )
+    result = pytester.runpytest("-n1")
+    assert result.ret == 0
+
+
+def test_remote_usage_prog(pytester: pytest.Pytester, request) -> None:
+    if not hasattr(request.config._parser, "prog"):
+        pytest.skip("prog not available in config parser")
+    pytester.makeconftest(
+        """
+        import pytest
+
+        config_parser = None
+
+        @pytest.fixture
+        def get_config_parser():
+            return config_parser
+
+        def pytest_configure(config):
+            global config_parser
+            config_parser = config._parser
+    """
+    )
+    pytester.makepyfile(
+        """
+        import sys
+
+        def test(get_config_parser, request):
+            get_config_parser._getparser().error("my_usage_error")
+    """
+    )
+
+    result = pytester.runpytest_subprocess("-n1")
+    assert result.ret == 1
+    result.stdout.fnmatch_lines(["*usage: *", "*error: my_usage_error"])
+
+
+def test_remote_sys_path(pytester: pytest.Pytester) -> None:
+    """Work around sys.path differences due to execnet using `python -c`."""
+    pytester.makepyfile(
+        """
+        import sys
+
+        def test_sys_path():
+            assert "" not in sys.path
+        """
+    )
+    result = pytester.runpytest("-n1")
     assert result.ret == 0

testing/test_slavemanage.py

@@ -1,273 +0,0 @@
-from __future__ import print_function
-import py
-import pytest
-import textwrap
-import execnet
-from _pytest.pytester import HookRecorder
-from xdist import workermanage, newhooks
-from xdist.workermanage import HostRSync, NodeManager
-
-pytest_plugins = "pytester"
-
-
-@pytest.fixture
-def hookrecorder(request, config):
-    hookrecorder = HookRecorder(config.pluginmanager)
-    if hasattr(hookrecorder, "start_recording"):
-        hookrecorder.start_recording(newhooks)
-    request.addfinalizer(hookrecorder.finish_recording)
-    return hookrecorder
-
-
-@pytest.fixture
-def config(testdir):
-    return testdir.parseconfig()
-
-
-@pytest.fixture
-def mysetup(tmpdir):
-    class mysetup:
-        source = tmpdir.mkdir("source")
-        dest = tmpdir.mkdir("dest")
-
-    return mysetup()
-
-
-@pytest.fixture
-def workercontroller(monkeypatch):
-    class MockController(object):
-        def __init__(self, *args):
-            pass
-
-        def setup(self):
-            pass
-
-    monkeypatch.setattr(workermanage, "WorkerController", MockController)
-    return MockController
-
-
-class TestNodeManagerPopen:
-    def test_popen_no_default_chdir(self, config):
-        gm = NodeManager(config, ["popen"])
-        assert gm.specs[0].chdir is None
-
-    def test_default_chdir(self, config):
-        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):
-        hm = NodeManager(config, ["popen"] * 2)
-        hm.setup_nodes(None)
-        call = hookrecorder.popcall("pytest_xdist_setupnodes")
-        assert len(call.specs) == 2
-
-        call = hookrecorder.popcall("pytest_xdist_newgateway")
-        assert call.gateway.spec == execnet.XSpec("popen")
-        assert call.gateway.id == "gw0"
-        call = hookrecorder.popcall("pytest_xdist_newgateway")
-        assert call.gateway.id == "gw1"
-        assert len(hm.group) == 2
-        hm.teardown_nodes()
-        assert not len(hm.group)
-
-    def test_popens_rsync(self, config, mysetup, workercontroller):
-        source = mysetup.source
-        hm = NodeManager(config, ["popen"] * 2)
-        hm.setup_nodes(None)
-        assert len(hm.group) == 2
-        for gw in hm.group:
-
-            class pseudoexec:
-                args = []
-
-                def __init__(self, *args):
-                    self.args.extend(args)
-
-                def waitclose(self):
-                    pass
-
-            gw.remote_exec = pseudoexec
-        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]
-
-    def test_rsync_popen_with_path(self, config, mysetup, workercontroller):
-        source, dest = mysetup.source, mysetup.dest
-        hm = NodeManager(config, ["popen//chdir=%s" % dest] * 1)
-        hm.setup_nodes(None)
-        source.ensure("dir1", "dir2", "hello")
-        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)
-        assert dest.join("dir1").check()
-        assert dest.join("dir1", "dir2").check()
-        assert dest.join("dir1", "dir2", "hello").check()
-
-    def test_rsync_same_popen_twice(
-        self, config, mysetup, hookrecorder, workercontroller
-    ):
-        source, dest = mysetup.source, mysetup.dest
-        hm = NodeManager(config, ["popen//chdir=%s" % dest] * 2)
-        hm.roots = []
-        hm.setup_nodes(None)
-        source.ensure("dir1", "dir2", "hello")
-        gw = hm.group[0]
-        hm.rsync(gw, source)
-        call = hookrecorder.popcall("pytest_xdist_rsyncstart")
-        assert call.source == source
-        assert len(call.gateways) == 1
-        assert call.gateways[0] in hm.group
-        call = hookrecorder.popcall("pytest_xdist_rsyncfinish")
-
-
-class TestHRSync:
-    def test_hrsync_filter(self, mysetup):
-        source, _ = mysetup.source, mysetup.dest  # noqa
-        source.ensure("dir", "file.txt")
-        source.ensure(".svn", "entries")
-        source.ensure(".somedotfile", "moreentries")
-        source.ensure("somedir", "editfile~")
-        syncer = HostRSync(source, ignores=NodeManager.DEFAULT_IGNORES)
-        files = list(source.visit(rec=syncer.filter, fil=syncer.filter))
-        assert len(files) == 3
-        basenames = [x.basename for x in files]
-        assert "dir" in basenames
-        assert "file.txt" in basenames
-        assert "somedir" in basenames
-
-    def test_hrsync_one_host(self, mysetup):
-        source, dest = mysetup.source, mysetup.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")
-        rsync.send()
-        gw.exit()
-        assert dest.join(source.basename, "hello.py").check()
-        assert len(finished) == 1
-
-
-class TestNodeManager:
-    @py.test.mark.xfail(run=False)
-    def test_rsync_roots_no_roots(self, testdir, mysetup):
-        mysetup.source.ensure("dir1", "file1").write("hello")
-        config = testdir.parseconfig(mysetup.source)
-        nodemanager = NodeManager(config, ["popen//chdir=%s" % mysetup.dest])
-        # assert nodemanager.config.topdir == source == config.topdir
-        nodemanager.makegateways()
-        nodemanager.rsync_roots()
-        p, = nodemanager.gwmanager.multi_exec(
-            "import os ; channel.send(os.getcwd())"
-        ).receive_each()
-        p = py.path.local(p)
-        print("remote curdir", p)
-        assert p == mysetup.dest.join(config.topdir.basename)
-        assert p.join("dir1").check()
-        assert p.join("dir1", "file1").check()
-
-    def test_popen_rsync_subdir(self, testdir, mysetup, workercontroller):
-        source, dest = mysetup.source, mysetup.dest
-        dir1 = mysetup.source.mkdir("dir1")
-        dir2 = dir1.mkdir("dir2")
-        dir2.ensure("hello")
-        for rsyncroot in (dir1, source):
-            dest.remove()
-            nodemanager = NodeManager(
-                testdir.parseconfig(
-                    "--tx", "popen//chdir=%s" % dest, "--rsyncdir", rsyncroot, source
-                )
-            )
-            nodemanager.setup_nodes(None)  # calls .rsync_roots()
-            if rsyncroot == source:
-                dest = dest.join("source")
-            assert dest.join("dir1").check()
-            assert dest.join("dir1", "dir2").check()
-            assert dest.join("dir1", "dir2", "hello").check()
-            nodemanager.teardown_nodes()
-
-    def test_init_rsync_roots(self, testdir, mysetup, workercontroller):
-        source, dest = mysetup.source, mysetup.dest
-        dir2 = source.ensure("dir1", "dir2", dir=1)
-        source.ensure("dir1", "somefile", dir=1)
-        dir2.ensure("hello")
-        source.ensure("bogusdir", "file")
-        source.join("tox.ini").write(
-            textwrap.dedent(
-                """
-            [pytest]
-            rsyncdirs=dir1/dir2
-        """
-            )
-        )
-        config = testdir.parseconfig(source)
-        nodemanager = NodeManager(config, ["popen//chdir=%s" % dest])
-        nodemanager.setup_nodes(None)  # calls .rsync_roots()
-        assert dest.join("dir2").check()
-        assert not dest.join("dir1").check()
-        assert not dest.join("bogus").check()
-
-    def test_rsyncignore(self, testdir, mysetup, workercontroller):
-        source, dest = mysetup.source, mysetup.dest
-        dir2 = source.ensure("dir1", "dir2", dir=1)
-        source.ensure("dir5", "dir6", "bogus")
-        source.ensure("dir5", "file")
-        dir2.ensure("hello")
-        source.ensure("foo", "bar")
-        source.ensure("bar", "foo")
-        source.join("tox.ini").write(
-            textwrap.dedent(
-                """
-            [pytest]
-            rsyncdirs = dir1 dir5
-            rsyncignore = dir1/dir2 dir5/dir6 foo*
-        """
-            )
-        )
-        config = testdir.parseconfig(source)
-        config.option.rsyncignore = ["bar"]
-        nodemanager = NodeManager(config, ["popen//chdir=%s" % dest])
-        nodemanager.setup_nodes(None)  # calls .rsync_roots()
-        assert dest.join("dir1").check()
-        assert not dest.join("dir1", "dir2").check()
-        assert dest.join("dir5", "file").check()
-        assert not dest.join("dir6").check()
-        assert not dest.join("foo").check()
-        assert not dest.join("bar").check()
-
-    def test_optimise_popen(self, testdir, mysetup, workercontroller):
-        source = mysetup.source
-        specs = ["popen"] * 3
-        source.join("conftest.py").write("rsyncdirs = ['a']")
-        source.ensure("a", dir=1)
-        config = testdir.parseconfig(source)
-        nodemanager = NodeManager(config, specs)
-        nodemanager.setup_nodes(None)  # calls .rysnc_roots()
-        for gwspec in nodemanager.specs:
-            assert gwspec._samefilesystem()
-            assert not gwspec.chdir
-
-    def test_ssh_setup_nodes(self, specssh, testdir):
-        testdir.makepyfile(
-            __init__="",
-            test_x="""
-            def test_one():
-                pass
-        """,
-        )
-        reprec = testdir.inline_run(
-            "-d", "--rsyncdir=%s" % testdir.tmpdir, "--tx", specssh, testdir.tmpdir
-        )
-        rep, = reprec.getreports("pytest_runtest_logreport")
-        assert rep.passed

testing/test_workermanage.py

@@ -0,0 +1,405 @@
+import execnet
+import pytest
+import shutil
+import textwrap
+import warnings
+from pathlib import Path
+from util import generate_warning
+from xdist import workermanage
+from xdist._path import visit_path
+from xdist.remote import serialize_warning_message
+from xdist.workermanage import HostRSync, NodeManager, unserialize_warning_message
+
+pytest_plugins = "pytester"
+
+
+@pytest.fixture
+def hookrecorder(request, config, pytester: pytest.Pytester):
+    hookrecorder = pytester.make_hook_recorder(config.pluginmanager)
+    return hookrecorder
+
+
+@pytest.fixture
+def config(pytester: pytest.Pytester):
+    return pytester.parseconfig()
+
+
+@pytest.fixture
+def source(tmp_path: Path) -> Path:
+    source = tmp_path / "source"
+    source.mkdir()
+    return source
+
+
+@pytest.fixture
+def dest(tmp_path: Path) -> Path:
+    dest = tmp_path / "dest"
+    dest.mkdir()
+    return dest
+
+
+@pytest.fixture
+def workercontroller(monkeypatch: pytest.MonkeyPatch):
+    class MockController:
+        def __init__(self, *args):
+            pass
+
+        def setup(self):
+            pass
+
+    monkeypatch.setattr(workermanage, "WorkerController", MockController)
+    return MockController
+
+
+class TestNodeManagerPopen:
+    def test_popen_no_default_chdir(self, config) -> None:
+        gm = NodeManager(config, ["popen"])
+        assert gm.specs[0].chdir is None
+
+    def test_default_chdir(self, 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
+    ) -> None:
+        hm = NodeManager(config, ["popen"] * 2)
+        hm.setup_nodes(None)
+        call = hookrecorder.popcall("pytest_xdist_setupnodes")
+        assert len(call.specs) == 2
+
+        call = hookrecorder.popcall("pytest_xdist_newgateway")
+        assert call.gateway.spec == execnet.XSpec("popen")
+        assert call.gateway.id == "gw0"
+        call = hookrecorder.popcall("pytest_xdist_newgateway")
+        assert call.gateway.id == "gw1"
+        assert len(hm.group) == 2
+        hm.teardown_nodes()
+        assert not len(hm.group)
+
+    def test_popens_rsync(
+        self, config, source: Path, dest: Path, workercontroller
+    ) -> None:
+        hm = NodeManager(config, ["popen"] * 2)
+        hm.setup_nodes(None)
+        assert len(hm.group) == 2
+        for gw in hm.group:
+
+            class pseudoexec:
+                args = []  # type: ignore[var-annotated]
+
+                def __init__(self, *args):
+                    self.args.extend(args)
+
+                def waitclose(self):
+                    pass
+
+            gw.remote_exec = pseudoexec
+        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]
+
+    def test_rsync_popen_with_path(
+        self, config, source: Path, dest: Path, workercontroller
+    ) -> None:
+        hm = NodeManager(config, ["popen//chdir=%s" % dest] * 1)
+        hm.setup_nodes(None)
+        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.joinpath(source.name)
+        assert dest.joinpath("dir1").exists()
+        assert dest.joinpath("dir1", "dir2").exists()
+        assert dest.joinpath("dir1", "dir2", "hello").exists()
+
+    def test_rsync_same_popen_twice(
+        self,
+        config,
+        source: Path,
+        dest: Path,
+        hookrecorder,
+        workercontroller,
+    ) -> None:
+        hm = NodeManager(config, ["popen//chdir=%s" % dest] * 2)
+        hm.roots = []
+        hm.setup_nodes(None)
+        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")
+        assert call.source == source
+        assert len(call.gateways) == 1
+        assert call.gateways[0] in hm.group
+        call = hookrecorder.popcall("pytest_xdist_rsyncfinish")
+
+
+class TestHRSync:
+    def test_hrsync_filter(self, source: Path, dest: Path) -> None:
+        source.joinpath("dir").mkdir()
+        source.joinpath("dir", "file.txt").touch()
+        source.joinpath(".svn").mkdir()
+        source.joinpath(".svn", "entries").touch()
+        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(visit_path(source, recurse=syncer.filter, filter=syncer.filter))
+        names = {x.name for x in files}
+        assert names == {"dir", "file.txt", "somedir"}
+
+    def test_hrsync_one_host(self, source: Path, dest: Path) -> None:
+        gw = execnet.makegateway("popen//chdir=%s" % dest)
+        finished = []
+        rsync = HostRSync(source)
+        rsync.add_target_host(gw, finished=lambda: finished.append(1))
+        source.joinpath("hello.py").write_text("world")
+        rsync.send()
+        gw.exit()
+        assert dest.joinpath(source.name, "hello.py").exists()
+        assert len(finished) == 1
+
+
+class TestNodeManager:
+    @pytest.mark.xfail(run=False)
+    def test_rsync_roots_no_roots(
+        self, pytester: pytest.Pytester, source: Path, dest: Path
+    ) -> None:
+        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()  # type: ignore[attr-defined]
+        nodemanager.rsync_roots()  # type: ignore[call-arg]
+        (p,) = nodemanager.gwmanager.multi_exec(  # type: ignore[attr-defined]
+            "import os ; channel.send(os.getcwd())"
+        ).receive_each()
+        p = Path(p)
+        print("remote curdir", p)
+        assert p == dest.joinpath(config.rootpath.name)
+        assert p.joinpath("dir1").check()
+        assert p.joinpath("dir1", "file1").check()
+
+    def test_popen_rsync_subdir(
+        self, pytester: pytest.Pytester, source: Path, dest: Path, workercontroller
+    ) -> None:
+        dir1 = source / "dir1"
+        dir1.mkdir()
+        dir2 = dir1 / "dir2"
+        dir2.mkdir()
+        dir2.joinpath("hello").touch()
+        for rsyncroot in (dir1, source):
+            shutil.rmtree(str(dest), ignore_errors=True)
+            nodemanager = NodeManager(
+                pytester.parseconfig(
+                    "--tx", "popen//chdir=%s" % dest, "--rsyncdir", rsyncroot, source
+                )
+            )
+            nodemanager.setup_nodes(None)  # calls .rsync_roots()
+            if rsyncroot == source:
+                dest = dest.joinpath("source")
+            assert dest.joinpath("dir1").exists()
+            assert dest.joinpath("dir1", "dir2").exists()
+            assert dest.joinpath("dir1", "dir2", "hello").exists()
+            nodemanager.teardown_nodes()
+
+    @pytest.mark.parametrize(
+        "flag, expects_report", [("-q", False), ("", False), ("-v", True)]
+    )
+    def test_rsync_report(
+        self,
+        pytester: pytest.Pytester,
+        source: Path,
+        dest: Path,
+        workercontroller,
+        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.append(flag)
+        nodemanager = NodeManager(pytester.parseconfig(*args))
+        nodemanager.setup_nodes(None)  # calls .rsync_roots()
+        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, pytester: pytest.Pytester, source: Path, dest: Path, workercontroller
+    ) -> 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]
+                rsyncdirs=dir1/dir2
+                """
+            )
+        )
+        config = pytester.parseconfig(source)
+        nodemanager = NodeManager(config, ["popen//chdir=%s" % dest])
+        nodemanager.setup_nodes(None)  # calls .rsync_roots()
+        assert dest.joinpath("dir2").exists()
+        assert not dest.joinpath("dir1").exists()
+        assert not dest.joinpath("bogus").exists()
+
+    def test_rsyncignore(
+        self, pytester: pytest.Pytester, source: Path, dest: Path, workercontroller
+    ) -> None:
+        dir2 = source.joinpath("dir1", "dir2")
+        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]
+                rsyncdirs = dir1 dir5
+                rsyncignore = dir1/dir2 dir5/dir6 foo*
+                """
+            )
+        )
+        config = pytester.parseconfig(source)
+        config.option.rsyncignore = ["bar"]
+        nodemanager = NodeManager(config, ["popen//chdir=%s" % dest])
+        nodemanager.setup_nodes(None)  # calls .rsync_roots()
+        assert dest.joinpath("dir1").exists()
+        assert not dest.joinpath("dir1", "dir2").exists()
+        assert dest.joinpath("dir5", "file").exists()
+        assert not dest.joinpath("dir6").exists()
+        assert not dest.joinpath("foo").exists()
+        assert not dest.joinpath("bar").exists()
+
+    def test_optimise_popen(
+        self, pytester: pytest.Pytester, source: Path, dest: Path, workercontroller
+    ) -> None:
+        specs = ["popen"] * 3
+        source.joinpath("conftest.py").write_text("rsyncdirs = ['a']")
+        source.joinpath("a").mkdir()
+        config = pytester.parseconfig(source)
+        nodemanager = NodeManager(config, specs)
+        nodemanager.setup_nodes(None)  # calls .rysnc_roots()
+        for gwspec in nodemanager.specs:
+            assert gwspec._samefilesystem()
+            assert not gwspec.chdir
+
+    def test_ssh_setup_nodes(self, specssh: str, pytester: pytest.Pytester) -> None:
+        pytester.makepyfile(
+            __init__="",
+            test_x="""
+            def test_one():
+                pass
+        """,
+        )
+        reprec = pytester.inline_run(
+            "-d", "--rsyncdir=%s" % pytester.path, "--tx", specssh, pytester.path
+        )
+        (rep,) = reprec.getreports("pytest_runtest_logreport")
+        assert rep.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):
+    """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():
+    """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():
+    warnings.warn(MyWarning2("hello"))

tox.ini

@@ -1,55 +1,68 @@
 [tox]
-# if you change the envlist, please update .travis.yml file as well
 envlist=
   linting
-  py{27,34,35,36}-pytest{30,31,32,33,36}
+  py{37,38,39,310,311,312}-pytestlatest
-  py{27,36}-pytest36-pexpect
+  py310-pytestmain
-  py{27,36}-pytest{master,features}
+  py310-psutil
-
+  py310-setproctitle
-
+isolated_build = true
 [testenv]
-changedir=testing
+extras = testing
-passenv = USER USERNAME
 deps =
-  pycmd
+  pytestlatest: pytest
-  # to avoid .eggs
+  pytestmain: git+https://github.com/pytest-dev/pytest.git
-  setuptools_scm
-  pytest30: pytest~=3.0.5
-  pytest31: pytest~=3.1.0
-  pytest32: pytest~=3.2.0
-  pytest33: pytest~=3.3.0
-  pytest36: pytest~=3.6.0
-  pytestmaster: git+https://github.com/pytest-dev/pytest.git@master
-  pytestfeatures: git+https://github.com/pytest-dev/pytest.git@features
-  pexpect: pexpect
-platform=
-  pexpect: linux|darwin
 commands=
-  # always clean to avoid code unmarshal mismatch on old python/pytest
+  pytest {posargs}
-  py.cleanup -aq
+
+[testenv:py310-psutil]
+extras =
+  testing
+  psutil
+commands =
+  pytest {posargs:-k psutil}
+
+[testenv:py310-setproctitle]
+extras =
+  testing
+  setproctitle
+deps = pytest
+commands =
   pytest {posargs}
 
 [testenv:linting]
-skipsdist = True
+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=
-decription = do a release, required posarg of the version number
+description = do a release, required posarg of the version number
-basepython = python3.6
+basepython = python3.10
 skipsdist = True
 usedevelop = True
 passenv = *
 deps =
   towncrier
 commands =
-    towncrier --version {posargs} --yes
+  towncrier build --version {posargs} --yes
+
+[testenv:docs]
+basepython = python3.10
+usedevelop = True
+deps =
+    sphinx
+    sphinx_rtd_theme
+commands =
+    sphinx-build -W --keep-going -b html docs docs/_build/html {posargs:}
 
 [pytest]
-addopts = -rsfxX
+# 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
 
 [flake8]
 max-line-length = 120

xdist/__init__.py

@@ -1,3 +0,0 @@
-from xdist._version import version as __version__
-
-__all__ = ["__version__"]

xdist/newhooks.py

@@ -1,52 +0,0 @@
-"""
-xdist hooks.
-
-Additionally, pytest-xdist will also decorate a few other hooks
-with the worker instance that executed the hook originally:
-
-``pytest_runtest_logreport``: ``rep`` parameter has a ``node`` attribute.
-
-You can use this hooks just as you would use normal pytest hooks, but some care
-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
-"""
-import pytest
-
-
-def pytest_xdist_setupnodes(config, specs):
-    """ called before any remote node is set up. """
-
-
-def pytest_xdist_newgateway(gateway):
-    """ called on new raw gateway creation. """
-
-
-def pytest_xdist_rsyncstart(source, gateways):
-    """ called before rsyncing a directory to remote gateways takes place. """
-
-
-def pytest_xdist_rsyncfinish(source, gateways):
-    """ called after rsyncing a directory to remote gateways takes place. """
-
-
-def pytest_configure_node(node):
-    """ configure node information before it gets instantiated. """
-
-
-def pytest_testnodeready(node):
-    """ Test Node is ready to operate. """
-
-
-def pytest_testnodedown(node, error):
-    """ Test Node is down. """
-
-
-def pytest_xdist_node_collection_finished(node, ids):
-    """called by the master node when a node finishes collecting.
-    """
-
-
-@pytest.mark.firstresult
-def pytest_xdist_make_scheduler(config, log):
-    """ return a node scheduler implementation """

xdist/plugin.py

@@ -1,201 +0,0 @@
-import os
-
-import py
-import pytest
-
-
-def auto_detect_cpus():
-    try:
-        from os import sched_getaffinity
-    except ImportError:
-        if os.environ.get("TRAVIS") == "true":
-            # workaround https://bitbucket.org/pypy/pypy/issues/2375
-            return 2
-        try:
-            from os import cpu_count
-        except ImportError:
-            from multiprocessing import cpu_count
-    else:
-
-        def cpu_count():
-            return len(sched_getaffinity(0))
-
-    try:
-        n = cpu_count()
-    except NotImplementedError:
-        return 1
-    return n if n else 1
-
-
-def parse_numprocesses(s):
-    if s == "auto":
-        return auto_detect_cpus()
-    else:
-        return int(s)
-
-
-def pytest_addoption(parser):
-    group = parser.getgroup("xdist", "distributed and subprocess testing")
-    group._addoption(
-        "-n",
-        "--numprocesses",
-        dest="numprocesses",
-        metavar="numprocesses",
-        action="store",
-        type=parse_numprocesses,
-        help="shortcut for '--dist=load --tx=NUM*popen', "
-        "you can use 'auto' here for auto detection CPUs number on "
-        "host system",
-    )
-    group.addoption(
-        "--max-worker-restart",
-        "--max-slave-restart",
-        action="store",
-        default=None,
-        dest="maxworkerrestart",
-        help="maximum number of workers that can be restarted "
-        "when crashed (set to zero to disable this feature)\n"
-        "'--max-slave-restart' option is deprecated and will be removed in "
-        "a future release",
-    )
-    group.addoption(
-        "--dist",
-        metavar="distmode",
-        action="store",
-        choices=["each", "load", "loadscope", "loadfile", "no"],
-        dest="dist",
-        default="no",
-        help=(
-            "set mode for distributing tests to exec environments.\n\n"
-            "each: send each test to all available environments.\n\n"
-            "load: load balance by sending any pending test to any"
-            " available environment.\n\n"
-            "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"
-            " to any available environment.\n\n"
-            "(default) no: run tests inprocess, don't distribute."
-        ),
-    )
-    group.addoption(
-        "--tx",
-        dest="tx",
-        action="append",
-        default=[],
-        metavar="xspec",
-        help=(
-            "add a test execution environment. some examples: "
-            "--tx popen//python=python2.5 --tx socket=192.168.1.102:8888 "
-            "--tx ssh=user@codespeak.net//chdir=testcache"
-        ),
-    )
-    group._addoption(
-        "-d",
-        action="store_true",
-        dest="distload",
-        default=False,
-        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.",
-    )
-    group.addoption(
-        "--rsyncignore",
-        action="append",
-        default=[],
-        metavar="GLOB",
-        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",
-    )
-    parser.addini(
-        "rsyncdirs",
-        "list of (relative) paths to be rsynced for" " remote distributed testing.",
-        type="pathlist",
-    )
-    parser.addini(
-        "rsyncignore",
-        "list of (relative) glob-style paths to be ignored " "for rsyncing.",
-        type="pathlist",
-    )
-    parser.addini(
-        "looponfailroots",
-        type="pathlist",
-        help="directories to check for changes",
-        default=[py.path.local()],
-    )
-
-
-# -------------------------------------------------------------------------
-# distributed testing hooks
-# -------------------------------------------------------------------------
-
-
-def pytest_addhooks(pluginmanager):
-    from xdist import newhooks
-
-    # avoid warnings with pytest-2.8
-    method = getattr(pluginmanager, "add_hookspecs", None)
-    if method is None:
-        method = pluginmanager.addhooks
-    method(newhooks)
-
-
-# -------------------------------------------------------------------------
-# distributed testing initialization
-# -------------------------------------------------------------------------
-
-
-@pytest.mark.trylast
-def pytest_configure(config):
-    if config.getoption("dist") != "no" and not config.getvalue("collectonly"):
-        from xdist.dsession import DSession
-
-        session = DSession(config)
-        config.pluginmanager.register(session, "dsession")
-        tr = config.pluginmanager.getplugin("terminalreporter")
-        tr.showfspath = False
-    if config.getoption("boxed"):
-        config.option.forked = True
-
-
-@pytest.mark.tryfirst
-def pytest_cmdline_main(config):
-    if config.option.numprocesses:
-        if config.option.dist == "no":
-            config.option.dist = "load"
-        config.option.tx = ["popen"] * config.option.numprocesses
-    if config.option.distload:
-        config.option.dist = "load"
-    val = config.getvalue
-    if not val("collectonly"):
-        usepdb = config.getoption("usepdb")  # a core option
-        if val("dist") != "no":
-            if usepdb:
-                raise pytest.UsageError(
-                    "--pdb is incompatible with distributing tests; try using -n0."
-                )  # noqa: E501
-
-
-# -------------------------------------------------------------------------
-# fixtures
-# -------------------------------------------------------------------------
-
-
-@pytest.fixture(scope="session")
-def worker_id(request):
-    """Return the id of the current worker ('gw0', 'gw1', etc) or 'master'
-    if running on the master node.
-    """
-    if hasattr(request.config, "workerinput"):
-        return request.config.workerinput["workerid"]
-    else:
-        return "master"

xdist/remote.py

@@ -1,215 +0,0 @@
-"""
-    This module is executed in remote subprocesses and helps to
-    control a remote testing session and relay back information.
-    It assumes that 'py' is importable and does not have dependencies
-    on the rest of the xdist code.  This means that the xdist-plugin
-    needs not to be installed in remote environments.
-"""
-
-import sys
-import os
-import time
-
-import _pytest.hookspec
-import pytest
-
-
-class WorkerInteractor(object):
-    def __init__(self, config, channel):
-        self.config = config
-        self.workerid = config.workerinput.get("workerid", "?")
-        self.log = py.log.Producer("worker-%s" % self.workerid)
-        if not config.option.debug:
-            py.log.setconsumer(self.log._keywords, None)
-        self.channel = channel
-        config.pluginmanager.register(self)
-
-    def sendevent(self, name, **kwargs):
-        self.log("sending", name, kwargs)
-        self.channel.send((name, kwargs))
-
-    def pytest_internalerror(self, excrepr):
-        for line in str(excrepr).split("\n"):
-            self.log("IERROR>", line)
-
-    def pytest_sessionstart(self, session):
-        self.session = session
-        workerinfo = getinfodict()
-        self.sendevent("workerready", workerinfo=workerinfo)
-
-    @pytest.hookimpl(hookwrapper=True)
-    def pytest_sessionfinish(self, exitstatus):
-        self.config.workeroutput["exitstatus"] = exitstatus
-        yield
-        self.sendevent("workerfinished", workeroutput=self.config.workeroutput)
-
-    def pytest_collection(self, session):
-        self.sendevent("collectionstart")
-
-    def pytest_runtestloop(self, session):
-        self.log("entering main loop")
-        torun = []
-        while 1:
-            try:
-                name, kwargs = self.channel.receive()
-            except EOFError:
-                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):
-        items = self.session.items
-        self.item_index = torun.pop(0)
-        item = items[self.item_index]
-        if torun:
-            nextitem = items[torun[0]]
-        else:
-            nextitem = None
-
-        start = time.time()
-        self.config.hook.pytest_runtest_protocol(item=item, nextitem=nextitem)
-        duration = time.time() - start
-        self.sendevent(
-            "runtest_protocol_complete", item_index=self.item_index, duration=duration
-        )
-
-    def pytest_collection_finish(self, session):
-        self.sendevent(
-            "collectionfinish",
-            topdir=str(session.fspath),
-            ids=[item.nodeid for item in session.items],
-        )
-
-    def pytest_runtest_logstart(self, nodeid, location):
-        self.sendevent("logstart", nodeid=nodeid, location=location)
-
-    # the pytest_runtest_logfinish hook was introduced in pytest 3.4
-    if hasattr(_pytest.hookspec, "pytest_runtest_logfinish"):
-
-        def pytest_runtest_logfinish(self, nodeid, location):
-            self.sendevent("logfinish", nodeid=nodeid, location=location)
-
-    def pytest_runtest_logreport(self, report):
-        data = serialize_report(report)
-        data["item_index"] = self.item_index
-        data["worker_id"] = self.workerid
-        assert self.session.items[self.item_index].nodeid == report.nodeid
-        self.sendevent("testreport", data=data)
-
-    def pytest_collectreport(self, report):
-        # master only needs reports that failed, as optimization send only them instead (#330)
-        if report.failed:
-            data = serialize_report(report)
-            self.sendevent("collectreport", data=data)
-
-    def pytest_logwarning(self, message, code, nodeid, fslocation):
-        self.sendevent(
-            "logwarning",
-            message=message,
-            code=code,
-            nodeid=nodeid,
-            fslocation=str(fslocation),
-        )
-
-
-def serialize_report(rep):
-    def disassembled_report(rep):
-        reprtraceback = rep.longrepr.reprtraceback.__dict__.copy()
-        reprcrash = rep.longrepr.reprcrash.__dict__.copy()
-
-        new_entries = []
-        for entry in reprtraceback["reprentries"]:
-            entry_data = {"type": type(entry).__name__, "data": entry.__dict__.copy()}
-            for key, value in entry_data["data"].items():
-                if hasattr(value, "__dict__"):
-                    entry_data["data"][key] = value.__dict__.copy()
-            new_entries.append(entry_data)
-
-        reprtraceback["reprentries"] = new_entries
-
-        return {
-            "reprcrash": reprcrash,
-            "reprtraceback": reprtraceback,
-            "sections": rep.longrepr.sections,
-        }
-
-    import py
-
-    d = rep.__dict__.copy()
-    if hasattr(rep.longrepr, "toterminal"):
-        if hasattr(rep.longrepr, "reprtraceback") and hasattr(
-            rep.longrepr, "reprcrash"
-        ):
-            d["longrepr"] = disassembled_report(rep)
-        else:
-            d["longrepr"] = str(rep.longrepr)
-    else:
-        d["longrepr"] = rep.longrepr
-    for name in d:
-        if isinstance(d[name], py.path.local):
-            d[name] = str(d[name])
-        elif name == "result":
-            d[name] = None  # for now
-    return d
-
-
-def getinfodict():
-    import platform
-
-    return dict(
-        version=sys.version,
-        version_info=tuple(sys.version_info),
-        sysplatform=sys.platform,
-        platform=platform.platform(),
-        executable=sys.executable,
-        cwd=os.getcwd(),
-    )
-
-
-def remote_initconfig(option_dict, args):
-    from _pytest.config import Config
-
-    option_dict["plugins"].append("no:terminal")
-    config = Config.fromdictargs(option_dict, args)
-    config.option.looponfail = False
-    config.option.usepdb = False
-    config.option.dist = "no"
-    config.option.distload = False
-    config.option.numprocesses = None
-    config.args = args
-    return config
-
-
-if __name__ == "__channelexec__":
-    channel = channel  # noqa
-    workerinput, args, option_dict = channel.receive()
-    importpath = os.getcwd()
-    sys.path.insert(0, importpath)  # XXX only for remote situations
-    os.environ["PYTHONPATH"] = (
-        importpath + os.pathsep + os.environ.get("PYTHONPATH", "")
-    )
-    os.environ["PYTEST_XDIST_WORKER"] = workerinput["workerid"]
-    os.environ["PYTEST_XDIST_WORKER_COUNT"] = str(workerinput["workercount"])
-    # os.environ['PYTHONPATH'] = importpath
-    import py
-
-    config = remote_initconfig(option_dict, args)
-    config.workerinput = workerinput
-    config.workeroutput = {}
-    # TODO: deprecated name, backward compatibility only. Remove it in future
-    config.slaveinput = config.workerinput
-    config.slaveoutput = config.workeroutput
-    interactor = WorkerInteractor(config, channel)
-    config.hook.pytest_cmdline_main(config=config)

xdist/scheduler/__init__.py

@@ -1,4 +0,0 @@
-from xdist.scheduler.each import EachScheduling  # noqa
-from xdist.scheduler.load import LoadScheduling  # noqa
-from xdist.scheduler.loadscope import LoadScopeScheduling  # noqa
-from xdist.scheduler.filescope import LoadFileScheduling  # noqa