8332885: Clarify failure_handler self-tests

Reviewed-by: lmesnik

make/test/BuildFailureHandler.gmk

@@ -81,6 +81,10 @@ IMAGES_TARGETS += $(COPY_FH)
 # Use JTREG_TEST_OPTS for test VM options
 # Use JTREG_TESTS for jtreg tests parameter
 #
+# Most likely you want to select a specific test from test/failure_handler/test
+# and manually inspect the results. This target does not actually verify
+# anything about the failure_handler's output or even if it ran at all.
+#
 RUN_DIR := $(FH_SUPPORT)/test
 
 test:

test/failure_handler/README

@@ -102,3 +102,15 @@ $ ${JTREG_HOME}/bin/jtreg -jdk:${JAVA_HOME}                                   \
  -timeoutHandler:jdk.test.failurehandler.jtreg.GatherProcessInfoTimeoutHandler\
  -observer:jdk.test.failurehandler.jtreg.GatherDiagnosticInfoObserver         \
  ${WS}/hotspot/test/
+
+TESTING
+
+There are a few make targets for testing the failure_handler itself.
+ - Everything in `test/failure_handler/Makefile`
+ - The `test-failure-handler` target in `make/RunTests.gmk`
+ - The `test` target in `make/test/BuildFailureHandler.gmk`
+All of these targets are written for manual testing only. They rely on
+manual inspection of generated artifacts and cannot be run as part of a CI.
+They are tests which timeout, crash, fail in various ways and you can check
+the failure_handler output yourself. They might also leave processes running
+on your machine so be extra careful about cleaning up.