Deprecate matplotlib.test()

timhoffm · timhoffm · commit 45bcd44c3d9c · 2021-07-06T23:08:12.000+02:00
This is not a function that can be easily executed by the end user with
a standard setup.  Testing requires substantial setup such as installing
additional dependencies and reference data.  A function
`matplotlib.test()` gives the false impression that a user can simply
call it to verify if Matplotlib is working correctly.  Running pytest
explicitly has become a de-facto standard and allows users to customize
the run by various command line arguments.  There is no point in having
a second own and more limited entry point to tests.
diff --git a/doc/api/next_api_changes/deprecations/20586-TH.rst b/doc/api/next_api_changes/deprecations/20586-TH.rst
@@ -0,0 +1,5 @@
+``matplotlib.test()`` is deprecated
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Run tests using ``pytest`` from the commandline instead. See :ref:`testing`
+for more details. The variable ``matplotlib.default_test_modules`` is only
+used for ``matplotlib.test()`` and is thus deprecated as well.
diff --git a/doc/devel/testing.rst b/doc/devel/testing.rst
@@ -57,14 +57,6 @@ not need to be installed, but Matplotlib should be)::
   pytest lib/matplotlib/tests/test_simplification.py::test_clipping
 
 
-An alternative implementation that does not look at command line arguments
-and works from within Python is to run the tests from the Matplotlib library
-function :func:`matplotlib.test`::
-
-  import matplotlib
-  matplotlib.test()
-
-
 .. _command-line parameters: http://doc.pytest.org/en/latest/usage.html
 
 
diff --git a/lib/matplotlib/__init__.py b/lib/matplotlib/__init__.py
@@ -1179,6 +1179,7 @@ def _init_tests():
                 "" if ft2font.__freetype_build_type__ == 'local' else "not "))
 
 
+@_api.deprecated("3.5", alternative='pytest')
 def test(verbosity=None, coverage=False, **kwargs):
     """Run the matplotlib test suite."""
 
