wip: fix capfd

[pre-commit.ci] pre-commit autoupdate

.github/PULL_REQUEST_TEMPLATE.md

@@ -13,7 +13,7 @@ If this change fixes an issue, please:
 
 Unless your change is trivial or a small documentation fix (e.g., a typo or reword of a small section) please:
 
-- [ ] Create a new changelog file in the `changelog` folder, with a name like `<ISSUE NUMBER>.<TYPE>.rst`. See [changelog/README.rst](https://github.com/pytest-dev/pytest/blob/master/changelog/README.rst) for details.
+- [ ] Create a new changelog file in the `changelog` folder, with a name like `<ISSUE NUMBER>.<TYPE>.rst`. See [changelog/README.rst](https://github.com/pytest-dev/pytest/blob/main/changelog/README.rst) for details.
 
   Write sentences in the **past or present tense**, examples:
 

.github/workflows/main.yml

@@ -3,7 +3,7 @@ name: main
 on:
   push:
     branches:
-      - master
+      - main
       - "[0-9]+.[0-9]+.x"
     tags:
       - "[0-9]+.[0-9]+.[0-9]+"
@@ -11,7 +11,7 @@ on:
 
   pull_request:
     branches:
-      - master
+      - main
       - "[0-9]+.[0-9]+.x"
 
 jobs:
@@ -27,6 +27,8 @@ jobs:
           "windows-py37",
           "windows-py37-pluggy",
           "windows-py38",
+          "windows-py39",
+          "windows-py310",
 
           "ubuntu-py36",
           "ubuntu-py37",
@@ -34,6 +36,7 @@ jobs:
           "ubuntu-py37-freeze",
           "ubuntu-py38",
           "ubuntu-py39",
+          "ubuntu-py310",
           "ubuntu-pypy3",
 
           "macos-py37",
@@ -56,12 +59,20 @@ jobs:
           - name: "windows-py37-pluggy"
             python: "3.7"
             os: windows-latest
-            tox_env: "py37-pluggymaster-xdist"
+            tox_env: "py37-pluggymain-xdist"
           - name: "windows-py38"
             python: "3.8"
             os: windows-latest
             tox_env: "py38-unittestextras"
             use_coverage: true
+          - name: "windows-py39"
+            python: "3.9"
+            os: windows-latest
+            tox_env: "py39-xdist"
+          - name: "windows-py310"
+            python: "3.10-dev"
+            os: windows-latest
+            tox_env: "py310-xdist"
 
           - name: "ubuntu-py36"
             python: "3.6"
@@ -75,7 +86,7 @@ jobs:
           - name: "ubuntu-py37-pluggy"
             python: "3.7"
             os: ubuntu-latest
-            tox_env: "py37-pluggymaster-xdist"
+            tox_env: "py37-pluggymain-xdist"
           - name: "ubuntu-py37-freeze"
             python: "3.7"
             os: ubuntu-latest
@@ -88,8 +99,12 @@ jobs:
             python: "3.9"
             os: ubuntu-latest
             tox_env: "py39-xdist"
+          - name: "ubuntu-py310"
+            python: "3.10-dev"
+            os: ubuntu-latest
+            tox_env: "py310-xdist"
           - name: "ubuntu-pypy3"
-            python: "pypy3"
+            python: "pypy-3.7"
             os: ubuntu-latest
             tox_env: "pypy3-xdist"
 
@@ -137,22 +152,13 @@ jobs:
 
     - name: Test with coverage
       if: "matrix.use_coverage"
-      env:
-        _PYTEST_TOX_COVERAGE_RUN: "coverage run -m"
-        COVERAGE_PROCESS_START: ".coveragerc"
-        _PYTEST_TOX_EXTRA_DEP: "coverage-enable-subprocess"
-      run: "tox -e ${{ matrix.tox_env }}"
+      run: "tox -e ${{ matrix.tox_env }}-coverage"
 
-    - name: Prepare coverage token
-      if: (matrix.use_coverage && ( github.repository == 'pytest-dev/pytest' || github.event_name == 'pull_request' ))
-      run: |
-        python scripts/append_codecov_token.py
-
-    - name: Report coverage
-      if: (matrix.use_coverage)
+    - name: Upload coverage
+      if: matrix.use_coverage && github.repository == 'pytest-dev/pytest'
       env:
         CODECOV_NAME: ${{ matrix.name }}
-      run: bash scripts/report-coverage.sh -F GHA,${{ runner.os }}
+      run: bash scripts/upload-coverage.sh -F GHA,${{ runner.os }}
 
   linting:
     runs-on: ubuntu-latest

.github/workflows/prepare-release-pr.yml

@@ -0,0 +1,42 @@
+name: prepare release pr
+
+on:
+  workflow_dispatch:
+    inputs:
+      branch:
+        description: 'Branch to base the release from'
+        required: true
+        default: ''
+      major:
+        description: 'Major release? (yes/no)'
+        required: true
+        default: 'no'
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v2
+      with:
+        fetch-depth: 0
+
+    - name: Set up Python
+      uses: actions/setup-python@v2
+      with:
+        python-version: "3.8"
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install --upgrade setuptools tox
+
+    - name: Prepare release PR (minor/patch release)
+      if: github.event.inputs.major == 'no'
+      run: |
+        tox -e prepare-release-pr -- ${{ github.event.inputs.branch }} ${{ secrets.chatops }}
+
+    - name: Prepare release PR (major release)
+      if: github.event.inputs.major == 'yes'
+      run: |
+        tox -e prepare-release-pr -- ${{ github.event.inputs.branch }} ${{ secrets.chatops }} --major

.github/workflows/update-plugin-list.yml

@@ -0,0 +1,35 @@
+name: Update Plugin List
+
+on:
+  schedule:
+    # At 00:00 on Sunday.
+    # https://crontab.guru
+    - cron: '0 0 * * 0'
+  workflow_dispatch:
+
+jobs:
+  createPullRequest:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v2
+      - name: Setup Python
+        uses: actions/setup-python@v2
+        with:
+          python-version: 3.8
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install packaging requests tabulate[widechars]
+      - name: Update Plugin List
+        run: python scripts/update-plugin-list.py
+      - name: Create Pull Request
+        uses: peter-evans/create-pull-request@2455e1596942c2902952003bbb574afbbe2ab2e6
+        with:
+          commit-message: '[automated] Update plugin list'
+          author: 'pytest bot <pytestbot@users.noreply.github.com>'
+          branch: update-plugin-list/patch
+          delete-branch: true
+          branch-suffix: short-commit-hash
+          title: '[automated] Update plugin list'
+          body: '[automated] Update plugin list'

.pre-commit-config.yaml

@@ -1,16 +1,16 @@
 repos:
 -   repo: https://github.com/psf/black
-    rev: 19.10b0
+    rev: 21.4b0
     hooks:
     -   id: black
         args: [--safe, --quiet]
 -   repo: https://github.com/asottile/blacken-docs
-    rev: v1.8.0
+    rev: v1.10.0
     hooks:
     -   id: blacken-docs
-        additional_dependencies: [black==19.10b0]
+        additional_dependencies: [black==20.8b1]
 -   repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v3.2.0
+    rev: v3.4.0
     hooks:
     -   id: trailing-whitespace
     -   id: end-of-file-fixer
@@ -20,8 +20,8 @@ repos:
     -   id: debug-statements
         exclude: _pytest/(debugging|hookspec).py
         language_version: python3
--   repo: https://gitlab.com/pycqa/flake8
-    rev: 3.8.3
+-   repo: https://github.com/PyCQA/flake8
+    rev: 3.9.1
     hooks:
     -   id: flake8
         language_version: python3
@@ -29,27 +29,26 @@ repos:
           - flake8-typing-imports==1.9.0
           - flake8-docstrings==1.5.0
 -   repo: https://github.com/asottile/reorder_python_imports
-    rev: v2.3.5
+    rev: v2.5.0
     hooks:
     -   id: reorder-python-imports
         args: ['--application-directories=.:src', --py36-plus]
 -   repo: https://github.com/asottile/pyupgrade
-    rev: v2.7.2
+    rev: v2.13.0
     hooks:
     -   id: pyupgrade
         args: [--py36-plus]
 -   repo: https://github.com/asottile/setup-cfg-fmt
-    rev: v1.11.0
+    rev: v1.17.0
     hooks:
     -   id: setup-cfg-fmt
-        # TODO: when upgrading setup-cfg-fmt this can be removed
-        args: [--max-py-version=3.9]
+        args: [--max-py-version=3.10]
 -   repo: https://github.com/pre-commit/pygrep-hooks
-    rev: v1.6.0
+    rev: v1.8.0
     hooks:
     -   id: python-use-type-annotations
 -   repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v0.790
+    rev: v0.812
     hooks:
     -   id: mypy
         files: ^(src/|testing/)
@@ -89,3 +88,9 @@ repos:
                 xml\.
             )
         types: [python]
+    -   id: py-path-deprecated
+        name: py.path usage is deprecated
+        exclude: docs|src/_pytest/deprecated.py|testing/deprecated_test.py
+        language: pygrep
+        entry: \bpy\.path\.local
+        types: [python]

AUTHORS

@@ -5,6 +5,7 @@ Contributors include::
 
 Aaron Coleman
 Abdeali JK
+Abdelrahman Elbehery
 Abhijeet Kasurde
 Adam Johnson
 Adam Uhlir
@@ -21,6 +22,7 @@ Anders Hovmöller
 Andras Mitzki
 Andras Tim
 Andrea Cimatoribus
+Andreas Motl
 Andreas Zeidler
 Andrey Paramonov
 Andrzej Klajnert
@@ -29,6 +31,7 @@ Andy Freeland
 Anthon van der Neut
 Anthony Shaw
 Anthony Sottile
+Anton Grinevich
 Anton Lodder
 Antony Lee
 Arel Cordero
@@ -39,6 +42,7 @@ Aron Curzon
 Aviral Verma
 Aviv Palivoda
 Barney Gale
+Ben Gartner
 Ben Webb
 Benjamin Peterson
 Bernard Pratz
@@ -56,6 +60,7 @@ Charles Cloud
 Charles Machalow
 Charnjit SiNGH (CCSJ)
 Chris Lamb
+Chris NeJame
 Christian Boelsen
 Christian Fetzer
 Christian Neumüller
@@ -74,6 +79,7 @@ Daniel Grana
 Daniel Hahler
 Daniel Nuri
 Daniel Wandschneider
+Daniele Procida
 Danielle Jenkins
 Daniil Galiev
 Dave Hunt
@@ -93,6 +99,7 @@ Dominic Mortlock
 Duncan Betts
 Edison Gustavo Muenz
 Edoardo Batini
+Edson Tadeu M. Manoel
 Eduardo Schettino
 Eli Boyarski
 Elizaveta Shashkova
@@ -271,6 +278,7 @@ Sankt Petersbug
 Segev Finer
 Serhii Mozghovyi
 Seth Junot
+Shantanu Jain
 Shubham Adep
 Simon Gomizelj
 Simon Kerr

CHANGELOG.rst

@@ -4,4 +4,4 @@ Changelog
 
 The pytest CHANGELOG is located `here <https://docs.pytest.org/en/stable/changelog.html>`__.
 
-The source document can be found at: https://github.com/pytest-dev/pytest/blob/master/doc/en/changelog.rst
+The source document can be found at: https://github.com/pytest-dev/pytest/blob/main/doc/en/changelog.rst

CONTRIBUTING.rst

@@ -160,7 +160,7 @@ the following:
 
 - an issue tracker for bug reports and enhancement requests.
 
-- a `changelog <http://keepachangelog.com/>`_.
+- a `changelog <https://keepachangelog.com/>`_.
 
 If no contributor strongly objects and two agree, the repository can then be
 transferred to the ``pytest-dev`` organisation.
@@ -234,9 +234,9 @@ Here is a simple overview, with pytest-specific bits:
 
     $ git clone git@github.com:YOUR_GITHUB_USERNAME/pytest.git
     $ cd pytest
-    # now, create your own branch off "master":
+    # now, create your own branch off "main":
 
-        $ git checkout -b your-bugfix-branch-name master
+        $ git checkout -b your-bugfix-branch-name main
 
    Given we have "major.minor.micro" version numbers, bug fixes will usually
    be released in micro releases whereas features will be released in
@@ -259,7 +259,7 @@ Here is a simple overview, with pytest-specific bits:
 
    Tox is used to run all the tests and will automatically setup virtualenvs
    to run the tests in.
-   (will implicitly use http://www.virtualenv.org/en/latest/)::
+   (will implicitly use https://virtualenv.pypa.io/en/latest/)::
 
     $ pip install tox
 
@@ -318,26 +318,26 @@ Here is a simple overview, with pytest-specific bits:
     compare: your-branch-name
 
     base-fork: pytest-dev/pytest
-    base: master
+    base: main
 
 
 Writing Tests
 ~~~~~~~~~~~~~
 
-Writing tests for plugins or for pytest itself is often done using the `testdir fixture <https://docs.pytest.org/en/stable/reference.html#testdir>`_, as a "black-box" test.
+Writing tests for plugins or for pytest itself is often done using the `pytester fixture <https://docs.pytest.org/en/stable/reference.html#pytester>`_, as a "black-box" test.
 
 For example, to ensure a simple test passes you can write:
 
 .. code-block:: python
 
-    def test_true_assertion(testdir):
-        testdir.makepyfile(
+    def test_true_assertion(pytester):
+        pytester.makepyfile(
             """
             def test_foo():
                 assert True
         """
         )
-        result = testdir.runpytest()
+        result = pytester.runpytest()
         result.assert_outcomes(failed=0, passed=1)
 
 
@@ -346,14 +346,14 @@ Alternatively, it is possible to make checks based on the actual output of the t
 
 .. code-block:: python
 
-    def test_true_assertion(testdir):
-        testdir.makepyfile(
+    def test_true_assertion(pytester):
+        pytester.makepyfile(
             """
             def test_foo():
                 assert False
         """
         )
-        result = testdir.runpytest()
+        result = pytester.runpytest()
         result.stdout.fnmatch_lines(["*assert False*", "*1 failed*"])
 
 When choosing a file where to write a new test, take a look at the existing files and see if there's
@@ -387,15 +387,15 @@ Suppose for example that the latest release was 1.2.3, and you want to include
 a bug fix in 1.2.4 (check https://github.com/pytest-dev/pytest/releases for the
 actual latest release). The procedure for this is:
 
-#. First, make sure the bug is fixed the ``master`` branch, with a regular pull
+#. First, make sure the bug is fixed the ``main`` branch, with a regular pull
    request, as described above. An exception to this is if the bug fix is not
-   applicable to ``master`` anymore.
+   applicable to ``main`` anymore.
 
-#. ``git checkout origin/1.2.x -b backport-XXXX`` # use the master PR number here
+#. ``git checkout origin/1.2.x -b backport-XXXX`` # use the main PR number here
 
 #. Locate the merge commit on the PR, in the *merged* message, for example:
 
-    nicoddemus merged commit 0f8b462 into pytest-dev:master
+    nicoddemus merged commit 0f8b462 into pytest-dev:main
 
 #. ``git cherry-pick -x -m1 REVISION`` # use the revision you found above (``0f8b462``).
 
@@ -408,8 +408,8 @@ actual latest release). The procedure for this is:
 Who does the backporting
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
-As mentioned above, bugs should first be fixed on ``master`` (except in rare occasions
-that a bug only happens in a previous release). So who should do the backport procedure described
+As mentioned above, bugs should first be fixed on ``main`` (except in rare occasions
+that a bug only happens in a previous release). So, who should do the backport procedure described
 above?
 
 1. If the bug was fixed by a core developer, it is the main responsibility of that core developer
@@ -417,8 +417,8 @@ above?
 2. However, often the merge is done by another maintainer, in which case it is nice of them to
    do the backport procedure if they have the time.
 3. For bugs submitted by non-maintainers, it is expected that a core developer will to do
-   the backport, normally the one that merged the PR on ``master``.
-4. If a non-maintainers notices a bug which is fixed on ``master`` but has not been backported
+   the backport, normally the one that merged the PR on ``main``.
+4. If a non-maintainers notices a bug which is fixed on ``main`` but has not been backported
    (due to maintainers forgetting to apply the *needs backport* label, or just plain missing it),
    they are also welcome to open a PR with the backport. The procedure is simple and really
    helps with the maintenance of the project.
@@ -447,7 +447,7 @@ can always reopen the issue/pull request in their own time later if it makes sen
 When to close
 ~~~~~~~~~~~~~
 
-Here are a few general rules the maintainers use to decide when to close issues/PRs because
+Here are a few general rules the maintainers use deciding when to close issues/PRs because
 of lack of inactivity:
 
 * Issues labeled ``question`` or ``needs information``: closed after 14 days inactive.
@@ -459,15 +459,15 @@ The above are **not hard rules**, but merely **guidelines**, and can be (and oft
 Closing pull requests
 ~~~~~~~~~~~~~~~~~~~~~
 
-When closing a Pull Request, it needs to be acknowledge the time, effort, and interest demonstrated by the person which submitted it. As mentioned previously, it is not the intent of the team to dismiss stalled pull request entirely but to merely to clear up our queue, so a message like the one below is warranted when closing a pull request that went stale:
+When closing a Pull Request, it needs to be acknowledging the time, effort, and interest demonstrated by the person which submitted it. As mentioned previously, it is not the intent of the team to dismiss a stalled pull request entirely but to merely to clear up our queue, so a message like the one below is warranted when closing a pull request that went stale:
 
     Hi <contributor>,
 
-    First of all we would like to thank you for your time and effort on working on this, the pytest team deeply appreciates it.
+    First of all, we would like to thank you for your time and effort on working on this, the pytest team deeply appreciates it.
 
     We noticed it has been awhile since you have updated this PR, however. pytest is a high activity project, with many issues/PRs being opened daily, so it is hard for us maintainers to track which PRs are ready for merging, for review, or need more attention.
 
-    So for those reasons we think it is best to close the PR for now, but with the only intention to cleanup our queue, it is by no means a rejection of your changes. We still encourage you to re-open this PR (it is just a click of a button away) when you are ready to get back to it.
+    So for those reasons we, think it is best to close the PR for now, but with the only intention to clean up our queue, it is by no means a rejection of your changes. We still encourage you to re-open this PR (it is just a click of a button away) when you are ready to get back to it.
 
     Again we appreciate your time for working on this, and hope you might get back to this at a later time!
 

README.rst

@@ -1,6 +1,7 @@
-.. image:: https://docs.pytest.org/en/stable/_static/pytest1.png
+.. image:: https://github.com/pytest-dev/pytest/raw/main/doc/en/img/pytest_logo_curves.svg
    :target: https://docs.pytest.org/en/stable/
    :align: center
+   :height: 200
    :alt: pytest
 
 
@@ -15,16 +16,17 @@
 .. image:: https://img.shields.io/pypi/pyversions/pytest.svg
     :target: https://pypi.org/project/pytest/
 
-.. image:: https://codecov.io/gh/pytest-dev/pytest/branch/master/graph/badge.svg
+.. image:: https://codecov.io/gh/pytest-dev/pytest/branch/main/graph/badge.svg
     :target: https://codecov.io/gh/pytest-dev/pytest
     :alt: Code coverage Status
 
-.. image:: https://travis-ci.org/pytest-dev/pytest.svg?branch=master
-    :target: https://travis-ci.org/pytest-dev/pytest
-
 .. image:: https://github.com/pytest-dev/pytest/workflows/main/badge.svg
     :target: https://github.com/pytest-dev/pytest/actions?query=workflow%3Amain
 
+.. image:: https://results.pre-commit.ci/badge/github/pytest-dev/pytest/main.svg
+   :target: https://results.pre-commit.ci/latest/github/pytest-dev/pytest/main
+   :alt: pre-commit.ci status
+
 .. image:: https://img.shields.io/badge/code%20style-black-000000.svg
     :target: https://github.com/psf/black
 
@@ -91,7 +93,7 @@ Features
 
 - Python 3.6+ and PyPy3
 
-- Rich plugin architecture, with over 850+ `external plugins <http://plugincompat.herokuapp.com>`_ and thriving community
+- Rich plugin architecture, with over 850+ `external plugins <https://docs.pytest.org/en/stable/plugin_list.html>`_ and thriving community
 
 
 Documentation
@@ -149,8 +151,8 @@ Tidelift will coordinate the fix and disclosure.
 License
 -------
 
-Copyright Holger Krekel and others, 2004-2020.
+Copyright Holger Krekel and others, 2004-2021.
 
 Distributed under the terms of the `MIT`_ license, pytest is free and open source software.
 
-.. _`MIT`: https://github.com/pytest-dev/pytest/blob/master/LICENSE
+.. _`MIT`: https://github.com/pytest-dev/pytest/blob/main/LICENSE

RELEASING.rst

@@ -32,10 +32,10 @@ and notify it as a comment in the issue.
 Minor releases
 ^^^^^^^^^^^^^^
 
-1. Create a new maintenance branch from ``master``::
+1. Create a new maintenance branch from ``main``::
 
         git fetch --all
-        git branch 5.2.x upstream/master
+        git branch 5.2.x upstream/main
         git push upstream 5.2.x
 
 2. Open a new issue and add this comment to the body::
@@ -48,10 +48,10 @@ notify it as a comment in the issue.
 Major and release candidates
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-1. Create a new maintenance branch from ``master``::
+1. Create a new maintenance branch from ``main``::
 
         git fetch --all
-        git branch 6.0.x upstream/master
+        git branch 6.0.x upstream/main
         git push upstream 6.0.x
 
 2. For a **major release**, open a new issue and add this comment in the body::
@@ -66,7 +66,7 @@ The automated workflow will publish a PR for a branch ``release-6.0.0`` and
 notify it as a comment in the issue.
 
 At this point on, this follows the same workflow as other maintenance branches: bug-fixes are merged
-into ``master`` and ported back to the maintenance branch, even for release candidates.
+into ``main`` and ported back to the maintenance branch, even for release candidates.
 
 **A note about release candidates**
 
@@ -83,7 +83,7 @@ to be executed on that platform.
 To release a version ``MAJOR.MINOR.PATCH``, follow these steps:
 
 #. For major and minor releases, create a new branch ``MAJOR.MINOR.x`` from
-   ``upstream/master`` and push it to ``upstream``.
+   ``upstream/main`` and push it to ``upstream``.
 
 #. Create a branch ``release-MAJOR.MINOR.PATCH`` from the ``MAJOR.MINOR.x`` branch.
 
@@ -114,18 +114,18 @@ Both automatic and manual processes described above follow the same steps from t
 
 #. Merge the PR.
 
-#. Cherry-pick the CHANGELOG / announce files to the ``master`` branch::
+#. Cherry-pick the CHANGELOG / announce files to the ``main`` branch::
 
        git fetch --all --prune
-       git checkout origin/master -b cherry-pick-release
+       git checkout origin/main -b cherry-pick-release
        git cherry-pick -x -m1 upstream/MAJOR.MINOR.x
 
 #. Open a PR for ``cherry-pick-release`` and merge it once CI passes. No need to wait for approvals if there were no conflicts on the previous step.
 
-#. For major and minor releases, tag the release cherry-pick merge commit in master with
+#. For major and minor releases, tag the release cherry-pick merge commit in main with
    a dev tag for the next feature release::
 
-       git checkout master
+       git checkout main
        git pull
        git tag MAJOR.{MINOR+1}.0.dev0
        git push git@github.com:pytest-dev/pytest.git MAJOR.{MINOR+1}.0.dev0

changelog/5105.doc.rst

@@ -0,0 +1 @@
+Add automatically generated :ref:`plugin-list`. The list is updated on a periodic schedule.

changelog/7259.feature.rst

@@ -0,0 +1,2 @@
+Added :meth:`cache.mkdir() <pytest.Cache.mkdir>`, which is similar to the existing :meth:`cache.makedir() <pytest.Cache.makedir>`,
+but returns a :class:`pathlib.Path` instead of a legacy ``py.path.local``.

changelog/7469.deprecation.rst

@@ -0,0 +1,10 @@
+Directly constructing the following classes is now deprecated:
+
+- ``_pytest.mark.structures.Mark``
+- ``_pytest.mark.structures.MarkDecorator``
+- ``_pytest.mark.structures.MarkGenerator``
+- ``_pytest.python.Metafunc``
+- ``_pytest.runner.CallInfo``
+- ``_pytest._code.ExceptionInfo``
+
+These have always been considered private, but now issue a deprecation warning, which may become a hard error in pytest 7.0.0.

changelog/7469.feature.rst

@@ -0,0 +1,15 @@
+The types of objects used in pytest's API are now exported so they may be used in type annotations.
+
+The newly-exported types are:
+
+- ``pytest.Mark`` for :class:`marks <pytest.Mark>`.
+- ``pytest.MarkDecorator`` for :class:`mark decorators <pytest.MarkDecorator>`.
+- ``pytest.MarkGenerator`` for the :class:`pytest.mark <pytest.MarkGenerator>` singleton.
+- ``pytest.Metafunc`` for the :class:`metafunc <pytest.MarkGenerator>` argument to the :func:`pytest_generate_tests <pytest.hookspec.pytest_generate_tests>` hook.
+- ``pytest.CallInfo`` for the :class:`CallInfo <pytest.CallInfo>` type passed to various hooks.
+- ``pytest.ExceptionInfo`` for the :class:`ExceptionInfo <pytest.ExceptionInfo>` type returned from :func:`pytest.raises` and passed to various hooks.
+
+Constructing them directly is not supported; they are only meant for use in type annotations.
+Doing so will emit a deprecation warning, and may become a hard-error in pytest 7.0.
+
+Subclassing them is also not supported. This is not currently enforced at runtime, but is detected by type-checkers such as mypy.

changelog/7856.feature.rst

@@ -0,0 +1,2 @@
+:ref:`--import-mode=importlib <import-modes>` now works with features that
+depend on modules being on :py:data:`sys.modules`, such as :mod:`pickle` and :mod:`dataclasses`.

changelog/8061.bugfix.rst

@@ -0,0 +1 @@
+Fixed failing staticmethod test cases if they are inherited from a parent test class.

changelog/8144.feature.rst

@@ -0,0 +1,7 @@
+The following hooks now receive an additional ``pathlib.Path`` argument, equivalent to an existing ``py.path.local`` argument:
+
+- :func:`pytest_ignore_collect <_pytest.hookspec.pytest_ignore_collect>` - The ``fspath`` parameter (equivalent to existing ``path`` parameter).
+- :func:`pytest_collect_file <_pytest.hookspec.pytest_collect_file>` - The ``fspath`` parameter (equivalent to existing ``path`` parameter).
+- :func:`pytest_pycollect_makemodule <_pytest.hookspec.pytest_pycollect_makemodule>` - The ``fspath`` parameter (equivalent to existing ``path`` parameter).
+- :func:`pytest_report_header <_pytest.hookspec.pytest_report_header>` - The ``startpath`` parameter (equivalent to existing ``startdir`` parameter).
+- :func:`pytest_report_collectionfinish <_pytest.hookspec.pytest_report_collectionfinish>` - The ``startpath`` parameter (equivalent to existing ``startdir`` parameter).

changelog/8174.trivial.rst

@@ -0,0 +1,6 @@
+The following changes have been made to internal pytest types/functions:
+
+- The ``path`` property of ``_pytest.code.Code`` returns ``Path`` instead of ``py.path.local``.
+- The ``path`` property of ``_pytest.code.TracebackEntry`` returns ``Path`` instead of ``py.path.local``.
+- The ``_pytest.code.getfslineno()`` function returns ``Path`` instead of ``py.path.local``.
+- The ``_pytest.python.path_matches_patterns()`` function takes ``Path`` instead of ``py.path.local``.

changelog/8192.bugfix.rst

@@ -0,0 +1,3 @@
+``testdir.makefile`` now silently accepts values which don't start with ``.`` to maintain backward compatibility with older pytest versions.
+
+``pytester.makefile`` now issues a clearer error if the ``.`` is missing in the ``ext`` argument.

changelog/8242.deprecation.rst

@@ -0,0 +1,7 @@
+Raising :class:`unittest.SkipTest` to skip collection of tests during the
+pytest collection phase is deprecated. Use :func:`pytest.skip` instead.
+
+Note: This deprecation only relates to using `unittest.SkipTest` during test
+collection. You are probably not doing that. Ordinary usage of
+:class:`unittest.SkipTest` / :meth:`unittest.TestCase.skipTest` /
+:func:`unittest.skip` in unittest test cases is fully supported.

changelog/8248.trivial.rst

@@ -0,0 +1 @@
+Internal Restructure: let python.PyObjMixing inherit from nodes.Node to carry over typing information.

changelog/8251.deprecation.rst

@@ -0,0 +1 @@
+Deprecate ``Node.fspath`` as we plan to move off `py.path.local <https://py.readthedocs.io/en/latest/path.html>`__ and switch to :mod:``pathlib``.

changelog/8251.feature.rst

@@ -0,0 +1 @@
+Implement ``Node.path`` as a ``pathlib.Path``.

changelog/8258.bugfix.rst

@@ -0,0 +1,3 @@
+Fixed issue where pytest's ``faulthandler`` support would not dump traceback on crashes
+if the :mod:`faulthandler` module was already enabled during pytest startup (using
+``python -X dev -m pytest`` for example).

changelog/8315.deprecation.rst

@@ -0,0 +1,5 @@
+Several behaviors of :meth:`Parser.addoption <_pytest.config.argparsing.Parser.addoption>` are now
+scheduled for removal in pytest 7 (deprecated since pytest 2.4.0):
+
+- ``parser.addoption(..., help=".. %default ..")`` - use ``%(default)s`` instead.
+- ``parser.addoption(..., type="int/string/float/complex")`` - use ``type=int`` etc. instead.

changelog/8317.bugfix.rst

@@ -0,0 +1 @@
+Fixed an issue where illegal directory characters derived from ``getpass.getuser()`` raised an ``OSError``.

changelog/8367.bugfix.rst

@@ -0,0 +1 @@
+Fix ``Class.from_parent`` so it forwards extra keyword arguments to the constructor.

changelog/8384.bugfix.rst

@@ -0,0 +1 @@
+The ``@pytest.mark.skip`` decorator now correctly handles its arguments. When the ``reason`` argument is accidentally given both positional and as a keyword (e.g. because it was confused with ``skipif``), a ``TypeError`` now occurs. Before, such tests were silently skipped, and the positional argument ignored. Additionally, ``reason`` is now documented correctly as positional or keyword (rather than keyword-only).

changelog/8394.bugfix.rst

@@ -0,0 +1 @@
+Use private names for internal fixtures that handle classic setup/teardown so that they don't show up with the default ``--fixtures`` invocation (but they still show up with ``--fixtures -v``).

changelog/8403.improvement.rst

@@ -0,0 +1,5 @@
+By default, pytest will truncate long strings in assert errors so they don't clutter the output too much,
+currently at ``240`` characters by default.
+
+However, in some cases the longer output helps, or is even crucial, to diagnose a failure. Using ``-v`` will
+now increase the truncation threshold to ``2400`` characters, and ``-vv`` or higher will disable truncation entirely.

changelog/8411.trivial.rst

@@ -0,0 +1 @@
+Assert the outcomes for the issue 518 test and fix the test.

changelog/8421.feature.rst

@@ -0,0 +1 @@
+:func:`pytest.approx` now works on :class:`~decimal.Decimal` within mappings/dicts and sequences/lists.

changelog/8456.bugfix.rst

@@ -0,0 +1 @@
+The :confval:`required_plugins` config option now works correctly when pre-releases of plugins are installed, rather than falsely claiming that those plugins aren't installed at all.

changelog/8464.bugfix.rst

@@ -0,0 +1 @@
+``-c <config file>`` now also properly defines ``rootdir`` as the directory that contains ``<config file>``.

changelog/8494.feature.rst

@@ -0,0 +1 @@
+Python 3.10 is now supported.

changelog/8503.trivial.rst

@@ -0,0 +1,4 @@
+:meth:`pytest.MonkeyPatch.syspath_prepend` no longer fails when
+``setuptools`` is not installed.
+It now only calls :func:`pkg_resources.fixup_namespace_packages` if
+``pkg_resources`` was previously imported, because it is not needed otherwise.

changelog/8539.bugfix.rst

@@ -0,0 +1 @@
+Fixed assertion rewriting on Python 3.10.

doc/en/_templates/globaltoc.html

@@ -1,12 +1,19 @@
-<h3><a href="{{ pathto(master_doc) }}">{{ _('Table Of Contents') }}</a></h3>
+<h3>Contents</h3>
 
 <ul>
   <li><a href="{{ pathto('index') }}">Home</a></li>
-  <li><a href="{{ pathto('getting-started') }}">Install</a></li>
-  <li><a href="{{ pathto('contents') }}">Contents</a></li>
-  <li><a href="{{ pathto('reference') }}">API Reference</a></li>
-  <li><a href="{{ pathto('example/index') }}">Examples</a></li>
-  <li><a href="{{ pathto('customize') }}">Customize</a></li>
+
+  <li><a href="{{ pathto('getting-started') }}">Get started</a></li>
+  <li><a href="{{ pathto('how-to/index') }}">How-to guides</a></li>
+  <li><a href="{{ pathto('reference/index') }}">Reference guides</a></li>
+  <li><a href="{{ pathto('explanation/index') }}">Explanation</a></li>
+  <li><a href="{{ pathto('contents') }}">Complete table of contents</a></li>
+  <li><a href="{{ pathto('example/index') }}">Library of examples</a></li>
+</ul>
+
+<h3>About the project</h3>
+
+<ul>
   <li><a href="{{ pathto('changelog') }}">Changelog</a></li>
   <li><a href="{{ pathto('contributing') }}">Contributing</a></li>
   <li><a href="{{ pathto('backwards-compatibility') }}">Backwards Compatibility</a></li>

doc/en/_templates/links.html

@@ -2,7 +2,6 @@
 <ul>
   <li><a href="https://pypi.org/project/pytest/">pytest @ PyPI</a></li>
   <li><a href="https://github.com/pytest-dev/pytest/">pytest @ GitHub</a></li>
-  <li><a href="http://plugincompat.herokuapp.com/">3rd party plugins</a></li>
   <li><a href="https://github.com/pytest-dev/pytest/issues">Issue Tracker</a></li>
   <li><a href="https://media.readthedocs.org/pdf/pytest/latest/pytest.pdf">PDF Documentation</a>
 </ul>

doc/en/announce/index.rst

@@ -6,6 +6,9 @@ Release announcements
    :maxdepth: 2
 
 
+   release-6.2.3
+   release-6.2.2
+   release-6.2.1
    release-6.2.0
    release-6.1.2
    release-6.1.1

doc/en/announce/release-2.1.0.rst

@@ -24,7 +24,7 @@ If you want to install or upgrade pytest, just type one of::
     easy_install -U pytest
 
 best,
-holger krekel / http://merlinux.eu
+holger krekel / https://merlinux.eu/
 
 Changes between 2.0.3 and 2.1.0
 ----------------------------------------------

doc/en/announce/release-2.1.1.rst

@@ -20,7 +20,7 @@ If you want to install or upgrade pytest, just type one of::
     easy_install -U pytest
 
 best,
-holger krekel / http://merlinux.eu
+holger krekel / https://merlinux.eu/
 
 Changes between 2.1.0 and 2.1.1
 ----------------------------------------------

doc/en/announce/release-2.1.2.rst

@@ -19,7 +19,7 @@ If you want to install or upgrade pytest, just type one of::
     easy_install -U pytest
 
 best,
-holger krekel / http://merlinux.eu
+holger krekel / https://merlinux.eu/
 
 Changes between 2.1.1 and 2.1.2
 ----------------------------------------

doc/en/announce/release-6.2.1.rst

@@ -0,0 +1,20 @@
+pytest-6.2.1
+=======================================
+
+pytest 6.2.1 has just been released to PyPI.
+
+This is a bug-fix release, being a drop-in replacement. To upgrade::
+
+  pip install --upgrade pytest
+
+The full changelog is available at https://docs.pytest.org/en/stable/changelog.html.
+
+Thanks to all of the contributors to this release:
+
+* Bruno Oliveira
+* Jakob van Santen
+* Ran Benita
+
+
+Happy testing,
+The pytest Development Team

doc/en/announce/release-6.2.2.rst

@@ -0,0 +1,21 @@
+pytest-6.2.2
+=======================================
+
+pytest 6.2.2 has just been released to PyPI.
+
+This is a bug-fix release, being a drop-in replacement. To upgrade::
+
+  pip install --upgrade pytest
+
+The full changelog is available at https://docs.pytest.org/en/stable/changelog.html.
+
+Thanks to all of the contributors to this release:
+
+* Adam Johnson
+* Bruno Oliveira
+* Chris NeJame
+* Ran Benita
+
+
+Happy testing,
+The pytest Development Team

doc/en/announce/release-6.2.3.rst

@@ -0,0 +1,19 @@
+pytest-6.2.3
+=======================================
+
+pytest 6.2.3 has just been released to PyPI.
+
+This is a bug-fix release, being a drop-in replacement. To upgrade::
+
+  pip install --upgrade pytest
+
+The full changelog is available at https://docs.pytest.org/en/stable/changelog.html.
+
+Thanks to all of the contributors to this release:
+
+* Bruno Oliveira
+* Ran Benita
+
+
+Happy testing,
+The pytest Development Team

doc/en/builtin.rst

@@ -6,7 +6,7 @@ Pytest API and builtin fixtures
 ================================================
 
 
-Most of the information of this page has been moved over to :ref:`reference`.
+Most of the information of this page has been moved over to :ref:`api-reference`.
 
 For information on plugin hooks and objects, see :ref:`plugins`.
 
@@ -144,14 +144,14 @@ For information about fixtures, see :ref:`fixtures`. To see a complete list of a
     recwarn
         Return a :class:`WarningsRecorder` instance that records all warnings emitted by test functions.
 
-        See http://docs.python.org/library/warnings.html for information
+        See https://docs.python.org/library/warnings.html for information
         on warning categories.
 
     tmpdir_factory [session scope]
-        Return a :class:`_pytest.tmpdir.TempdirFactory` instance for the test session.
+        Return a :class:`pytest.TempdirFactory` instance for the test session.
 
     tmp_path_factory [session scope]
-        Return a :class:`_pytest.tmpdir.TempPathFactory` instance for the test session.
+        Return a :class:`pytest.TempPathFactory` instance for the test session.
 
     tmpdir
         Return a temporary directory path object which is unique to each test

doc/en/changelog.rst

@@ -28,6 +28,58 @@ with advance notice in the **Deprecations** section of releases.
 
 .. towncrier release notes start
 
+pytest 6.2.3 (2021-04-03)
+=========================
+
+Bug Fixes
+---------
+
+- `#8414 <https://github.com/pytest-dev/pytest/issues/8414>`_: pytest used to create directories under ``/tmp`` with world-readable
+  permissions. This means that any user in the system was able to read
+  information written by tests in temporary directories (such as those created by
+  the ``tmp_path``/``tmpdir`` fixture). Now the directories are created with
+  private permissions.
+
+  pytest used to silenty use a pre-existing ``/tmp/pytest-of-<username>`` directory,
+  even if owned by another user. This means another user could pre-create such a
+  directory and gain control of another user's temporary directory. Now such a
+  condition results in an error.
+
+
+pytest 6.2.2 (2021-01-25)
+=========================
+
+Bug Fixes
+---------
+
+- `#8152 <https://github.com/pytest-dev/pytest/issues/8152>`_: Fixed "(<Skipped instance>)" being shown as a skip reason in the verbose test summary line when the reason is empty.
+
+
+- `#8249 <https://github.com/pytest-dev/pytest/issues/8249>`_: Fix the ``faulthandler`` plugin for occasions when running with ``twisted.logger`` and using ``pytest --capture=no``.
+
+
+pytest 6.2.1 (2020-12-15)
+=========================
+
+Bug Fixes
+---------
+
+- `#7678 <https://github.com/pytest-dev/pytest/issues/7678>`_: Fixed bug where ``ImportPathMismatchError`` would be raised for files compiled in
+  the host and loaded later from an UNC mounted path (Windows).
+
+
+- `#8132 <https://github.com/pytest-dev/pytest/issues/8132>`_: Fixed regression in ``approx``: in 6.2.0 ``approx`` no longer raises
+  ``TypeError`` when dealing with non-numeric types, falling back to normal comparison.
+  Before 6.2.0, array types like tf.DeviceArray fell through to the scalar case,
+  and happened to compare correctly to a scalar if they had only one element.
+  After 6.2.0, these types began failing, because they inherited neither from
+  standard Python number hierarchy nor from ``numpy.ndarray``.
+
+  ``approx`` now converts arguments to ``numpy.ndarray`` if they expose the array
+  protocol and are not scalars. This treats array-like objects like numpy arrays,
+  regardless of size.
+
+
 pytest 6.2.0 (2020-12-12)
 =========================
 
@@ -994,7 +1046,7 @@ Bug Fixes
 - `#7110 <https://github.com/pytest-dev/pytest/issues/7110>`_: Fixed regression: ``asyncbase.TestCase`` tests are executed correctly again.
 
 
-- `#7143 <https://github.com/pytest-dev/pytest/issues/7143>`_: Fix ``File.from_constructor`` so it forwards extra keyword arguments to the constructor.
+- `#7143 <https://github.com/pytest-dev/pytest/issues/7143>`_: Fix ``File.from_parent`` so it forwards extra keyword arguments to the constructor.
 
 
 - `#7145 <https://github.com/pytest-dev/pytest/issues/7145>`_: Classes with broken ``__getattribute__`` methods are displayed correctly during failures.
@@ -3056,12 +3108,12 @@ Features
   will not issue the warning.
 
 
-- `#3632 <https://github.com/pytest-dev/pytest/issues/3632>`_: Richer equality comparison introspection on ``AssertionError`` for objects created using `attrs <http://www.attrs.org/en/stable/>`__ or `dataclasses <https://docs.python.org/3/library/dataclasses.html>`_ (Python 3.7+, `backported to 3.6 <https://pypi.org/project/dataclasses>`__).
+- `#3632 <https://github.com/pytest-dev/pytest/issues/3632>`_: Richer equality comparison introspection on ``AssertionError`` for objects created using `attrs <https://www.attrs.org/en/stable/>`__ or `dataclasses <https://docs.python.org/3/library/dataclasses.html>`_ (Python 3.7+, `backported to 3.6 <https://pypi.org/project/dataclasses>`__).
 
 
 - `#4278 <https://github.com/pytest-dev/pytest/issues/4278>`_: ``CACHEDIR.TAG`` files are now created inside cache directories.
 
-  Those files are part of the `Cache Directory Tagging Standard <http://www.bford.info/cachedir/spec.html>`__, and can
+  Those files are part of the `Cache Directory Tagging Standard <https://bford.info/cachedir/spec.html>`__, and can
   be used by backup or synchronization programs to identify pytest's cache directory as such.
 
 
@@ -5045,7 +5097,7 @@ Improved Documentation
 
 - In one of the simple examples, use ``pytest_collection_modifyitems()`` to skip
   tests based on a command-line option, allowing its sharing while preventing a
-  user error when acessing ``pytest.config`` before the argument parsing.
+  user error when accessing ``pytest.config`` before the argument parsing.
   (`#2653 <https://github.com/pytest-dev/pytest/issues/2653>`_)
 
 
@@ -5457,7 +5509,7 @@ Changes
   Thanks `@ojii`_ for the PR.
 
 * Replace minor/patch level version numbers in the documentation with placeholders.
-  This significantly reduces change-noise as different contributors regnerate
+  This significantly reduces change-noise as different contributors regenerate
   the documentation on different platforms.
   Thanks `@RonnyPfannschmidt`_ for the PR.
 
@@ -8414,7 +8466,7 @@ Bug fixes:
 
 - fixes for making the jython/win32 combination work, note however:
   jython2.5.1/win32 does not provide a command line launcher, see
-  http://bugs.jython.org/issue1491 . See pylib install documentation
+  https://bugs.jython.org/issue1491 . See pylib install documentation
   for how to work around.
 
 - fixes for handling of unicode exception values and unprintable objects

doc/en/conf.py

@@ -35,6 +35,7 @@ release = ".".join(version.split(".")[:2])
 # sys.path.insert(0, os.path.abspath('.'))
 
 autodoc_member_order = "bysource"
+autodoc_typehints = "description"
 todo_include_todos = 1
 
 # -- General configuration -----------------------------------------------------
@@ -159,7 +160,7 @@ html_short_title = "pytest-%s" % release
 
 # The name of an image file (relative to this directory) to place at the top
 # of the sidebar.
-html_logo = "img/pytest1.png"
+html_logo = "img/pytest_logo_curves.svg"
 
 # The name of an image file (within the static path) to use as favicon of the
 # docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
@@ -251,7 +252,7 @@ latex_documents = [
         "contents",
         "pytest.tex",
         "pytest Documentation",
-        "holger krekel, trainer and consultant, http://merlinux.eu",
+        "holger krekel, trainer and consultant, https://merlinux.eu/",
         "manual",
     )
 ]

doc/en/contact.rst

@@ -30,19 +30,19 @@ Contact channels
   consulting.
 
 .. _`pytest issue tracker`: https://github.com/pytest-dev/pytest/issues
-.. _`old issue tracker`: http://bitbucket.org/hpk42/py-trunk/issues/
+.. _`old issue tracker`: https://bitbucket.org/hpk42/py-trunk/issues/
 
-.. _`merlinux.eu`: http://merlinux.eu
+.. _`merlinux.eu`: https://merlinux.eu/
 
 .. _`get an account`:
 
-.. _tetamap: http://tetamap.wordpress.com
+.. _tetamap: https://tetamap.wordpress.com/
 
-.. _`@pylibcommit`: http://twitter.com/pylibcommit
+.. _`@pylibcommit`: https://twitter.com/pylibcommit
 
 
 .. _`Testing in Python`: http://lists.idyll.org/listinfo/testing-in-python
-.. _FOAF: http://en.wikipedia.org/wiki/FOAF
+.. _FOAF: https://en.wikipedia.org/wiki/FOAF
 .. _`py-dev`:
 .. _`development mailing list`:
 .. _`pytest-dev at python.org (mailing list)`: http://mail.python.org/mailman/listinfo/pytest-dev

doc/en/contents.rst

@@ -7,37 +7,81 @@ Full pytest documentation
 
 .. `Download latest version as EPUB <http://media.readthedocs.org/epub/pytest/latest/pytest.epub>`_
 
+
+Start here
+-----------
+
 .. toctree::
    :maxdepth: 2
 
    getting-started
-   usage
-   existingtestsuite
-   assert
-   fixture
-   mark
-   monkeypatch
-   tmpdir
-   capture
-   warnings
-   doctest
-   skipping
-   parametrize
-   cache
-   unittest
-   nose
-   xunit_setup
-   plugins
-   writing_plugins
-   logging
-   reference
 
-   goodpractices
-   flaky
-   pythonpath
-   customize
+
+How-to guides
+-------------
+
+.. toctree::
+   :maxdepth: 2
+
+   how-to/usage
+   how-to/assert
+   how-to/fixtures
+   how-to/mark
+   how-to/parametrize
+   how-to/tmpdir
+   how-to/monkeypatch
+   how-to/doctest
+   how-to/cache
+
+   how-to/logging
+   how-to/capture-stdout-stderr
+   how-to/capture-warnings
+   how-to/skipping
+
+   how-to/plugins
+   how-to/writing_plugins
+   how-to/writing_hook_functions
+
+   how-to/existingtestsuite
+   how-to/unittest
+   how-to/nose
+   how-to/xunit_setup
+
+   how-to/bash-completion
+
+
+Reference guides
+-----------------
+
+.. toctree::
+   :maxdepth: 2
+
+   reference/fixtures
+   reference/plugin_list
+   reference/customize
+   reference/reference
+
+
+Explanation
+-----------------
+
+.. toctree::
+   :maxdepth: 2
+
+   explanation/anatomy
+   explanation/fixtures
+   explanation/goodpractices
+   explanation/flaky
+   explanation/pythonpath
+
+
+Further topics
+-----------------
+
+.. toctree::
+   :maxdepth: 2
+
    example/index
-   bash-completion
 
    backwards-compatibility
    deprecations

doc/en/deprecations.rst

@@ -18,6 +18,57 @@ Deprecated Features
 Below is a complete list of all pytest features which are considered deprecated. Using those features will issue
 :class:`PytestWarning` or subclasses, which can be filtered using :ref:`standard warning filters <warnings>`.
 
+
+``py.path.local`` arguments for hooks replaced with ``pathlib.Path``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In order to support the transition to :mod:`pathlib`, the following hooks now receive additional arguments:
+
+*  :func:`pytest_ignore_collect(fspath: pathlib.Path) <_pytest.hookspec.pytest_ignore_collect>`
+*  :func:`pytest_collect_file(fspath: pathlib.Path) <_pytest.hookspec.pytest_collect_file>`
+*  :func:`pytest_pycollect_makemodule(fspath: pathlib.Path) <_pytest.hookspec.pytest_pycollect_makemodule>`
+*  :func:`pytest_report_header(startpath: pathlib.Path) <_pytest.hookspec.pytest_report_header>`
+*  :func:`pytest_report_collectionfinish(startpath: pathlib.Path) <_pytest.hookspec.pytest_report_collectionfinish>`
+
+The accompanying ``py.path.local`` based paths have been deprecated: plugins which manually invoke those hooks should only pass the new ``pathlib.Path`` arguments, and users should change their hook implementations to use the new ``pathlib.Path`` arguments.
+
+
+``Node.fspath`` in favor of ``pathlib`` and ``Node.path``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. deprecated:: 6.3
+
+As pytest tries to move off `py.path.local <https://py.readthedocs.io/en/latest/path.html>`__ we ported most of the node internals to :mod:`pathlib`.
+
+Pytest will provide compatibility for quite a while.
+
+
+Backward compatibilities in ``Parser.addoption``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. deprecated:: 2.4
+
+Several behaviors of :meth:`Parser.addoption <_pytest.config.argparsing.Parser.addoption>` are now
+scheduled for removal in pytest 7 (deprecated since pytest 2.4.0):
+
+- ``parser.addoption(..., help=".. %default ..")`` - use ``%(default)s`` instead.
+- ``parser.addoption(..., type="int/string/float/complex")`` - use ``type=int`` etc. instead.
+
+
+Raising ``unittest.SkipTest`` during collection
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. deprecated:: 6.3
+
+Raising :class:`unittest.SkipTest` to skip collection of tests during the
+pytest collection phase is deprecated. Use :func:`pytest.skip` instead.
+
+Note: This deprecation only relates to using `unittest.SkipTest` during test
+collection. You are probably not doing that. Ordinary usage of
+:class:`unittest.SkipTest` / :meth:`unittest.TestCase.skipTest` /
+:func:`unittest.skip` in unittest test cases is fully supported.
+
+
 The ``--strict`` command-line option
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -397,8 +448,8 @@ Metafunc.addcall
 
 .. versionremoved:: 4.0
 
-``_pytest.python.Metafunc.addcall`` was a precursor to the current parametrized mechanism. Users should use
-:meth:`_pytest.python.Metafunc.parametrize` instead.
+``Metafunc.addcall`` was a precursor to the current parametrized mechanism. Users should use
+:meth:`pytest.Metafunc.parametrize` instead.
 
 Example:
 

doc/en/development_guide.rst

@@ -4,4 +4,4 @@ Development Guide
 
 The contributing guidelines are to be found :ref:`here <contributing>`.
 The release procedure for pytest is documented on
-`GitHub <https://github.com/pytest-dev/pytest/blob/master/RELEASING.rst>`_.
+`GitHub <https://github.com/pytest-dev/pytest/blob/main/RELEASING.rst>`_.

doc/en/example/assertion/test_failures.py

@@ -5,9 +5,9 @@ failure_demo = os.path.join(os.path.dirname(__file__), "failure_demo.py")
 pytest_plugins = ("pytester",)
 
 
-def test_failure_demo_fails_properly(testdir):
-    target = testdir.tmpdir.join(os.path.basename(failure_demo))
+def test_failure_demo_fails_properly(pytester):
+    target = pytester.path.joinpath(os.path.basename(failure_demo))
     shutil.copy(failure_demo, target)
-    result = testdir.runpytest(target, syspathinsert=True)
+    result = pytester.runpytest(target, syspathinsert=True)
     result.stdout.fnmatch_lines(["*44 failed*"])
     assert result.ret != 0

doc/en/example/fixtures/fixture_availability.svg

@@ -0,0 +1,132 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="572" height="542">
+    <style>
+        text {
+            font-family: 'Consolas', 'Menlo', 'DejaVu Sans Mono', 'Bitstream Vera Sans Mono', monospace;
+            dominant-baseline: middle;
+            text-anchor: middle;
+            fill: #062886;
+            font-size: medium;
+        }
+        ellipse.fixture, rect.test {
+            fill: #eeffcc;
+            stroke: #007020;
+            stroke-width: 2;
+        }
+        text.fixture {
+            color: #06287e;
+        }
+        circle.class, circle.module, circle.package {
+            fill: #c3e0ec;
+            stroke: #0e84b5;
+            stroke-width: 2;
+        }
+        text.class, text.module, text.package {
+            fill: #0e84b5;
+        }
+        line, path {
+            stroke: black;
+            stroke-width: 2;
+            fill: none;
+        }
+    </style>
+
+    <!-- main scope -->
+    <circle class="package" r="270" cx="286" cy="271" />
+    <!-- scope name -->
+    <defs>
+        <path d="M 26,271 A 260 260 0 0 1 546 271" id="testp"/>
+    </defs>
+    <text class="package">
+        <textPath href="#testp" startOffset="50%">tests</textPath>
+    </text>
+
+    <!-- subpackage -->
+    <circle class="package" r="140" cx="186" cy="271" />
+    <!-- scope name -->
+    <defs>
+        <path d="M 56,271 A 130 130 0 0 1 316 271" id="subpackage"/>
+    </defs>
+    <text class="package">
+        <textPath href="#subpackage" startOffset="50%">subpackage</textPath>
+    </text>
+
+    <!-- test_subpackage.py -->
+    <circle class="module" r="90" cx="186" cy="311" />
+    <!-- scope name -->
+    <defs>
+        <path d="M 106,311 A 80 80 0 0 1 266 311" id="testSubpackage"/>
+    </defs>
+    <text class="module">
+        <textPath href="#testSubpackage" startOffset="50%">test_subpackage.py</textPath>
+    </text>
+    <!-- innermost -->
+    <line x1="186" x2="186" y1="271" y2="351"/>
+    <!-- mid -->
+    <path d="M 186 351 L 136 351 L 106 331 L 106 196" />
+    <!-- order -->
+    <path d="M 186 351 L 256 351 L 316 291 L 316 136" />
+    <!-- top -->
+    <path d="M 186 351 L 186 391 L 231 436 L 331 436" />
+    <ellipse class="fixture" rx="50" ry="25" cx="186" cy="271" />
+    <text x="186" y="271">innermost</text>
+    <rect class="test" width="110" height="50" x="131" y="326" />
+    <text x="186" y="351">test_order</text>
+    <ellipse class="fixture" rx="50" ry="25" cx="126" cy="196" />
+    <text x="126" y="196">mid</text>
+    <!-- scope order number -->
+    <mask id="testSubpackageOrderMask">
+        <rect x="0" y="0" width="100%" height="100%" fill="white"/>
+        <circle fill="black" stroke="white" stroke-width="2" r="90" cx="186" cy="311" />
+    </mask>
+    <circle class="module" r="15" cx="96" cy="311" mask="url(#testSubpackageOrderMask)"/>
+    <text class="module" x="96" y="311">1</text>
+     <!-- scope order number -->
+    <mask id="subpackageOrderMask">
+        <rect x="0" y="0" width="100%" height="100%" fill="white"/>
+        <circle fill="black" stroke="white" stroke-width="2" r="140" cx="186" cy="271" />
+    </mask>
+    <circle class="module" r="15" cx="46" cy="271" mask="url(#subpackageOrderMask)"/>
+    <text class="module" x="46" y="271">2</text>
+    <!-- scope order number -->
+    <mask id="testsOrderMask">
+        <rect x="0" y="0" width="100%" height="100%" fill="white"/>
+        <circle fill="black" stroke="white" stroke-width="2" r="270" cx="286" cy="271" />
+    </mask>
+    <circle class="module" r="15" cx="16" cy="271" mask="url(#testsOrderMask)"/>
+    <text class="module" x="16" y="271">3</text>
+
+    <!-- test_top.py -->
+    <circle class="module" r="85" cx="441" cy="271" />
+    <!-- scope name -->
+    <defs>
+        <path d="M 366,271 A 75 75 0 0 1 516 271" id="testTop"/>
+    </defs>
+    <text class="module">
+        <textPath href="#testTop" startOffset="50%">test_top.py</textPath>
+    </text>
+    <!-- innermost -->
+    <line x1="441" x2="441" y1="306" y2="236"/>
+    <!-- order -->
+    <path d="M 441 306 L 376 306 L 346 276 L 346 136" />
+    <!-- top -->
+    <path d="M 441 306 L 441 411 L 411 436 L 331 436" />
+    <ellipse class="fixture" rx="50" ry="25" cx="441" cy="236" />
+    <text x="441" y="236">innermost</text>
+    <rect class="test" width="110" height="50" x="386" y="281" />
+    <text x="441" y="306">test_order</text>
+    <!-- scope order number -->
+    <mask id="testTopOrderMask">
+        <rect x="0" y="0" width="100%" height="100%" fill="white"/>
+        <circle fill="black" stroke="white" stroke-width="2" r="85" cx="441" cy="271" />
+    </mask>
+    <circle class="module" r="15" cx="526" cy="271" mask="url(#testTopOrderMask)"/>
+    <text class="module" x="526" y="271">1</text>
+    <!-- scope order number -->
+    <circle class="module" r="15" cx="556" cy="271" mask="url(#testsOrderMask)"/>
+    <text class="module" x="556" y="271">2</text>
+
+    <ellipse class="fixture" rx="50" ry="25" cx="331" cy="436" />
+    <text x="331" y="436">top</text>
+    <ellipse class="fixture" rx="50" ry="25" cx="331" cy="136" />
+    <text x="331" y="136">order</text>
+</svg>

doc/en/example/fixtures/fixture_availability_plugins.svg

@@ -0,0 +1,142 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="587" height="382">
+    <style>
+        text {
+            font-family: 'Consolas', 'Menlo', 'DejaVu Sans Mono', 'Bitstream Vera Sans Mono', monospace;
+            dominant-baseline: middle;
+            text-anchor: middle;
+            fill: #062886;
+            font-size: medium;
+            alignment-baseline: center;
+        }
+        ellipse.fixture, rect.test {
+            fill: #eeffcc;
+            stroke: #007020;
+            stroke-width: 2;
+        }
+        text.fixture {
+            color: #06287e;
+        }
+        circle.class, circle.module, circle.package, circle.plugin {
+            fill: #c3e0ec;
+            stroke: #0e84b5;
+            stroke-width: 2;
+        }
+        text.class, text.module, text.package, text.plugin {
+            fill: #0e84b5;
+        }
+        line, path {
+            stroke: black;
+            stroke-width: 2;
+            fill: none;
+        }
+    </style>
+
+    <!-- plugin_a.py scope -->
+    <circle class="plugin" r="85" cx="486" cy="86" />
+    <!-- plugin name -->
+    <defs>
+        <path d="M 411,86 A 75 75 0 0 1 561 86" id="pluginA"/>
+    </defs>
+    <text class="plugin">
+        <textPath href="#pluginA" startOffset="50%">plugin_a</textPath>
+    </text>
+    <!-- scope order number -->
+    <mask id="pluginAOrderMask">
+        <rect x="0" y="0" width="100%" height="100%" fill="white"/>
+        <circle fill="black" stroke="white" stroke-width="2" r="85" cx="486" cy="86" />
+    </mask>
+    <circle class="module" r="15" cx="571" cy="86" mask="url(#pluginAOrderMask)"/>
+    <text class="module" x="571" y="86">4</text>
+
+    <!-- plugin_b.py scope -->
+    <circle class="plugin" r="85" cx="486" cy="296" />
+    <!-- plugin name -->
+    <defs>
+        <path d="M 411,296 A 75 75 0 0 1 561 296" id="pluginB"/>
+    </defs>
+    <text class="plugin">
+        <textPath href="#pluginB" startOffset="50%">plugin_b</textPath>
+    </text>
+    <!-- scope order number -->
+    <mask id="pluginBOrderMask">
+        <rect x="0" y="0" width="100%" height="100%" fill="white"/>
+        <circle fill="black" stroke="white" stroke-width="2" r="85" cx="486" cy="296" />
+    </mask>
+    <circle class="module" r="15" cx="571" cy="296" mask="url(#pluginBOrderMask)"/>
+    <text class="module" x="571" y="296">4</text>
+
+    <!-- main scope -->
+    <circle class="package" r="190" cx="191" cy="191" />
+    <!-- scope name -->
+    <defs>
+        <path d="M 11,191 A 180 180 0 0 1 371 191" id="testp"/>
+    </defs>
+    <text class="package">
+        <textPath href="#testp" startOffset="50%">tests</textPath>
+    </text>
+    <!-- scope order number -->
+    <mask id="mainOrderMask">
+        <rect x="0" y="0" width="100%" height="100%" fill="white"/>
+        <circle fill="black" stroke="white" stroke-width="2" r="190" cx="191" cy="191" />
+    </mask>
+    <circle class="module" r="15" cx="381" cy="191" mask="url(#mainOrderMask)"/>
+    <text class="module" x="381" y="191">3</text>
+
+    <!-- subpackage -->
+    <circle class="package" r="140" cx="191" cy="231" />
+    <!-- scope name -->
+    <defs>
+        <path d="M 61,231 A 130 130 0 0 1 321 231" id="subpackage"/>
+    </defs>
+    <text class="package">
+        <textPath href="#subpackage" startOffset="50%">subpackage</textPath>
+    </text>
+    <!-- scope order number -->
+    <mask id="subpackageOrderMask">
+        <rect x="0" y="0" width="100%" height="100%" fill="white"/>
+        <circle fill="black" stroke="white" stroke-width="2" r="140" cx="191" cy="231" />
+    </mask>
+    <circle class="module" r="15" cx="331" cy="231" mask="url(#subpackageOrderMask)"/>
+    <text class="module" x="331" y="231">2</text>
+
+    <!-- test_subpackage.py -->
+    <circle class="module" r="90" cx="191" cy="271" />
+    <!-- scope name -->
+    <defs>
+        <path d="M 111,271 A 80 80 0 0 1 271 271" id="testSubpackage"/>
+    </defs>
+    <text class="module">
+        <textPath href="#testSubpackage" startOffset="50%">test_subpackage.py</textPath>
+    </text>
+    <!-- scope order number -->
+    <mask id="testSubpackageOrderMask">
+        <rect x="0" y="0" width="100%" height="100%" fill="white"/>
+        <circle fill="black" stroke="white" stroke-width="2" r="90" cx="191" cy="271" />
+    </mask>
+    <circle class="module" r="15" cx="281" cy="271" mask="url(#testSubpackageOrderMask)"/>
+    <text class="module" x="281" y="271">1</text>
+
+    <!-- innermost -->
+    <line x1="191" x2="191" y1="231" y2="311"/>
+    <!-- mid -->
+    <path d="M 191 306 L 101 306 L 91 296 L 91 156 L 101 146 L 191 146" />
+    <!-- order -->
+    <path d="M 191 316 L 91 316 L 81 306 L 81 61 L 91 51 L 191 51" />
+    <!-- a_fix -->
+    <path d="M 191 306 L 291 306 L 301 296 L 301 96 L 311 86 L 486 86" />
+    <!-- b_fix -->
+    <path d="M 191 316 L 316 316 L 336 296 L 486 296" />
+    <ellipse class="fixture" rx="50" ry="25" cx="191" cy="231" />
+    <text x="191" y="231">inner</text>
+    <rect class="test" width="110" height="50" x="136" y="286" />
+    <text x="191" y="311">test_order</text>
+    <ellipse class="fixture" rx="50" ry="25" cx="191" cy="146" />
+    <text x="191" y="146">mid</text>
+    <ellipse class="fixture" rx="50" ry="25" cx="191" cy="51" />
+    <text x="191" y="51">order</text>
+
+    <ellipse class="fixture" rx="50" ry="25" cx="486" cy="86" />
+    <text x="486" y="86">a_fix</text>
+    <ellipse class="fixture" rx="50" ry="25" cx="486" cy="296" />
+    <text x="486" y="296">b_fix</text>
+</svg>

doc/en/example/fixtures/test_fixtures_order.py

@@ -1,38 +0,0 @@
-import pytest
-
-# fixtures documentation order example
-order = []
-
-
-@pytest.fixture(scope="session")
-def s1():
-    order.append("s1")
-
-
-@pytest.fixture(scope="module")
-def m1():
-    order.append("m1")
-
-
-@pytest.fixture
-def f1(f3):
-    order.append("f1")
-
-
-@pytest.fixture
-def f3():
-    order.append("f3")
-
-
-@pytest.fixture(autouse=True)
-def a1():
-    order.append("a1")
-
-
-@pytest.fixture
-def f2():
-    order.append("f2")
-
-
-def test_order(f1, m1, f2, s1):
-    assert order == ["s1", "m1", "a1", "f3", "f1", "f2"]

doc/en/example/fixtures/test_fixtures_order_autouse.py

@@ -0,0 +1,45 @@
+import pytest
+
+
+@pytest.fixture
+def order():
+    return []
+
+
+@pytest.fixture
+def a(order):
+    order.append("a")
+
+
+@pytest.fixture
+def b(a, order):
+    order.append("b")
+
+
+@pytest.fixture(autouse=True)
+def c(b, order):
+    order.append("c")
+
+
+@pytest.fixture
+def d(b, order):
+    order.append("d")
+
+
+@pytest.fixture
+def e(d, order):
+    order.append("e")
+
+
+@pytest.fixture
+def f(e, order):
+    order.append("f")
+
+
+@pytest.fixture
+def g(f, c, order):
+    order.append("g")
+
+
+def test_order_and_g(g, order):
+    assert order == ["a", "b", "c", "d", "e", "f", "g"]

doc/en/example/fixtures/test_fixtures_order_autouse.svg

@@ -0,0 +1,64 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="252" height="682">
+    <style>
+        text {
+            font-family: 'Consolas', 'Menlo', 'DejaVu Sans Mono', 'Bitstream Vera Sans Mono', monospace;
+            dominant-baseline: middle;
+            text-anchor: middle;
+            fill: #062886;
+            font-size: medium;
+        }
+        ellipse.fixture, rect.test {
+            fill: #eeffcc;
+            stroke: #007020;
+            stroke-width: 2;
+        }
+        text.fixture {
+            color: #06287e;
+        }
+        circle.class {
+            fill: #c3e0ec;
+            stroke: #0e84b5;
+            stroke-width: 2;
+        }
+        text.class {
+            fill: #0e84b5;
+        }
+        path, line {
+            stroke: black;
+            stroke-width: 2;
+            fill: none;
+        }
+        rect.autouse {
+            fill: #ca7f3d;
+        }
+    </style>
+    <path d="M126,586 L26,506 L26,236" />
+    <path d="M226,446 L226,236 L126,166" />
+    <line x1="126" x2="126" y1="656" y2="516" />
+    <line x1="126" x2="226" y1="516" y2="446" />
+    <line x1="226" x2="126" y1="446" y2="376" />
+    <line x1="126" x2="126" y1="376" y2="166" />
+    <line x1="26" x2="126" y1="236" y2="166" />
+    <line x1="126" x2="126" y1="166" y2="26" />
+    <line x1="126" x2="126" y1="96" y2="26" />
+    <rect class="autouse" width="251" height="40" x="0" y="286" />
+    <text x="126" y="306">autouse</text>
+    <ellipse class="fixture" rx="50" ry="25" cx="126" cy="26" />
+    <text x="126" y="26">order</text>
+    <ellipse class="fixture" rx="25" ry="25" cx="126" cy="96" />
+    <text x="126" y="96">a</text>
+    <ellipse class="fixture" rx="25" ry="25" cx="126" cy="166" />
+    <text x="126" y="166">b</text>
+    <ellipse class="fixture" rx="25" ry="25" cx="26" cy="236" />
+    <text x="26" y="236">c</text>
+    <ellipse class="fixture" rx="25" ry="25" cx="126" cy="376" />
+    <text x="126" y="376">d</text>
+    <ellipse class="fixture" rx="25" ry="25" cx="226" cy="446" />
+    <text x="226" y="446">e</text>
+    <ellipse class="fixture" rx="25" ry="25" cx="126" cy="516" />
+    <text x="126" y="516">f</text>
+    <ellipse class="fixture" rx="25" ry="25" cx="126" cy="586" />
+    <text x="126" y="586">g</text>
+    <rect class="test" width="110" height="50" x="71" y="631" />
+    <text x="126" y="656">test_order</text>
+</svg>

doc/en/example/fixtures/test_fixtures_order_autouse_multiple_scopes.py

@@ -0,0 +1,31 @@
+import pytest
+
+
+@pytest.fixture(scope="class")
+def order():
+    return []
+
+
+@pytest.fixture(scope="class", autouse=True)
+def c1(order):
+    order.append("c1")
+
+
+@pytest.fixture(scope="class")
+def c2(order):
+    order.append("c2")
+
+
+@pytest.fixture(scope="class")
+def c3(order, c1):
+    order.append("c3")
+
+
+class TestClassWithC1Request:
+    def test_order(self, order, c1, c3):
+        assert order == ["c1", "c3"]
+
+
+class TestClassWithoutC1Request:
+    def test_order(self, order, c2):
+        assert order == ["c1", "c2"]

doc/en/example/fixtures/test_fixtures_order_autouse_multiple_scopes.svg

@@ -0,0 +1,76 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="862" height="402">
+    <style>
+        text {
+            font-family: 'Consolas', 'Menlo', 'DejaVu Sans Mono', 'Bitstream Vera Sans Mono', monospace;
+            dominant-baseline: middle;
+            text-anchor: middle;
+            fill: #062886;
+            font-size: medium;
+        }
+        ellipse.fixture, rect.test {
+            fill: #eeffcc;
+            stroke: #007020;
+            stroke-width: 2;
+        }
+        text.fixture {
+            color: #06287e;
+        }
+        circle.class {
+            fill: #c3e0ec;
+            stroke: #0e84b5;
+            stroke-width: 2;
+        }
+        text.class {
+            fill: #0e84b5;
+        }
+        line {
+            stroke: black;
+            stroke-width: 2;
+        }
+        rect.autouse {
+            fill: #ca7f3d;
+        }
+    </style>
+
+    <!-- TestWithC1Request -->
+    <circle class="class" r="200" cx="221" cy="201" />
+    <line x1="221" x2="221" y1="61" y2="316"/>
+    <ellipse class="fixture" rx="50" ry="25" cx="221" cy="61" />
+    <text x="221" y="61">order</text>
+    <ellipse class="fixture" rx="25" ry="25" cx="221" cy="131" />
+    <text x="221" y="131">c1</text>
+    <ellipse class="fixture" rx="25" ry="25" cx="221" cy="271" />
+    <text x="221" y="271">c3</text>
+    <rect class="test" width="110" height="50" x="166" y="316" />
+    <text x="221" y="341">test_order</text>
+    <!-- scope name -->
+    <defs>
+        <path d="M31,201 A 190 190 0 0 1 411 201" id="testClassWith"/>
+    </defs>
+    <text class="class">
+        <textPath href="#testClassWith" startOffset="50%">TestWithC1Request</textPath>
+    </text>
+
+    <!-- TestWithoutC1Request -->
+    <circle class="class" r="200" cx="641" cy="201" />
+    <line x1="641" x2="641" y1="61" y2="316"/>
+    <ellipse class="fixture" rx="50" ry="25" cx="641" cy="61" />
+    <text x="641" y="61">order</text>
+    <ellipse class="fixture" rx="25" ry="25" cx="641" cy="131" />
+    <text x="641" y="131">c1</text>
+    <ellipse class="fixture" rx="25" ry="25" cx="641" cy="271" />
+    <text x="641" y="271">c2</text>
+    <rect class="test" width="110" height="50" x="586" y="316" />
+    <text x="641" y="341">test_order</text>
+    <!-- scope name -->
+    <defs>
+        <path d="M451,201 A 190 190 0 0 1 831 201" id="testClassWithout"/>
+    </defs>
+    <text class="class">
+        <textPath href="#testClassWithout" startOffset="50%">TestWithoutC1Request</textPath>
+    </text>
+
+    <rect class="autouse" width="862" height="40" x="1" y="181" />
+    <rect width="10" height="100" class="autouse" x="426" y="151" />
+    <text x="431" y="201">autouse</text>
+</svg>

doc/en/example/fixtures/test_fixtures_order_autouse_temp_effects.py

@@ -0,0 +1,36 @@
+import pytest
+
+
+@pytest.fixture
+def order():
+    return []
+
+
+@pytest.fixture
+def c1(order):
+    order.append("c1")
+
+
+@pytest.fixture
+def c2(order):
+    order.append("c2")
+
+
+class TestClassWithAutouse:
+    @pytest.fixture(autouse=True)
+    def c3(self, order, c2):
+        order.append("c3")
+
+    def test_req(self, order, c1):
+        assert order == ["c2", "c3", "c1"]
+
+    def test_no_req(self, order):
+        assert order == ["c2", "c3"]
+
+
+class TestClassWithoutAutouse:
+    def test_req(self, order, c1):
+        assert order == ["c1"]
+
+    def test_no_req(self, order):
+        assert order == []

doc/en/example/fixtures/test_fixtures_order_autouse_temp_effects.svg

@@ -0,0 +1,100 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="862" height="502">
+    <style>
+        text {
+            font-family: 'Consolas', 'Menlo', 'DejaVu Sans Mono', 'Bitstream Vera Sans Mono', monospace;
+            dominant-baseline: middle;
+            text-anchor: middle;
+            fill: #062886;
+            font-size: medium;
+        }
+        ellipse.fixture, rect.test {
+            fill: #eeffcc;
+            stroke: #007020;
+            stroke-width: 2;
+        }
+        text.fixture {
+            color: #06287e;
+        }
+        circle.class {
+            fill: #c3e0ec;
+            stroke: #0e84b5;
+            stroke-width: 2;
+        }
+        text.class {
+            fill: #0e84b5;
+        }
+        line {
+            stroke: black;
+            stroke-width: 2;
+        }
+        rect.autouse {
+            fill: #ca7f3d;
+        }
+    </style>
+
+    <!-- TestWithAutouse -->
+    <circle class="class" r="250" cx="251" cy="251" />
+    <!-- scope name -->
+    <defs>
+        <path d="M11,251 A 240 240 0 0 1 491 251" id="testClassWith"/>
+    </defs>
+    <text class="class">
+        <textPath href="#testClassWith" startOffset="50%">TestWithAutouse</textPath>
+    </text>
+    <mask id="autouseScope">
+        <circle fill="white" r="249" cx="251" cy="251" />
+    </mask>
+
+    <!-- TestWithAutouse.test_req -->
+    <line x1="176" x2="176" y1="76" y2="426"/>
+    <ellipse class="fixture" rx="50" ry="25" cx="176" cy="76" />
+    <text x="176" y="76">order</text>
+    <ellipse class="fixture" rx="25" ry="25" cx="176" cy="146" />
+    <text x="176" y="146">c2</text>
+    <ellipse class="fixture" rx="25" ry="25" cx="176" cy="216" />
+    <text x="176" y="216">c3</text>
+    <ellipse class="fixture" rx="25" ry="25" cx="176" cy="356" />
+    <text x="176" y="356">c1</text>
+    <rect class="test" width="100" height="50" x="126" y="401" />
+    <text x="176" y="426">test_req</text>
+
+    <!-- TestWithAutouse.test_no_req -->
+    <line x1="326" x2="326" y1="76" y2="346"/>
+    <ellipse class="fixture" rx="50" ry="25" cx="326" cy="76" />
+    <text x="326" y="76">order</text>
+    <ellipse class="fixture" rx="25" ry="25" cx="326" cy="146" />
+    <text x="326" y="146">c2</text>
+    <ellipse class="fixture" rx="25" ry="25" cx="326" cy="216" />
+    <text x="326" y="216">c3</text>
+    <rect class="test" width="120" height="50" x="266" y="331" />
+    <text x="326" y="356">test_no_req</text>
+
+    <rect class="autouse" width="500" height="40" x="1" y="266" mask="url(#autouseScope)"/>
+    <text x="261" y="286">autouse</text>
+
+    <!-- TestWithoutAutouse -->
+    <circle class="class" r="170" cx="691" cy="251" />
+    <!-- scope name -->
+    <defs>
+        <path d="M 531,251 A 160 160 0 0 1 851 251" id="testClassWithout"/>
+    </defs>
+    <text class="class">
+        <textPath href="#testClassWithout" startOffset="50%">TestWithoutAutouse</textPath>
+    </text>
+
+    <!-- TestWithoutAutouse.test_req -->
+    <line x1="616" x2="616" y1="181" y2="321"/>
+    <ellipse class="fixture" rx="50" ry="25" cx="616" cy="181" />
+    <text x="616" y="181">order</text>
+    <ellipse class="fixture" rx="25" ry="25" cx="616" cy="251" />
+    <text x="616" y="251">c1</text>
+    <rect class="test" width="100" height="50" x="566" y="296" />
+    <text x="616" y="321">test_req</text>
+
+    <!-- TestWithoutAutouse.test_no_req -->
+    <line x1="766" x2="766" y1="181" y2="251"/>
+    <ellipse class="fixture" rx="50" ry="25" cx="766" cy="181" />
+    <text x="766" y="181">order</text>
+    <rect class="test" width="120" height="50" x="706" y="226" />
+    <text x="766" y="251">test_no_req</text>
+</svg>

doc/en/example/fixtures/test_fixtures_order_dependencies.py

@@ -0,0 +1,45 @@
+import pytest
+
+
+@pytest.fixture
+def order():
+    return []
+
+
+@pytest.fixture
+def a(order):
+    order.append("a")
+
+
+@pytest.fixture
+def b(a, order):
+    order.append("b")
+
+
+@pytest.fixture
+def c(a, b, order):
+    order.append("c")
+
+
+@pytest.fixture
+def d(c, b, order):
+    order.append("d")
+
+
+@pytest.fixture
+def e(d, b, order):
+    order.append("e")
+
+
+@pytest.fixture
+def f(e, order):
+    order.append("f")
+
+
+@pytest.fixture
+def g(f, c, order):
+    order.append("g")
+
+
+def test_order(g, order):
+    assert order == ["a", "b", "c", "d", "e", "f", "g"]

doc/en/example/fixtures/test_fixtures_order_dependencies.svg

@@ -0,0 +1,60 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="252" height="612">
+    <style>
+        text {
+            font-family: 'Consolas', 'Menlo', 'DejaVu Sans Mono', 'Bitstream Vera Sans Mono', monospace;
+            dominant-baseline: middle;
+            text-anchor: middle;
+            fill: #062886;
+            font-size: medium;
+        }
+        ellipse.fixture, rect.test {
+            fill: #eeffcc;
+            stroke: #007020;
+            stroke-width: 2;
+        }
+        text.fixture {
+            color: #06287e;
+        }
+        circle.class {
+            fill: #c3e0ec;
+            stroke: #0e84b5;
+            stroke-width: 2;
+        }
+        text.class {
+            fill: #0e84b5;
+        }
+        path, line {
+            stroke: black;
+            stroke-width: 2;
+            fill: none;
+        }
+    </style>
+    <path d="M126,516 L26,436 L26,236" />
+    <path d="M226,376 L226,236 L126,166" />
+    <line x1="126" x2="126" y1="586" y2="446" />
+    <line x1="126" x2="226" y1="446" y2="376" />
+    <line x1="226" x2="126" y1="376" y2="306" />
+    <line x1="126" x2="26" y1="306" y2="236" />
+    <line x1="126" x2="126" y1="306" y2="166" />
+    <line x1="26" x2="126" y1="236" y2="166" />
+    <line x1="126" x2="126" y1="166" y2="26" />
+    <line x1="126" x2="126" y1="96" y2="26" />
+    <ellipse class="fixture" rx="50" ry="25" cx="126" cy="26" />
+    <text x="126" y="26">order</text>
+    <ellipse class="fixture" rx="25" ry="25" cx="126" cy="96" />
+    <text x="126" y="96">a</text>
+    <ellipse class="fixture" rx="25" ry="25" cx="126" cy="166" />
+    <text x="126" y="166">b</text>
+    <ellipse class="fixture" rx="25" ry="25" cx="26" cy="236" />
+    <text x="26" y="236">c</text>
+    <ellipse class="fixture" rx="25" ry="25" cx="126" cy="306" />
+    <text x="126" y="306">d</text>
+    <ellipse class="fixture" rx="25" ry="25" cx="226" cy="376" />
+    <text x="226" y="376">e</text>
+    <ellipse class="fixture" rx="25" ry="25" cx="126" cy="446" />
+    <text x="126" y="446">f</text>
+    <ellipse class="fixture" rx="25" ry="25" cx="126" cy="516" />
+    <text x="126" y="516">g</text>
+    <rect class="test" width="110" height="50" x="71" y="561" />
+    <text x="126" y="586">test_order</text>
+</svg>

doc/en/example/fixtures/test_fixtures_order_dependencies_flat.svg

@@ -0,0 +1,51 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="112" height="612">
+    <style>
+        text {
+            font-family: 'Consolas', 'Menlo', 'DejaVu Sans Mono', 'Bitstream Vera Sans Mono', monospace;
+            dominant-baseline: middle;
+            text-anchor: middle;
+            fill: #062886;
+            font-size: medium;
+        }
+        ellipse.fixture, rect.test {
+            fill: #eeffcc;
+            stroke: #007020;
+            stroke-width: 2;
+        }
+        text.fixture {
+            color: #06287e;
+        }
+        circle.class {
+            fill: #c3e0ec;
+            stroke: #0e84b5;
+            stroke-width: 2;
+        }
+        text.class {
+            fill: #0e84b5;
+        }
+        path, line {
+            stroke: black;
+            stroke-width: 2;
+            fill: none;
+        }
+    </style>
+    <line x1="56" x2="56" y1="611" y2="26" />
+    <ellipse class="fixture" rx="50" ry="25" cx="56" cy="26" />
+    <text x="56" y="26">order</text>
+    <ellipse class="fixture" rx="25" ry="25" cx="56" cy="96" />
+    <text x="56" y="96">a</text>
+    <ellipse class="fixture" rx="25" ry="25" cx="56" cy="166" />
+    <text x="56" y="166">b</text>
+    <ellipse class="fixture" rx="25" ry="25" cx="56" cy="236" />
+    <text x="56" y="236">c</text>
+    <ellipse class="fixture" rx="25" ry="25" cx="56" cy="306" />
+    <text x="56" y="306">d</text>
+    <ellipse class="fixture" rx="25" ry="25" cx="56" cy="376" />
+    <text x="56" y="376">e</text>
+    <ellipse class="fixture" rx="25" ry="25" cx="56" cy="446" />
+    <text x="56" y="446">f</text>
+    <ellipse class="fixture" rx="25" ry="25" cx="56" cy="516" />
+    <text x="56" y="516">g</text>
+    <rect class="test" width="110" height="50" x="1" y="561" />
+    <text x="56" y="586">test_order</text>
+</svg>

doc/en/example/fixtures/test_fixtures_order_dependencies_unclear.svg

@@ -0,0 +1,60 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="252" height="542">
+    <style>
+        text {
+            font-family: 'Consolas', 'Menlo', 'DejaVu Sans Mono', 'Bitstream Vera Sans Mono', monospace;
+            dominant-baseline: middle;
+            text-anchor: middle;
+            fill: #062886;
+            font-size: medium;
+        }
+        ellipse.fixture, rect.test {
+            fill: #eeffcc;
+            stroke: #007020;
+            stroke-width: 2;
+        }
+        text.fixture {
+            color: #06287e;
+        }
+        circle.class {
+            fill: #c3e0ec;
+            stroke: #0e84b5;
+            stroke-width: 2;
+        }
+        text.class {
+            fill: #0e84b5;
+        }
+        path, line {
+            stroke: black;
+            stroke-width: 2;
+            fill: none;
+        }
+    </style>
+    <path d="M126,446 L26,376 L26,236" />
+    <path d="M226,306 L126,236 L126,166" />
+    <line x1="126" x2="126" y1="516" y2="446" />
+    <line x1="226" x2="226" y1="376" y2="306" />
+    <line x1="226" x2="226" y1="306" y2="236" />
+    <line x1="226" x2="126" y1="236" y2="166" />
+    <line x1="126" x2="226" y1="446" y2="376" />
+    <line x1="26" x2="126" y1="236" y2="166" />
+    <line x1="126" x2="126" y1="166" y2="96" />
+    <line x1="126" x2="126" y1="96" y2="26" />
+    <ellipse class="fixture" rx="50" ry="25" cx="126" cy="26" />
+    <text x="126" y="26">order</text>
+    <ellipse class="fixture" rx="25" ry="25" cx="126" cy="96" />
+    <text x="126" y="96">a</text>
+    <ellipse class="fixture" rx="25" ry="25" cx="126" cy="166" />
+    <text x="126" y="166">b</text>
+    <ellipse class="fixture" rx="25" ry="25" cx="26" cy="236" />
+    <text x="26" y="236">c</text>
+    <ellipse class="fixture" rx="25" ry="25" cx="226" cy="236" />
+    <text x="226" y="236">d</text>
+    <ellipse class="fixture" rx="25" ry="25" cx="226" cy="306" />
+    <text x="226" y="306">e</text>
+    <ellipse class="fixture" rx="25" ry="25" cx="226" cy="376" />
+    <text x="226" y="376">f</text>
+    <ellipse class="fixture" rx="25" ry="25" cx="126" cy="446" />
+    <text x="126" y="446">g</text>
+    <rect class="test" width="110" height="50" x="71" y="491" />
+    <text x="126" y="516">test_order</text>
+</svg>

doc/en/example/fixtures/test_fixtures_order_scope.py

@@ -0,0 +1,36 @@
+import pytest
+
+
+@pytest.fixture(scope="session")
+def order():
+    return []
+
+
+@pytest.fixture
+def func(order):
+    order.append("function")
+
+
+@pytest.fixture(scope="class")
+def cls(order):
+    order.append("class")
+
+
+@pytest.fixture(scope="module")
+def mod(order):
+    order.append("module")
+
+
+@pytest.fixture(scope="package")
+def pack(order):
+    order.append("package")
+
+
+@pytest.fixture(scope="session")
+def sess(order):
+    order.append("session")
+
+
+class TestClass:
+    def test_order(self, func, cls, mod, pack, sess, order):
+        assert order == ["session", "package", "module", "class", "function"]

doc/en/example/fixtures/test_fixtures_order_scope.svg

@@ -0,0 +1,55 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="262" height="537">
+    <style>
+        text {
+            font-family: 'Consolas', 'Menlo', 'DejaVu Sans Mono', 'Bitstream Vera Sans Mono', monospace;
+            dominant-baseline: middle;
+            text-anchor: middle;
+            fill: #062886;
+            font-size: medium;
+        }
+        ellipse.fixture, rect.test {
+            fill: #eeffcc;
+            stroke: #007020;
+            stroke-width: 2;
+        }
+        text.fixture {
+            color: #06287e;
+        }
+        circle.class {
+            fill: #c3e0ec;
+            stroke: #0e84b5;
+            stroke-width: 2;
+        }
+        text.class {
+            fill: #0e84b5;
+        }
+        line {
+            stroke: black;
+            stroke-width: 2;
+        }
+    </style>
+    <!-- TestClass -->
+    <circle class="class" r="130" cx="131" cy="406" />
+    <line x1="131" x2="131" y1="21" y2="446"/>
+    <ellipse class="fixture" rx="50" ry="25" cx="131" cy="26" />
+    <text x="131" y="26">order</text>
+    <ellipse class="fixture" rx="50" ry="25" cx="131" cy="96" />
+    <text x="131" y="96">sess</text>
+    <ellipse class="fixture" rx="50" ry="25" cx="131" cy="166" />
+    <text x="131" y="166">pack</text>
+    <ellipse class="fixture" rx="50" ry="25" cx="131" cy="236" />
+    <text x="131" y="236">mod</text>
+    <ellipse class="fixture" rx="50" ry="25" cx="131" cy="306" />
+    <text x="131" y="306">cls</text>
+    <ellipse class="fixture" rx="50" ry="25" cx="131" cy="376" />
+    <text x="131" y="376">func</text>
+    <rect class="test" width="110" height="50" x="76" y="421" />
+    <text x="131" y="446">test_order</text>
+    <!-- scope name -->
+    <defs>
+        <path d="M131,526 A 120 120 0 0 1 136 286" id="testClass"/>
+    </defs>
+    <text class="class">
+        <textPath href="#testClass" startOffset="50%">TestClass</textPath>
+    </text>
+</svg>

doc/en/example/fixtures/test_fixtures_request_different_scope.py

@@ -0,0 +1,29 @@
+import pytest
+
+
+@pytest.fixture
+def order():
+    return []
+
+
+@pytest.fixture
+def outer(order, inner):
+    order.append("outer")
+
+
+class TestOne:
+    @pytest.fixture
+    def inner(self, order):
+        order.append("one")
+
+    def test_order(self, order, outer):
+        assert order == ["one", "outer"]
+
+
+class TestTwo:
+    @pytest.fixture
+    def inner(self, order):
+        order.append("two")
+
+    def test_order(self, order, outer):
+        assert order == ["two", "outer"]

doc/en/example/fixtures/test_fixtures_request_different_scope.svg

@@ -0,0 +1,115 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="562" height="532">
+    <style>
+        text {
+            font-family: 'Consolas', 'Menlo', 'DejaVu Sans Mono', 'Bitstream Vera Sans Mono', monospace;
+            dominant-baseline: middle;
+            text-anchor: middle;
+            fill: #062886;
+            font-size: medium;
+        }
+        ellipse.fixture, rect.test {
+            fill: #eeffcc;
+            stroke: #007020;
+            stroke-width: 2;
+        }
+        text.fixture {
+            color: #06287e;
+        }
+        circle.class {
+            fill: #c3e0ec;
+            stroke: #0e84b5;
+            stroke-width: 2;
+        }
+        circle.module {
+            fill: #c3e0ec;
+            stroke: #0e84b5;
+            stroke-width: 2;
+        }
+        text.class, text.module {
+            fill: #0e84b5;
+        }
+        line, path {
+            stroke: black;
+            stroke-width: 2;
+            fill: none;
+        }
+    </style>
+    <!-- main scope -->
+    <circle class="module" r="265" cx="281" cy="266" />
+    <!-- scope name -->
+    <defs>
+        <path d="M 26,266 A 255 255 0 0 1 536 266" id="testModule"/>
+    </defs>
+    <text class="module">
+        <textPath href="#testModule" startOffset="50%">test_fixtures_request_different_scope.py</textPath>
+    </text>
+
+    <!-- TestOne -->
+    <circle class="class" r="100" cx="141" cy="266" />
+    <!-- inner -->
+    <line x1="141" x2="141" y1="231" y2="301"/>
+    <!-- order -->
+    <path d="M 141 296 L 201 296 L 211 286 L 211 146 L 221 136 L 281 136" />
+    <!-- outer -->
+    <path d="M 141 306 L 201 306 L 211 316 L 211 386 L 221 396 L 281 396" />
+    <ellipse class="fixture" rx="50" ry="25" cx="141" cy="231" />
+    <text x="141" y="231">inner</text>
+    <rect class="test" width="110" height="50" x="86" y="276" />
+    <text x="141" y="301">test_order</text>
+    <!-- scope name -->
+    <defs>
+        <path d="M 51,266 A 90 90 0 0 1 231 266" id="testOne"/>
+    </defs>
+    <text class="class">
+        <textPath href="#testOne" startOffset="50%">TestOne</textPath>
+    </text>
+    <!-- scope order number -->
+    <mask id="testOneOrderMask">
+        <rect x="0" y="0" width="100%" height="100%" fill="white"/>
+        <circle fill="black" stroke="white" stroke-width="2" r="100" cx="141" cy="266" />
+    </mask>
+    <circle class="module" r="15" cx="41" cy="266" mask="url(#testOneOrderMask)"/>
+    <text class="module" x="41" y="266">1</text>
+    <!-- scope order number -->
+    <mask id="testMainOrderMask">
+        <rect x="0" y="0" width="100%" height="100%" fill="white"/>
+        <circle fill="black" stroke="white" stroke-width="2" r="265" cx="281" cy="266" />
+    </mask>
+    <circle class="module" r="15" cx="16" cy="266" mask="url(#testMainOrderMask)"/>
+    <text class="module" x="16" y="266">2</text>
+
+    <!-- TestTwo -->
+    <circle class="class" r="100" cx="421" cy="266" />
+    <!-- inner -->
+    <line x1="421" x2="421" y1="231" y2="301"/>
+    <!-- order -->
+    <path d="M 421 296 L 361 296 L 351 286 L 351 146 L 341 136 L 281 136" />
+    <!-- outer -->
+    <path d="M 421 306 L 361 306 L 351 316 L 351 386 L 341 396 L 281 396" />
+    <ellipse class="fixture" rx="50" ry="25" cx="421" cy="231" />
+    <text x="421" y="231">inner</text>
+    <rect class="test" width="110" height="50" x="366" y="276" />
+    <text x="421" y="301">test_order</text>
+    <!-- scope name -->
+    <defs>
+        <path d="M 331,266 A 90 90 0 0 1 511 266" id="testTwo"/>
+    </defs>
+    <text class="class">
+        <textPath href="#testTwo" startOffset="50%">TestTwo</textPath>
+    </text>
+    <!-- scope order number -->
+    <mask id="testTwoOrderMask">
+        <rect x="0" y="0" width="100%" height="100%" fill="white"/>
+        <circle fill="black" stroke="white" stroke-width="2" r="100" cx="421" cy="266" />
+    </mask>
+    <circle class="module" r="15" cx="521" cy="266" mask="url(#testTwoOrderMask)"/>
+    <text class="module" x="521" y="266">1</text>
+    <!-- scope order number -->
+    <circle class="module" r="15" cx="546" cy="266" mask="url(#testMainOrderMask)"/>
+    <text class="module" x="546" y="266">2</text>
+
+    <ellipse class="fixture" rx="50" ry="25" cx="281" cy="396" />
+    <text x="281" y="396">outer</text>
+    <ellipse class="fixture" rx="50" ry="25" cx="281" cy="136" />
+    <text x="281" y="136">order</text>
+</svg>

doc/en/example/index.rst

@@ -13,12 +13,12 @@ answers.
 
 For basic examples, see
 
-- :doc:`../getting-started` for basic introductory examples
+- :ref:`get-started` for basic introductory examples
 - :ref:`assert` for basic assertion examples
 - :ref:`Fixtures <fixtures>` for basic fixture/setup examples
 - :ref:`parametrize` for basic test function parametrization
-- :doc:`../unittest` for basic unittest integration
-- :doc:`../nose` for basic nosetests integration
+- :ref:`unittest` for basic unittest integration
+- :ref:`noseintegration` for basic nosetests integration
 
 The following examples aim at various use cases you might encounter.
 

doc/en/example/multipython.py

@@ -12,8 +12,8 @@ pythonlist = ["python3.5", "python3.6", "python3.7"]
 
 
 @pytest.fixture(params=pythonlist)
-def python1(request, tmpdir):
-    picklefile = tmpdir.join("data.pickle")
+def python1(request, tmp_path):
+    picklefile = tmp_path / "data.pickle"
     return Python(request.param, picklefile)
 
 
@@ -30,8 +30,8 @@ class Python:
         self.picklefile = picklefile
 
     def dumps(self, obj):
-        dumpfile = self.picklefile.dirpath("dump.py")
-        dumpfile.write(
+        dumpfile = self.picklefile.with_name("dump.py")
+        dumpfile.write_text(
             textwrap.dedent(
                 r"""
                 import pickle
@@ -46,8 +46,8 @@ class Python:
         subprocess.check_call((self.pythonpath, str(dumpfile)))
 
     def load_and_is_true(self, expression):
-        loadfile = self.picklefile.dirpath("load.py")
-        loadfile.write(
+        loadfile = self.picklefile.with_name("load.py")
+        loadfile.write_text(
             textwrap.dedent(
                 r"""
                 import pickle

doc/en/example/nonpython/conftest.py

@@ -2,9 +2,9 @@
 import pytest
 
 
-def pytest_collect_file(parent, path):
-    if path.ext == ".yaml" and path.basename.startswith("test"):
-        return YamlFile.from_parent(parent, fspath=path)
+def pytest_collect_file(parent, fspath):
+    if fspath.suffix == ".yaml" and fspath.name.startswith("test"):
+        return YamlFile.from_parent(parent, path=fspath)
 
 
 class YamlFile(pytest.File):
@@ -12,7 +12,7 @@ class YamlFile(pytest.File):
         # We need a yaml parser, e.g. PyYAML.
         import yaml
 
-        raw = yaml.safe_load(self.fspath.open())
+        raw = yaml.safe_load(self.path.open())
         for name, spec in sorted(raw.items()):
             yield YamlItem.from_parent(self, name=name, spec=spec)
 

doc/en/example/parametrize.rst

@@ -97,10 +97,10 @@ the argument name:
 
     # content of test_time.py
 
-    import pytest
-
     from datetime import datetime, timedelta
 
+    import pytest
+
     testdata = [
         (datetime(2001, 12, 12), datetime(2001, 12, 11), timedelta(1)),
         (datetime(2001, 12, 11), datetime(2001, 12, 12), timedelta(-1)),
@@ -508,11 +508,12 @@ Running it results in some skips if we don't have all the python interpreters in
 .. code-block:: pytest
 
    . $ pytest -rs -q multipython.py
-   ssssssssssss...ssssssssssss                                          [100%]
+   sssssssssssssssssssssssssss                                          [100%]
    ========================= short test summary info ==========================
-   SKIPPED [12] multipython.py:29: 'python3.5' not found
-   SKIPPED [12] multipython.py:29: 'python3.7' not found
-   3 passed, 24 skipped in 0.12s
+   SKIPPED [9] multipython.py:29: 'python3.5' not found
+   SKIPPED [9] multipython.py:29: 'python3.6' not found
+   SKIPPED [9] multipython.py:29: 'python3.7' not found
+   27 skipped in 0.12s
 
 Indirect parametrization of optional implementations/imports
 --------------------------------------------------------------------
@@ -637,13 +638,13 @@ Then run ``pytest`` with verbose mode and with only the ``basic`` marker:
     platform linux -- Python 3.x.y, pytest-6.x.y, py-1.x.y, pluggy-0.x.y -- $PYTHON_PREFIX/bin/python
     cachedir: $PYTHON_PREFIX/.pytest_cache
     rootdir: $REGENDOC_TMPDIR
-    collecting ... collected 14 items / 11 deselected / 3 selected
+    collecting ... collected 24 items / 21 deselected / 3 selected
 
     test_pytest_param_example.py::test_eval[1+7-8] PASSED                [ 33%]
     test_pytest_param_example.py::test_eval[basic_2+4] PASSED            [ 66%]
     test_pytest_param_example.py::test_eval[basic_6*9] XFAIL             [100%]
 
-    =============== 2 passed, 11 deselected, 1 xfailed in 0.12s ================
+    =============== 2 passed, 21 deselected, 1 xfailed in 0.12s ================
 
 As the result:
 

doc/en/example/simple.rst

@@ -69,7 +69,7 @@ Here is a basic pattern to achieve this:
 
 
 For this to work we need to add a command line option and
-provide the ``cmdopt`` through a :ref:`fixture function <fixture function>`:
+provide the ``cmdopt`` through a :ref:`fixture function <fixture>`:
 
 .. code-block:: python
 
@@ -621,7 +621,7 @@ Package/Directory-level fixtures (setups)
 -------------------------------------------------------
 
 If you have nested test directories, you can have per-directory fixture scopes
-by placing fixture functions in a ``conftest.py`` file in that directory
+by placing fixture functions in a ``conftest.py`` file in that directory.
 You can use all types of fixtures including :ref:`autouse fixtures
 <autouse fixtures>` which are the equivalent of xUnit's setup/teardown
 concept.  It's however recommended to have explicit fixture references in your
@@ -768,8 +768,8 @@ case we just write some information out to a ``failures`` file:
             mode = "a" if os.path.exists("failures") else "w"
             with open("failures", mode) as f:
                 # let's also access a fixture for the fun of it
-                if "tmpdir" in item.fixturenames:
-                    extra = " ({})".format(item.funcargs["tmpdir"])
+                if "tmp_path" in item.fixturenames:
+                    extra = " ({})".format(item.funcargs["tmp_path"])
                 else:
                     extra = ""
 
@@ -781,7 +781,7 @@ if you then have failing tests:
 .. code-block:: python
 
     # content of test_module.py
-    def test_fail1(tmpdir):
+    def test_fail1(tmp_path):
         assert 0
 
 
@@ -804,9 +804,9 @@ and run them:
     ================================= FAILURES =================================
     ________________________________ test_fail1 ________________________________
 
-    tmpdir = local('PYTEST_TMPDIR/test_fail10')
+    tmp_path = Path('PYTEST_TMPDIR/test_fail10')
 
-        def test_fail1(tmpdir):
+        def test_fail1(tmp_path):
     >       assert 0
     E       assert 0
 

doc/en/explanation/anatomy.rst

@@ -0,0 +1,46 @@
+.. _test-anatomy:
+
+Anatomy of a test
+=================
+
+In the simplest terms, a test is meant to look at the result of a particular
+behavior, and make sure that result aligns with what you would expect.
+Behavior is not something that can be empirically measured, which is why writing
+tests can be challenging.
+
+"Behavior" is the way in which some system **acts in response** to a particular
+situation and/or stimuli. But exactly *how* or *why* something is done is not
+quite as important as *what* was done.
+
+You can think of a test as being broken down into four steps:
+
+1. **Arrange**
+2. **Act**
+3. **Assert**
+4. **Cleanup**
+
+**Arrange** is where we prepare everything for our test. This means pretty
+much everything except for the "**act**". It's lining up the dominoes so that
+the **act** can do its thing in one, state-changing step. This can mean
+preparing objects, starting/killing services, entering records into a database,
+or even things like defining a URL to query, generating some credentials for a
+user that doesn't exist yet, or just waiting for some process to finish.
+
+**Act** is the singular, state-changing action that kicks off the **behavior**
+we want to test. This behavior is what carries out the changing of the state of
+the system under test (SUT), and it's the resulting changed state that we can
+look at to make a judgement about the behavior. This typically takes the form of
+a function/method call.
+
+**Assert** is where we look at that resulting state and check if it looks how
+we'd expect after the dust has settled. It's where we gather evidence to say the
+behavior does or does not aligns with what we expect. The ``assert`` in our test
+is where we take that measurement/observation and apply our judgement to it. If
+something should be green, we'd say ``assert thing == "green"``.
+
+**Cleanup** is where the test picks up after itself, so other tests aren't being
+accidentally influenced by it.
+
+At its core, the test is ultimately the **act** and **assert** steps, with the
+**arrange** step only providing the context. **Behavior** exists between **act**
+and **assert**.

doc/en/explanation/fixtures.rst

@@ -0,0 +1,158 @@
+.. _about-fixtures:
+
+About fixtures
+===============
+
+.. seealso:: :ref:`how-to-fixtures`
+.. seealso:: :ref:`Fixtures reference <reference-fixtures>`
+
+pytest fixtures are designed to be explicit, modular and scalable.
+
+What fixtures are
+-----------------
+
+In testing, a `fixture <https://en.wikipedia.org/wiki/Test_fixture#Software>`_
+provides a defined, reliable and consistent context for the tests. This could
+include environment (for example a database configured with known parameters)
+or content (such as a dataset).
+
+Fixtures define the steps and data that constitute the *arrange* phase of a
+test (see :ref:`test-anatomy`). In pytest, they are functions you define that
+serve this purpose. They can also be used to define a test's *act* phase; this
+is a powerful technique for designing more complex tests.
+
+The services, state, or other operating environments set up by fixtures are
+accessed by test functions through arguments. For each fixture used by a test
+function there is typically a parameter (named after the fixture) in the test
+function's definition.
+
+We can tell pytest that a particular function is a fixture by decorating it with
+:py:func:`@pytest.fixture <pytest.fixture>`. Here's a simple example of
+what a fixture in pytest might look like:
+
+.. code-block:: python
+
+    import pytest
+
+
+    class Fruit:
+        def __init__(self, name):
+            self.name = name
+
+        def __eq__(self, other):
+            return self.name == other.name
+
+
+    @pytest.fixture
+    def my_fruit():
+        return Fruit("apple")
+
+
+    @pytest.fixture
+    def fruit_basket(my_fruit):
+        return [Fruit("banana"), my_fruit]
+
+
+    def test_my_fruit_in_basket(my_fruit, fruit_basket):
+        assert my_fruit in fruit_basket
+
+Tests don't have to be limited to a single fixture, either. They can depend on
+as many fixtures as you want, and fixtures can use other fixtures, as well. This
+is where pytest's fixture system really shines.
+
+
+Improvements over xUnit-style setup/teardown functions
+-----------------------------------------------------------
+
+pytest fixtures offer dramatic improvements over the classic xUnit
+style of setup/teardown functions:
+
+* fixtures have explicit names and are activated by declaring their use
+  from test functions, modules, classes or whole projects.
+
+* fixtures are implemented in a modular manner, as each fixture name
+  triggers a *fixture function* which can itself use other fixtures.
+
+* fixture management scales from simple unit to complex
+  functional testing, allowing to parametrize fixtures and tests according
+  to configuration and component options, or to re-use fixtures
+  across function, class, module or whole test session scopes.
+
+* teardown logic can be easily, and safely managed, no matter how many fixtures
+  are used, without the need to carefully handle errors by hand or micromanage
+  the order that cleanup steps are added.
+
+In addition, pytest continues to support :ref:`xunitsetup`.  You can mix
+both styles, moving incrementally from classic to new style, as you
+prefer.  You can also start out from existing :ref:`unittest.TestCase
+style <unittest.TestCase>` or :ref:`nose based <nosestyle>` projects.
+
+
+
+Fixture errors
+--------------
+
+pytest does its best to put all the fixtures for a given test in a linear order
+so that it can see which fixture happens first, second, third, and so on. If an
+earlier fixture has a problem, though, and raises an exception, pytest will stop
+executing fixtures for that test and mark the test as having an error.
+
+When a test is marked as having an error, it doesn't mean the test failed,
+though. It just means the test couldn't even be attempted because one of the
+things it depends on had a problem.
+
+This is one reason why it's a good idea to cut out as many unnecessary
+dependencies as possible for a given test. That way a problem in something
+unrelated isn't causing us to have an incomplete picture of what may or may not
+have issues.
+
+Here's a quick example to help explain:
+
+.. code-block:: python
+
+    import pytest
+
+
+    @pytest.fixture
+    def order():
+        return []
+
+
+    @pytest.fixture
+    def append_first(order):
+        order.append(1)
+
+
+    @pytest.fixture
+    def append_second(order, append_first):
+        order.extend([2])
+
+
+    @pytest.fixture(autouse=True)
+    def append_third(order, append_second):
+        order += [3]
+
+
+    def test_order(order):
+        assert order == [1, 2, 3]
+
+
+If, for whatever reason, ``order.append(1)`` had a bug and it raises an exception,
+we wouldn't be able to know if ``order.extend([2])`` or ``order += [3]`` would
+also have problems. After ``append_first`` throws an exception, pytest won't run
+any more fixtures for ``test_order``, and it won't even try to run
+``test_order`` itself. The only things that would've run would be ``order`` and
+``append_first``.
+
+
+Sharing test data
+-----------------
+
+If you want to make test data from files available to your tests, a good way
+to do this is by loading these data in a fixture for use by your tests.
+This makes use of the automatic caching mechanisms of pytest.
+
+Another good approach is by adding the data files in the ``tests`` folder.
+There are also community plugins available to help managing this aspect of
+testing, e.g. `pytest-datadir <https://pypi.org/project/pytest-datadir/>`__
+and `pytest-datafiles <https://pypi.org/project/pytest-datafiles/>`__.

doc/en/explanation/flaky.rst

@@ -113,7 +113,7 @@ Resources
 
 * `Eradicating Non-Determinism in Tests <https://martinfowler.com/articles/nonDeterminism.html>`_ by Martin Fowler, 2011
 * `No more flaky tests on the Go team <https://www.thoughtworks.com/insights/blog/no-more-flaky-tests-go-team>`_ by Pavan Sudarshan, 2012
-* `The Build That Cried Broken: Building Trust in your Continuous Integration Tests <https://www.youtube.com/embed/VotJqV4n8ig>`_ talk (video) by `Angie Jones <http://angiejones.tech/>`_ at SeleniumConf Austin 2017
+* `The Build That Cried Broken: Building Trust in your Continuous Integration Tests <https://www.youtube.com/embed/VotJqV4n8ig>`_ talk (video) by `Angie Jones <https://angiejones.tech/>`_ at SeleniumConf Austin 2017
 * `Test and Code Podcast: Flaky Tests and How to Deal with Them <https://testandcode.com/50>`_ by Brian Okken and Anthony Shaw, 2018
 * Microsoft:
 

doc/en/explanation/goodpractices.rst

@@ -48,7 +48,7 @@ Conventions for Python test discovery
   * ``test`` prefixed test functions or methods outside of class
   * ``test`` prefixed test functions or methods inside ``Test`` prefixed test classes (without an ``__init__`` method)
 
-For examples of how to customize your test discovery :doc:`example/pythoncollection`.
+For examples of how to customize your test discovery :doc:`/example/pythoncollection`.
 
 Within Python modules, ``pytest`` also discovers tests using the standard
 :ref:`unittest.TestCase <unittest.TestCase>` subclassing technique.
@@ -151,7 +151,7 @@ This layout prevents a lot of common pitfalls and has many benefits, which are b
 
 .. note::
     The new ``--import-mode=importlib`` (see :ref:`import-modes`) doesn't have
-    any of the drawbacks above because ``sys.path`` and ``sys.modules`` are not changed when importing
+    any of the drawbacks above because ``sys.path`` is not changed when importing
     test modules, so users that run
     into this issue are strongly encouraged to try it and report if the new option works well for them.
 
@@ -231,7 +231,7 @@ Note that this layout also works in conjunction with the ``src`` layout mentione
 
 
 .. _`virtualenv`: https://pypi.org/project/virtualenv/
-.. _`buildout`: http://www.buildout.org/
+.. _`buildout`: http://www.buildout.org/en/latest/
 .. _pip: https://pypi.org/project/pip/
 
 .. _`use tox`:

doc/en/explanation/index.rst

@@ -0,0 +1,15 @@
+:orphan:
+
+.. _explanation:
+
+Explanation
+================
+
+.. toctree::
+   :maxdepth: 1
+
+   anatomy
+   fixtures
+   goodpractices
+   flaky
+   pythonpath

doc/en/explanation/pythonpath.rst

@@ -16,14 +16,14 @@ import process can be controlled through the ``--import-mode`` command-line flag
 these values:
 
 * ``prepend`` (default): the directory path containing each module will be inserted into the *beginning*
-  of ``sys.path`` if not already there, and then imported with the `__import__ <https://docs.python.org/3/library/functions.html#__import__>`__ builtin.
+  of :py:data:`sys.path` if not already there, and then imported with the `__import__ <https://docs.python.org/3/library/functions.html#__import__>`__ builtin.
 
   This requires test module names to be unique when the test directory tree is not arranged in
-  packages, because the modules will put in ``sys.modules`` after importing.
+  packages, because the modules will put in :py:data:`sys.modules` after importing.
 
   This is the classic mechanism, dating back from the time Python 2 was still supported.
 
-* ``append``: the directory containing each module is appended to the end of ``sys.path`` if not already
+* ``append``: the directory containing each module is appended to the end of :py:data:`sys.path` if not already
   there, and imported with ``__import__``.
 
   This better allows to run test modules against installed versions of a package even if the
@@ -41,17 +41,14 @@ these values:
   we advocate for using :ref:`src <src-layout>` layouts.
 
   Same as ``prepend``, requires test module names to be unique when the test directory tree is
-  not arranged in packages, because the modules will put in ``sys.modules`` after importing.
+  not arranged in packages, because the modules will put in :py:data:`sys.modules` after importing.
 
-* ``importlib``: new in pytest-6.0, this mode uses `importlib <https://docs.python.org/3/library/importlib.html>`__ to import test modules. This gives full control over the import process, and doesn't require
-  changing ``sys.path`` or ``sys.modules`` at all.
+* ``importlib``: new in pytest-6.0, this mode uses `importlib <https://docs.python.org/3/library/importlib.html>`__ to import test modules. This gives full control over the import process, and doesn't require changing :py:data:`sys.path`.
 
-  For this reason this doesn't require test module names to be unique at all, but also makes test
-  modules non-importable by each other. This was made possible in previous modes, for tests not residing
-  in Python packages, because of the side-effects of changing ``sys.path`` and ``sys.modules``
-  mentioned above. Users which require this should turn their tests into proper packages instead.
+  For this reason this doesn't require test module names to be unique, but also makes test
+  modules non-importable by each other.
 
-  We intend to make ``importlib`` the default in future releases.
+  We intend to make ``importlib`` the default in future releases, depending on feedback.
 
 ``prepend`` and ``append`` import modes scenarios
 -------------------------------------------------
@@ -133,4 +130,4 @@ Running pytest with ``pytest [...]`` instead of ``python -m pytest [...]`` yield
 equivalent behaviour, except that the latter will add the current directory to ``sys.path``, which
 is standard ``python`` behavior.
 
-See also :ref:`cmdline`.
+See also :ref:`invoke-python`.

doc/en/funcarg_compare.rst

@@ -47,7 +47,7 @@ There are several limitations and difficulties with this approach:
 2. parametrizing the "db" resource is not straight forward:
    you need to apply a "parametrize" decorator or implement a
    :py:func:`~hookspec.pytest_generate_tests` hook
-   calling :py:func:`~python.Metafunc.parametrize` which
+   calling :py:func:`~pytest.Metafunc.parametrize` which
    performs parametrization at the places where the resource
    is used.  Moreover, you need to modify the factory to use an
    ``extrakey`` parameter containing ``request.param`` to the
@@ -113,7 +113,7 @@ This new way of parametrizing funcarg factories should in many cases
 allow to re-use already written factories because effectively
 ``request.param`` was already used when test functions/classes were
 parametrized via
-:py:func:`metafunc.parametrize(indirect=True) <_pytest.python.Metafunc.parametrize>` calls.
+:py:func:`metafunc.parametrize(indirect=True) <pytest.Metafunc.parametrize>` calls.
 
 Of course it's perfectly fine to combine parametrization and scoping:
 
@@ -168,7 +168,7 @@ pytest for a long time offered a pytest_configure and a pytest_sessionstart
 hook which are often used to setup global resources.  This suffers from
 several problems:
 
-1. in distributed testing the master process would setup test resources
+1. in distributed testing the managing process would setup test resources
    that are never needed because it only co-ordinates the test run
    activities of the worker processes.
 

doc/en/getting-started.rst

@@ -1,22 +1,16 @@
-Installation and Getting Started
+.. _get-started:
+
+Get Started
 ===================================
 
-**Pythons**: Python 3.6, 3.7, 3.8, 3.9, PyPy3
-
-**Platforms**: Linux and Windows
-
-**PyPI package name**: `pytest <https://pypi.org/project/pytest/>`_
-
-**Documentation as PDF**: `download latest <https://media.readthedocs.org/pdf/pytest/latest/pytest.pdf>`_
-
-``pytest`` is a framework that makes building simple and scalable tests easy. Tests are expressive and readable—no boilerplate code required. Get started in minutes with a small unit test or complex functional test for your application or library.
-
 .. _`getstarted`:
 .. _`installation`:
 
 Install ``pytest``
 ----------------------------------------
 
+``pytest`` requires: Python 3.6, 3.7, 3.8, 3.9, or PyPy3.
+
 1. Run the following command in your command line:
 
 .. code-block:: bash
@@ -28,14 +22,14 @@ Install ``pytest``
 .. code-block:: bash
 
     $ pytest --version
-    pytest 6.2.0
+    pytest 6.2.3
 
 .. _`simpletest`:
 
 Create your first test
 ----------------------------------------------------------
 
-Create a simple test function with just four lines of code:
+Create a new file called ``test_sample.py``, containing a function, and a test:
 
 .. code-block:: python
 
@@ -47,7 +41,7 @@ Create a simple test function with just four lines of code:
     def test_answer():
         assert func(3) == 5
 
-That’s it. You can now execute the test function:
+The test
 
 .. code-block:: pytest
 
@@ -77,7 +71,7 @@ The ``[100%]`` refers to the overall progress of running all test cases. After i
 
 .. note::
 
-    You can use the ``assert`` statement to verify test expectations. pytest’s `Advanced assertion introspection <http://docs.python.org/reference/simple_stmts.html#the-assert-statement>`_ will intelligently report intermediate values of the assert expression so you can avoid the many names `of JUnit legacy methods <http://docs.python.org/library/unittest.html#test-cases>`_.
+    You can use the ``assert`` statement to verify test expectations. pytest’s `Advanced assertion introspection <https://docs.python.org/reference/simple_stmts.html>`_ will intelligently report intermediate values of the assert expression so you can avoid the many names `of JUnit legacy methods <https://docs.python.org/library/unittest.html>`_.
 
 Run multiple tests
 ----------------------------------------------------------
@@ -210,6 +204,8 @@ This is outlined below:
     FAILED test_class_demo.py::TestClassDemoInstance::test_two - assert 0
     2 failed in 0.12s
 
+Note that attributes added at class level are *class attributes*, so they will be shared between tests.
+
 Request a unique temporary directory for functional tests
 --------------------------------------------------------------
 
@@ -217,24 +213,24 @@ Request a unique temporary directory for functional tests
 
 .. code-block:: python
 
-    # content of test_tmpdir.py
-    def test_needsfiles(tmpdir):
-        print(tmpdir)
+    # content of test_tmp_path.py
+    def test_needsfiles(tmp_path):
+        print(tmp_path)
         assert 0
 
-List the name ``tmpdir`` in the test function signature and ``pytest`` will lookup and call a fixture factory to create the resource before performing the test function call. Before the test runs, ``pytest`` creates a unique-per-test-invocation temporary directory:
+List the name ``tmp_path`` in the test function signature and ``pytest`` will lookup and call a fixture factory to create the resource before performing the test function call. Before the test runs, ``pytest`` creates a unique-per-test-invocation temporary directory:
 
 .. code-block:: pytest
 
-    $ pytest -q test_tmpdir.py
+    $ pytest -q test_tmp_path.py
     F                                                                    [100%]
     ================================= FAILURES =================================
     _____________________________ test_needsfiles ______________________________
 
-    tmpdir = local('PYTEST_TMPDIR/test_needsfiles0')
+    tmp_path = Path('PYTEST_TMPDIR/test_needsfiles0')
 
-        def test_needsfiles(tmpdir):
-            print(tmpdir)
+        def test_needsfiles(tmp_path):
+            print(tmp_path)
     >       assert 0
     E       assert 0
 
@@ -242,10 +238,10 @@ List the name ``tmpdir`` in the test function signature and ``pytest`` will look
     --------------------------- Captured stdout call ---------------------------
     PYTEST_TMPDIR/test_needsfiles0
     ========================= short test summary info ==========================
-    FAILED test_tmpdir.py::test_needsfiles - assert 0
+    FAILED test_tmp_path.py::test_needsfiles - assert 0
     1 failed in 0.12s
 
-More info on tmpdir handling is available at :ref:`Temporary directories and files <tmpdir handling>`.
+More info on temporary directory handling is available at :ref:`Temporary directories and files <tmpdir handling>`.
 
 Find out what kind of builtin :ref:`pytest fixtures <fixtures>` exist with the command:
 
@@ -260,7 +256,7 @@ Continue reading
 
 Check out additional pytest resources to help you customize tests for your unique workflow:
 
-* ":ref:`cmdline`" for command line invocation examples
+* ":ref:`usage`" for command line invocation examples
 * ":ref:`existingtestsuite`" for working with pre-existing tests
 * ":ref:`mark`" for information on the ``pytest.mark`` mechanism
 * ":ref:`fixtures`" for providing a functional baseline to your tests

doc/en/how-to/assert.rst

@@ -1,16 +1,14 @@
-
-The writing and reporting of assertions in tests
-==================================================
-
-.. _`assertfeedback`:
-.. _`assert with the assert statement`:
 .. _`assert`:
 
+How to write and report assertions in tests
+==================================================
+
+.. _`assert with the assert statement`:
 
 Asserting with the ``assert`` statement
 ---------------------------------------------------------
 
-``pytest`` allows you to use the standard python ``assert`` for verifying
+``pytest`` allows you to use the standard Python ``assert`` for verifying
 expectations and values in Python tests.  For example, you can write the
 following:
 
@@ -98,7 +96,7 @@ and if you need to have access to the actual exception info you may use:
             f()
         assert "maximum recursion" in str(excinfo.value)
 
-``excinfo`` is an ``ExceptionInfo`` instance, which is a wrapper around
+``excinfo`` is an :class:`~pytest.ExceptionInfo` instance, which is a wrapper around
 the actual exception raised.  The main attributes of interest are
 ``.type``, ``.value`` and ``.traceback``.
 
@@ -175,8 +173,6 @@ when it encounters comparisons.  For example:
 .. code-block:: python
 
     # content of test_assert2.py
-
-
     def test_set_comparison():
         set1 = set("1308")
         set2 = set("8035")

doc/en/how-to/bash-completion.rst

@@ -1,8 +1,8 @@
 
 .. _bash_completion:
 
-Setting up bash completion
-==========================
+How to set up bash completion
+=============================
 
 When using bash as your shell, ``pytest`` can use argcomplete
 (https://argcomplete.readthedocs.io/) for auto-completion.

doc/en/how-to/cache.rst

@@ -2,8 +2,8 @@
 .. _cache:
 
 
-Cache: working with cross-testrun state
-=======================================
+How to re-run failed tests and maintain state between test runs
+===============================================================
 
 
 

doc/en/how-to/capture-stdout-stderr.rst

@@ -1,7 +1,7 @@
 
 .. _`captures`:
 
-Capturing of the stdout/stderr output
+How to capture stdout/stderr output
 =========================================================
 
 Default stdout/stderr/stdin capturing behaviour

doc/en/how-to/capture-warnings.rst

@@ -1,7 +1,7 @@
 .. _`warnings`:
 
-Warnings Capture
-================
+How to capture warnings
+=======================
 
 
 

doc/en/how-to/doctest.rst

@@ -1,5 +1,6 @@
+.. _doctest:
 
-Doctest integration for modules and test files
+How to run doctests
 =========================================================
 
 By default, all files matching the ``test*.txt`` pattern will
@@ -48,7 +49,7 @@ and functions, including from test modules:
 
     # content of mymodule.py
     def something():
-        """ a doctest in a docstring
+        """a doctest in a docstring
         >>> something()
         42
         """
@@ -193,7 +194,7 @@ It is possible to use fixtures using the ``getfixture`` helper:
 .. code-block:: text
 
     # content of example.rst
-    >>> tmp = getfixture('tmpdir')
+    >>> tmp = getfixture('tmp_path')
     >>> ...
     >>>
 

doc/en/how-to/existingtestsuite.rst

@@ -1,7 +1,7 @@
 .. _existingtestsuite:
 
-Using pytest with an existing test suite
-===========================================
+How to use pytest with an existing test suite
+==============================================
 
 Pytest can be used with most existing test suites, but its
 behavior differs from other test runners such as :ref:`nose <noseintegration>` or

doc/en/how-to/failures.rst

@@ -0,0 +1,162 @@
+.. _how-to-handle-failures:
+
+How to handle test failures
+=============================
+
+.. _maxfail:
+
+Stopping after the first (or N) failures
+---------------------------------------------------
+
+To stop the testing process after the first (N) failures:
+
+.. code-block:: bash
+
+    pytest -x           # stop after first failure
+    pytest --maxfail=2  # stop after two failures
+
+
+.. _pdb-option:
+
+Using PDB_ (Python Debugger) with pytest
+----------------------------------------------------------
+
+Dropping to PDB_ (Python Debugger) on failures
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. _PDB: https://docs.python.org/library/pdb.html
+
+Python comes with a builtin Python debugger called PDB_.  ``pytest``
+allows one to drop into the PDB_ prompt via a command line option:
+
+.. code-block:: bash
+
+    pytest --pdb
+
+This will invoke the Python debugger on every failure (or KeyboardInterrupt).
+Often you might only want to do this for the first failing test to understand
+a certain failure situation:
+
+.. code-block:: bash
+
+    pytest -x --pdb   # drop to PDB on first failure, then end test session
+    pytest --pdb --maxfail=3  # drop to PDB for first three failures
+
+Note that on any failure the exception information is stored on
+``sys.last_value``, ``sys.last_type`` and ``sys.last_traceback``. In
+interactive use, this allows one to drop into postmortem debugging with
+any debug tool. One can also manually access the exception information,
+for example::
+
+    >>> import sys
+    >>> sys.last_traceback.tb_lineno
+    42
+    >>> sys.last_value
+    AssertionError('assert result == "ok"',)
+
+
+.. _trace-option:
+
+Dropping to PDB_ at the start of a test
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+``pytest`` allows one to drop into the PDB_ prompt immediately at the start of each test via a command line option:
+
+.. code-block:: bash
+
+    pytest --trace
+
+This will invoke the Python debugger at the start of every test.
+
+.. _breakpoints:
+
+Setting breakpoints
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. versionadded: 2.4.0
+
+To set a breakpoint in your code use the native Python ``import pdb;pdb.set_trace()`` call
+in your code and pytest automatically disables its output capture for that test:
+
+* Output capture in other tests is not affected.
+* Any prior test output that has already been captured and will be processed as
+  such.
+* Output capture gets resumed when ending the debugger session (via the
+  ``continue`` command).
+
+
+.. _`breakpoint-builtin`:
+
+Using the builtin breakpoint function
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Python 3.7 introduces a builtin ``breakpoint()`` function.
+Pytest supports the use of ``breakpoint()`` with the following behaviours:
+
+ - When ``breakpoint()`` is called and ``PYTHONBREAKPOINT`` is set to the default value, pytest will use the custom internal PDB trace UI instead of the system default ``Pdb``.
+ - When tests are complete, the system will default back to the system ``Pdb`` trace UI.
+ - With ``--pdb`` passed to pytest, the custom internal Pdb trace UI is used with both ``breakpoint()`` and failed tests/unhandled exceptions.
+ - ``--pdbcls`` can be used to specify a custom debugger class.
+
+
+.. _faulthandler:
+
+Fault Handler
+-------------
+
+.. versionadded:: 5.0
+
+The `faulthandler <https://docs.python.org/3/library/faulthandler.html>`__ standard module
+can be used to dump Python tracebacks on a segfault or after a timeout.
+
+The module is automatically enabled for pytest runs, unless the ``-p no:faulthandler`` is given
+on the command-line.
+
+Also the :confval:`faulthandler_timeout=X<faulthandler_timeout>` configuration option can be used
+to dump the traceback of all threads if a test takes longer than ``X``
+seconds to finish (not available on Windows).
+
+.. note::
+
+    This functionality has been integrated from the external
+    `pytest-faulthandler <https://github.com/pytest-dev/pytest-faulthandler>`__ plugin, with two
+    small differences:
+
+    * To disable it, use ``-p no:faulthandler`` instead of ``--no-faulthandler``: the former
+      can be used with any plugin, so it saves one option.
+
+    * The ``--faulthandler-timeout`` command-line option has become the
+      :confval:`faulthandler_timeout` configuration option. It can still be configured from
+      the command-line using ``-o faulthandler_timeout=X``.
+
+
+.. _unraisable:
+
+Warning about unraisable exceptions and unhandled thread exceptions
+-------------------------------------------------------------------
+
+.. versionadded:: 6.2
+
+.. note::
+
+    These features only work on Python>=3.8.
+
+Unhandled exceptions are exceptions that are raised in a situation in which
+they cannot propagate to a caller. The most common case is an exception raised
+in a :meth:`__del__ <object.__del__>` implementation.
+
+Unhandled thread exceptions are exceptions raised in a :class:`~threading.Thread`
+but not handled, causing the thread to terminate uncleanly.
+
+Both types of exceptions are normally considered bugs, but may go unnoticed
+because they don't cause the program itself to crash. Pytest detects these
+conditions and issues a warning that is visible in the test run summary.
+
+The plugins are automatically enabled for pytest runs, unless the
+``-p no:unraisableexception`` (for unraisable exceptions) and
+``-p no:threadexception`` (for thread exceptions) options are given on the
+command-line.
+
+The warnings may be silenced selectively using the :ref:`pytest.mark.filterwarnings ref`
+mark. The warning categories are :class:`pytest.PytestUnraisableExceptionWarning` and
+:class:`pytest.PytestUnhandledThreadExceptionWarning`.

doc/en/how-to/index.rst

@@ -0,0 +1,64 @@
+:orphan:
+
+.. _how-to:
+
+How-to guides
+================
+
+Core pytest functionality
+-------------------------
+
+.. toctree::
+   :maxdepth: 1
+
+   usage
+   assert
+   fixtures
+   mark
+   parametrize
+   tmpdir
+   monkeypatch
+   doctest
+   cache
+
+Test output and outcomes
+----------------------------
+
+.. toctree::
+   :maxdepth: 1
+
+   failures
+   output
+   logging
+   capture-stdout-stderr
+   capture-warnings
+   skipping
+
+Plugins
+----------------------------
+
+.. toctree::
+   :maxdepth: 1
+
+   plugins
+   writing_plugins
+   writing_hook_functions
+
+pytest and other test systems
+-----------------------------
+
+.. toctree::
+   :maxdepth: 1
+
+   existingtestsuite
+   unittest
+   nose
+   xunit_setup
+
+pytest development environment
+------------------------------
+
+.. toctree::
+   :maxdepth: 1
+
+   bash-completion

doc/en/how-to/logging.rst

@@ -1,10 +1,7 @@
 .. _logging:
 
-Logging
--------
-
-
-
+How to manage logging
+---------------------
 
 pytest captures log messages of level ``WARNING`` or above automatically and displays them in their own section
 for each failed test in the same manner as captured stdout and stderr.
@@ -170,7 +167,7 @@ the records for the ``setup`` and ``call`` stages during teardown like so:
 
 
 
-The full API is available at :class:`_pytest.logging.LogCaptureFixture`.
+The full API is available at :class:`pytest.LogCaptureFixture`.
 
 
 .. _live_logs:

doc/en/how-to/mark.rst

@@ -1,7 +1,7 @@
 .. _mark:
 
-Marking test functions with attributes
-======================================
+How to mark test functions with attributes
+===========================================
 
 By using the ``pytest.mark`` helper you can easily set
 metadata on your test functions. You can find the full list of builtin markers

doc/en/how-to/monkeypatch.rst

@@ -1,5 +1,6 @@
+.. _monkeypatching:
 
-Monkeypatching/mocking modules and environments
+How to monkeypatch/mock modules and environments
 ================================================================
 
 .. currentmodule:: _pytest.monkeypatch
@@ -16,6 +17,7 @@ functionality in tests:
 .. code-block:: python
 
     monkeypatch.setattr(obj, name, value, raising=True)
+    monkeypatch.setattr("somemodule.obj.name", value, raising=True)
     monkeypatch.delattr(obj, name, raising=True)
     monkeypatch.setitem(mapping, name, value)
     monkeypatch.delitem(obj, name, raising=True)
@@ -56,7 +58,7 @@ call ``pkg_resources.fixup_namespace_packages`` and :py:func:`importlib.invalida
 See the `monkeypatch blog post`_ for some introduction material
 and a discussion of its motivation.
 
-.. _`monkeypatch blog post`: http://tetamap.wordpress.com/2009/03/03/monkeypatching-in-unit-tests-done-right/
+.. _`monkeypatch blog post`: https://tetamap.wordpress.com//2009/03/03/monkeypatching-in-unit-tests-done-right/
 
 Simple example: monkeypatching functions
 ----------------------------------------

doc/en/how-to/nose.rst

@@ -1,6 +1,6 @@
 .. _`noseintegration`:
 
-Running tests written for nose
+How to run tests written for nose
 =======================================
 
 ``pytest`` has basic support for running tests written for nose_.

doc/en/how-to/output.rst

@@ -1,146 +1,10 @@
+.. _how-to-manage-output:
 
-.. _usage:
-
-Usage and Invocations
-==========================================
-
-
-.. _cmdline:
-
-Calling pytest through ``python -m pytest``
------------------------------------------------------
-
-
-
-You can invoke testing through the Python interpreter from the command line:
-
-.. code-block:: text
-
-    python -m pytest [...]
-
-This is almost equivalent to invoking the command line script ``pytest [...]``
-directly, except that calling via ``python`` will also add the current directory to ``sys.path``.
-
-Possible exit codes
---------------------------------------------------------------
-
-Running ``pytest`` can result in six different exit codes:
-
-:Exit code 0: All tests were collected and passed successfully
-:Exit code 1: Tests were collected and run but some of the tests failed
-:Exit code 2: Test execution was interrupted by the user
-:Exit code 3: Internal error happened while executing tests
-:Exit code 4: pytest command line usage error
-:Exit code 5: No tests were collected
-
-They are represented by the :class:`pytest.ExitCode` enum. The exit codes being a part of the public API can be imported and accessed directly using:
-
-.. code-block:: python
-
-    from pytest import ExitCode
-
-.. note::
-
-    If you would like to customize the exit code in some scenarios, specially when
-    no tests are collected, consider using the
-    `pytest-custom_exit_code <https://github.com/yashtodi94/pytest-custom_exit_code>`__
-    plugin.
-
-
-Getting help on version, option names, environment variables
---------------------------------------------------------------
-
-.. code-block:: bash
-
-    pytest --version   # shows where pytest was imported from
-    pytest --fixtures  # show available builtin function arguments
-    pytest -h | --help # show help on command line and config file options
-
-
-The full command-line flags can be found in the :ref:`reference <command-line-flags>`.
-
-.. _maxfail:
-
-Stopping after the first (or N) failures
----------------------------------------------------
-
-To stop the testing process after the first (N) failures:
-
-.. code-block:: bash
-
-    pytest -x           # stop after first failure
-    pytest --maxfail=2  # stop after two failures
-
-.. _select-tests:
-
-Specifying tests / selecting tests
----------------------------------------------------
-
-Pytest supports several ways to run and select tests from the command-line.
-
-**Run tests in a module**
-
-.. code-block:: bash
-
-    pytest test_mod.py
-
-**Run tests in a directory**
-
-.. code-block:: bash
-
-    pytest testing/
-
-**Run tests by keyword expressions**
-
-.. code-block:: bash
-
-    pytest -k "MyClass and not method"
-
-This will run tests which contain names that match the given *string expression* (case-insensitive),
-which can include Python operators that use filenames, class names and function names as variables.
-The example above will run ``TestMyClass.test_something``  but not ``TestMyClass.test_method_simple``.
-
-.. _nodeids:
-
-**Run tests by node ids**
-
-Each collected test is assigned a unique ``nodeid`` which consist of the module filename followed
-by specifiers like class names, function names and parameters from parametrization, separated by ``::`` characters.
-
-To run a specific test within a module:
-
-.. code-block:: bash
-
-    pytest test_mod.py::test_func
-
-
-Another example specifying a test method in the command line:
-
-.. code-block:: bash
-
-    pytest test_mod.py::TestClass::test_method
-
-**Run tests by marker expressions**
-
-.. code-block:: bash
-
-    pytest -m slow
-
-Will run all tests which are decorated with the ``@pytest.mark.slow`` decorator.
-
-For more information see :ref:`marks <mark>`.
-
-**Run tests from packages**
-
-.. code-block:: bash
-
-    pytest --pyargs pkg.testing
-
-This will import ``pkg.testing`` and use its filesystem location to find and run tests from.
-
+Managing pytest's output
+=========================
 
 Modifying Python traceback printing
-----------------------------------------------
+--------------------------------------------------
 
 Examples for modifying traceback printing:
 
@@ -166,16 +30,255 @@ will be shown (because KeyboardInterrupt is caught by pytest). By using this
 option you make sure a trace is shown.
 
 
+Verbosity
+--------------------------------------------------
+
+The ``-v`` flag controls the verbosity of pytest output in various aspects: test session progress, assertion
+details when tests fail, fixtures details with ``--fixtures``, etc.
+
+.. regendoc:wipe
+
+Consider this simple file:
+
+.. code-block:: python
+
+    # content of test_verbosity_example.py
+    def test_ok():
+        pass
+
+
+    def test_words_fail():
+        fruits1 = ["banana", "apple", "grapes", "melon", "kiwi"]
+        fruits2 = ["banana", "apple", "orange", "melon", "kiwi"]
+        assert fruits1 == fruits2
+
+
+    def test_numbers_fail():
+        number_to_text1 = {str(x): x for x in range(5)}
+        number_to_text2 = {str(x * 10): x * 10 for x in range(5)}
+        assert number_to_text1 == number_to_text2
+
+
+    def test_long_text_fail():
+        long_text = "Lorem ipsum dolor sit amet " * 10
+        assert "hello world" in long_text
+
+Executing pytest normally gives us this output (we are skipping the header to focus on the rest):
+
+.. code-block:: pytest
+
+    $ pytest --no-header
+    =========================== test session starts ===========================
+    collected 4 items
+
+    test_verbosity_example.py .FFF                                       [100%]
+
+    ================================ FAILURES =================================
+    _____________________________ test_words_fail _____________________________
+
+        def test_words_fail():
+            fruits1 = ["banana", "apple", "grapes", "melon", "kiwi"]
+            fruits2 = ["banana", "apple", "orange", "melon", "kiwi"]
+    >       assert fruits1 == fruits2
+    E       AssertionError: assert ['banana', 'a...elon', 'kiwi'] == ['banana', 'a...elon', 'kiwi']
+    E         At index 2 diff: 'grapes' != 'orange'
+    E         Use -v to get the full diff
+
+    test_verbosity_example.py:8: AssertionError
+    ____________________________ test_numbers_fail ____________________________
+
+        def test_numbers_fail():
+            number_to_text1 = {str(x): x for x in range(5)}
+            number_to_text2 = {str(x * 10): x * 10 for x in range(5)}
+    >       assert number_to_text1 == number_to_text2
+    E       AssertionError: assert {'0': 0, '1':..., '3': 3, ...} == {'0': 0, '10'...'30': 30, ...}
+    E         Omitting 1 identical items, use -vv to show
+    E         Left contains 4 more items:
+    E         {'1': 1, '2': 2, '3': 3, '4': 4}
+    E         Right contains 4 more items:
+    E         {'10': 10, '20': 20, '30': 30, '40': 40}
+    E         Use -v to get the full diff
+
+    test_verbosity_example.py:14: AssertionError
+    ___________________________ test_long_text_fail ___________________________
+
+        def test_long_text_fail():
+            long_text = "Lorem ipsum dolor sit amet " * 10
+    >       assert "hello world" in long_text
+    E       AssertionError: assert 'hello world' in 'Lorem ipsum dolor sit amet Lorem ipsum dolor sit amet Lorem ipsum dolor sit amet Lorem ipsum dolor sit amet Lorem ips... sit amet Lorem ipsum dolor sit amet Lorem ipsum dolor sit amet Lorem ipsum dolor sit amet Lorem ipsum dolor sit amet '
+
+    test_verbosity_example.py:19: AssertionError
+    ========================= short test summary info =========================
+    FAILED test_verbosity_example.py::test_words_fail - AssertionError: asser...
+    FAILED test_verbosity_example.py::test_numbers_fail - AssertionError: ass...
+    FAILED test_verbosity_example.py::test_long_text_fail - AssertionError: a...
+    ======================= 3 failed, 1 passed in 0.08s =======================
+
+Notice that:
+
+* Each test inside the file is shown by a single character in the output: ``.`` for passing, ``F`` for failure.
+* ``test_words_fail`` failed, and we are shown a short summary indicating the index 2 of the two lists differ.
+* ``test_numbers_fail`` failed, and we are shown a summary of left/right differences on dictionary items. Identical items are omitted.
+* ``test_long_text_fail`` failed, and the right hand side of the ``in`` statement is truncated using ``...```
+  because it is longer than an internal threshold (240 characters currently).
+
+Now we can increase pytest's verbosity:
+
+.. code-block:: pytest
+
+    $ pytest --no-header -v
+    =========================== test session starts ===========================
+    collecting ... collected 4 items
+
+    test_verbosity_example.py::test_ok PASSED                            [ 25%]
+    test_verbosity_example.py::test_words_fail FAILED                    [ 50%]
+    test_verbosity_example.py::test_numbers_fail FAILED                  [ 75%]
+    test_verbosity_example.py::test_long_text_fail FAILED                [100%]
+
+    ================================ FAILURES =================================
+    _____________________________ test_words_fail _____________________________
+
+        def test_words_fail():
+            fruits1 = ["banana", "apple", "grapes", "melon", "kiwi"]
+            fruits2 = ["banana", "apple", "orange", "melon", "kiwi"]
+    >       assert fruits1 == fruits2
+    E       AssertionError: assert ['banana', 'a...elon', 'kiwi'] == ['banana', 'a...elon', 'kiwi']
+    E         At index 2 diff: 'grapes' != 'orange'
+    E         Full diff:
+    E         - ['banana', 'apple', 'orange', 'melon', 'kiwi']
+    E         ?                      ^  ^^
+    E         + ['banana', 'apple', 'grapes', 'melon', 'kiwi']
+    E         ?                      ^  ^ +
+
+    test_verbosity_example.py:8: AssertionError
+    ____________________________ test_numbers_fail ____________________________
+
+        def test_numbers_fail():
+            number_to_text1 = {str(x): x for x in range(5)}
+            number_to_text2 = {str(x * 10): x * 10 for x in range(5)}
+    >       assert number_to_text1 == number_to_text2
+    E       AssertionError: assert {'0': 0, '1':..., '3': 3, ...} == {'0': 0, '10'...'30': 30, ...}
+    E         Omitting 1 identical items, use -vv to show
+    E         Left contains 4 more items:
+    E         {'1': 1, '2': 2, '3': 3, '4': 4}
+    E         Right contains 4 more items:
+    E         {'10': 10, '20': 20, '30': 30, '40': 40}
+    E         Full diff:
+    E         - {'0': 0, '10': 10, '20': 20, '30': 30, '40': 40}...
+    E
+    E         ...Full output truncated (3 lines hidden), use '-vv' to show
+
+    test_verbosity_example.py:14: AssertionError
+    ___________________________ test_long_text_fail ___________________________
+
+        def test_long_text_fail():
+            long_text = "Lorem ipsum dolor sit amet " * 10
+    >       assert "hello world" in long_text
+    E       AssertionError: assert 'hello world' in 'Lorem ipsum dolor sit amet Lorem ipsum dolor sit amet Lorem ipsum dolor sit amet Lorem ipsum dolor sit amet Lorem ipsum dolor sit amet Lorem ipsum dolor sit amet Lorem ipsum dolor sit amet Lorem ipsum dolor sit amet Lorem ipsum dolor sit amet Lorem ipsum dolor sit amet '
+
+    test_verbosity_example.py:19: AssertionError
+    ========================= short test summary info =========================
+    FAILED test_verbosity_example.py::test_words_fail - AssertionError: asser...
+    FAILED test_verbosity_example.py::test_numbers_fail - AssertionError: ass...
+    FAILED test_verbosity_example.py::test_long_text_fail - AssertionError: a...
+    ======================= 3 failed, 1 passed in 0.07s =======================
+
+Notice now that:
+
+* Each test inside the file gets its own line in the output.
+* ``test_words_fail`` now shows the two failing lists in full, in addition to which index differs.
+* ``test_numbers_fail`` now shows a text diff of the two dictionaries, truncated.
+* ``test_long_text_fail`` no longer truncates the right hand side of the ``in`` statement, because the internal
+  threshold for truncation is larger now (2400 characters currently).
+
+Now if we increase verbosity even more:
+
+.. code-block:: pytest
+
+    $ pytest --no-header -vv
+    =========================== test session starts ===========================
+    collecting ... collected 4 items
+
+    test_verbosity_example.py::test_ok PASSED                            [ 25%]
+    test_verbosity_example.py::test_words_fail FAILED                    [ 50%]
+    test_verbosity_example.py::test_numbers_fail FAILED                  [ 75%]
+    test_verbosity_example.py::test_long_text_fail FAILED                [100%]
+
+    ================================ FAILURES =================================
+    _____________________________ test_words_fail _____________________________
+
+        def test_words_fail():
+            fruits1 = ["banana", "apple", "grapes", "melon", "kiwi"]
+            fruits2 = ["banana", "apple", "orange", "melon", "kiwi"]
+    >       assert fruits1 == fruits2
+    E       AssertionError: assert ['banana', 'apple', 'grapes', 'melon', 'kiwi'] == ['banana', 'apple', 'orange', 'melon', 'kiwi']
+    E         At index 2 diff: 'grapes' != 'orange'
+    E         Full diff:
+    E         - ['banana', 'apple', 'orange', 'melon', 'kiwi']
+    E         ?                      ^  ^^
+    E         + ['banana', 'apple', 'grapes', 'melon', 'kiwi']
+    E         ?                      ^  ^ +
+
+    test_verbosity_example.py:8: AssertionError
+    ____________________________ test_numbers_fail ____________________________
+
+        def test_numbers_fail():
+            number_to_text1 = {str(x): x for x in range(5)}
+            number_to_text2 = {str(x * 10): x * 10 for x in range(5)}
+    >       assert number_to_text1 == number_to_text2
+    E       AssertionError: assert {'0': 0, '1': 1, '2': 2, '3': 3, '4': 4} == {'0': 0, '10': 10, '20': 20, '30': 30, '40': 40}
+    E         Common items:
+    E         {'0': 0}
+    E         Left contains 4 more items:
+    E         {'1': 1, '2': 2, '3': 3, '4': 4}
+    E         Right contains 4 more items:
+    E         {'10': 10, '20': 20, '30': 30, '40': 40}
+    E         Full diff:
+    E         - {'0': 0, '10': 10, '20': 20, '30': 30, '40': 40}
+    E         ?            -    -    -    -    -    -    -    -
+    E         + {'0': 0, '1': 1, '2': 2, '3': 3, '4': 4}
+
+    test_verbosity_example.py:14: AssertionError
+    ___________________________ test_long_text_fail ___________________________
+
+        def test_long_text_fail():
+            long_text = "Lorem ipsum dolor sit amet " * 10
+    >       assert "hello world" in long_text
+    E       AssertionError: assert 'hello world' in 'Lorem ipsum dolor sit amet Lorem ipsum dolor sit amet Lorem ipsum dolor sit amet Lorem ipsum dolor sit amet Lorem ipsum dolor sit amet Lorem ipsum dolor sit amet Lorem ipsum dolor sit amet Lorem ipsum dolor sit amet Lorem ipsum dolor sit amet Lorem ipsum dolor sit amet '
+
+    test_verbosity_example.py:19: AssertionError
+    ========================= short test summary info =========================
+    FAILED test_verbosity_example.py::test_words_fail - AssertionError: asser...
+    FAILED test_verbosity_example.py::test_numbers_fail - AssertionError: ass...
+    FAILED test_verbosity_example.py::test_long_text_fail - AssertionError: a...
+    ======================= 3 failed, 1 passed in 0.07s =======================
+
+Notice now that:
+
+* Each test inside the file gets its own line in the output.
+* ``test_words_fail`` gives the same output as before in this case.
+* ``test_numbers_fail`` now shows a full text diff of the two dictionaries.
+* ``test_long_text_fail`` also doesn't truncate on the right hand side as before, but now pytest won't truncate any
+  text at all, regardless of its size.
+
+Those were examples of how verbosity affects normal test session output, but verbosity also is used in other
+situations, for example you are shown even fixtures that start with ``_`` if you use ``pytest --fixtures -v``.
+
+Using higher verbosity levels (``-vvv``, ``-vvvv``, ...) is supported, but has no effect in pytest itself at the moment,
+however some plugins might make use of higher verbosity.
+
 .. _`pytest.detailed_failed_tests_usage`:
 
-Detailed summary report
------------------------
+Producing a detailed summary report
+--------------------------------------------------
 
 The ``-r`` flag can be used to display a "short test summary info" at the end of the test session,
 making it easy in large test suites to get a clear picture of all failures, skips, xfails, etc.
 
 It defaults to ``fE`` to list failures and errors.
 
+.. regendoc:wipe
+
 Example:
 
 .. code-block:: python
@@ -344,162 +447,30 @@ captured output:
     PASSED test_example.py::test_ok
     == 1 failed, 1 passed, 1 skipped, 1 xfailed, 1 xpassed, 1 error in 0.12s ===
 
-.. _pdb-option:
 
-Dropping to PDB_ (Python Debugger) on failures
------------------------------------------------
+Creating resultlog format files
+--------------------------------------------------
 
-.. _PDB: http://docs.python.org/library/pdb.html
-
-Python comes with a builtin Python debugger called PDB_.  ``pytest``
-allows one to drop into the PDB_ prompt via a command line option:
+To create plain-text machine-readable result files you can issue:
 
 .. code-block:: bash
 
-    pytest --pdb
+    pytest --resultlog=path
 
-This will invoke the Python debugger on every failure (or KeyboardInterrupt).
-Often you might only want to do this for the first failing test to understand
-a certain failure situation:
+and look at the content at the ``path`` location.  Such files are used e.g.
+by the `PyPy-test`_ web page to show test results over several revisions.
 
-.. code-block:: bash
+.. warning::
 
-    pytest -x --pdb   # drop to PDB on first failure, then end test session
-    pytest --pdb --maxfail=3  # drop to PDB for first three failures
+    This option is rarely used and is scheduled for removal in pytest 6.0.
 
-Note that on any failure the exception information is stored on
-``sys.last_value``, ``sys.last_type`` and ``sys.last_traceback``. In
-interactive use, this allows one to drop into postmortem debugging with
-any debug tool. One can also manually access the exception information,
-for example::
+    If you use this option, consider using the new `pytest-reportlog <https://github.com/pytest-dev/pytest-reportlog>`__ plugin instead.
 
-    >>> import sys
-    >>> sys.last_traceback.tb_lineno
-    42
-    >>> sys.last_value
-    AssertionError('assert result == "ok"',)
-
-.. _trace-option:
-
-Dropping to PDB_ (Python Debugger) at the start of a test
-----------------------------------------------------------
+    See `the deprecation docs <https://docs.pytest.org/en/stable/deprecations.html#result-log-result-log>`__
+    for more information.
 
 
-``pytest`` allows one to drop into the PDB_ prompt immediately at the start of each test via a command line option:
-
-.. code-block:: bash
-
-    pytest --trace
-
-This will invoke the Python debugger at the start of every test.
-
-.. _breakpoints:
-
-Setting breakpoints
--------------------
-
-.. versionadded: 2.4.0
-
-To set a breakpoint in your code use the native Python ``import pdb;pdb.set_trace()`` call
-in your code and pytest automatically disables its output capture for that test:
-
-* Output capture in other tests is not affected.
-* Any prior test output that has already been captured and will be processed as
-  such.
-* Output capture gets resumed when ending the debugger session (via the
-  ``continue`` command).
-
-
-.. _`breakpoint-builtin`:
-
-Using the builtin breakpoint function
--------------------------------------
-
-Python 3.7 introduces a builtin ``breakpoint()`` function.
-Pytest supports the use of ``breakpoint()`` with the following behaviours:
-
- - When ``breakpoint()`` is called and ``PYTHONBREAKPOINT`` is set to the default value, pytest will use the custom internal PDB trace UI instead of the system default ``Pdb``.
- - When tests are complete, the system will default back to the system ``Pdb`` trace UI.
- - With ``--pdb`` passed to pytest, the custom internal Pdb trace UI is used with both ``breakpoint()`` and failed tests/unhandled exceptions.
- - ``--pdbcls`` can be used to specify a custom debugger class.
-
-.. _durations:
-
-Profiling test execution duration
--------------------------------------
-
-.. versionchanged:: 6.0
-
-To get a list of the slowest 10 test durations over 1.0s long:
-
-.. code-block:: bash
-
-    pytest --durations=10 --durations-min=1.0
-
-By default, pytest will not show test durations that are too small (<0.005s) unless ``-vv`` is passed on the command-line.
-
-
-.. _faulthandler:
-
-Fault Handler
--------------
-
-.. versionadded:: 5.0
-
-The `faulthandler <https://docs.python.org/3/library/faulthandler.html>`__ standard module
-can be used to dump Python tracebacks on a segfault or after a timeout.
-
-The module is automatically enabled for pytest runs, unless the ``-p no:faulthandler`` is given
-on the command-line.
-
-Also the :confval:`faulthandler_timeout=X<faulthandler_timeout>` configuration option can be used
-to dump the traceback of all threads if a test takes longer than ``X``
-seconds to finish (not available on Windows).
-
-.. note::
-
-    This functionality has been integrated from the external
-    `pytest-faulthandler <https://github.com/pytest-dev/pytest-faulthandler>`__ plugin, with two
-    small differences:
-
-    * To disable it, use ``-p no:faulthandler`` instead of ``--no-faulthandler``: the former
-      can be used with any plugin, so it saves one option.
-
-    * The ``--faulthandler-timeout`` command-line option has become the
-      :confval:`faulthandler_timeout` configuration option. It can still be configured from
-      the command-line using ``-o faulthandler_timeout=X``.
-
-
-.. _unraisable:
-
-Warning about unraisable exceptions and unhandled thread exceptions
--------------------------------------------------------------------
-
-.. versionadded:: 6.2
-
-.. note::
-
-    These features only work on Python>=3.8.
-
-Unhandled exceptions are exceptions that are raised in a situation in which
-they cannot propagate to a caller. The most common case is an exception raised
-in a :meth:`__del__ <object.__del__>` implementation.
-
-Unhandled thread exceptions are exceptions raised in a :class:`~threading.Thread`
-but not handled, causing the thread to terminate uncleanly.
-
-Both types of exceptions are normally considered bugs, but may go unnoticed
-because they don't cause the program itself to crash. Pytest detects these
-conditions and issues a warning that is visible in the test run summary.
-
-The plugins are automatically enabled for pytest runs, unless the
-``-p no:unraisableexception`` (for unraisable exceptions) and
-``-p no:threadexception`` (for thread exceptions) options are given on the
-command-line.
-
-The warnings may be silenced selectivly using the :ref:`pytest.mark.filterwarnings ref`
-mark. The warning categories are :class:`pytest.PytestUnraisableExceptionWarning` and
-:class:`pytest.PytestUnhandledThreadExceptionWarning`.
+.. _`PyPy-test`: http://buildbot.pypy.org/summary
 
 
 Creating JUnitXML format files
@@ -540,7 +511,7 @@ instead, configure the ``junit_duration_report`` option like this:
 .. _record_property example:
 
 record_property
-^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~
 
 If you want to log additional information for a test, you can use the
 ``record_property`` fixture:
@@ -602,10 +573,9 @@ Will result in:
     Please note that using this feature will break schema verifications for the latest JUnitXML schema.
     This might be a problem when used with some CI servers.
 
+
 record_xml_attribute
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-
+~~~~~~~~~~~~~~~~~~~~~~~
 
 To add an additional xml attribute to a testcase element, you can use
 ``record_xml_attribute`` fixture. This can also be used to override existing values:
@@ -714,34 +684,8 @@ The generated XML is compatible with the latest ``xunit`` standard, contrary to
 and `record_xml_attribute`_.
 
 
-Creating resultlog format files
-----------------------------------------------------
-
-
-To create plain-text machine-readable result files you can issue:
-
-.. code-block:: bash
-
-    pytest --resultlog=path
-
-and look at the content at the ``path`` location.  Such files are used e.g.
-by the `PyPy-test`_ web page to show test results over several revisions.
-
-.. warning::
-
-    This option is rarely used and is scheduled for removal in pytest 6.0.
-
-    If you use this option, consider using the new `pytest-reportlog <https://github.com/pytest-dev/pytest-reportlog>`__ plugin instead.
-
-    See `the deprecation docs <https://docs.pytest.org/en/stable/deprecations.html#result-log-result-log>`__
-    for more information.
-
-
-.. _`PyPy-test`: http://buildbot.pypy.org/summary
-
-
-Sending test report to online pastebin service
------------------------------------------------------
+Sending test report to an online pastebin service
+--------------------------------------------------
 
 **Creating a URL for each test failure**:
 
@@ -759,114 +703,11 @@ for example ``-x`` if you only want to send one particular failure.
 
     pytest --pastebin=all
 
-Currently only pasting to the http://bpaste.net service is implemented.
+Currently only pasting to the https://bpaste.net/ service is implemented.
 
 .. versionchanged:: 5.2
 
 If creating the URL fails for any reason, a warning is generated instead of failing the
 entire test suite.
 
-Early loading plugins
----------------------
-
-You can early-load plugins (internal and external) explicitly in the command-line with the ``-p`` option::
-
-    pytest -p mypluginmodule
-
-The option receives a ``name`` parameter, which can be:
-
-* A full module dotted name, for example ``myproject.plugins``. This dotted name must be importable.
-* The entry-point name of a plugin. This is the name passed to ``setuptools`` when the plugin is
-  registered. For example to early-load the `pytest-cov <https://pypi.org/project/pytest-cov/>`__ plugin you can use::
-
-    pytest -p pytest_cov
-
-
-Disabling plugins
------------------
-
-To disable loading specific plugins at invocation time, use the ``-p`` option
-together with the prefix ``no:``.
-
-Example: to disable loading the plugin ``doctest``, which is responsible for
-executing doctest tests from text files, invoke pytest like this:
-
-.. code-block:: bash
-
-    pytest -p no:doctest
-
-.. _`pytest.main-usage`:
-
-Calling pytest from Python code
-----------------------------------------------------
-
-
-
-You can invoke ``pytest`` from Python code directly:
-
-.. code-block:: python
-
-    pytest.main()
-
-this acts as if you would call "pytest" from the command line.
-It will not raise ``SystemExit`` but return the exitcode instead.
-You can pass in options and arguments:
-
-.. code-block:: python
-
-    pytest.main(["-x", "mytestdir"])
-
-You can specify additional plugins to ``pytest.main``:
-
-.. code-block:: python
-
-    # content of myinvoke.py
-    import pytest
-
-
-    class MyPlugin:
-        def pytest_sessionfinish(self):
-            print("*** test run reporting finishing")
-
-
-    pytest.main(["-qq"], plugins=[MyPlugin()])
-
-Running it will show that ``MyPlugin`` was added and its
-hook was invoked:
-
-.. code-block:: pytest
-
-    $ python myinvoke.py
-    .FEsxX.                                                              [100%]*** test run reporting finishing
-
-    ================================== ERRORS ==================================
-    _______________________ ERROR at setup of test_error _______________________
-
-        @pytest.fixture
-        def error_fixture():
-    >       assert 0
-    E       assert 0
-
-    test_example.py:6: AssertionError
-    ================================= FAILURES =================================
-    ________________________________ test_fail _________________________________
-
-        def test_fail():
-    >       assert 0
-    E       assert 0
-
-    test_example.py:14: AssertionError
-    ========================= short test summary info ==========================
-    FAILED test_example.py::test_fail - assert 0
-    ERROR test_example.py::test_error - assert 0
-
-.. note::
-
-    Calling ``pytest.main()`` will result in importing your tests and any modules
-    that they import. Due to the caching mechanism of python's import system,
-    making subsequent calls to ``pytest.main()`` from the same process will not
-    reflect changes to those files between the calls. For this reason, making
-    multiple calls to ``pytest.main()`` from the same process (in order to re-run
-    tests, for example) is not recommended.
-
-.. _jenkins: http://jenkins-ci.org/
+.. _jenkins: https://jenkins-ci.org

doc/en/how-to/parametrize.rst

@@ -6,7 +6,7 @@
 
 .. _`parametrize-basics`:
 
-Parametrizing fixtures and test functions
+How to parametrize fixtures and test functions
 ==========================================================================
 
 pytest enables test parametrization at several levels: