diff --git a/core/modules/simpletest/simpletest.api.php b/core/modules/simpletest/simpletest.api.php
index d1b5f442c7..fbb24f9f11 100644
--- a/core/modules/simpletest/simpletest.api.php
+++ b/core/modules/simpletest/simpletest.api.php
@@ -29,6 +29,12 @@ function hook_simpletest_alter(&$groups) {
  * A test group has started.
  *
  * This hook is called just once at the beginning of a test group.
+ *
+ * This hook is only invoked by the Simpletest UI builder. It will not be
+ * invoked by run-tests.sh or the phpunit tool.
+ *
+ * @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_test_group_started() {
 }
@@ -37,6 +43,12 @@ function hook_test_group_started() {
  * A test group has finished.
  *
  * This hook is called just once at the end of a test group.
+ *
+ * This hook is only invoked by the Simpletest UI builder. It will not be
+ * invoked by run-tests.sh or the phpunit tool.
+ *
+ * @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_test_group_finished() {
 }
@@ -46,11 +58,17 @@ function hook_test_group_finished() {
  *
  * This hook is called when an individual test has finished.
  *
+ * This hook is only invoked by the Simpletest UI builder. It will not be
+ * invoked by run-tests.sh or the phpunit tool.
+ *
  * @param
  *   $results The results of the test as gathered by
  *   \Drupal\simpletest\WebTestBase.
  *
  * @see \Drupal\simpletest\WebTestBase::results()
+ *
+ * @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_test_finished($results) {
 }