diff --git a/core/modules/simpletest/simpletest.api.php b/core/modules/simpletest/simpletest.api.php
index d1b5f442c7..ea83e07dc6 100644
--- a/core/modules/simpletest/simpletest.api.php
+++ b/core/modules/simpletest/simpletest.api.php
@@ -13,10 +13,16 @@
 /**
  * Alter the list of tests.
  *
+ * This hook is only invoked by the Simpletest UI builder. It will not be
+ * invoked by run-tests.sh or the phpunit tool.
+ *
  * @param $groups
  *   A two dimensional array, the first key is the test group, the second is the
  *   name of the test class, and the value is in associative array containing
  *   'name', 'description', 'group', and 'requires' keys.
+ *
+ * @deprecated in Drupal 8.6.x and will be removed before Drupal 9.0.0. Convert
+ *   your test to a PHPUnit-based one and implement test listeners.
  */
 function hook_simpletest_alter(&$groups) {
   // An alternative session handler module would not want to run the original
diff --git a/core/modules/simpletest/src/TestDiscovery.php b/core/modules/simpletest/src/TestDiscovery.php
index da3d3af4af..62cc9d65ec 100644
--- a/core/modules/simpletest/src/TestDiscovery.php
+++ b/core/modules/simpletest/src/TestDiscovery.php
@@ -209,7 +209,7 @@ public function getTestClasses($extension = NULL, array $types = []) {
     }
 
     // Allow modules extending core tests to disable originals.
-    $this->moduleHandler->alter('simpletest', $list);
+    $this->moduleHandler->alterDeprecated('Convert your test to a PHPUnit-based one and implement test listeners.', 'simpletest', $list);
 
     if (!isset($extension) && empty($types)) {
       $this->testClasses = $list;