Add pytest-filter-subpackage as an extension to pytest (#2688)

* Add pytest-filter-subpackage as an extension

* Discuss -P flag

* Small clarification in testing guide

* Edit changelog: 2688.internal.rst

changelog/2688.internal.rst

@@ -0,0 +1,2 @@
+Added ``pytest-filter-subpackage`` to the ``tests`` dependency set. This dependency enables
+us to run, for example, ``pytest -P particles`` to invoke tests for `plasmapy.particles`.

ci_requirements/tests-3.10-lowest-direct.txt

@@ -233,6 +233,7 @@ packaging==23.2
     #   nox
     #   pyproject-api
     #   pytest
+    #   pytest-filter-subpackage
     #   pytest-rerunfailures
     #   tox
     #   tox-uv
@@ -290,13 +291,15 @@ pytest==8.0.2
     #   plasmapy (pyproject.toml)
     #   pytest-cov
     #   pytest-datadir
+    #   pytest-filter-subpackage
     #   pytest-regressions
     #   pytest-rerunfailures
     #   pytest-xdist
 pytest-cov==5.0.0
     # via plasmapy (pyproject.toml)
 pytest-datadir==1.5.0
     # via pytest-regressions
+pytest-filter-subpackage==0.2.0
 pytest-regressions==2.5.0
     # via plasmapy (pyproject.toml)
 pytest-rerunfailures==13.0

ci_requirements/tests-3.10.txt

@@ -225,6 +225,7 @@ packaging==24.0
     #   nox
     #   pyproject-api
     #   pytest
+    #   pytest-filter-subpackage
     #   pytest-rerunfailures
     #   tox
     #   tox-uv
@@ -281,13 +282,15 @@ pytest==8.2.0
     #   plasmapy (pyproject.toml)
     #   pytest-cov
     #   pytest-datadir
+    #   pytest-filter-subpackage
     #   pytest-regressions
     #   pytest-rerunfailures
     #   pytest-xdist
 pytest-cov==5.0.0
     # via plasmapy (pyproject.toml)
 pytest-datadir==1.5.0
     # via pytest-regressions
+pytest-filter-subpackage==0.2.0
 pytest-regressions==2.5.0
     # via plasmapy (pyproject.toml)
 pytest-rerunfailures==14.0

ci_requirements/tests-3.11-lowest-direct.txt

@@ -227,6 +227,7 @@ packaging==23.2
     #   nox
     #   pyproject-api
     #   pytest
+    #   pytest-filter-subpackage
     #   pytest-rerunfailures
     #   tox
     #   tox-uv
@@ -284,13 +285,15 @@ pytest==8.0.2
     #   plasmapy (pyproject.toml)
     #   pytest-cov
     #   pytest-datadir
+    #   pytest-filter-subpackage
     #   pytest-regressions
     #   pytest-rerunfailures
     #   pytest-xdist
 pytest-cov==5.0.0
     # via plasmapy (pyproject.toml)
 pytest-datadir==1.5.0
     # via pytest-regressions
+pytest-filter-subpackage==0.2.0
 pytest-regressions==2.5.0
     # via plasmapy (pyproject.toml)
 pytest-rerunfailures==13.0

ci_requirements/tests-3.11.txt

@@ -219,6 +219,7 @@ packaging==24.0
     #   nox
     #   pyproject-api
     #   pytest
+    #   pytest-filter-subpackage
     #   pytest-rerunfailures
     #   tox
     #   tox-uv
@@ -275,13 +276,15 @@ pytest==8.2.0
     #   plasmapy (pyproject.toml)
     #   pytest-cov
     #   pytest-datadir
+    #   pytest-filter-subpackage
     #   pytest-regressions
     #   pytest-rerunfailures
     #   pytest-xdist
 pytest-cov==5.0.0
     # via plasmapy (pyproject.toml)
 pytest-datadir==1.5.0
     # via pytest-regressions
+pytest-filter-subpackage==0.2.0
 pytest-regressions==2.5.0
     # via plasmapy (pyproject.toml)
 pytest-rerunfailures==14.0

ci_requirements/tests-3.12-lowest-direct.txt

@@ -227,6 +227,7 @@ packaging==23.2
     #   nox
     #   pyproject-api
     #   pytest
+    #   pytest-filter-subpackage
     #   pytest-rerunfailures
     #   tox
     #   tox-uv
@@ -284,13 +285,15 @@ pytest==8.0.2
     #   plasmapy (pyproject.toml)
     #   pytest-cov
     #   pytest-datadir
+    #   pytest-filter-subpackage
     #   pytest-regressions
     #   pytest-rerunfailures
     #   pytest-xdist
 pytest-cov==5.0.0
     # via plasmapy (pyproject.toml)
 pytest-datadir==1.5.0
     # via pytest-regressions
+pytest-filter-subpackage==0.2.0
 pytest-regressions==2.5.0
     # via plasmapy (pyproject.toml)
 pytest-rerunfailures==13.0

ci_requirements/tests-3.12.txt

@@ -219,6 +219,7 @@ packaging==24.0
     #   nox
     #   pyproject-api
     #   pytest
+    #   pytest-filter-subpackage
     #   pytest-rerunfailures
     #   tox
     #   tox-uv
@@ -275,13 +276,15 @@ pytest==8.2.0
     #   plasmapy (pyproject.toml)
     #   pytest-cov
     #   pytest-datadir
+    #   pytest-filter-subpackage
     #   pytest-regressions
     #   pytest-rerunfailures
     #   pytest-xdist
 pytest-cov==5.0.0
     # via plasmapy (pyproject.toml)
 pytest-datadir==1.5.0
     # via pytest-regressions
+pytest-filter-subpackage==0.2.0
 pytest-regressions==2.5.0
     # via plasmapy (pyproject.toml)
 pytest-rerunfailures==14.0

docs/contributing/testing_guide.rst

@@ -684,13 +684,19 @@ This command will run all of the tests found within your current
 directory and all of its subdirectories. Because it takes time to run
 PlasmaPy's tests, it is usually most convenient to specify that only a
 subset of the tests be run. To run the tests contained within a
-particular file or directory, include its name after `pytest`. If you
-are in the directory :file:`plasmapy/particles/tests/`, then the tests
-in in :file:`test_atomic.py` can be run with:
+particular file or directory, include its name after `pytest`.
 
 .. code-block:: console
 
-   pytest test_atomic.py
+   pytest tests/particles/test_atomic.py
+
+The ``pytest-filter-subpackage`` extension lets us use the ``-P`` flag
+to specify a subpackage (directory) that tests should be run for. To
+perform tests for `plasmapy.particles`, run:
+
+.. code-block:: console
+
+   pytest -P particles
 
 The documentation for `pytest` describes `how to invoke pytest`_ and
 specify which tests will or will not be run. A few useful examples of

pyproject.toml

@@ -114,6 +114,7 @@ tests = [
   "pre-commit >= 3.6.0",
   "pytest >= 8.0.2",
   "pytest-cov >= 5.0.0",
+  "pytest-filter-subpackage >= 0.2.0",
   "pytest-regressions >= 2.5.0",
   "pytest-rerunfailures >= 13.0",
   "pytest-xdist >= 3.5.0",