Rewrite documentation and examples with new MojoTest usage

maven-plugin-testing-harness/src/main/java/org/apache/maven/api/plugin/testing/InjectMojo.java

@@ -30,7 +30,7 @@
  * which Mojo should be instantiated and how it should be configured.
  *
  * <p>The annotation requires a {@code goal} attribute to specify which Mojo goal
- * should be instantiated. Optionally, a custom {@code pom} file can be specified
+ * should be instantiated. Optionally, a custom {@code POM} file can be specified
  * to provide specific configuration for the test.</p>
  *
  * <p>Example usage on a test method:</p>
@@ -85,7 +85,24 @@
 @Target({ElementType.METHOD, ElementType.PARAMETER})
 public @interface InjectMojo {
 
+    /**
+     * Specifies the goal of the Mojo to instantiate.
+     * This is a required attribute that maps to the Mojo's {@code @Mojo(name = "...")}
+     * annotation value.
+     *
+     * @return the goal name of the Mojo to test
+     */
     String goal();
 
+    /**
+     * Specifies an optional POM file to use for Mojo configuration.
+     * The path is relative to the test class location.
+     *
+     * <p><b>NOTE:</b> only plugin configuration is taken from provided POM, all other tags are ignored.</p>
+     *
+     * <p>If not specified, the default project configuration will be used.</p>
+     *
+     * @return the path to a custom POM file, or an empty string to use defaults
+     */
     String pom() default "";
 }

maven-plugin-testing-harness/src/main/java/org/apache/maven/api/plugin/testing/MojoExtension.java

@@ -138,7 +138,10 @@
  * </pre>
  **
  * <p>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.</p>*
+ * attribute. The extension will merge this configuration with default test project settings.</p>
+ *
+ * <p><b>NOTE:</b> only plugin configuration is taken from provided POM, all other tags are ignored.</p>
+ *
  *
  * @see MojoTest
  * @see InjectMojo

maven-plugin-testing-harness/src/site/markdown/examples/artifact.md

@@ -23,203 +23,103 @@ date: February 2008
 
 ### NOTE
 
-`JUnit 3` based tests are deprecated since `3.4.0`.
+**Note**: This example improves the [cookbook](../getting-started/index.html) to play with artifact handler.
 
-Use JUnit 5 annotations, consult [javadocs](../apidocs/org/apache/maven/api/plugin/testing/package-summary.html) for examples.
 
- **Note**: This example improves the [cookbook](../getting-started/index.html) to play with artifact handler.
+Sometimes, your Mojo uses project artifact and ArtifactHandler mechanisms. For instance, you could need to filter on Java projects, i.e.:
 
+```java
+import javax.inject.Inject;
 
- Sometimes, your Mojo uses project artifact and ArtifactHandler mechanisms. For instance, you could need to filter on Java projects, i.e.:
+import org.apache.maven.project.MavenProject;
 
-
-
-```
-public class MyMojo
-    extends AbstractMojo
-{
+public class MyMojo extends AbstractMojo {
     /**
      * The Maven Project.
      */
-    @Component
-    protected MavenProject project;
-
-    public void execute()
-        throws MojoExecutionException
-    {
-        ...
-
-        ArtifactHandler artifactHandler = project.getArtifact().getArtifactHandler();
-        if ( "java".equals( artifactHandler.getLanguage() ) )
-        {
-            ...
-        }
-
-        ...
-     }
-}
-```
-
-### Create Stubs
-
-
-
-```
-public class MyArtifactHandlerStub
-    extends DefaultArtifactHandler
-{
-    private String language;
-
-    public String getLanguage()
-    {
-        if ( language == null )
-        {
-            language = "java";
-        }
-
-        return language;
-    }
+    private final MavenProject project;
 
-    public void setLanguage( String language )
-    {
-        this.language = language;
+    @Inject
+    MyMojo(MavenProject project) {
+        this.project = project;
     }
-}
-```
-
-
-```
-public class MyArtifactStub
-    extends ArtifactStub
-{
-    private String groupId;
-
-    private String artifactId;
-
-    private String version;
-
-    private String packaging;
 
-    private VersionRange versionRange;
+    public void execute() throws MojoExecutionException {
+        // ...
 
-    private ArtifactHandler handler;
-
-    /**
-     * @param groupId
-     * @param artifactId
-     * @param version
-     * @param packaging
-     */
-    public ProjectInfoPluginArtifactStub( String groupId, String artifactId,
-                                          String version, String packaging )
-    {
-        this.groupId = groupId;
-        this.artifactId = artifactId;
-        this.version = version;
-        this.packaging = packaging;
-        versionRange = VersionRange.createFromVersion( version );
-    }
-
-    /** {@inheritDoc} */
-    public void setGroupId( String groupId )
-    {
-        this.groupId = groupId;
-    }
-
-    /** {@inheritDoc} */
-    public String getGroupId()
-    {
-        return groupId;
-    }
-
-    /** {@inheritDoc} */
-    public void setArtifactId( String artifactId )
-    {
-        this.artifactId = artifactId;
-    }
-
-    /** {@inheritDoc} */
-    public String getArtifactId()
-    {
-        return artifactId;
-    }
-
-    /** {@inheritDoc} */
-    public void setVersion( String version )
-    {
-        this.version = version;
-    }
-
-    /** {@inheritDoc} */
-    public String getVersion()
-    {
-        return version;
-    }
-
-    /**
-     * @param packaging
-     */
-    public void setPackaging( String packaging )
-    {
-        this.packaging = packaging;
-    }
-
-    /**
-     * @return the packaging
-     */
-    public String getPackaging()
-    {
-        return packaging;
-    }
-
-    /** {@inheritDoc} */
-    public VersionRange getVersionRange()
-    {
-        return versionRange;
-    }
-
-    /** {@inheritDoc} */
-    public void setVersionRange( VersionRange versionRange )
-    {
-        this.versionRange = versionRange;
-    }
-
-    /** {@inheritDoc} */
-    public ArtifactHandler getArtifactHandler()
-    {
-        return handler;
-    }
+        ArtifactHandler artifactHandler = project.getArtifact().getArtifactHandler();
+        if ("java".equals(artifactHandler.getLanguage())) {
+            //...
+        }
 
-    /** {@inheritDoc} */
-    public void setArtifactHandler( ArtifactHandler handler )
-    {
-        this.handler = handler;
+        // ...
     }
 }
 ```
 
+### Create a test
+
+```java
+import org.apache.maven.api.di.Provides;import org.apache.maven.api.plugin.testing.InjectMojo;
+import org.apache.maven.api.plugin.testing.MojoTest;
+import org.apache.maven.artifact.Artifact;
+import org.apache.maven.artifact.handler.ArtifactHandler;
+import org.apache.maven.artifact.handler.manager.ArtifactHandlerManager;import org.apache.maven.project.MavenProject;
+import org.junit.jupiter.api.Nested;
+import org.mockito.Mockito;
+
+@MojoTest
+class ArtifactTest {
+
+    @Inject
+    private MavenProject project;
+
+    @Test
+    @InjectMojo(goal = "test")
+    void testUsingMockito(MyMojo mojo) {
+        // Mock ArtifactHandler
+        ArtifactHandler artifactHandler = Mockito.mock(ArtifactHandler.class);
+        Mockito.when(artifactHandler.getLanguage()).thenReturn("java");
+
+        // Mock Artifact
+        Artifact artifact = Mockito.mock(Artifact.class);
+        Mockito.when(artifact.getArtifactHandler()).thenReturn(artifactHandler);
+
+        // Set the mocked Artifact to the default provided project
+        project.setArtifact(artifact);
+
+        // Now you can test your Mojo logic that depends on the ArtifactHandler
+        mojo.execute();
+    }
+
+    @Nested
+    class NestedTest1 {
+
+        @Inject
+        private ArtifactHandlerManager artifactHandlerManager;
+
+        @Provides
+        MavenProject stubbedProject() {
+            MavenProject stubProject = new CustomMavenProject(); // your custom implementation
+
+            ArtifactHandler stubArtifactHandler = new CustomArtifactHandler(); // your custom implementation
+
+            // You can also get a real ArtifactHandler from the manager if needed
+            ArtifactHandler jarArtifactHandler = artifactHandlerManager.getArtifactHandler("jar");
+
+            Artifact stubArtifact = new CustomArtifact(stubArtifactHandler); // your custom implementation
+
+            stubProject.setArtifact(stubArtifact);
+            return stubProject;
+        }
 
-```
-public class MyProjectStub
-    extends MavenProjectStub
-{
-    /**
-     * Default constructor
-     */
-    public MyProjectStub()
-    {
-        ...
-
-        Artifact artifact = new MyArtifactStub( getGroupId(), getArtifactId(),
-                                                getVersion(), getPackaging() );
-        artifact.setArtifactHandler( new MyArtifactHandlerStub() );
-        setArtifact( artifact );
-
-        ...
+        @Test
+        @InjectMojo(goal = "test")
+        void testUsingStubbedProject (MyMojo mojo) {
+            // Use the stubbed project in your test
+            mojo.execute();
+        }
     }
-
-    ...
 }
 ```
 
-