Merge pull request #50941 from michalvavrik/feature/support-quarkus-test-meta-annotation

gsmet · web-flow · commit 9211a18c6e10 · 2025-11-12T11:08:46.000+01:00
Support using `@QuarkusTest` in meta-annotations
diff --git a/docs/src/main/asciidoc/getting-started-testing.adoc b/docs/src/main/asciidoc/getting-started-testing.adoc
@@ -1640,6 +1640,36 @@ 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.
 ====
 
+== Creating `@QuarkusTest` meta-annotation
+
+The `@QuarkusTest` annotation can be grouped with other annotations by defining a custom meta-annotation.
+For instance, you can bundle it with the `@Tag` annotation to automatically mark a group of tests like in the example below:
+
+[source,java]
+----
+org.acme.test
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Inherited;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+import io.quarkus.test.junit.QuarkusTest;
+import org.junit.jupiter.api.Tag;
+
+@Target(ElementType.TYPE)
+@Retention(RetentionPolicy.RUNTIME)
+@Documented
+@Inherited
+@QuarkusTest
+@Tag("security")
+public @interface QuarkusSecurityTest {   <1>
+}
+----
+<1> The `@QuarkusSecurityTest` annotation can be used instead of the `@QuarkusTest` annotation.
+
 == Testing Components
 
 Quarkus provides the `QuarkusComponentTestExtension`, a JUnit extension to ease the testing of components and mocking of their dependencies.
diff --git a/extensions/arc/deployment/src/main/java/io/quarkus/arc/deployment/TestsAsBeansProcessor.java b/extensions/arc/deployment/src/main/java/io/quarkus/arc/deployment/TestsAsBeansProcessor.java
@@ -5,6 +5,7 @@
 import java.util.List;
 import java.util.Optional;
 import java.util.Set;
+import java.util.stream.Collectors;
 
 import org.jboss.jandex.AnnotationInstance;
 import org.jboss.jandex.AnnotationTarget;
@@ -61,7 +62,11 @@ public void testClassBeans(List<TestClassBeanBuildItem> items, BuildProducer<Add
 
     @BuildStep(onlyIf = IsTest.class)
     AnnotationsTransformerBuildItem vetoTestClassesNotMatchingTestProfile(Optional<TestProfileBuildItem> testProfile,
-            CombinedIndexBuildItem index) {
+            CombinedIndexBuildItem index, List<TestAnnotationBuildItem> testAnnotationBuildItems) {
+        Set<String> additionalTestAnnotationNames = testAnnotationBuildItems.stream()
+                .map(TestAnnotationBuildItem::getAnnotationClassName)
+                .filter(a -> !a.equals(QUARKUS_TEST.toString()))
+                .collect(Collectors.toSet());
         // Since we only need to register all test classes that belong to the "current" test profile
         // we need to veto other test classes during the build
         return new AnnotationsTransformerBuildItem(AnnotationTransformation
@@ -71,7 +76,8 @@ AnnotationsTransformerBuildItem vetoTestClassesNotMatchingTestProfile(Optional<T
                     boolean veto = false;
                     if (maybeTestClass.hasAnnotation(QUARKUS_TEST)
                             || maybeTestClass.hasAnnotation(QUARKUS_INTEGRATION_TEST)
-                            || maybeTestClass.hasAnnotation(QUARKUS_MAIN_TEST)) {
+                            || maybeTestClass.hasAnnotation(QUARKUS_MAIN_TEST)
+                            || additionalTestAnnotationNames.stream().anyMatch(maybeTestClass::hasAnnotation)) {
                         String testProfileClassName = testProfile.map(TestProfileBuildItem::getTestProfileClassName)
                                 .orElse(null);
                         veto = !matchesProfile(maybeTestClass, testProfileClassName);
diff --git a/integration-tests/test-extension/tests/src/test/java/io/quarkus/it/extension/AbstractQuarkusTestMetaAnnotationTest.java b/integration-tests/test-extension/tests/src/test/java/io/quarkus/it/extension/AbstractQuarkusTestMetaAnnotationTest.java
@@ -0,0 +1,28 @@
+package io.quarkus.it.extension;
+
+import jakarta.enterprise.context.ApplicationScoped;
+import jakarta.inject.Inject;
+
+import org.junit.jupiter.api.Assertions;
+import org.junit.jupiter.api.Test;
+
+public abstract class AbstractQuarkusTestMetaAnnotationTest {
+
+    @Inject
+    MyTestBean bean;
+
+    @Test
+    void testInjectedBean() {
+        Assertions.assertEquals("foo", bean.foo());
+    }
+
+    @ApplicationScoped
+    public static class MyTestBean {
+
+        public String foo() {
+            return "foo";
+        }
+
+    }
+
+}
diff --git a/integration-tests/test-extension/tests/src/test/java/io/quarkus/it/extension/QuarkusTestExtensionMetaAnnotationHierarchyDepth1Test.java b/integration-tests/test-extension/tests/src/test/java/io/quarkus/it/extension/QuarkusTestExtensionMetaAnnotationHierarchyDepth1Test.java
@@ -0,0 +1,6 @@
+package io.quarkus.it.extension;
+
+@QuarkusTestExtensionMetaAnnotationL1
+public class QuarkusTestExtensionMetaAnnotationHierarchyDepth1Test extends AbstractQuarkusTestMetaAnnotationTest {
+
+}
diff --git a/integration-tests/test-extension/tests/src/test/java/io/quarkus/it/extension/QuarkusTestExtensionMetaAnnotationHierarchyDepth2Test.java b/integration-tests/test-extension/tests/src/test/java/io/quarkus/it/extension/QuarkusTestExtensionMetaAnnotationHierarchyDepth2Test.java
@@ -0,0 +1,6 @@
+package io.quarkus.it.extension;
+
+@QuarkusTestExtensionMetaAnnotationL2
+public class QuarkusTestExtensionMetaAnnotationHierarchyDepth2Test extends AbstractQuarkusTestMetaAnnotationTest {
+
+}
diff --git a/integration-tests/test-extension/tests/src/test/java/io/quarkus/it/extension/QuarkusTestExtensionMetaAnnotationL1.java b/integration-tests/test-extension/tests/src/test/java/io/quarkus/it/extension/QuarkusTestExtensionMetaAnnotationL1.java
@@ -0,0 +1,20 @@
+package io.quarkus.it.extension;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Inherited;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+import org.junit.jupiter.api.extension.ExtendWith;
+
+import io.quarkus.test.junit.QuarkusTestExtension;
+
+@Target(ElementType.TYPE)
+@Retention(RetentionPolicy.RUNTIME)
+@Documented
+@Inherited
+@ExtendWith(QuarkusTestExtension.class)
+public @interface QuarkusTestExtensionMetaAnnotationL1 {
+}
diff --git a/integration-tests/test-extension/tests/src/test/java/io/quarkus/it/extension/QuarkusTestExtensionMetaAnnotationL2.java b/integration-tests/test-extension/tests/src/test/java/io/quarkus/it/extension/QuarkusTestExtensionMetaAnnotationL2.java
@@ -0,0 +1,16 @@
+package io.quarkus.it.extension;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Inherited;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+@Target(ElementType.TYPE)
+@Retention(RetentionPolicy.RUNTIME)
+@Documented
+@Inherited
+@QuarkusTestExtensionMetaAnnotationL2Parent
+public @interface QuarkusTestExtensionMetaAnnotationL2 {
+}
diff --git a/integration-tests/test-extension/tests/src/test/java/io/quarkus/it/extension/QuarkusTestExtensionMetaAnnotationL2Parent.java b/integration-tests/test-extension/tests/src/test/java/io/quarkus/it/extension/QuarkusTestExtensionMetaAnnotationL2Parent.java
@@ -0,0 +1,20 @@
+package io.quarkus.it.extension;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Inherited;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+import org.junit.jupiter.api.extension.ExtendWith;
+
+import io.quarkus.test.junit.QuarkusTestExtension;
+
+@Target(ElementType.TYPE)
+@Retention(RetentionPolicy.RUNTIME)
+@Documented
+@Inherited
+@ExtendWith(QuarkusTestExtension.class)
+public @interface QuarkusTestExtensionMetaAnnotationL2Parent {
+}
diff --git a/integration-tests/test-extension/tests/src/test/java/io/quarkus/it/extension/QuarkusTestMetaAnnotationHierarchyDepth1Test.java b/integration-tests/test-extension/tests/src/test/java/io/quarkus/it/extension/QuarkusTestMetaAnnotationHierarchyDepth1Test.java
@@ -0,0 +1,6 @@
+package io.quarkus.it.extension;
+
+@QuarkusTestMetaAnnotationL1
+public class QuarkusTestMetaAnnotationHierarchyDepth1Test extends AbstractQuarkusTestMetaAnnotationTest {
+
+}
diff --git a/integration-tests/test-extension/tests/src/test/java/io/quarkus/it/extension/QuarkusTestMetaAnnotationHierarchyDepth2Test.java b/integration-tests/test-extension/tests/src/test/java/io/quarkus/it/extension/QuarkusTestMetaAnnotationHierarchyDepth2Test.java
@@ -0,0 +1,6 @@
+package io.quarkus.it.extension;
+
+@QuarkusTestMetaAnnotationL2
+public class QuarkusTestMetaAnnotationHierarchyDepth2Test extends AbstractQuarkusTestMetaAnnotationTest {
+
+}
diff --git a/integration-tests/test-extension/tests/src/test/java/io/quarkus/it/extension/QuarkusTestMetaAnnotationL1.java b/integration-tests/test-extension/tests/src/test/java/io/quarkus/it/extension/QuarkusTestMetaAnnotationL1.java
@@ -0,0 +1,21 @@
+package io.quarkus.it.extension;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Inherited;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+import org.junit.jupiter.api.Tag;
+
+import io.quarkus.test.junit.QuarkusTest;
+
+@Target(ElementType.TYPE)
+@Retention(RetentionPolicy.RUNTIME)
+@Documented
+@Inherited
+@QuarkusTest
+@Tag("custom-tag")
+public @interface QuarkusTestMetaAnnotationL1 {
+}
diff --git a/integration-tests/test-extension/tests/src/test/java/io/quarkus/it/extension/QuarkusTestMetaAnnotationL2.java b/integration-tests/test-extension/tests/src/test/java/io/quarkus/it/extension/QuarkusTestMetaAnnotationL2.java
@@ -0,0 +1,16 @@
+package io.quarkus.it.extension;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Inherited;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+@Target(ElementType.TYPE)
+@Retention(RetentionPolicy.RUNTIME)
+@Documented
+@Inherited
+@QuarkusTestMetaAnnotationL2Parent
+public @interface QuarkusTestMetaAnnotationL2 {
+}
diff --git a/integration-tests/test-extension/tests/src/test/java/io/quarkus/it/extension/QuarkusTestMetaAnnotationL2Parent.java b/integration-tests/test-extension/tests/src/test/java/io/quarkus/it/extension/QuarkusTestMetaAnnotationL2Parent.java
@@ -0,0 +1,18 @@
+package io.quarkus.it.extension;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Inherited;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+import io.quarkus.test.junit.QuarkusTest;
+
+@Target(ElementType.TYPE)
+@Retention(RetentionPolicy.RUNTIME)
+@Documented
+@Inherited
+@QuarkusTest
+public @interface QuarkusTestMetaAnnotationL2Parent {
+}
diff --git a/test-framework/junit5/src/main/java/io/quarkus/test/junit/TestBuildChainFunction.java b/test-framework/junit5/src/main/java/io/quarkus/test/junit/TestBuildChainFunction.java
@@ -2,8 +2,12 @@
 
 import java.nio.file.Path;
 import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.Collection;
+import java.util.HashSet;
 import java.util.List;
 import java.util.Map;
+import java.util.Objects;
 import java.util.ServiceLoader;
 import java.util.function.Consumer;
 import java.util.function.Function;
@@ -15,6 +19,7 @@
 import org.jboss.jandex.FieldInfo;
 import org.jboss.jandex.Index;
 import org.jboss.jandex.Type;
+import org.junit.jupiter.api.extension.ExtendWith;
 
 import io.quarkus.bootstrap.classloading.QuarkusClassLoader;
 import io.quarkus.builder.BuildChainBuilder;
@@ -31,12 +36,16 @@
 
 public class TestBuildChainFunction implements Function<Map<String, Object>, List<Consumer<BuildChainBuilder>>> {
 
+    private static final String QUARKUS_TEST_NAME = QuarkusTest.class.getName();
+    private static final String QUARKUS_TEST_EXTENSION_NAME = QuarkusTestExtension.class.getName();
+
     @Override
     public List<Consumer<BuildChainBuilder>> apply(Map<String, Object> stringObjectMap) {
         Path testLocation = (Path) stringObjectMap.get(AbstractJvmQuarkusTestExtension.TEST_LOCATION);
         // the index was written by the extension
         Index testClassesIndex = TestClassIndexer.readIndex(testLocation,
                 (Class<?>) stringObjectMap.get(AbstractJvmQuarkusTestExtension.TEST_CLASS));
+        Collection<TestAnnotationBuildItem> testAnnotationBuildItems = collectTestAnnotationItems(testClassesIndex);
 
         List<Consumer<BuildChainBuilder>> allCustomizers = new ArrayList<>(1);
         Consumer<BuildChainBuilder> defaultCustomizer = new Consumer<BuildChainBuilder>() {
@@ -76,7 +85,7 @@ public boolean test(String className) {
                 buildChainBuilder.addBuildStep(new BuildStep() {
                     @Override
                     public void execute(BuildContext context) {
-                        context.produce(new TestAnnotationBuildItem(QuarkusTest.class.getName()));
+                        testAnnotationBuildItems.forEach(context::produce);
                     }
                 })
                         .produces(TestAnnotationBuildItem.class)
@@ -160,4 +169,40 @@ public void execute(BuildContext context) {
 
         return allCustomizers;
     }
+
+    private static Collection<TestAnnotationBuildItem> collectTestAnnotationItems(Index testClassesIndex) {
+        var result = new HashSet<String>();
+        result.add(QUARKUS_TEST_NAME);
+
+        // collect meta-annotations with @QuarkusTest
+        result.addAll(collectMetaAnnotations(QUARKUS_TEST_NAME, testClassesIndex));
+        // collect meta-annotations with @ExtendWith(QuarkusTestExtension.class)
+        Predicate<AnnotationInstance> isValueQuarkusTestExtension = ai -> ai.value() != null
+                && Arrays.stream(ai.value().asClassArray())
+                        .anyMatch(type -> type.name() != null && QUARKUS_TEST_EXTENSION_NAME.equals(type.name().toString()));
+        result.addAll(collectMetaAnnotations(ExtendWith.class.getName(), testClassesIndex, isValueQuarkusTestExtension));
+
+        return result.stream().map(TestAnnotationBuildItem::new).toList();
+    }
+
+    private static List<String> collectMetaAnnotations(String annotationName, Index testClassesIndex) {
+        return collectMetaAnnotations(annotationName, testClassesIndex, ai -> true);
+    }
+
+    private static List<String> collectMetaAnnotations(String annotationName, Index testClassesIndex,
+            Predicate<AnnotationInstance> initialFilter) {
+        return testClassesIndex.getAnnotations(annotationName)
+                .stream()
+                .filter(initialFilter)
+                .map(AnnotationInstance::target)
+                .filter(Objects::nonNull)
+                .filter(at -> at.kind() == AnnotationTarget.Kind.CLASS)
+                .map(AnnotationTarget::asClass)
+                .filter(ClassInfo::isAnnotation)
+                .<String> mapMulti((ci, consumer) -> {
+                    consumer.accept(ci.name().toString());
+                    collectMetaAnnotations(ci.name().toString(), testClassesIndex).forEach(consumer);
+                })
+                .toList();
+    }
 }
