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