Merge pull request #33607 from mkouba/component-test

QuarkusComponentTest

bom/application/pom.xml

@@ -2955,6 +2955,11 @@
                 <artifactId>quarkus-test-security-webauthn</artifactId>
                 <version>${project.version}</version>
             </dependency>
+            <dependency>
+                <groupId>io.quarkus</groupId>
+                <artifactId>quarkus-junit5-component</artifactId>
+                <version>${project.version}</version>
+            </dependency>
             <dependency>
                 <groupId>io.quarkus</groupId>
                 <artifactId>quarkus-junit5-internal</artifactId>

core/deployment/src/main/java/io/quarkus/deployment/dev/testing/JunitTestRunner.java

@@ -569,6 +569,7 @@ private DiscoveryResult discoverTestClasses() {
                 }
             }
         }
+
         Set<DotName> allTestAnnotations = collectTestAnnotations(index);
         Set<DotName> allTestClasses = new HashSet<>();
         Map<DotName, DotName> enclosingClasses = new HashMap<>();
@@ -600,7 +601,8 @@ private DiscoveryResult discoverTestClasses() {
         Set<String> unitTestClasses = new HashSet<>();
         for (DotName testClass : allTestClasses) {
             String name = testClass.toString();
-            if (integrationTestClasses.contains(name) || quarkusTestClasses.contains(name)) {
+            if (integrationTestClasses.contains(name)
+                    || quarkusTestClasses.contains(name)) {
                 continue;
             }
             var enclosing = enclosingClasses.get(testClass);

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

@@ -1507,3 +1507,135 @@ For `@QuarkusIntegrationTest` tests that result in launcher the application as a
 This can be used by `QuarkusTestResourceLifecycleManager` that need to launch additional containers that the application will communicate with.
 ====
 
+== Testing Components
+
+IMPORTANT: This feature is experimental and the API may change in the future.
+
+In Quarkus, the component model is built on top CDI.
+Therefore, Quarkus provides the `QuarkusComponentTestExtension`, a JUnit extension to ease the testing of components and mocking of their dependencies.
+This extension is available in the `quarkus-junit5-component` dependency.
+
+Let's have a component `Foo`:
+
+[source, java]
+----
+package org.acme;
+
+import jakarta.enterprise.context.ApplicationScoped;
+import jakarta.inject.Inject;
+
+@ApplicationScoped <1>
+public class Foo {
+
+    @Inject
+    Charlie charlie; <2>
+    
+    @ConfigProperty(name = "bar") 
+    boolean bar; <3>
+
+    public String ping() {
+        return bar ? charlie.ping() : "nok";
+    }
+}
+----
+<1> `Foo` is an `@ApplicationScoped` CDI bean.
+<2> `Foo` depends on `Charlie` which declares a method `ping()`.
+<3> `Foo` depends on the config property `bar`.
+
+Then a component test could look like:
+
+[source, java]
+----
+import static org.junit.jupiter.api.Assertions.assertEquals;
+
+import jakarta.inject.Inject;
+import io.quarkus.test.component.TestConfigProperty;
+import io.quarkus.test.component.TestMock;
+import io.quarkus.test.component.QuarkusComponentTest;
+import org.junit.jupiter.api.Test;
+import org.mockito.Mockito;
+
+@QuarkusComponentTest <1>
+@TestConfigProperty(key = "bar", value = "true") <2>
+public class FooTest {
+
+    @Inject
+    Foo foo; <3>
+
+    @ConfigureMock
+    Charlie charlieMock; <4>
+
+    @Test
+    public void testPing() {
+        Mockito.when(charlieMock.ping()).thenReturn("OK"); <5>
+        assertEquals("OK", foo.ping());
+    }
+}
+----
+<1> The `QuarkusComponentTest` annotation registers the JUnit extension.
+<2> Set a configuration property for the test.
+<3> The test injects the component under the test. The types of all fields annotated with `@Inject` are considered the component types under test. You can also specify additional component classes via `@QuarkusComponentTest#value()`.
+<4> The test also injects `Charlie`, a dependency for which a synthetic `@Singleton` bean is registered automatically. The injected reference is an "unconfigured" Mockito mock.
+<5> We can leverage the Mockito API in a test method to configure the behavior.
+
+If you need the full control over the `QuarkusComponentTestExtension` configuration then you can use the `@RegisterExtension` annotation and configure the extension programatically.
+The test above could be rewritten like:
+
+[source, java]
+----
+import static org.junit.jupiter.api.Assertions.assertEquals;
+
+import jakarta.inject.Inject;
+import io.quarkus.test.component.TestMock;
+import io.quarkus.test.component.QuarkusComponentTestExtension;
+import org.junit.jupiter.api.Test;
+import org.mockito.Mockito;
+
+public class FooTest {
+
+    @RegisterExtension <1>
+    static final QuarkusComponentTestExtension extension = new QuarkusComponentTestExtension().configProperty("bar","true");
+
+    @Inject
+    Foo foo;
+
+    @ConfigureMock
+    Charlie charlieMock;
+
+    @Test
+    public void testPing() {
+        Mockito.when(charlieMock.ping()).thenReturn("OK");
+        assertEquals("OK", foo.ping());
+    }
+}
+----
+<1> The `QuarkusComponentTestExtension` is configured in a static field.
+
+=== Lifecycle
+
+So what exactly does the `QuarkusComponentTest` do?
+It starts the CDI container and registers a dedicated xref:config-reference.adoc[configuration object] during the `before all` test phase. 
+The container is stopped and the config is released during the `after all` test phase.
+The fields annotated with `@Inject` and `@ConfigureMock` are injected after a test instance is created and unset before a test instance is destroyed.
+Finally, the CDI request context is activated and terminated per each test method.
+
+NOTE: By default, a new test instance is created for each test method. Therefore, a new CDI container is started for each test method. However, if the test class is annotated with `@org.junit.jupiter.api.TestInstance` and the test instance lifecycle is set to `org.junit.jupiter.api.TestInstance.Lifecycle.PER_CLASS` then the CDI container will be shared across all test method executions of a given test class.
+
+=== Auto Mocking Unsatisfied Dependencies
+
+Unlike in regular CDI environments the test does not fail if a component injects an unsatisfied dependency. 
+Instead, a synthetic bean is registered automatically for each combination of required type and qualifiers of an injection point that resolves to an unsatisfied dependency.
+The bean has the `@Singleton` scope so it's shared across all injection points with the same required type and qualifiers. 
+The injected reference is an _unconfigured_ Mockito mock.
+You can inject the mock in your test and leverage the Mockito API to configure the behavior.
+
+=== Custom Mocks For Unsatisfied Dependencies
+
+Sometimes you need the full control over the bean attributes and maybe even configure the default mock behavior.
+You can use the mock configurator API via the `QuarkusComponentTestExtension#mock()` method.
+
+=== Configuration
+
+A dedicated `SmallRyeConfig` is registered during the `before all` test phase.
+Moreover, it's possible to set the configuration properties via the `QuarkusComponentTestExtension#configProperty(String, String)` method or the `@TestConfigProperty` annotation.
+If you only need to use the default values for missing config properties, then the `QuarkusComponentTestExtension#useDefaultConfigProperties()` or `@QuarkusComponentTest#useDefaultConfigProperties()` might come in useful.

independent-projects/arc/processor/src/main/java/io/quarkus/arc/processor/Annotations.java

@@ -1,10 +1,15 @@
 package io.quarkus.arc.processor;
 
+import java.lang.annotation.Annotation;
+import java.lang.reflect.Method;
+import java.util.ArrayDeque;
 import java.util.ArrayList;
+import java.util.Arrays;
 import java.util.Collection;
 import java.util.Collections;
 import java.util.HashSet;
 import java.util.List;
+import java.util.Queue;
 import java.util.Set;
 import java.util.function.Function;
 
@@ -196,4 +201,162 @@ public static Collection<AnnotationInstance> onlyRuntimeVisible(Collection<Annot
         return result;
     }
 
+    public static org.jboss.jandex.AnnotationInstance jandexAnnotation(Annotation annotation) {
+        Class<? extends Annotation> annotationType = annotationType(annotation);
+
+        DotName name = DotName.createSimple(annotationType.getName());
+        @SuppressWarnings("unchecked")
+        org.jboss.jandex.AnnotationValue[] jandexAnnotationValues = jandexAnnotationValues(
+                (Class<Annotation>) annotationType, annotation);
+
+        return org.jboss.jandex.AnnotationInstance.create(name, null, jandexAnnotationValues);
+    }
+
+    @SuppressWarnings("unchecked")
+    private static Class<? extends Annotation> annotationType(Annotation annotation) {
+        Class<? extends Annotation> annotationType = null;
+
+        Queue<Class<?>> candidates = new ArrayDeque<>();
+        candidates.add(annotation.getClass());
+        while (!candidates.isEmpty()) {
+            Class<?> candidate = candidates.remove();
+
+            if (candidate.isAnnotation()) {
+                annotationType = (Class<? extends Annotation>) candidate;
+                break;
+            }
+
+            Collections.addAll(candidates, candidate.getInterfaces());
+        }
+
+        if (annotationType == null) {
+            throw new IllegalArgumentException("Not an annotation: " + annotation);
+        }
+
+        return annotationType;
+    }
+
+    private static <A extends Annotation> org.jboss.jandex.AnnotationValue[] jandexAnnotationValues(
+            Class<A> annotationType, A annotationInstance) {
+        List<org.jboss.jandex.AnnotationValue> result = new ArrayList<>();
+        for (Method member : annotationType.getDeclaredMethods()) {
+            try {
+                // annotation types do not necessarily have to be public (if the annotation type
+                // and the build compatible extension class reside in the same package)
+                if (!member.canAccess(annotationInstance)) {
+                    member.setAccessible(true);
+                }
+                result.add(jandexAnnotationValue(member.getName(), member.invoke(annotationInstance)));
+            } catch (ReflectiveOperationException e) {
+                throw new RuntimeException(e);
+            }
+        }
+        return result.toArray(new org.jboss.jandex.AnnotationValue[0]);
+    }
+
+    private static org.jboss.jandex.AnnotationValue jandexAnnotationValue(String name, Object value) {
+        if (value instanceof Boolean) {
+            return org.jboss.jandex.AnnotationValue.createBooleanValue(name, (Boolean) value);
+        } else if (value instanceof Byte) {
+            return org.jboss.jandex.AnnotationValue.createByteValue(name, (Byte) value);
+        } else if (value instanceof Short) {
+            return org.jboss.jandex.AnnotationValue.createShortValue(name, (Short) value);
+        } else if (value instanceof Integer) {
+            return org.jboss.jandex.AnnotationValue.createIntegerValue(name, (Integer) value);
+        } else if (value instanceof Long) {
+            return org.jboss.jandex.AnnotationValue.createLongValue(name, (Long) value);
+        } else if (value instanceof Float) {
+            return org.jboss.jandex.AnnotationValue.createFloatValue(name, (Float) value);
+        } else if (value instanceof Double) {
+            return org.jboss.jandex.AnnotationValue.createDoubleValue(name, (Double) value);
+        } else if (value instanceof Character) {
+            return org.jboss.jandex.AnnotationValue.createCharacterValue(name, (Character) value);
+        } else if (value instanceof String) {
+            return org.jboss.jandex.AnnotationValue.createStringValue(name, (String) value);
+        } else if (value instanceof Enum) {
+            return org.jboss.jandex.AnnotationValue.createEnumValue(name,
+                    DotName.createSimple(((Enum<?>) value).getDeclaringClass().getName()), ((Enum<?>) value).name());
+        } else if (value instanceof Class) {
+            return org.jboss.jandex.AnnotationValue.createClassValue(name, Types.jandexType((Class<?>) value));
+        } else if (value.getClass().isAnnotation()) {
+            Class<? extends Annotation> annotationType = annotationType((Annotation) value);
+            @SuppressWarnings("unchecked")
+            org.jboss.jandex.AnnotationValue[] jandexAnnotationValues = jandexAnnotationValues(
+                    (Class<Annotation>) annotationType, (Annotation) value);
+            org.jboss.jandex.AnnotationInstance jandexAnnotation = org.jboss.jandex.AnnotationInstance.create(
+                    DotName.createSimple(annotationType.getName()), null, jandexAnnotationValues);
+            return org.jboss.jandex.AnnotationValue.createNestedAnnotationValue(name, jandexAnnotation);
+        } else if (value.getClass().isArray()) {
+            org.jboss.jandex.AnnotationValue[] jandexAnnotationValues = Arrays.stream(boxArray(value))
+                    .map(it -> jandexAnnotationValue(name, it))
+                    .toArray(org.jboss.jandex.AnnotationValue[]::new);
+            return org.jboss.jandex.AnnotationValue.createArrayValue(name, jandexAnnotationValues);
+        } else {
+            throw new IllegalArgumentException("Unknown annotation attribute value: " + value);
+        }
+    }
+
+    private static Object[] boxArray(Object value) {
+        if (value instanceof boolean[]) {
+            boolean[] primitiveArray = (boolean[]) value;
+            Object[] boxedArray = new Boolean[primitiveArray.length];
+            for (int i = 0; i < primitiveArray.length; i++) {
+                boxedArray[i] = primitiveArray[i];
+            }
+            return boxedArray;
+        } else if (value instanceof byte[]) {
+            byte[] primitiveArray = (byte[]) value;
+            Object[] boxedArray = new Byte[primitiveArray.length];
+            for (int i = 0; i < primitiveArray.length; i++) {
+                boxedArray[i] = primitiveArray[i];
+            }
+            return boxedArray;
+        } else if (value instanceof short[]) {
+            short[] primitiveArray = (short[]) value;
+            Object[] boxedArray = new Short[primitiveArray.length];
+            for (int i = 0; i < primitiveArray.length; i++) {
+                boxedArray[i] = primitiveArray[i];
+            }
+            return boxedArray;
+        } else if (value instanceof int[]) {
+            int[] primitiveArray = (int[]) value;
+            Object[] boxedArray = new Integer[primitiveArray.length];
+            for (int i = 0; i < primitiveArray.length; i++) {
+                boxedArray[i] = primitiveArray[i];
+            }
+            return boxedArray;
+        } else if (value instanceof long[]) {
+            long[] primitiveArray = (long[]) value;
+            Object[] boxedArray = new Long[primitiveArray.length];
+            for (int i = 0; i < primitiveArray.length; i++) {
+                boxedArray[i] = primitiveArray[i];
+            }
+            return boxedArray;
+        } else if (value instanceof float[]) {
+            float[] primitiveArray = (float[]) value;
+            Object[] boxedArray = new Float[primitiveArray.length];
+            for (int i = 0; i < primitiveArray.length; i++) {
+                boxedArray[i] = primitiveArray[i];
+            }
+            return boxedArray;
+        } else if (value instanceof double[]) {
+            double[] primitiveArray = (double[]) value;
+            Object[] boxedArray = new Double[primitiveArray.length];
+            for (int i = 0; i < primitiveArray.length; i++) {
+                boxedArray[i] = primitiveArray[i];
+            }
+            return boxedArray;
+        } else if (value instanceof char[]) {
+            char[] primitiveArray = (char[]) value;
+            Object[] boxedArray = new Character[primitiveArray.length];
+            for (int i = 0; i < primitiveArray.length; i++) {
+                boxedArray[i] = primitiveArray[i];
+            }
+            return boxedArray;
+        } else if (value instanceof Object[]) {
+            return (Object[]) value;
+        } else {
+            throw new IllegalArgumentException("Not an array: " + value);
+        }
+    }
 }

independent-projects/arc/processor/src/main/java/io/quarkus/arc/processor/BeanConfigurator.java

@@ -71,6 +71,7 @@ public void done() {
 
             BeanInfo.Builder builder = new BeanInfo.Builder()
                     .implClazz(implClass)
+                    .identifier(identifier)
                     .providerType(providerType)
                     .beanDeployment(beanDeployment)
                     .scope(scope)

independent-projects/arc/processor/src/main/java/io/quarkus/arc/processor/BeanConfiguratorBase.java

@@ -22,6 +22,7 @@
 
 import io.quarkus.arc.BeanCreator;
 import io.quarkus.arc.BeanDestroyer;
+import io.quarkus.arc.InjectableBean;
 import io.quarkus.arc.InjectableReferenceProvider;
 import io.quarkus.arc.SyntheticCreationalContext;
 import io.quarkus.arc.processor.InjectionPointInfo.TypeAndQualifiers;
@@ -36,6 +37,7 @@
 public abstract class BeanConfiguratorBase<THIS extends BeanConfiguratorBase<THIS, T>, T> extends ConfiguratorBase<THIS>
         implements Consumer<AnnotationInstance> {
 
+    protected String identifier;
     protected final DotName implClazz;
     protected final Set<Type> types;
     protected final Set<AnnotationInstance> qualifiers;
@@ -311,6 +313,21 @@ public THIS destroyer(Consumer<MethodCreator> methodCreatorConsumer) {
         return cast(this);
     }
 
+    /**
+     * The identifier becomes part of the {@link BeanInfo#getIdentifier()} and {@link InjectableBean#getIdentifier()}.
+     * <p>
+     * An identifier can be used to register multiple synthetic beans with the same set of types and qualifiers.
+     *
+     * @param identifier
+     * @return self
+     * @see #defaultBean()
+     * @see #alternative(boolean)
+     */
+    public THIS identifier(String identifier) {
+        this.identifier = identifier;
+        return cast(this);
+    }
+
     @SuppressWarnings("unchecked")
     protected static <T> T cast(Object obj) {
         return (T) obj;