diff --git a/core/modules/simpletest/simpletest.api.php b/core/modules/simpletest/simpletest.api.php
index d1b5f442c7..aaea9fdba3 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.4.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