Merge pull request quarkusio#50323 from mkouba/component-callbacks

QuarkusComponentTest: introduce QuarkusComponentTestCallbacks, integrate seamlessly with quarkus-panache-mock

Author: FroMage

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

@@ -863,7 +863,7 @@ public String apply(Class<?> aClass) {
                             ClassLoader excl = (ClassLoader) getClassLoader.invoke(ecl, componentTestClass, cl);
                             utClasses.add(excl.loadClass(componentTestClass));
                         } catch (Exception e) {
-                            log.debug(e);
+                            log.debug(e.getMessage(), e);
                             log.warnf("Failed to load component test class %s, it will not be executed this run.",
                                     componentTestClass);
                         }

docs/src/main/asciidoc/hibernate-orm-panache.adoc

@@ -1164,6 +1164,7 @@ public class PersonRepository implements PanacheRepositoryBase<Person,Integer> {
 
 == Mocking
 
+[[mocking_active_record]]
 === Using the active record pattern
 
 If you are using the active record pattern you cannot use Mockito directly as it does not support mocking static methods,

docs/src/main/asciidoc/testing-components.adoc

@@ -18,7 +18,7 @@ Therefore, Quarkus provides `QuarkusComponentTestExtension` - a JUnit extension
 Unlike `@QuarkusTest` this extension does not start a full Quarkus application but merely the CDI container and the configuration service.
 You can find more details in the <<lifecycle>> section.
 
-TIP: This extension is available in the `quarkus-junit5-component` dependency.
+TIP: This JUnit extension is available in the `quarkus-junit5-component` dependency.
 
 == Basic example
 
@@ -303,6 +303,101 @@ By default, only the config properties from `application.properties` and propert
 System properties and ENV variables are _not_ included in the test config by default.
 However, you can use `@QuarkusComponentTest#useSystemConfigSources()` or `QuarkusComponentTestExtensionBuilder#useSystemConfigSources()` to configure this behavior.
 
+== Panache entities using the active record pattern
+
+If you are using the active record pattern you cannot easily leverage `Mockito#mockStatic()` to mock static methods declared on `PanacheEntityBase`.
+In a normal Quarkus app, these static methods are automatically overridden in subclasses.
+However, `QuarkusComponentTest` does not start a full Quarkus application.
+Nevertheless, you can use the `quarkus-panache-mock` module which integrates seamlessly with `QuarkusComponentTest`.
+
+Add this dependency to your `pom.xml`:
+
+[source,xml]
+----
+<dependency>
+    <groupId>io.quarkus</groupId>
+    <artifactId>quarkus-panache-mock</artifactId>
+    <scope>test</scope>
+</dependency>
+----
+
+Given this simple entity:
+
+[source,java]
+----
+@Entity
+public class Person extends PanacheEntity {
+
+   public String name;
+   
+   public Person(String name) {
+      this.name = name;
+   }
+
+   public static List<Person> findOrdered() {
+      return find("ORDER BY name").list();
+   }
+}
+----
+
+That is used in a simple bean:
+
+[source,java]
+----
+public class PersonService {
+
+   public List<Person> getPersons(boolen sorted) {
+      if (sorted) {
+         return Person.findOrdered();
+      }
+      return Person.listAll();
+   }
+}
+----
+
+You can write your component test like:
+
+.Nested test
+[source, java]
+----
+import static org.junit.jupiter.api.Assertions.assertEquals;
+
+import jakarta.inject.Inject;
+import io.quarkus.test.component.QuarkusComponentTest;
+import io.quarkus.panache.mock.MockPanacheEntities;
+import org.junit.jupiter.api.Test;
+import org.mockito.Mockito;
+
+@QuarkusComponentTest <1>
+@MockPanacheEntities(Person.class) <2>
+public class PersonServiceTest {
+
+    @Inject
+    PersonService personService; <3>
+    
+    @Test
+    public void testGetPersons() { 
+        Mockito.when(Person.listAll()).thenReturn(List.of(new Person("Tom")));
+        List<Person> list = personService.getPersons(false);
+        assertEquals(1, list.size());
+        assertEquals("Tom", list.get(0).name);
+        
+        Mockito.when(Person.findOrdered()).thenReturn(List.of(new Person("Tom")));
+        list = personService.getPersons(true);
+        assertEquals(1, list.size());
+        assertEquals("Tom", list.get(0).name);
+    }
+
+}
+----
+<1> The `QuarkusComponentTest` annotation registers the JUnit extension.
+<2> `@MockPanacheEntities` installs mocks for the given entity classes. 
+<3> The test injects the component under the test - `PersonService`.
+
+TIP: See also xref:hibernate-orm-panache.adoc#mocking_active_record[Simplified Hibernate ORM with Panache - Using the active record pattern] for more information.
+
+NOTE: Currently, only the integration with Hibernate ORM is supported. Other variants of the Panache API, such as MongoDB and Hibernate Reactive, are not supported yet.
+
 == Mocking CDI Interceptors
 
 If a tested component class declares an interceptor binding then you might need to mock the interception too.

extensions/panache/panache-mock/pom.xml

@@ -30,10 +30,20 @@
             <groupId>io.quarkus</groupId>
             <artifactId>quarkus-junit5-mockito</artifactId>
         </dependency>
+        <dependency>
+            <groupId>io.quarkus</groupId>
+            <artifactId>quarkus-junit5-component</artifactId>
+            <optional>true</optional>
+        </dependency>
         <dependency>
             <groupId>org.mockito</groupId>
             <artifactId>mockito-core</artifactId>
         </dependency>
+        <dependency>
+            <groupId>io.quarkus</groupId>
+            <artifactId>quarkus-hibernate-orm-panache</artifactId>
+            <scope>test</scope>
+        </dependency>
     </dependencies>
     <build>
         <plugins>

extensions/panache/panache-mock/src/main/java/io/quarkus/panache/mock/MockPanacheEntities.java

@@ -0,0 +1,24 @@
+package io.quarkus.panache.mock;
+
+import static java.lang.annotation.ElementType.TYPE;
+import static java.lang.annotation.RetentionPolicy.RUNTIME;
+
+import java.lang.annotation.Retention;
+import java.lang.annotation.Target;
+
+/**
+ * Install mocks for the given entity classes.
+ * <p>
+ * This annotation only works together with {@code QuarkusComponentTest}.
+ *
+ * @see PanacheMock#mock(Class...)
+ */
+@Retention(RUNTIME)
+@Target(TYPE)
+public @interface MockPanacheEntities {
+
+    /**
+     * The entity classes.
+     */
+    Class<?>[] value() default {};
+}

extensions/panache/panache-mock/src/main/java/io/quarkus/panache/mock/impl/PanacheQuarkusComponentTestCallbacks.java

@@ -0,0 +1,189 @@
+package io.quarkus.panache.mock.impl;
+
+import java.lang.reflect.Modifier;
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.function.BiFunction;
+
+import org.jboss.jandex.AnnotationInstance;
+import org.jboss.jandex.ClassInfo;
+import org.jboss.jandex.DotName;
+import org.jboss.jandex.MethodInfo;
+import org.objectweb.asm.ClassVisitor;
+import org.objectweb.asm.Opcodes;
+
+import io.quarkus.arc.processor.BytecodeTransformer;
+import io.quarkus.gizmo.BytecodeCreator;
+import io.quarkus.gizmo.CatchBlockCreator;
+import io.quarkus.gizmo.ClassTransformer;
+import io.quarkus.gizmo.FieldDescriptor;
+import io.quarkus.gizmo.MethodCreator;
+import io.quarkus.gizmo.MethodDescriptor;
+import io.quarkus.gizmo.ResultHandle;
+import io.quarkus.gizmo.TryBlock;
+import io.quarkus.panache.common.deployment.PanacheConstants;
+import io.quarkus.panache.mock.MockPanacheEntities;
+import io.quarkus.panache.mock.PanacheMock;
+import io.quarkus.test.component.QuarkusComponentTestCallbacks;
+
+public class PanacheQuarkusComponentTestCallbacks implements QuarkusComponentTestCallbacks {
+
+    private static final DotName PANACHE_ENTITY = DotName.createSimple("io.quarkus.hibernate.orm.panache.PanacheEntity");
+    private static final DotName PANACHE_ENTITY_BASE = DotName
+            .createSimple("io.quarkus.hibernate.orm.panache.PanacheEntityBase");
+
+    @Override
+    public void beforeBuild(BeforeBuildContext buildContext) {
+        Class<?> testClass = buildContext.getTestClass();
+        MockPanacheEntities panacheMocks = testClass.getAnnotation(MockPanacheEntities.class);
+        if (panacheMocks == null || panacheMocks.value().length == 0) {
+            return;
+        }
+        List<ClassInfo> mockedEntities = new ArrayList<>();
+        for (Class<?> mockClass : panacheMocks.value()) {
+            ClassInfo maybeMockedEntity = buildContext.getComputingBeanArchiveIndex().getClassByName(mockClass);
+            DotName superName = maybeMockedEntity.superName();
+            if (maybeMockedEntity.isAbstract()
+                    || superName == null
+                    || (!superName.equals(PANACHE_ENTITY)
+                            && !superName.equals(PANACHE_ENTITY_BASE))) {
+                continue;
+            }
+            mockedEntities.add(maybeMockedEntity);
+        }
+
+        Map<DotName, List<MethodInfo>> entityUserMethods = new HashMap<>();
+        for (ClassInfo entity : mockedEntities) {
+            for (MethodInfo method : entity.methods()) {
+                if (!method.isSynthetic()
+                        && Modifier.isStatic(method.flags())
+                        && Modifier.isPublic(method.flags())) {
+                    List<MethodInfo> userMethods = entityUserMethods.get(entity.name());
+                    if (userMethods == null) {
+                        userMethods = new ArrayList<>();
+                        entityUserMethods.put(entity.name(), userMethods);
+                    }
+                    userMethods.add(method);
+                }
+            }
+        }
+
+        Map<DotName, List<MethodInfo>> entityGeneratedMethods = new HashMap<>();
+        ClassInfo panacheEntityBaseClassInfo = buildContext.getComputingBeanArchiveIndex()
+                .getClassByName(DotName.createSimple("io.quarkus.hibernate.orm.panache.PanacheEntityBase"));
+        for (ClassInfo entity : mockedEntities) {
+            for (MethodInfo method : panacheEntityBaseClassInfo.methods()) {
+                if (!userMethodExists(entityUserMethods.get(entity.name()), method)) {
+                    AnnotationInstance bridge = method.annotation(PanacheConstants.DOTNAME_GENERATE_BRIDGE);
+                    if (bridge != null) {
+                        // TODO bridge.value("targetReturnTypeErased") and bridge.value("callSuperMethod")
+                        List<MethodInfo> generated = entityGeneratedMethods.get(entity.name());
+                        if (generated == null) {
+                            generated = new ArrayList<>();
+                            entityGeneratedMethods.put(entity.name(), generated);
+                        }
+                        generated.add(method);
+                    }
+                }
+            }
+        }
+
+        for (ClassInfo entity : mockedEntities) {
+            String entityClassName = entity.name().toString();
+            ClassTransformer transformer = new ClassTransformer(entity.name().toString());
+            List<MethodInfo> userMethods = entityUserMethods.get(entity.name());
+            if (userMethods != null) {
+                for (MethodInfo userMethod : userMethods) {
+                    transformer.removeMethod(MethodDescriptor.of(userMethod));
+                    addMethod(entityClassName, transformer, userMethod);
+                }
+            }
+            List<MethodInfo> generatedMethods = entityGeneratedMethods.get(entity.name());
+            if (generatedMethods != null) {
+                for (MethodInfo generatedMethod : generatedMethods) {
+                    addMethod(entityClassName, transformer, generatedMethod);
+                }
+            }
+            buildContext.addBytecodeTransformer(
+                    new BytecodeTransformer(entityClassName, new BiFunction<String, ClassVisitor, ClassVisitor>() {
+                        @Override
+                        public ClassVisitor apply(String className, ClassVisitor originalVisitor) {
+                            return transformer.applyTo(originalVisitor);
+                        }
+                    }));
+        }
+    }
+
+    private void addMethod(String entityClass, ClassTransformer transformer, MethodInfo method) {
+        MethodCreator transform = transformer.addMethod(MethodDescriptor.of(method));
+        transform.setModifiers(Opcodes.ACC_PUBLIC | Opcodes.ACC_STATIC);
+        // if (!PanacheMock.IsMockEnabled)
+        //   throw new RuntimeException("Panache mock not enabled");
+        // if (!PanacheMock.isMocked(TestClass.class))
+        //   throw new RuntimeException("FooEntity not mocked");
+        // try {
+        //    return (int)PanacheMock.mockMethod(TestClass.class, "foo", new Class<?>[] {int.class}, new Object[] {arg});
+        // } catch (PanacheMock.InvokeRealMethodException e) {
+        //    throw new RuntimeException("Unstubbed method called", e);
+        // }
+        ResultHandle isMockEnabled = transform
+                .readStaticField(FieldDescriptor.of(PanacheMock.class, "IsMockEnabled", boolean.class));
+        BytecodeCreator mockNotEnabled = transform.ifTrue(isMockEnabled).falseBranch();
+        mockNotEnabled.throwException(RuntimeException.class, "Panache mock not enabled");
+        ResultHandle isMocked = transform.invokeStaticMethod(
+                MethodDescriptor.ofMethod(PanacheMock.class, "isMocked", boolean.class, Class.class),
+                transform.loadClass(entityClass));
+        BytecodeCreator notMocked = transform.ifTrue(isMocked).falseBranch();
+        notMocked.throwException(RuntimeException.class, entityClass + " not mocked");
+        ResultHandle entityClazz = transform.loadClass(entityClass);
+        ResultHandle methodName = transform.load(method.name());
+        ResultHandle paramTypes = transform.newArray(Class.class, method.parametersCount());
+        for (int i = 0; i < method.parametersCount(); i++) {
+            transform.writeArrayValue(paramTypes, i, transform.loadClass(method.parameterType(i).name().toString()));
+        }
+        ResultHandle args = transform.newArray(Object.class, method.parametersCount());
+        for (int i = 0; i < method.parametersCount(); i++) {
+            transform.writeArrayValue(args, i, transform.getMethodParam(i));
+        }
+        TryBlock tryInvoke = transform.tryBlock();
+        ResultHandle ret = tryInvoke.invokeStaticMethod(MethodDescriptor.ofMethod(PanacheMock.class, "mockMethod",
+                Object.class, Class.class, String.class, Class[].class, Object[].class), entityClazz, methodName,
+                paramTypes,
+                args);
+        tryInvoke.returnValue(ret);
+        CatchBlockCreator catched = tryInvoke.addCatch(PanacheMock.InvokeRealMethodException.class);
+        catched.throwException(RuntimeException.class,
+                "Unstubbed method called: " + method.toString(), catched.getCaughtException());
+    }
+
+    @Override
+    public void afterStart(AfterStartContext afterStartContext) {
+        Class<?> testClass = afterStartContext.getTestClass();
+        MockPanacheEntities panacheMocks = testClass.getAnnotation(MockPanacheEntities.class);
+        if (panacheMocks == null || panacheMocks.value().length == 0) {
+            return;
+        }
+        PanacheMock.mock(panacheMocks.value());
+    }
+
+    @Override
+    public void afterStop(AfterStopContext afterStopContext) {
+        PanacheMock.reset();
+    }
+
+    private boolean userMethodExists(List<MethodInfo> userMethods, MethodInfo method) {
+        if (userMethods == null || userMethods.isEmpty()) {
+            return false;
+        }
+        String descriptor = method.descriptor();
+        for (MethodInfo userMethod : userMethods) {
+            if (userMethod.descriptor().equals(descriptor)) {
+                return true;
+            }
+        }
+        return false;
+    }
+
+}

extensions/panache/panache-mock/src/main/resources/META-INF/services/io.quarkus.test.component.QuarkusComponentTestCallbacks

@@ -0,0 +1 @@
+io.quarkus.panache.mock.impl.PanacheQuarkusComponentTestCallbacks