Example usage:
+ *
+ * {@code
+ * @MojoTest
+ * class MyMojoTest {
+ * @Test
+ * @Basedir("src/test/resources/specific-test-case")
+ * @InjectMojo(goal = "compile")
+ * void testSpecificCase(MyMojo mojo) {
+ * // Test resources will be loaded from src/test/resources/specific-test-case
+ * mojo.execute();
+ * }
+ * }
+ * }
+ *
+ *
+ * @see MojoTest
+ * @see MojoExtension
+ * @since 3.4.0
*/
@Retention(RetentionPolicy.RUNTIME)
@Inherited
+@Target(ElementType.METHOD)
public @interface Basedir {
String value() default "";
}
diff --git a/maven-plugin-testing-harness/src/main/java/org/apache/maven/api/plugin/testing/InjectMojo.java b/maven-plugin-testing-harness/src/main/java/org/apache/maven/api/plugin/testing/InjectMojo.java
index 272eb9b4..24961bcb 100644
--- a/maven-plugin-testing-harness/src/main/java/org/apache/maven/api/plugin/testing/InjectMojo.java
+++ b/maven-plugin-testing-harness/src/main/java/org/apache/maven/api/plugin/testing/InjectMojo.java
@@ -18,15 +18,71 @@
*/
package org.apache.maven.api.plugin.testing;
+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;
/**
+ * Annotation used in Maven plugin tests to inject and configure a Mojo instance.
+ * This annotation can be applied to either test methods or parameters to specify
+ * which Mojo should be instantiated and how it should be configured.
*
+ * The annotation requires a {@code goal} attribute to specify which Mojo goal + * should be instantiated. Optionally, a custom {@code pom} file can be specified + * to provide specific configuration for the test.
+ * + *Example usage on a test method:
+ *
+ * {@code
+ * @Test
+ * @InjectMojo(goal = "compile")
+ * void testCompileMojo(CompileMojo mojo) {
+ * mojo.execute();
+ * // verify compilation results
+ * }
+ * }
+ *
+ *
+ * Example usage with a custom POM:
+ *
+ * {@code
+ * @Test
+ * @InjectMojo(
+ * goal = "compile",
+ * pom = "src/test/resources/test-pom.xml"
+ * )
+ * void testCompileMojoWithCustomConfig(CompileMojo mojo) {
+ * mojo.execute();
+ * // verify compilation results
+ * }
+ * }
+ *
+ *
+ * The annotation can be used in conjunction with {@link MojoParameter} to provide + * specific parameter values for the Mojo:
+ *
+ * {@code
+ * @Test
+ * @InjectMojo(goal = "compile")
+ * @MojoParameter(name = "source", value = "1.8")
+ * @MojoParameter(name = "target", value = "1.8")
+ * void testCompileMojoWithParameters(CompileMojo mojo) {
+ * mojo.execute();
+ * // verify compilation results
+ * }
+ * }
+ *
+ *
+ * @see MojoTest
+ * @see MojoParameter
+ * @see MojoExtension
+ * @since 3.4.0
*/
@Retention(RetentionPolicy.RUNTIME)
@Inherited
+@Target(ElementType.METHOD)
public @interface InjectMojo {
String goal();
diff --git a/maven-plugin-testing-harness/src/main/java/org/apache/maven/api/plugin/testing/MojoExtension.java b/maven-plugin-testing-harness/src/main/java/org/apache/maven/api/plugin/testing/MojoExtension.java
index 268a033f..2697dcb6 100644
--- a/maven-plugin-testing-harness/src/main/java/org/apache/maven/api/plugin/testing/MojoExtension.java
+++ b/maven-plugin-testing-harness/src/main/java/org/apache/maven/api/plugin/testing/MojoExtension.java
@@ -93,12 +93,45 @@
import static org.mockito.Mockito.mockingDetails;
/**
- * JUnit's extension to help testing Mojos. The extension should be automatically registered
- * by adding the {@link MojoTest} annotation on the test class.
+ * JUnit Jupiter extension that provides support for testing Maven plugins (Mojos).
+ * This extension handles the lifecycle of Mojo instances in tests, including instantiation,
+ * configuration, and dependency injection.
+ *
+ * The extension is automatically registered when using the {@link MojoTest} annotation + * on a test class. It provides the following features:
+ *Example usage in a test class:
+ *
+ * {@code
+ * @MojoTest
+ * class MyMojoTest {
+ * @Test
+ * @InjectMojo(goal = "my-goal")
+ * @MojoParameter(name = "outputDirectory", value = "${project.build.directory}/generated")
+ * void testMojoExecution(MyMojo mojo) throws Exception {
+ * mojo.execute();
+ * // verify execution results
+ * }
+ * }
+ * }
+ *
+ **
+ * For custom POM configurations, you can specify a POM file using the {@link InjectMojo#pom()} + * attribute. The extension will merge this configuration with default test project settings.
* * * @see MojoTest * @see InjectMojo * @see MojoParameter + * @see Basedir + * @since 3.4.0 */ public class MojoExtension extends PlexusExtension implements ParameterResolver { diff --git a/maven-plugin-testing-harness/src/main/java/org/apache/maven/api/plugin/testing/MojoParameter.java b/maven-plugin-testing-harness/src/main/java/org/apache/maven/api/plugin/testing/MojoParameter.java index 8c37804f..276ef659 100644 --- a/maven-plugin-testing-harness/src/main/java/org/apache/maven/api/plugin/testing/MojoParameter.java +++ b/maven-plugin-testing-harness/src/main/java/org/apache/maven/api/plugin/testing/MojoParameter.java @@ -18,17 +18,58 @@ */ package org.apache.maven.api.plugin.testing; +import java.lang.annotation.ElementType; import java.lang.annotation.Inherited; import java.lang.annotation.Repeatable; import java.lang.annotation.Retention; import java.lang.annotation.RetentionPolicy; +import java.lang.annotation.Target; /** - * Mojo parameter + * Specifies a parameter value for a Mojo in a Maven plugin test. + * This annotation can be used to configure individual Mojo parameters + * without requiring a full POM file. + * + *The annotation is repeatable, allowing multiple parameters to be set + * on a single test method or parameter. For multiple parameters, you can + * either use multiple {@code @MojoParameter} annotations or a single + * {@link MojoParameters} annotation.
+ * + *Example usage with a single parameter:
+ *
+ * {@code
+ * @Test
+ * @InjectMojo(goal = "compile")
+ * @MojoParameter(name = "source", value = "1.8")
+ * void testCompilation(CompileMojo mojo) {
+ * mojo.execute();
+ * }
+ * }
+ *
+ *
+ * Example usage with multiple parameters:
+ *
+ * {@code
+ * @Test
+ * @InjectMojo(goal = "compile")
+ * @MojoParameter(name = "source", value = "1.8")
+ * @MojoParameter(name = "target", value = "1.8")
+ * @MojoParameter(name = "debug", value = "true")
+ * void testCompilation(CompileMojo mojo) {
+ * mojo.execute();
+ * }
+ * }
+ *
+ *
+ * @see MojoParameters
+ * @see InjectMojo
+ * @see MojoTest
+ * @since 3.4.0
*/
@Retention(RetentionPolicy.RUNTIME)
@Repeatable(MojoParameters.class)
@Inherited
+@Target(ElementType.METHOD)
public @interface MojoParameter {
String name();
diff --git a/maven-plugin-testing-harness/src/main/java/org/apache/maven/api/plugin/testing/MojoParameters.java b/maven-plugin-testing-harness/src/main/java/org/apache/maven/api/plugin/testing/MojoParameters.java
index 373c9260..ebe63bf8 100644
--- a/maven-plugin-testing-harness/src/main/java/org/apache/maven/api/plugin/testing/MojoParameters.java
+++ b/maven-plugin-testing-harness/src/main/java/org/apache/maven/api/plugin/testing/MojoParameters.java
@@ -18,15 +18,59 @@
*/
package org.apache.maven.api.plugin.testing;
+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;
/**
- * Mojo parameters container
+ * Container annotation for multiple {@link MojoParameter} annotations.
+ * This annotation is automatically used by Java when multiple {@code @MojoParameter}
+ * annotations are applied to the same element.
+ *
+ * While this annotation can be used directly, it's generally more convenient + * to use multiple {@code @MojoParameter} annotations, which Java will automatically + * wrap in this container annotation.
+ * + *Example of direct usage:
+ *
+ * {@code
+ * @Test
+ * @InjectMojo(goal = "compile")
+ * @MojoParameters({
+ * @MojoParameter(name = "source", value = "1.8"),
+ * @MojoParameter(name = "target", value = "1.8"),
+ * @MojoParameter(name = "debug", value = "true")
+ * })
+ * void testCompilation(CompileMojo mojo) {
+ * mojo.execute();
+ * }
+ * }
+ *
+ *
+ * Equivalent usage with repeatable annotation:
+ *
+ * {@code
+ * @Test
+ * @InjectMojo(goal = "compile")
+ * @MojoParameter(name = "source", value = "1.8")
+ * @MojoParameter(name = "target", value = "1.8")
+ * @MojoParameter(name = "debug", value = "true")
+ * void testCompilation(CompileMojo mojo) {
+ * mojo.execute();
+ * }
+ * }
+ *
+ *
+ * @see MojoParameter
+ * @see InjectMojo
+ * @see MojoTest
+ * @since 3.4.0
*/
@Retention(RetentionPolicy.RUNTIME)
@Inherited
+@Target(ElementType.METHOD)
public @interface MojoParameters {
MojoParameter[] value();
}
diff --git a/maven-plugin-testing-harness/src/main/java/org/apache/maven/api/plugin/testing/MojoTest.java b/maven-plugin-testing-harness/src/main/java/org/apache/maven/api/plugin/testing/MojoTest.java
index eb94c091..4aa9bbfc 100644
--- a/maven-plugin-testing-harness/src/main/java/org/apache/maven/api/plugin/testing/MojoTest.java
+++ b/maven-plugin-testing-harness/src/main/java/org/apache/maven/api/plugin/testing/MojoTest.java
@@ -18,15 +18,67 @@
*/
package org.apache.maven.api.plugin.testing;
+import javax.inject.Inject;
+
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
+import org.apache.maven.api.di.Provides;
import org.junit.jupiter.api.extension.ExtendWith;
/**
+ * Annotation that enables Maven plugin (Mojo) testing support in JUnit tests.
+ * When applied to a test class, it automatically sets up the testing environment
+ * for Maven plugins, including dependency injection and parameter resolution.
+ *
+ * This annotation works in conjunction with {@link InjectMojo} and {@link MojoParameter} + * to provide a comprehensive testing framework for Maven plugins. It automatically registers + * the {@link MojoExtension} which handles the plugin lifecycle and dependency injection.
+ * + *Example usage:
+ *
+ * {@code
+ * @MojoTest
+ * class MyMojoTest {
+ * @Inject
+ * private SomeComponent component;
+ *
+ * @Test
+ * @InjectMojo(goal = "my-goal")
+ * @MojoParameter(name = "parameter", value = "value")
+ * void testMojoExecution(MyMojo mojo) {
+ * // mojo is instantiated with the specified parameters
+ * // component is automatically injected
+ * mojo.execute();
+ * // verify execution results
+ * }
+ *
+ * @Provides
+ * SomeComponent provideMockedComponent() {
+ * return mock(SomeComponent.class);
+ * }
+ * }
+ * }
+ *
+ *
+ * The annotation supports:
+ *