diff --git a/doc/source/index.rst b/doc/source/index.rst
index 35e5fa92..18388763 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -390,6 +390,53 @@ environment, you can use::
     testing =
         quux:python_version=='2.7'
 
+
+Testing
+-------
+
+pbr overrides the ``setuptools`` hook ``test`` (i.e. ``setup.py
+test``).  The following sequence is followed:
+
+#. If a ``.testr.conf`` file exists and `testrepository
+   <https://pypi.python.org/pypi/testrepository>`__ is installed, PBR
+   will use it as the test runner.  See the ``testr`` documentation
+   for more details.
+
+   .. note::
+
+     This is separate to ``setup.py testr`` (note the extra ``r``) which
+     is provided directly by the ``testrepository`` package.  Be careful
+     as there is some overlap of command arguments.
+
+#. Although deprecated, if ``[nosetests]`` is defined in ``setup.cfg``
+   and `nose <http://nose.readthedocs.io/en/latest/>`__ is installed,
+   the ``nose`` runner will be used.
+
+#. In other cases no override will be installed and the ``test``
+   command will revert to `setuptools
+   <http://setuptools.readthedocs.io/en/latest/setuptools.html#test-build-package-and-run-a-unittest-suite>`__.
+
+A typical usage would be in ``tox.ini`` such as::
+
+  [tox]
+  minversion = 2.0
+  skipsdist = True
+  envlist = py33,py34,py35,py26,py27,pypy,pep8,docs
+
+  [testenv]
+  usedevelop = True
+  setenv =
+    VIRTUAL_ENV={envdir}
+    CLIENT_NAME=pbr
+  deps = .
+       -r{toxinidir}/test-requirements.txt
+  commands =
+    python setup.py test --testr-args='{posargs}'
+
+The argument ``--coverage`` will set ``PYTHON`` to ``coverage run`` to
+produce a coverage report.  ``--coverage-package-name`` can be used to
+modify or narrow the packages traced.
+
 Additional Docs
 ===============
 
diff --git a/pbr/testr_command.py b/pbr/testr_command.py
index 2598a0b6..ad80765a 100644
--- a/pbr/testr_command.py
+++ b/pbr/testr_command.py
@@ -26,16 +26,18 @@
 # license you chose for the specific language governing permissions and
 # limitations under that license.
 
-"""setuptools/distutils commands to run testr via setup.py
+"""setuptools/distutils command to run testr via setup.py
 
-Currently provides 'testr' which runs tests using testr. You can pass
---coverage which will also export PYTHON='coverage run --source <your package>'
-and automatically combine the coverage from each testr backend test runner
-after the run completes.
+PBR will hook in the Testr class to provide "setup.py test" when
+.testr.conf is present in the repository (see pbr/hooks/commands.py).
+
+If we are activated but testrepository is not installed, we provide a
+sensible error.
+
+You can pass --coverage which will also export PYTHON='coverage run
+--source <your package>' and automatically combine the coverage from
+each testr backend test runner after the run completes.
 
-To use, just use setuptools/distribute and depend on testr, and it should be
-picked up automatically (as the commands are exported in the testrepository
-package metadata.
 """
 
 from distutils import cmd
diff --git a/setup.cfg b/setup.cfg
index 6640a38d..37091b67 100644
--- a/setup.cfg
+++ b/setup.cfg
@@ -42,8 +42,6 @@ autodoc_tree_excludes =
 [entry_points]
 distutils.setup_keywords =
     pbr = pbr.core:pbr
-distutils.commands =
-    testr = pbr.testr_command:Testr
 egg_info.writers =
     pbr.json = pbr.pbr_json:write_pbr_json
 console_scripts =
diff --git a/tox.ini b/tox.ini
index 65f6aa50..c8c4c9c6 100644
--- a/tox.ini
+++ b/tox.ini
@@ -13,7 +13,7 @@ setenv =
 deps = .
        -r{toxinidir}/test-requirements.txt
 commands =
-  python setup.py testr --testr-args='{posargs}'
+  python setup.py test --testr-args='{posargs}'
 
 [tox:jenkins]
 sitepackages = True
@@ -26,7 +26,7 @@ commands = python setup.py build_sphinx
 
 [testenv:cover]
 commands =
-  python setup.py testr --coverage
+  python setup.py test --coverage
 
 [testenv:venv]
 commands = {posargs}