[WIP] [MPLUGINTESTING-93] - Prepare documentation / examples for JUnit 5 and Maven 3

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

@@ -0,0 +1,32 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.maven.api.plugin.testing;
+
+import java.lang.annotation.Inherited;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+
+/**
+ * Mojo parameters container
+ */
+@Retention(RetentionPolicy.RUNTIME)
+@Inherited
+public @interface Basedir {
+    String value() default "";
+}

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

@@ -16,20 +16,20 @@
  * specific language governing permissions and limitations
  * under the License.
  */
-package org.apache.maven.plugin.testing.junit5;
+package org.apache.maven.api.plugin.testing;
 
+import java.lang.annotation.Inherited;
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 
 /**
  *
  */
 @Retention(RetentionPolicy.RUNTIME)
+@Inherited
 public @interface InjectMojo {
 
     String goal();
 
-    String pom();
-
-    boolean empty() default false;
+    String pom() default "";
 }

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

@@ -16,7 +16,7 @@
  * specific language governing permissions and limitations
  * under the License.
  */
-package org.apache.maven.plugin.testing.junit5;
+package org.apache.maven.api.plugin.testing;
 
 import java.io.BufferedReader;
 import java.io.File;
@@ -54,7 +54,6 @@
 import org.apache.maven.plugin.descriptor.PluginDescriptor;
 import org.apache.maven.plugin.descriptor.PluginDescriptorBuilder;
 import org.apache.maven.plugin.logging.Log;
-import org.apache.maven.plugin.testing.ConfigurationException;
 import org.apache.maven.plugin.testing.MojoLogWrapper;
 import org.apache.maven.project.MavenProject;
 import org.codehaus.plexus.DefaultPlexusContainer;
@@ -77,6 +76,7 @@
 import org.junit.jupiter.api.extension.ParameterContext;
 import org.junit.jupiter.api.extension.ParameterResolutionException;
 import org.junit.jupiter.api.extension.ParameterResolver;
+import org.junit.platform.commons.support.AnnotationSupport;
 import org.mockito.Mockito;
 import org.slf4j.LoggerFactory;
 
@@ -131,7 +131,10 @@ public void beforeEach(ExtensionContext context) throws Exception {
         // TODO provide protected setters in PlexusExtension
         Field field = PlexusExtension.class.getDeclaredField("basedir");
         field.setAccessible(true);
-        field.set(null, getBasedir());
+        String basedir = AnnotationSupport.findAnnotation(context.getElement().get(), Basedir.class)
+                .map(Basedir::value)
+                .orElse(getBasedir());
+        field.set(null, basedir);
         field = PlexusExtension.class.getDeclaredField("context");
         field.setAccessible(true);
         field.set(this, context);
@@ -165,6 +168,13 @@ public void beforeEach(ExtensionContext context) throws Exception {
         }
     }
 
+    @Override
+    public void afterEach(ExtensionContext context) throws Exception {
+        Field field = PlexusExtension.class.getDeclaredField("basedir");
+        field.setAccessible(true);
+        field.set(null, null);
+    }
+
     /**
      * Default MojoExecution mock
      *
@@ -333,9 +343,7 @@ public static Xpp3Dom extractPluginConfiguration(String artifactId, Xpp3Dom pomD
                 .filter(e -> e.getChild("artifactId").getValue().equals(artifactId))
                 .findFirst()
                 .flatMap(buildElement -> child(buildElement, "configuration"))
-                .orElseThrow(
-                        () -> new ConfigurationException("Cannot find a configuration element for a plugin with an "
-                                + "artifactId of " + artifactId + "."));
+                .orElse(Xpp3DomBuilder.build(new StringReader("<configuration/>")));
         return pluginConfigurationElement;
     }
 

maven-plugin-testing-harness/src/main/java/org/apache/maven/plugin/testing/junit5/MojoParameter.java → maven-plugin-testing-harness/src/main/java/org/apache/maven/api/plugin/testing/MojoParameter.java

@@ -16,8 +16,9 @@
  * specific language governing permissions and limitations
  * under the License.
  */
-package org.apache.maven.plugin.testing.junit5;
+package org.apache.maven.api.plugin.testing;
 
+import java.lang.annotation.Inherited;
 import java.lang.annotation.Repeatable;
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
@@ -27,6 +28,7 @@
  */
 @Retention(RetentionPolicy.RUNTIME)
 @Repeatable(MojoParameters.class)
+@Inherited
 public @interface MojoParameter {
     String name();
 

maven-plugin-testing-harness/src/main/java/org/apache/maven/plugin/testing/junit5/MojoParameters.java → maven-plugin-testing-harness/src/main/java/org/apache/maven/api/plugin/testing/MojoParameters.java

@@ -16,15 +16,17 @@
  * specific language governing permissions and limitations
  * under the License.
  */
-package org.apache.maven.plugin.testing.junit5;
+package org.apache.maven.api.plugin.testing;
 
+import java.lang.annotation.Inherited;
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 
 /**
  * Mojo parameters container
  */
 @Retention(RetentionPolicy.RUNTIME)
+@Inherited
 public @interface MojoParameters {
     MojoParameter[] value();
 }

maven-plugin-testing-harness/src/main/java/org/apache/maven/plugin/testing/junit5/MojoTest.java → maven-plugin-testing-harness/src/main/java/org/apache/maven/api/plugin/testing/MojoTest.java

@@ -16,7 +16,7 @@
  * specific language governing permissions and limitations
  * under the License.
  */
-package org.apache.maven.plugin.testing.junit5;
+package org.apache.maven.api.plugin.testing;
 
 import java.lang.annotation.ElementType;
 import java.lang.annotation.Retention;

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

@@ -0,0 +1,113 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.maven.api.plugin.testing;
+
+import java.io.File;
+
+import org.apache.maven.artifact.repository.MavenArtifactRepository;
+import org.apache.maven.artifact.repository.layout.DefaultRepositoryLayout;
+import org.codehaus.plexus.component.configurator.expression.ExpressionEvaluationException;
+import org.codehaus.plexus.component.configurator.expression.ExpressionEvaluator;
+
+/**
+ * Stub for {@link ExpressionEvaluator}
+ *
+ * @author jesse
+ */
+public class ResolverExpressionEvaluatorStub implements ExpressionEvaluator {
+    /** {@inheritDoc} */
+    @Override
+    public Object evaluate(String expr) throws ExpressionEvaluationException {
+
+        Object value = null;
+
+        if (expr == null) {
+            return null;
+        }
+
+        String expression = stripTokens(expr);
+
+        if (expression.equals(expr)) {
+            int index = expr.indexOf("${");
+            if (index >= 0) {
+                int lastIndex = expr.indexOf("}", index);
+                if (lastIndex >= 0) {
+                    String retVal = expr.substring(0, index);
+
+                    if (index > 0 && expr.charAt(index - 1) == '$') {
+                        retVal += expr.substring(index + 1, lastIndex + 1);
+                    } else {
+                        retVal += evaluate(expr.substring(index, lastIndex + 1));
+                    }
+
+                    retVal += evaluate(expr.substring(lastIndex + 1));
+                    return retVal;
+                }
+            }
+
+            // Was not an expression
+            if (expression.indexOf("$$") > -1) {
+                return expression.replaceAll("\\$\\$", "\\$");
+            }
+        }
+
+        if ("basedir".equals(expression) || "project.basedir".equals(expression)) {
+            return MojoExtension.getBasedir();
+        } else if (expression.startsWith("basedir") || expression.startsWith("project.basedir")) {
+            int pathSeparator = expression.indexOf("/");
+
+            if (pathSeparator > 0) {
+                value = MojoExtension.getBasedir() + expression.substring(pathSeparator);
+            } else {
+                System.out.println("Got expression '" + expression + "' that was not recognised");
+            }
+            return value;
+        } else if ("localRepository".equals(expression)) {
+            File localRepo = new File(MojoExtension.getBasedir(), "target/local-repo");
+            return new MavenArtifactRepository(
+                    "localRepository",
+                    "file://" + localRepo.getAbsolutePath(),
+                    new DefaultRepositoryLayout(),
+                    null,
+                    null);
+        } else {
+            return expr;
+        }
+    }
+
+    private String stripTokens(String expr) {
+        if (expr.startsWith("${") && expr.indexOf("}") == expr.length() - 1) {
+            expr = expr.substring(2, expr.length() - 1);
+        }
+
+        return expr;
+    }
+
+    /** {@inheritDoc} */
+    @Override
+    public File alignToBaseDirectory(File file) {
+        if (file.getAbsolutePath().startsWith(MojoExtension.getBasedir())) {
+            return file;
+        } else if (file.isAbsolute()) {
+            return file;
+        } else {
+            return new File(MojoExtension.getBasedir(), file.getPath());
+        }
+    }
+}

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

@@ -36,6 +36,7 @@
 import java.util.Properties;
 
 import com.google.inject.Module;
+import org.apache.maven.api.plugin.testing.MojoTest;
 import org.apache.maven.artifact.Artifact;
 import org.apache.maven.artifact.DefaultArtifact;
 import org.apache.maven.artifact.handler.DefaultArtifactHandler;
@@ -80,7 +81,13 @@
 
 /**
  * @author jesse
+ *
+ * @deprected As of version 3.4.0, it is advised to work with JUnit5 tests which do not
+ * use this class but {@link MojoTest}
+ * instead.
+ *
  */
+@Deprecated
 public abstract class AbstractMojoTestCase extends PlexusTestCase {
     private static final DefaultArtifactVersion MAVEN_VERSION;
 

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

@@ -25,7 +25,13 @@
 
 /**
  * @author jdcasey
+ *
+ * @deprected As of version 3.4.0, it is advised to work with JUnit5 tests which do not
+ * use this class but {@link  javax.inject.Inject} to inject a Log instance
+ * instead.
+ *
  */
+@Deprecated
 public class MojoLogWrapper implements Log {
     private final Logger logger;
 

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

@@ -23,8 +23,13 @@
 /**
  * Static helpers to create and manipulate mojo execution configuration parameters
  *
+ * @deprected As of version 3.4.0, it is advised to work with JUnit5 tests which do not
+ * use this class but {@link org.apache.maven.api.plugin.testing.MojoParameters}
+ * instead.
+ *
  * @since 3.2.0
  */
+@Deprecated
 public class MojoParameters {
     public static Xpp3Dom newParameter(String name, String value) {
         Xpp3Dom child = new Xpp3Dom(name);

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

@@ -22,6 +22,7 @@
 import java.io.InputStream;
 import java.util.Map;
 
+import org.apache.maven.api.plugin.testing.MojoExtension;
 import org.apache.maven.execution.DefaultMavenExecutionRequest;
 import org.apache.maven.execution.MavenExecutionRequest;
 import org.apache.maven.execution.MavenSession;
@@ -52,9 +53,14 @@
  * exhibited as {@code public} in the rule. You may annotate single tests methods with
  * {@link WithoutMojo} to prevent the rule from firing.
  *
+ * @deprected As of version 3.4.0, it is advised to work with JUnit5 tests which do not
+ * use rules but extensions {@link MojoExtension}
+ * instead.
+ *
  * @author Mirko Friedenhagen
  * @since 2.2
  */
+@Deprecated
 public class MojoRule implements TestRule {
     private final AbstractMojoTestCase testCase;
 

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

@@ -30,7 +30,10 @@
  * Stub for {@link ExpressionEvaluator}
  *
  * @author jesse
+ * @deprected This stub is for deprecated JUnit 4 style tests.
+ * For JUnit Jupiter tests you have to use {@link org.apache.maven.api.plugin.testing.ResolverExpressionEvaluatorStub}.
  */
+@Deprecated
 public class ResolverExpressionEvaluatorStub implements ExpressionEvaluator {
     /** {@inheritDoc} */
     @Override

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

@@ -22,15 +22,22 @@
 import java.lang.annotation.Retention;
 import java.lang.annotation.Target;
 
+import org.apache.maven.api.plugin.testing.MojoExtension;
+
 import static java.lang.annotation.ElementType.METHOD;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
  *
  * An annotation for test methods that do not require the {@link MojoRule} to create and tear down the instance.
  *
+ * @deprected As of version 3.4.0, it is advised to work with JUnit5 tests which do not
+ * use rules but extensions {@link MojoExtension}
+ * instead.
+ *
  * @author Mirko Friedenhagen
  */
+@Deprecated
 @Retention(RUNTIME)
 @Documented
 @Target(METHOD)