Deprecate the test command

Provide a warning to users. Suggest using tox as an alternative generic
entry point.

Refs #1684

changelog.d/1878.change.rst

+Formally deprecated the ``test`` command, with the recommendation that users migrate to ``tox``.

docs/setuptools.txt

@@ -346,6 +346,8 @@ unless you need the associated ``setuptools`` feature.
     specified test suite, e.g. via ``setup.py test``.  See the section on the
     `test`_ command below for more details.
 
+    New in 41.5.0: Deprecated the test command.
+
 ``tests_require``
     If your project's tests need one or more additional packages besides those
     needed to install it, you can use this option to specify them.  It should
@@ -357,6 +359,8 @@ unless you need the associated ``setuptools`` feature.
     are run, but only downloaded to the project's setup directory if they're
     not already installed locally.
 
+    New in 41.5.0: Deprecated the test command.
+
 .. _test_loader:
 
 ``test_loader``
@@ -380,6 +384,8 @@ unless you need the associated ``setuptools`` feature.
     as long as you use the ``tests_require`` option to ensure that the package
     containing the loader class is available when the ``test`` command is run.
 
+    New in 41.5.0: Deprecated the test command.
+
 ``eager_resources``
     A list of strings naming resources that should be extracted together, if
     any of them is needed, or if any C extensions included in the project are
@@ -2142,6 +2148,11 @@ distutils configuration file the option will be added to (or removed from).
 ``test`` - Build package and run a unittest suite
 =================================================
 
+.. warning::
+    ``test`` is deprecated and will be removed in a future version. Users
+    looking for a generic test entry point independent of test runner are
+    encouraged to use `tox <https://tox.readthedocs.io>`_.
+
 When doing test-driven development, or running automated builds that need
 testing before they are deployed for downloading or use, it's often useful
 to be able to run a project's unit tests without actually deploying the project
@@ -2187,6 +2198,8 @@ available:
     If you did not set a ``test_suite`` in your ``setup()`` call, and do not
     provide a ``--test-suite`` option, an error will occur.
 
+New in 41.5.0: Deprecated the test command.
+
 
 .. _upload:
 

setuptools/command/test.py

@@ -74,7 +74,7 @@ class NonDataProperty:
 class test(Command):
     """Command to run unit tests after in-place build"""
 
-    description = "run unit tests after in-place build"
+    description = "run unit tests after in-place build (deprecated)"
 
     user_options = [
         ('test-module=', 'm', "Run 'test_suite' in specified module"),
@@ -214,6 +214,14 @@ class test(Command):
         return itertools.chain(ir_d, tr_d, er_d)
 
     def run(self):
+        self.announce(
+            "WARNING: Testing via this command is deprecated and will be "
+            "removed in a future version. Users looking for a generic test "
+            "entry point independent of test runner are encouraged to use "
+            "tox.",
+            log.WARN,
+        )
+
         installed_dists = self.install_dists(self.distribution)
 
         cmd = ' '.join(self._argv)

setuptools/tests/test_test.py

@@ -2,6 +2,7 @@
 
 from __future__ import unicode_literals
 
+import mock
 from distutils import log
 import os
 
@@ -124,3 +125,52 @@ def test_tests_are_run_once(capfd):
         cmd.run()
     out, err = capfd.readouterr()
     assert out == 'Foo\n'
+
+
+@pytest.mark.usefixtures('sample_test')
+def test_warns_deprecation(capfd):
+    params = dict(
+        name='foo',
+        packages=['name', 'name.space', 'name.space.tests'],
+        namespace_packages=['name'],
+        test_suite='name.space.tests.test_suite',
+        use_2to3=True
+    )
+    dist = Distribution(params)
+    dist.script_name = 'setup.py'
+    cmd = test(dist)
+    cmd.ensure_finalized()
+    cmd.announce = mock.Mock()
+    cmd.run()
+    capfd.readouterr()
+    msg = (
+        "WARNING: Testing via this command is deprecated and will be "
+        "removed in a future version. Users looking for a generic test "
+        "entry point independent of test runner are encouraged to use "
+        "tox."
+    )
+    cmd.announce.assert_any_call(msg, log.WARN)
+
+
+@pytest.mark.usefixtures('sample_test')
+def test_deprecation_stderr(capfd):
+    params = dict(
+        name='foo',
+        packages=['name', 'name.space', 'name.space.tests'],
+        namespace_packages=['name'],
+        test_suite='name.space.tests.test_suite',
+        use_2to3=True
+    )
+    dist = Distribution(params)
+    dist.script_name = 'setup.py'
+    cmd = test(dist)
+    cmd.ensure_finalized()
+    cmd.run()
+    out, err = capfd.readouterr()
+    msg = (
+        "WARNING: Testing via this command is deprecated and will be "
+        "removed in a future version. Users looking for a generic test "
+        "entry point independent of test runner are encouraged to use "
+        "tox.\n"
+    )
+    assert msg in err