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.

Author: timhoffm

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.

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
 
 

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."""