diff --git a/docs/src/main/asciidoc/getting-started-testing.adoc b/docs/src/main/asciidoc/getting-started-testing.adoc index 8f69be4a2c16e..b7aada35bd742 100644 --- a/docs/src/main/asciidoc/getting-started-testing.adoc +++ b/docs/src/main/asciidoc/getting-started-testing.adoc @@ -987,11 +987,68 @@ A very common need is to start some services on which your Quarkus application d 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)`. +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)`. + 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.KubernetesMockServerTestResource` 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-quickstarts/blob/master/kafka-quickstart/src/test/java/org/acme/kafka/KafkaResource.java[here]), or starting a mock HTTP server using http://wiremock.org/[Wiremock] (an example of which can be found https://github.com/geoand/quarkus-test-demo/blob/master/src/test/java/org/acme/getting/started/country/WiremockCountries.java[here]). +=== 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` +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) +@Retention(RetentionPolicy.RUNTIME) +@Target(ElementType.TYPE) +public @interface WithKubernetesTestServer { + /** + * Start it with HTTPS + */ + boolean https() default false; + + /** + * Start it in CRUD mode + */ + boolean crud() default true; + + /** + * Port to use, defaults to any available port + */ + int port() default 0; +} +---- + +The `KubernetesServerTestResource` class has to implement the +`QuarkusTestResourceConfigurableLifecycleManager` interface in order to be configured using the previous annotation: + +[source,java] +---- +public class KubernetesServerTestResource + implements QuarkusTestResourceConfigurableLifecycleManager { + + private boolean https = false; + private boolean crud = true; + private int port = 0; + + @Override + public void init(WithKubernetesTestServer annotation) { + this.https = annotation.https(); + this.crud = annotation.crud(); + this.port = annotation.port(); + } + + // ... +} +---- + == Hang Detection `@QuarkusTest` has support for hang detection to help diagnose any unexpected hangs. If no progress is made for a specified diff --git a/docs/src/main/asciidoc/kubernetes-client.adoc b/docs/src/main/asciidoc/kubernetes-client.adoc index 547a64ad48ac7..8624958617491 100644 --- a/docs/src/main/asciidoc/kubernetes-client.adoc +++ b/docs/src/main/asciidoc/kubernetes-client.adoc @@ -71,9 +71,9 @@ public class KubernetesClientProducer { == Testing -To make testing against a mock Kubernetes API extremely simple, Quarkus provides the `KubernetesMockServerTestResource` which automatically launches +To make testing against a mock Kubernetes API extremely simple, Quarkus provides the `WithKubernetesTestServer` annotation which automatically launches a mock of the Kubernetes API server and sets the proper environment variables needed so that the Kubernetes Client configures itself to use said mock. -Tests can inject the mock and set it up in any way necessary for the particular testing using the `@MockServer` annotation. +Tests can inject the mock server and set it up in any way necessary for the particular testing using the `@KubernetesTestServer` annotation. Let's assume we have a REST endpoint defined like so: @@ -100,12 +100,13 @@ We could write a test for this endpoint very easily like so: [source%nowrap,java] ---- -@QuarkusTestResource(KubernetesMockServerTestResource.class) +// you can even configure aspects like crud, https and port on this annotation +@WithKubernetesTestServer @QuarkusTest public class KubernetesClientTest { - @MockServer - KubernetesMockServer mockServer; + @KubernetesTestServer + KubernetesServer mockServer; @BeforeEach public void before() { @@ -139,14 +140,14 @@ Note that to take advantage of these features, the `quarkus-test-kubernetes-clie ---- -You can create a `CustomKubernetesMockServerTestResource.java` to ensure all your `@QuarkusTest` enabled test classes share the same mock server setup: +Alternately, you can create a `CustomKubernetesMockServerTestResource.java` to ensure all your `@QuarkusTest` enabled test classes share the same mock server setup: [source%nowrap,java] ---- -public class CustomKubernetesMockServerTestResource extends KubernetesMockServerTestResource { +public class CustomKubernetesMockServerTestResource extends KubernetesServerTestResource { @Override - public void configureMockServer(KubernetesMockServer mockServer) { + public void configureMockServer(KubernetesServer mockServer) { mockServer.expect().get().withPath("/api/v1/namespaces/test/pods") .andReturn(200, new PodList()) .always(); diff --git a/integration-tests/kubernetes-client/pom.xml b/integration-tests/kubernetes-client/pom.xml index dc37c18c7b122..ea2df35547387 100644 --- a/integration-tests/kubernetes-client/pom.xml +++ b/integration-tests/kubernetes-client/pom.xml @@ -93,6 +93,9 @@ org.apache.maven.plugins maven-surefire-plugin + + alphabetical +