Merge pull request quarkusio#42435 from geoand/quarkusio#42406

Update javadoc and docs about `@WithTestResource`

docs/src/main/asciidoc/getting-started-testing.adoc

@@ -1088,11 +1088,16 @@ If you are using Quarkus Security, check out the xref:security-testing.adoc[Test
 
 A very common need is to start some services on which your Quarkus application depends, before the Quarkus application starts for testing. To address this need, Quarkus provides `@io.quarkus.test.common.WithTestResource` and `io.quarkus.test.common.QuarkusTestResourceLifecycleManager`.
 
-By simply annotating any test in the test suite with `@WithTestResource`, Quarkus will run the corresponding `QuarkusTestResourceLifecycleManager` before any tests are run.
-A test suite is also free to utilize multiple `@WithTestResource` annotations, in which case all the corresponding `QuarkusTestResourceLifecycleManager` objects will be run before the tests. When using multiple test resources they can be started concurrently. For that you need to set `@WithTestResource(parallel = true)`.
+When a test annotated with `@WithTestResource`, Quarkus will run the corresponding `QuarkusTestResourceLifecycleManager` before the test.
+
+IMPORTANT: By default, `@WithTestResource` applies only to the test on which the annotation is placed. Each test that is annotated with `@WithTestResource`  will result in the application being re-augmented and restarted
+(in a similar fashion as happens in dev-mode when a change is detected) in order to incorporate the settings configured by the annotation. This means that if there are many instances of the annotation used throughout the testsuite,
+test execution speed will be impacted by these restarts.
 
 NOTE: Test resources are applied for a given test class or custom profile. To activate for all tests you can use `@WithTestResource(restrictToAnnotatedClass = false)`.
 
+NOTE: When using multiple test resources they can be started concurrently. For that you need to set `@WithTestResource(parallel = true)`.
+
 Quarkus provides a few implementations of `QuarkusTestResourceLifecycleManager` out of the box (see `io.quarkus.test.h2.H2DatabaseTestResource` which starts an H2 database, or `io.quarkus.test.kubernetes.client.KubernetesServerTestResource` which starts a mock Kubernetes API server),
 but it is common to create custom implementations to address specific application needs.
 Common cases include starting docker containers using https://www.testcontainers.org/[Testcontainers] (an example of which can be found https://github.com/quarkusio/quarkus/blob/main/test-framework/keycloak-server/src/main/java/io/quarkus/test/keycloak/server/KeycloakTestResourceLifecycleManager.java[here]),

test-framework/common/src/main/java/io/quarkus/test/common/QuarkusTestResource.java

@@ -12,12 +12,12 @@
 
 /**
  * Used to define a test resource.
- *
+ * <p>
  * <b>All</b> {@code QuarkusTestResource} annotations in the test module
  * are discovered (regardless of the test which contains the annotation)
  * and their corresponding {@code QuarkusTestResourceLifecycleManager}
  * started <b>before</b> <b>any</b> test is run.
- *
+ * <p>
  * Note that test resources are never restarted when running {@code @Nested} test classes.
  *
  * @deprecated Use the new {@link WithTestResource} instead. It will be a long while before this is removed, but better to move
@@ -51,6 +51,10 @@
      * Whether this annotation should only be enabled if it is placed on the currently running test class or test profile.
      * Note that this defaults to true for meta-annotations since meta-annotations are only considered
      * for the current test class or test profile.
+     * <p>
+     * Note: When this is set to {@code true} (which is the default), the annotation {@code @WithTestResource} will result
+     * in the application being re-augmented and restarted (in a similar fashion as happens in dev-mode when a change is
+     * detected).
      */
     boolean restrictToAnnotatedClass() default false;
 

test-framework/common/src/main/java/io/quarkus/test/common/WithTestResource.java

@@ -11,13 +11,18 @@
 import io.quarkus.test.common.WithTestResource.List;
 
 /**
- * Used to define a test resource.
- *
+ * Used to define a test resource, which can affect various aspects of the application lifecycle.
+ * <p>
+ * Note: When using the {@code restrictToAnnotatedClass=true} (which is the default), each test that is annotated
+ * with {@code @WithTestResource} will result in the application being re-augmented and restarted (in a similar fashion
+ * as happens in dev-mode when a change is detected) in order to incorporate the settings configured by the annotation.
+ * If there are many instances of the annotation used throughout the testsuite, this could result in slow test execution.
+ * <p>
  * <b>All</b> {@code WithTestResource} annotations in the test module
  * are discovered (regardless of the test which contains the annotation)
  * and their corresponding {@code QuarkusTestResourceLifecycleManager}
  * started <b>before</b> <b>any</b> test is run.
- *
+ * <p>
  * Note that test resources are never restarted when running {@code @Nested} test classes.
  * <p>
  * This replaces {@link QuarkusTestResource}. The only difference is that the default value for
@@ -55,6 +60,10 @@
      * Whether this annotation should only be enabled if it is placed on the currently running test class or test profile.
      * Note that this defaults to true for meta-annotations since meta-annotations are only considered
      * for the current test class or test profile.
+     * <p>
+     * Note: When this is set to {@code true} (which is the default), the annotation {@code @WithTestResource} will result
+     * in the application being re-augmented and restarted (in a similar fashion as happens in dev-mode when a change is
+     * detected) in order to incorporate the settings configured by the annotation.
      */
     boolean restrictToAnnotatedClass() default true;