From 77f65e8644618be62c66b2ef6c0d1ce48f2bda29 Mon Sep 17 00:00:00 2001
From: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com>
Date: Tue, 6 Jul 2021 23:01:30 +0200
Subject: [PATCH] Deprecate matplotlib.test()

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.
---
 doc/api/next_api_changes/deprecations/20586-TH.rst | 12 ++++++++++++
 doc/devel/testing.rst                              |  8 --------
 lib/matplotlib/__init__.py                         |  1 +
 3 files changed, 13 insertions(+), 8 deletions(-)
 create mode 100644 doc/api/next_api_changes/deprecations/20586-TH.rst

diff --git a/doc/api/next_api_changes/deprecations/20586-TH.rst b/doc/api/next_api_changes/deprecations/20586-TH.rst
new file mode 100644
index 000000000000..99cd1d0cd3bd
--- /dev/null
+++ b/doc/api/next_api_changes/deprecations/20586-TH.rst
@@ -0,0 +1,12 @@
+``matplotlib.test()`` is deprecated
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Run tests using ``pytest`` from the commandline instead. The variable
+``matplotlib.default_test_modules`` is only used for ``matplotlib.test()`` and
+is thus deprecated as well.
+
+To test an installed copy, be sure to specify both ``matplotlib`` and
+``mpl_toolkits`` with ``--pyargs``::
+
+    python -m pytest --pyargs matplotlib.tests mpl_toolkits.tests
+
+See :ref:`testing` for more details.
diff --git a/doc/devel/testing.rst b/doc/devel/testing.rst
index b46586104121..aa189948003c 100644
--- 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
index 677530a01b51..0361a37aed48 100644
--- a/lib/matplotlib/__init__.py
+++ b/lib/matplotlib/__init__.py
@@ -1211,6 +1211,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."""