Adding new WithTesResource annotation

Closes quarkusio#37853

devtools/project-core-extension-codestarts/src/main/resources/codestarts/quarkus/extension-codestarts/messaging-codestart/java/src/test/java/org/acme/MyMessagingApplicationTest.java

@@ -1,6 +1,6 @@
 package org.acme;
 
-import io.quarkus.test.common.QuarkusTestResource;
+import io.quarkus.test.common.WithTestResource;
 import io.quarkus.test.common.QuarkusTestResourceLifecycleManager;
 import io.quarkus.test.junit.QuarkusTest;
 

docs/src/main/asciidoc/datasource.adoc

@@ -700,8 +700,8 @@ This will allow you to test your application even when it is compiled into a nat
 
 . Add the following specific annotation on any class in your integration tests for running integration tests in both JVM or native executables:
 +
-* `@QuarkusTestResource(H2DatabaseTestResource.class)`
-* `@QuarkusTestResource(DerbyDatabaseTestResource.class)`
+* `@WithTestResource(H2DatabaseTestResource.class)`
+* `@WithTestResource(DerbyDatabaseTestResource.class)`
 +
 This ensures that the test suite starts and terminates the managed database in a separate process as required for test execution.
 +
@@ -710,10 +710,10 @@ This ensures that the test suite starts and terminates the managed database in a
 ----
 package my.app.integrationtests.db;
 
-import io.quarkus.test.common.QuarkusTestResource;
+import io.quarkus.test.common.WithTestResource;
 import io.quarkus.test.h2.H2DatabaseTestResource;
 
-@QuarkusTestResource(H2DatabaseTestResource.class)
+@WithTestResource(H2DatabaseTestResource.class)
 public class TestResources {
 }
 ----

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

@@ -550,7 +550,7 @@ public class MockGreetingProfile implements QuarkusTestProfile { <1>
      * Additional {@link QuarkusTestResourceLifecycleManager} classes (along with their init params) to be used from this
      * specific test profile.
      *
-     * If this method is not overridden, then only the {@link QuarkusTestResourceLifecycleManager} classes enabled via the {@link io.quarkus.test.common.QuarkusTestResource} class
+     * If this method is not overridden, then only the {@link QuarkusTestResourceLifecycleManager} classes enabled via the {@link io.quarkus.test.common.WithTestResource} class
      * annotation will be used for the tests using this profile (which is the same behavior as tests that don't use a profile at all).
      */
     @Override
@@ -1086,13 +1086,12 @@ If you are using Quarkus Security, check out the xref:security-testing.adoc[Test
 [[quarkus-test-resource]]
 == Starting services before the Quarkus application starts
 
-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.QuarkusTestResource` and `io.quarkus.test.common.QuarkusTestResourceLifecycleManager`.
+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 `@QuarkusTestResource`, Quarkus will run the corresponding `QuarkusTestResourceLifecycleManager` before any tests are run.
-A test suite is also free to utilize multiple `@QuarkusTestResource` 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 `@QuarkusTestResource(parallel = true)`.
+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)`.
 
-NOTE: Test resources are global, even if they are defined on a test class or custom profile, which means they will all be activated for all tests, even though we do
-remove duplicates. If you want to only enable a test resource on a single test class or test profile, you can use `@QuarkusTestResource(restrictToAnnotatedClass = true)`.
+NOTE: Test resources are applied for a given test class or custom profile. To activate for all tests you can use `@WithTestResource(restrictToAnnotatedClass = false)`.
 
 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.
@@ -1109,7 +1108,7 @@ If for example you have a test like the following:
 [source,java]
 ----
 @QuarkusTest
-@QuarkusTestResource(MyWireMockResource.class)
+@WithTestResource(MyWireMockResource.class)
 public class MyTest {
 
     @InjectWireMock // this a custom annotation you are defining in your own application
@@ -1160,15 +1159,15 @@ any necessary injections into the test class.
 
 === Annotation-based test resources
 
-It is possible to write test resources that are enabled and configured using annotations. This is enabled by placing the `@QuarkusTestResource`
+It is possible to write test resources that are enabled and configured using annotations. This is enabled by placing the `@WithTestResource`
 on an annotation which will be used to enable and configure the test resource.
 
 For example, this defines the `@WithKubernetesTestServer` annotation, which you can use on your tests to activate the `KubernetesServerTestResource`,
 but only for the annotated test class. You can also place them on your `QuarkusTestProfile` test profiles.
 
 [source,java]
 ----
-@QuarkusTestResource(KubernetesServerTestResource.class)
+@WithTestResource(KubernetesServerTestResource.class)
 @Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.TYPE)
 public @interface WithKubernetesTestServer {
@@ -1212,12 +1211,12 @@ public class KubernetesServerTestResource
 }
 ----
 
-If you want to make the annotation repeatable, the containing annotation type must be annotated with `@QuarkusTestResourceRepeatable`.
+If you want to make the annotation repeatable, the containing annotation type must be annotated with `@WithTestResourceRepeatable`.
 For example, this would define a repeatable `@WithRepeatableTestResource` annotation.
 
 [source,java]
 ----
-@QuarkusTestResource(KubernetesServerTestResource.class)
+@WithTestResource(KubernetesServerTestResource.class)
 @Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.TYPE)
 @Repeatable(WithRepeatableTestResource.List.class)
@@ -1227,7 +1226,7 @@ public @interface WithRepeatableTestResource {
 
     @Target(ElementType.TYPE)
     @Retention(RetentionPolicy.RUNTIME)
-    @QuarkusTestResourceRepeatable(WithRepeatableTestResource.class)
+    @WithTestResourceRepeatable(WithRepeatableTestResource.class)
     @interface List {
         WithRepeatableTestResource[] value();
     }
@@ -1412,7 +1411,7 @@ public class CustomResource implements QuarkusTestResourceLifecycleManager, DevS
 }
 ----
 
-`CustomResource` would be activated on a `@QuarkusIntegrationTest` using `@QuarkusTestResource` as is described in the corresponding section of this doc.
+`CustomResource` would be activated on a `@QuarkusIntegrationTest` using `@WithTestResource` as is described in the corresponding section of this doc.
 
 === Executing against a running application
 

docs/src/main/asciidoc/kafka-schema-registry-avro.adoc

@@ -440,7 +440,7 @@ what we send.
 ----
 package org.acme.kafka;
 
-import io.quarkus.test.common.QuarkusTestResource;
+import io.quarkus.test.common.WithTestResource;
 import io.quarkus.test.common.http.TestHTTPResource;
 import io.quarkus.test.junit.QuarkusTest;
 import io.restassured.http.ContentType;
@@ -607,7 +607,7 @@ public class KafkaAndSchemaRegistryTestResource implements QuarkusTestResourceLi
 [source,java]
 ----
 @QuarkusTest
-@QuarkusTestResource(KafkaAndSchemaRegistryTestResource.class)
+@WithTestResource(KafkaAndSchemaRegistryTestResource.class)
 public class MovieResourceTest {
     ...
 }

docs/src/main/asciidoc/kafka-schema-registry-json-schema.adoc

@@ -468,7 +468,7 @@ what we send.
 ----
 package org.acme.kafka;
 
-import io.quarkus.test.common.QuarkusTestResource;
+import io.quarkus.test.common.WithTestResource;
 import io.quarkus.test.common.http.TestHTTPResource;
 import io.quarkus.test.junit.QuarkusTest;
 import io.restassured.http.ContentType;
@@ -635,7 +635,7 @@ public class KafkaAndSchemaRegistryTestResource implements QuarkusTestResourceLi
 [source,java]
 ----
 @QuarkusTest
-@QuarkusTestResource(KafkaAndSchemaRegistryTestResource.class)
+@WithTestResource(KafkaAndSchemaRegistryTestResource.class)
 public class MovieResourceTest {
     ...
 }

docs/src/main/asciidoc/kafka.adoc

@@ -2236,7 +2236,7 @@ Create a Quarkus Test using the test resource created above:
 import static org.awaitility.Awaitility.await;
 
 @QuarkusTest
-@QuarkusTestResource(KafkaTestResourceLifecycleManager.class)
+@WithTestResource(KafkaTestResourceLifecycleManager.class)
 class BaristaTest {
 
     @Inject
@@ -2295,7 +2295,7 @@ public class BeverageProcessor {
 import static org.awaitility.Awaitility.await;
 
 @QuarkusTest
-@QuarkusTestResource(KafkaTestResourceLifecycleManager.class)
+@WithTestResource(KafkaTestResourceLifecycleManager.class)
 class BaristaTest {
 
     @Inject
@@ -2380,7 +2380,7 @@ For using `KafkaCompanion` API in tests, start by adding the following dependenc
 
 which provides `io.quarkus.test.kafka.KafkaCompanionResource` - an implementation of `io.quarkus.test.common.QuarkusTestResourceLifecycleManager`.
 
-Then use `@QuarkusTestResource` to configure the Kafka Companion in tests, for example:
+Then use `@WithTestResource` to configure the Kafka Companion in tests, for example:
 
 [source, java]
 ----
@@ -2391,15 +2391,15 @@ import java.util.UUID;
 import org.apache.kafka.clients.producer.ProducerRecord;
 import org.junit.jupiter.api.Test;
 
-import io.quarkus.test.common.QuarkusTestResource;
+import io.quarkus.test.common.WithTestResource;
 import io.quarkus.test.junit.QuarkusTest;
 import io.quarkus.test.kafka.InjectKafkaCompanion;
 import io.quarkus.test.kafka.KafkaCompanionResource;
 import io.smallrye.reactive.messaging.kafka.companion.ConsumerTask;
 import io.smallrye.reactive.messaging.kafka.companion.KafkaCompanion;
 
 @QuarkusTest
-@QuarkusTestResource(KafkaCompanionResource.class)
+@WithTestResource(KafkaCompanionResource.class)
 public class OrderProcessorTest {
 
     @InjectKafkaCompanion // <1>
@@ -2430,7 +2430,7 @@ If the Kafka Dev Service is available during tests, `KafkaCompanionResource` use
 The configuration of the created Kafka broker can be customized using `@ResourceArg`, for example:
 [source,java]
 ----
-@QuarkusTestResource(value = KafkaCompanionResource.class, initArgs = {
+@WithTestResource(value = KafkaCompanionResource.class, initArgs = {
         @ResourceArg(name = "strimzi.kafka.image", value = "quay.io/strimzi-test-container/test-container:0.106.0-kafka-3.7.0"), // Image name
         @ResourceArg(name = "kafka.port", value = "9092"), // Fixed port for kafka, by default it will be exposed on a random port
         @ResourceArg(name = "kraft", value = "true"), // Enable Kraft mode

docs/src/main/asciidoc/kubernetes-client.adoc

@@ -260,7 +260,7 @@ public class MyTest {
 }
 ----
 
-Alternately, you can create an extension of the `KubernetesServerTestResource` class to ensure all your `@QuarkusTest` enabled test classes share the same mock server setup via the `QuarkusTestResource` annotation:
+Alternately, you can create an extension of the `KubernetesServerTestResource` class to ensure all your `@QuarkusTest` enabled test classes share the same mock server setup via the `WithTestResource` annotation:
 
 [source%nowrap,java]
 ----
@@ -278,7 +278,7 @@ public class CustomKubernetesMockServerTestResource extends KubernetesServerTest
 and use this in your other test classes as follows:
 [source%nowrap,java]
 ----
-@QuarkusTestResource(CustomKubernetesMockServerTestResource.class)
+@WithTestResource(CustomKubernetesMockServerTestResource.class)
 @QuarkusTest
 public class KubernetesClientTest {
 
@@ -478,7 +478,7 @@ Mock support is also provided in a similar fashion:
 
 [source, java]
 ----
-@QuarkusTestResource(OpenShiftMockServerTestResource.class)
+@WithTestResource(OpenShiftMockServerTestResource.class)
 @QuarkusTest
 public class OpenShiftClientTest {
 

docs/src/main/asciidoc/messaging.adoc

@@ -703,7 +703,7 @@ Create a `@QuarkusTest` using the test resource created above:
 
 [source, java]
 ----
-import io.quarkus.test.common.QuarkusTestResource;
+import io.quarkus.test.common.WithTestResource;
 import io.quarkus.test.junit.QuarkusTest;
 import io.smallrye.reactive.messaging.memory.InMemoryConnector;
 import io.smallrye.reactive.messaging.memory.InMemorySink;
@@ -718,7 +718,7 @@ import static org.junit.jupiter.api.Assertions.assertEquals;
 import static org.awaitility.Awaitility.await;
 
 @QuarkusTest
-@QuarkusTestResource(InMemoryConnectorLifecycleManager.class)
+@WithTestResource(InMemoryConnectorLifecycleManager.class)
 class MyMessagingApplicationTest {
 
     @Inject

docs/src/main/asciidoc/observability-devservices-lgtm.adoc

@@ -113,11 +113,11 @@ And for the least 'auto-magical' usage in the tests, simply disable both (Dev Re
 quarkus.observability.enabled=false
 ----
 
-And then explicitly list LGTM Dev Resource in the test as a `@QuarkusTestResource` resource:
+And then explicitly list LGTM Dev Resource in the test as a `@WithTestResource` resource:
 [source, java]
 ----
 @QuarkusTest
-@QuarkusTestResource(value = LgtmResource.class, restrictToAnnotatedClass = true)
+@WithTestResource(LgtmResource.class)
 @TestProfile(QuarkusTestResourceTestProfile.class)
 public class LgtmLifecycleTest extends LgtmTestBase {
 }

docs/src/main/asciidoc/observability-devservices.adoc

@@ -20,7 +20,7 @@ NOTE: Each Dev Resource implementation is an `@QuarkusTestResourceLifecycleManag
 
 * explicitly disable Dev Services and enable Dev Resources and use less-heavy concept of starting and stopping Dev Resources
 
-* explicitly disable both Dev Services and Dev Resources, and use Quarkus' `@QuarkusTestResource` testing concept (see Note)
+* explicitly disable both Dev Services and Dev Resources, and use Quarkus' `@WithTestResource` testing concept (see Note)
 
 You can either add Observability extension dependency along with needed Dev Resources dependencies, or you use existing `sinks` - pom.xml files which add Observability extension dependency along with other required dependencies for certain technology stacks; e.g. `victoriametrics` sink would have `quarkus-observability-devresource-victoriametrics` and `quarkus-victoriametrics-client` dependencies already included in the `pom.xml`.
 

docs/src/main/asciidoc/rest-client.adoc

@@ -1856,13 +1856,13 @@ testImplementation("org.wiremock:wiremock:$wiremockVersion") <1>
 ----
 <1> Use a proper Wiremock version. All available versions can be found link:https://search.maven.org/artifact/org.wiremock/wiremock[here].
 
-In Quarkus tests when some service needs to be started before the Quarkus tests are ran, we utilize the `@io.quarkus.test.common.QuarkusTestResource`
+In Quarkus tests when some service needs to be started before the Quarkus tests are ran, we utilize the `@io.quarkus.test.common.WithTestResource`
 annotation to specify a `io.quarkus.test.common.QuarkusTestResourceLifecycleManager` which can start the service and supply configuration
 values that Quarkus will use.
 
 [NOTE]
 ====
-For more details about `@QuarkusTestResource` refer to  xref:getting-started-testing.adoc#quarkus-test-resource[this part of the documentation].
+For more details about `@WithTestResource` refer to  xref:getting-started-testing.adoc#quarkus-test-resource[this part of the documentation].
 ====
 
 Let's create an implementation of `QuarkusTestResourceLifecycleManager` called `WiremockExtensions` like so:
@@ -1926,17 +1926,12 @@ The `ExtensionsResourceTest` test class needs to be annotated like so:
 [source,java]
 ----
 @QuarkusTest
-@QuarkusTestResource(WireMockExtensions.class)
+@WithTestResource(WireMockExtensions.class)
 public class ExtensionsResourceTest {
 
 }
 ----
 
-[WARNING]
-====
-`@QuarkusTestResource` applies to all tests, not just `ExtensionsResourceTest`.
-====
-
 == Known limitations
 
 While the REST Client extension aims to be a drop-in replacement for the RESTEasy Client extension, there are some differences

docs/src/main/asciidoc/resteasy-client.adoc

@@ -317,11 +317,11 @@ import static org.hamcrest.Matchers.greaterThan;
 import org.acme.rest.client.resources.WireMockExtensionsResource;
 import org.junit.jupiter.api.Test;
 
-import io.quarkus.test.common.QuarkusTestResource;
+import io.quarkus.test.common.WithTestResource;
 import io.quarkus.test.junit.QuarkusTest;
 
 @QuarkusTest
-@QuarkusTestResource(WireMockExtensionsResource.class)
+@WithTestResource(WireMockExtensionsResource.class)
 public class ExtensionsResourceTest {
 
     @Test

docs/src/main/asciidoc/security-oauth2.adoc

@@ -348,13 +348,13 @@ testImplementation("org.wiremock:wiremock:${wiremock.version}") <1>
 ----
 <1> Use a proper Wiremock version. All available versions can be found link:https://search.maven.org/artifact/org.wiremock/wiremock[here].
 
-In Quarkus tests when some service needs to be started before the Quarkus tests are ran, we utilize the `@io.quarkus.test.common.QuarkusTestResource`
+In Quarkus tests when some service needs to be started before the Quarkus tests are ran, we utilize the `@io.quarkus.test.common.WithTestResource`
 annotation to specify a `io.quarkus.test.common.QuarkusTestResourceLifecycleManager` which can start the service and supply configuration
 values that Quarkus will use.
 
 [NOTE]
 ====
-For more details about `@QuarkusTestResource` refer to xref:getting-started-testing.adoc#quarkus-test-resource[this part of the documentation].
+For more details about `@WithTestResource` refer to xref:getting-started-testing.adoc#quarkus-test-resource[this part of the documentation].
 ====
 
 Let's create an implementation of `QuarkusTestResourceLifecycleManager` called `MockAuthorizationServerTestResource` like so:
@@ -402,14 +402,14 @@ public class MockAuthorizationServerTestResource implements QuarkusTestResourceL
 <5> When all tests have finished, shutdown Wiremock.
 
 
-Your test class needs to be annotated like with `@QuarkusTestResource(MockAuthorizationServerTestResource.class)` to use this `QuarkusTestResourceLifecycleManager`.
+Your test class needs to be annotated like with `@WithTestResource(MockAuthorizationServerTestResource.class)` to use this `QuarkusTestResourceLifecycleManager`.
 
 Below is an example of a test that uses the `MockAuthorizationServerTestResource`.
 
 [source,java]
 ----
 @QuarkusTest
-@QuarkusTestResource(MockAuthorizationServerTestResource.class) // <1>
+@WithTestResource(MockAuthorizationServerTestResource.class) // <1>
 class TokenSecuredResourceTest {
     // use whatever token you want as the mock OAuth server will accept all tokens
     private static final String BEARER_TOKEN = "337aab0f-b547-489b-9dbd-a54dc7bdf20d"; // <2>
@@ -442,13 +442,6 @@ class TokenSecuredResourceTest {
 <2> Define whatever token you want, it will not be validated by the OAuth2 mock authorization server.
 <3> Use this token inside the `Authorization` header to trigger OAuth2 authentication.
 
-
-[WARNING]
-====
-`@QuarkusTestResource` applies to all tests, not just `TokenSecuredResourceTest`.
-====
-
-
 == References
 
 * https://tools.ietf.org/html/rfc6749[OAuth2]