Author: vsiveton
Date: Wed Feb 20 15:15:21 2008
New Revision: 629650

URL: http://svn.apache.org/viewvc?rev=629650&view=rev
Log:
o first draft of documentation

Added:
    maven/plugin-tools/trunk/maven-plugin-testing-harness/src/site/
    maven/plugin-tools/trunk/maven-plugin-testing-harness/src/site/apt/
    maven/plugin-tools/trunk/maven-plugin-testing-harness/src/site/apt/examples/
    
maven/plugin-tools/trunk/maven-plugin-testing-harness/src/site/apt/examples/artifact.apt
   (with props)
    
maven/plugin-tools/trunk/maven-plugin-testing-harness/src/site/apt/examples/complex-mojo-parameters.apt
   (with props)
    
maven/plugin-tools/trunk/maven-plugin-testing-harness/src/site/apt/examples/multiproject.apt
   (with props)
    
maven/plugin-tools/trunk/maven-plugin-testing-harness/src/site/apt/examples/repositories.apt
   (with props)
    
maven/plugin-tools/trunk/maven-plugin-testing-harness/src/site/apt/getting-started/
    
maven/plugin-tools/trunk/maven-plugin-testing-harness/src/site/apt/getting-started/index.apt
   (with props)
    
maven/plugin-tools/trunk/maven-plugin-testing-harness/src/site/apt/index.apt   
(with props)
    maven/plugin-tools/trunk/maven-plugin-testing-harness/src/site/fml/
    maven/plugin-tools/trunk/maven-plugin-testing-harness/src/site/fml/faq.fml  
 (with props)
    maven/plugin-tools/trunk/maven-plugin-testing-harness/src/site/site.xml   
(with props)

Added: 
maven/plugin-tools/trunk/maven-plugin-testing-harness/src/site/apt/examples/artifact.apt
URL: 
http://svn.apache.org/viewvc/maven/plugin-tools/trunk/maven-plugin-testing-harness/src/site/apt/examples/artifact.apt?rev=629650&view=auto
==============================================================================
--- 
maven/plugin-tools/trunk/maven-plugin-testing-harness/src/site/apt/examples/artifact.apt
 (added)
+++ 
maven/plugin-tools/trunk/maven-plugin-testing-harness/src/site/apt/examples/artifact.apt
 Wed Feb 20 15:15:21 2008
@@ -0,0 +1,216 @@
+ ------
+ Testing Project Artifact
+ ------
+ Vincent Siveton
+ ------
+ February 2008
+ ------
+
+~~ 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.
+
+Testing Project Artifact
+
+ <<Note>>: This example improves the 
{{{../getting-started/index.html}cookbook}} 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.:
+
+-----
+public class MyMojo
+    extends AbstractMojo
+{
+    /**
+     * The Maven Project.
+     *
+     * @parameter expression="${project}"
+     * @required
+     * @readonly
+     */
+    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;
+    }
+
+    public void setLanguage( String language )
+    {
+        this.language = language;
+    }
+}
+-----
+
+-----
+public class MyArtifactStub
+    extends ArtifactStub
+{
+    private String groupId;
+
+    private String artifactId;
+
+    private String version;
+
+    private String packaging;
+
+    private VersionRange versionRange;
+
+    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 );
+    }
+
+    /** [EMAIL PROTECTED] */
+    public void setGroupId( String groupId )
+    {
+        this.groupId = groupId;
+    }
+
+    /** [EMAIL PROTECTED] */
+    public String getGroupId()
+    {
+        return groupId;
+    }
+
+    /** [EMAIL PROTECTED] */
+    public void setArtifactId( String artifactId )
+    {
+        this.artifactId = artifactId;
+    }
+
+    /** [EMAIL PROTECTED] */
+    public String getArtifactId()
+    {
+        return artifactId;
+    }
+
+    /** [EMAIL PROTECTED] */
+    public void setVersion( String version )
+    {
+        this.version = version;
+    }
+
+    /** [EMAIL PROTECTED] */
+    public String getVersion()
+    {
+        return version;
+    }
+
+    /**
+     * @param packaging
+     */
+    public void setPackaging( String packaging )
+    {
+        this.packaging = packaging;
+    }
+
+    /**
+     * @return the packaging
+     */
+    public String getPackaging()
+    {
+        return packaging;
+    }
+
+    /** [EMAIL PROTECTED] */
+    public VersionRange getVersionRange()
+    {
+        return versionRange;
+    }
+
+    /** [EMAIL PROTECTED] */
+    public void setVersionRange( VersionRange versionRange )
+    {
+        this.versionRange = versionRange;
+    }
+
+    /** [EMAIL PROTECTED] */
+    public ArtifactHandler getArtifactHandler()
+    {
+        return handler;
+    }
+
+    /** [EMAIL PROTECTED] */
+    public void setArtifactHandler( ArtifactHandler handler )
+    {
+        this.handler = handler;
+    }
+}
+-----
+
+-----
+public class MyProjectStub
+    extends MavenProjectStub
+{
+    /**
+     * Default constructor
+     */
+    public MyProjectStub()
+    {
+        ...
+
+        Artifact artifact = new MyArtifactStub( getGroupId(), getArtifactId(), 
getVersion(), getPackaging() );
+        artifact.setArtifactHandler( new MyArtifactHandlerStub() );
+        setArtifact( artifact );
+
+        ...
+    }
+
+    ...
+}
+-----

Propchange: 
maven/plugin-tools/trunk/maven-plugin-testing-harness/src/site/apt/examples/artifact.apt
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: 
maven/plugin-tools/trunk/maven-plugin-testing-harness/src/site/apt/examples/artifact.apt
------------------------------------------------------------------------------
    svn:keywords = "Author Date Id Revision"

Added: 
maven/plugin-tools/trunk/maven-plugin-testing-harness/src/site/apt/examples/complex-mojo-parameters.apt
URL: 
http://svn.apache.org/viewvc/maven/plugin-tools/trunk/maven-plugin-testing-harness/src/site/apt/examples/complex-mojo-parameters.apt?rev=629650&view=auto
==============================================================================
--- 
maven/plugin-tools/trunk/maven-plugin-testing-harness/src/site/apt/examples/complex-mojo-parameters.apt
 (added)
+++ 
maven/plugin-tools/trunk/maven-plugin-testing-harness/src/site/apt/examples/complex-mojo-parameters.apt
 Wed Feb 20 15:15:21 2008
@@ -0,0 +1,186 @@
+ ------
+ Testing Complex Mojo Parameters
+ ------
+ Vincent Siveton
+ ------
+ February 2008
+ ------
+
+~~ 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.
+
+Testing Complex Mojo Parameters
+
+ <<Note>>: This example improves the 
{{{../getting-started/index.html}cookbook}} for complex Mojo parameters testing.
+
+ In a real plugin development, you will use specific Maven objects like 
<<<MavenProject>>>, <<<localRepository>>> or
+ <<<MavenSettings>>>. You could use them by defining stubs.
+
+ Suppose that you have the following dependencies in the maven-my-plugin pom:
+
+-----
+<project>
+  ...
+  <dependencies>
+    <dependency>
+      <groupId>org.apache.maven</groupId>
+      <artifactId>maven-artifact</artifactId>
+      <version>2.0.8</version>
+    </dependency>
+    <dependency>
+      <groupId>org.apache.maven</groupId>
+      <artifactId>maven-project</artifactId>
+      <version>2.0.8</version>
+    </dependency>
+    ...
+  </dependencies>
+</project>
+-----
+
+ You will add the following in the <<<MyMojo>>>:
+
+-----
+public class MyMojo
+    extends AbstractMojo
+{
+    /**
+     * The Maven Project.
+     *
+     * @parameter expression="${project}"
+     * @required
+     * @readonly
+     */
+    protected MavenProject project;
+
+    /**
+     * Local Repository.
+     *
+     * @parameter expression="${localRepository}"
+     * @required
+     * @readonly
+     */
+    protected ArtifactRepository localRepository;
+
+    /**
+     * The Maven Settings.
+     *
+     * @parameter default-value="${settings}"
+     * @required
+     * @readonly
+     */
+    private Settings settings;
+
+    ...
+}
+-----
+
+* Create Stubs
+
+  You need to create stubs objects to run <<<MyMojoTest#testSomething()>>>. By 
convention, the package name should
+  reflect the stubs, i.e. in our case <<<org.apache.maven.plugin.my.stubs>>>.
+
+-----
+public class MyProjectStub
+    extends MavenProjectStub
+{
+    /**
+     * Default constructor
+     */
+    public MyProjectStub()
+    {
+        MavenXpp3Reader pomReader = new MavenXpp3Reader();
+        Model model;
+        try
+        {
+            model = pomReader.read( ReaderFactory.newXmlReader( new File( 
getBasedir(), "pom.xml" ) ) );
+            setModel( model );
+        }
+        catch ( Exception e )
+        {
+            throw new RuntimeException( e );
+        }
+
+        setGroupId( model.getGroupId() );
+        setArtifactId( model.getArtifactId() );
+        setVersion( model.getVersion() );
+        setName( model.getName() );
+        setUrl( model.getUrl() );
+        setPackaging( model.getPackaging() );
+
+        Build build = new Build();
+        build.setFinalName( model.getArtifactId() );
+        build.setDirectory( getBasedir() + "/target" );
+        build.setSourceDirectory( getBasedir() + "/src/main/java" );
+        build.setOutputDirectory( getBasedir() + "/target/classes" );
+        build.setTestSourceDirectory( getBasedir() + "/src/test/java" );
+        build.setTestOutputDirectory( getBasedir() + "/target/test-classes" );
+        setBuild( build );
+
+        List compileSourceRoots = new ArrayList();
+        compileSourceRoots.add( getBasedir() + "/src/main/java" );
+        setCompileSourceRoots( compileSourceRoots );
+
+        List testCompileSourceRoots = new ArrayList();
+        testCompileSourceRoots.add( getBasedir() + "/src/test/java" );
+        setTestCompileSourceRoots( testCompileSourceRoots );
+    }
+
+    /** [EMAIL PROTECTED] */
+    public File getBasedir()
+    {
+        return new File( super.getBasedir() + 
"/src/test/resources/unit/project-to-test/" );
+    }
+}
+-----
+
+-----
+public class SettingsStub
+    extends Settings
+{
+    /** [EMAIL PROTECTED] */
+    public List getProxies()
+    {
+        return Collections.EMPTY_LIST;
+    }
+}
+-----
+
+* Configuring <<<project-to-test>>> pom
+
+-----
+<project>
+  ...
+  <build>
+    <plugins>
+      <plugin>
+        <artifactId>maven-my-plugin</artifactId>
+        <configuration>
+          <!-- Specify where this pom will be outputted files -->
+          
<outputDirectory>target/test-harness/project-to-test</outputDirectory>
+
+          <!-- By default <<<${basedir}/target/local-repo", where basedir refer
+              to the basedir of maven-my-plugin. -->
+          <localRepository>${localRepository}</localRepository>
+          <!-- The defined stubs -->
+          <project 
implementation="org.apache.maven.plugin.my.stubs.MyProjectStub"/>
+          <settings 
implementation="org.apache.maven.plugin.my.stubs.SettingsStub"/>
+        </configuration>
+      </plugin>
+    </plugins>
+  </build>
+</project>
+-----

Propchange: 
maven/plugin-tools/trunk/maven-plugin-testing-harness/src/site/apt/examples/complex-mojo-parameters.apt
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: 
maven/plugin-tools/trunk/maven-plugin-testing-harness/src/site/apt/examples/complex-mojo-parameters.apt
------------------------------------------------------------------------------
    svn:keywords = "Author Date Id Revision"

Added: 
maven/plugin-tools/trunk/maven-plugin-testing-harness/src/site/apt/examples/multiproject.apt
URL: 
http://svn.apache.org/viewvc/maven/plugin-tools/trunk/maven-plugin-testing-harness/src/site/apt/examples/multiproject.apt?rev=629650&view=auto
==============================================================================
--- 
maven/plugin-tools/trunk/maven-plugin-testing-harness/src/site/apt/examples/multiproject.apt
 (added)
+++ 
maven/plugin-tools/trunk/maven-plugin-testing-harness/src/site/apt/examples/multiproject.apt
 Wed Feb 20 15:15:21 2008
@@ -0,0 +1,123 @@
+ ------
+ Testing Multiproject
+ ------
+ Vincent Siveton
+ ------
+ February 2008
+ ------
+
+~~ 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.
+
+Testing Multiproject
+
+ <<Note>>: This example improves the 
{{{../getting-started/index.html}cookbook}} for multi-project testing.
+
+ Your Mojo should have <<<@aggregator>>> parameter, i.e.:
+
+------
+/**
+ * @goal touch
+ * @aggregator
+ */
+public class MyMojo
+    extends AbstractMojo
+{
+  ...
+}
+------
+
+ To test a Mojo in a multiproject area, you need to define several stubs, i.e. 
for the main test project and his modules.
+
+* Create Stubs
+
+ Stub for the main test project:
+
+-----
+public class MyProjectStub
+    extends MavenProjectStub
+{
+    /**
+     * Default constructor
+     */
+    public MyProjectStub()
+    {
+        ...
+
+        setExecutionRoot( true );
+    }
+
+    /** [EMAIL PROTECTED] */
+    public MavenProject getExecutionProject()
+    {
+        return this;
+    }
+}
+-----
+
+ Stubs for the subprojects:
+
+-----
+public class SubProject1Stub
+    extends MavenProjectStub
+{
+    /**
+     * Default constructor
+     */
+    public SubProject1Stub()
+    {
+        ...
+    }
+}
+-----
+
+-----
+public class SubProject2Stub
+    extends MavenProjectStub
+{
+    /**
+     * Default constructor
+     */
+    public SubProject2Stub()
+    {
+        ...
+    }
+}
+-----
+
+* Configuring <<<project-to-test>>> pom
+
+-----
+<project>
+  ...
+  <build>
+    <plugins>
+      <plugin>
+        <artifactId>maven-my-plugin</artifactId>
+        <configuration>
+          ...
+          <project 
implementation="org.apache.maven.plugin.my.stubs.MyProjectStub"/>
+          <reactorProjects>
+            <project 
implementation="org.apache.maven.plugin.my.stubs.SubProject1Stub"/>
+            <project 
implementation="org.apache.maven.plugin.my.stubs.SubProject2Stub"/>
+          </reactorProjects>
+        </configuration>
+      </plugin>
+    </plugins>
+  </build>
+</project>
+-----

Propchange: 
maven/plugin-tools/trunk/maven-plugin-testing-harness/src/site/apt/examples/multiproject.apt
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: 
maven/plugin-tools/trunk/maven-plugin-testing-harness/src/site/apt/examples/multiproject.apt
------------------------------------------------------------------------------
    svn:keywords = "Author Date Id Revision"

Added: 
maven/plugin-tools/trunk/maven-plugin-testing-harness/src/site/apt/examples/repositories.apt
URL: 
http://svn.apache.org/viewvc/maven/plugin-tools/trunk/maven-plugin-testing-harness/src/site/apt/examples/repositories.apt?rev=629650&view=auto
==============================================================================
--- 
maven/plugin-tools/trunk/maven-plugin-testing-harness/src/site/apt/examples/repositories.apt
 (added)
+++ 
maven/plugin-tools/trunk/maven-plugin-testing-harness/src/site/apt/examples/repositories.apt
 Wed Feb 20 15:15:21 2008
@@ -0,0 +1,138 @@
+ ------
+ Testing Using Repositories
+ ------
+ Vincent Siveton
+ ------
+ February 2008
+ ------
+
+~~ 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.
+
+Testing Using Repositories
+
+ <<Note>>: This example improves the 
{{{../getting-started/index.html}cookbook}} for repositories testing.
+
+ Developing Maven plugin needs often to have to play with repositories. 
Suppose that the MyMojo needs
+ to download artifacts in your local repository, i.e.:
+
+-----
+public class MyMojo
+    extends AbstractMojo
+{
+    /**
+     * Used for resolving artifacts
+     *
+     * @component
+     */
+    private ArtifactResolver resolver;
+
+    /**
+     * Factory for creating artifact objects
+     *
+     * @component
+     */
+    private ArtifactFactory factory;
+
+    /**
+     * Local Repository.
+     *
+     * @parameter expression="${localRepository}"
+     * @required
+     * @readonly
+     */
+    private ArtifactRepository localRepository;
+
+    public void execute()
+        throws MojoExecutionException
+    {
+        ...
+
+        Artifact artifact = factory.createArtifact( "junit", "junit", "3.8.1", 
"compile", "jar" );
+        try
+        {
+            resolver.resolve( artifact, 
project.getRemoteArtifactRepositories(), localRepository );
+        }
+        catch ( ArtifactResolutionException e )
+        {
+            throw new MojoExecutionException( "Unable to resolve artifact:" + 
artifact, e );
+        }
+        catch ( ArtifactNotFoundException e )
+        {
+            throw new MojoExecutionException( "Unable to find artifact:" + 
artifact, e );
+        }
+
+        ...
+     }
+}
+-----
+
+* Create Stubs
+
+ Stub for the test project:
+
+-----
+public class MyProjectStub
+    extends MavenProjectStub
+{
+    /**
+     * Default constructor
+     */
+    public MyProjectStub()
+    {
+        ...
+    }
+
+    /** [EMAIL PROTECTED] */
+    public List getRemoteArtifactRepositories()
+    {
+        ArtifactRepository repository = new DefaultArtifactRepository( 
"central", "http://repo1.maven.org/maven2";,
+                                                                       new 
DefaultRepositoryLayout() );
+
+        return Collections.singletonList( repository );
+    }
+}
+-----
+
+* Configuring <<<project-to-test>>> pom
+
+-----
+<project>
+  ...
+  <build>
+    <plugins>
+      <plugin>
+        <artifactId>maven-my-plugin</artifactId>
+        <configuration>
+          <!-- Specify where this pom will be outputted files -->
+          
<outputDirectory>${basedir}/target/test-harness/project-to-test</outputDirectory>
+
+          <!-- By default <<<${basedir}/target/local-repo", where basedir refer
+              to the basedir of maven-my-plugin. -->
+          <localRepository>${localRepository}</localRepository>
+          <!-- The defined stub -->
+          <project 
implementation="org.apache.maven.plugin.my.stubs.MyProjectStub"/>
+        </configuration>
+      </plugin>
+    </plugins>
+  </build>
+</project>
+-----
+
+** Execute test
+
+ Calling <<<mvn test>>> will create 
<<<$\{basedir\}/target/local-repo/junitjunit/3.8.1/junit-3.8.1.jar>>> file.

Propchange: 
maven/plugin-tools/trunk/maven-plugin-testing-harness/src/site/apt/examples/repositories.apt
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: 
maven/plugin-tools/trunk/maven-plugin-testing-harness/src/site/apt/examples/repositories.apt
------------------------------------------------------------------------------
    svn:keywords = "Author Date Id Revision"

Added: 
maven/plugin-tools/trunk/maven-plugin-testing-harness/src/site/apt/getting-started/index.apt
URL: 
http://svn.apache.org/viewvc/maven/plugin-tools/trunk/maven-plugin-testing-harness/src/site/apt/getting-started/index.apt?rev=629650&view=auto
==============================================================================
--- 
maven/plugin-tools/trunk/maven-plugin-testing-harness/src/site/apt/getting-started/index.apt
 (added)
+++ 
maven/plugin-tools/trunk/maven-plugin-testing-harness/src/site/apt/getting-started/index.apt
 Wed Feb 20 15:15:21 2008
@@ -0,0 +1,186 @@
+ ------
+ How To Use Maven Plugin Testing Harness
+ ------
+ Vincent Siveton
+ ------
+ February 2008
+ ------
+
+~~ 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.
+
+Cookbook: How To Use Maven Plugin Testing Harness?
+
+ This guide is intended as a reference for those developing Maven plugins, 
with self-contained references and
+ solutions for common testing cases.
+
+* Prerequisites
+
+ We suppose that you had already created a plugin. In this cookbook, we make 
reference on <<<MyMojo>>> from
+ <<<maven-my-plugin>>> which is generated by the Maven Archetype Plugin, i.e.:
+
+-----
+mvn archetype:create \
+  -DgroupId=org.apache.maven.plugin.my \
+  -DartifactId=maven-my-plugin \
+  -DarchetypeArtifactId=maven-archetype-mojo
+-----
+
+ The generated structure should be:
+
+-----
+maven-my-plugin
+  |- pom.xml
+  +- src/
+   +- main/
+      +- java/
+        +- org/
+          +- apache/
+            +- maven/
+              +- plugin/
+                +- my/
+                  |- MyMojo.java
+-----
+
+* Recipe
+
+** Added <<<maven-plugin-testing-harness>>> dependency
+
+ As usually, just add <<<maven-plugin-testing-harness>>> as following in your 
pom. Be sure to specify <<<test>>> scope.
+
+-----
+<project>
+  ...
+  <dependencies>
+    <dependency>
+      <groupId>org.apache.maven</groupId>
+      <artifactId>maven-plugin-testing-harness</artifactId>
+      <scope>test</scope>
+    </dependency>
+    ...
+  </dependencies>
+  ...
+</project>
+-----
+
+** Create a <<<MyMojoTest>>>
+
+ Create a <<<MyMojoTest>>> (by convention) class in 
<<<src/test/java/org/apache/maven/plugin/my>>> directory.
+ This class should extends <<<AbstractMojoTestCase>>> from 
<<<maven-plugin-testing-harness>>>.
+
+-----
+public class MyMojoTest
+    extends AbstractMojoTestCase
+{
+    /** [EMAIL PROTECTED] */
+    protected void setUp()
+        throws Exception
+    {
+        // required
+        super.setUp();
+
+        ...
+    }
+
+    /** [EMAIL PROTECTED] */
+    protected void tearDown()
+        throws Exception
+    {
+        // required
+        super.tearDown();
+
+        ...
+    }
+
+    /**
+     * @throws Exception if any
+     */
+    public void testSomething()
+        throws Exception
+    {
+        File pom = getTestFile( 
"src/test/resources/unit/project-to-test/pom.xml" );
+        assertNotNull( pom );
+        assertTrue( pom.exists() );
+
+        MyMojo myMojo = (MyMojo) lookupMojo( "touch", pom );
+        assertNotNull( myMojo );
+        myMojo.execute();
+
+        ...
+    }
+}
+-----
+
+  In this case, <<<testSomething()>>> will test <<<MyMojo>>> against a Maven 
project called <<<project-to-test>>>.
+
+  <<Note>>: By convention, Mojo unit tests should be in the test resources 
directory.
+
+** Configuring <<<project-to-test>>> pom
+
+  Just create a pom as usual. The names for groupId and artifactId don't 
really care since this project will not be deployed.
+
+-----
+<project xmlns="http://maven.apache.org/POM/4.0.0";
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
+  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
+                      http://maven.apache.org/maven-v4_0_0.xsd";>
+  <modelVersion>4.0.0</modelVersion>
+
+  <groupId>org.apache.maven.plugin.my.unit</groupId>
+  <artifactId>project-to-test</artifactId>
+  <version>1.0-SNAPSHOT</version>
+  <packaging>jar</packaging>
+  <name>Test MyMojo</name>
+
+  <dependencies>
+    <dependency>
+      <groupId>junit</groupId>
+      <artifactId>junit</artifactId>
+      <version>3.8.1</version>
+      <scope>test</scope>
+    </dependency>
+  </dependencies>
+
+  <build>
+    <plugins>
+      <plugin>
+        <artifactId>maven-my-plugin</artifactId>
+        <configuration>
+          <!-- Specify the MyMojo parameter -->
+          
<outputDirectory>target/test-harness/project-to-test</outputDirectory>
+        </configuration>
+      </plugin>
+    </plugins>
+  </build>
+</project>
+-----
+
+** Execute test
+
+ As usual, just call:
+
+-----
+mvn test
+-----
+
+* Resources
+
+ [[1]] 
{{{http://maven.apache.org/guides/plugin/guide-java-plugin-development.html}Guide
 to Developing Java Plugins}}
+
+ [[2]] 
{{{http://maven.apache.org/guides/mini/guide-configuring-plugins.html}Guide to 
Configuring Plug-ins}}
+
+ []

Propchange: 
maven/plugin-tools/trunk/maven-plugin-testing-harness/src/site/apt/getting-started/index.apt
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: 
maven/plugin-tools/trunk/maven-plugin-testing-harness/src/site/apt/getting-started/index.apt
------------------------------------------------------------------------------
    svn:keywords = "Author Date Id Revision"

Added: 
maven/plugin-tools/trunk/maven-plugin-testing-harness/src/site/apt/index.apt
URL: 
http://svn.apache.org/viewvc/maven/plugin-tools/trunk/maven-plugin-testing-harness/src/site/apt/index.apt?rev=629650&view=auto
==============================================================================
--- 
maven/plugin-tools/trunk/maven-plugin-testing-harness/src/site/apt/index.apt 
(added)
+++ 
maven/plugin-tools/trunk/maven-plugin-testing-harness/src/site/apt/index.apt 
Wed Feb 20 15:15:21 2008
@@ -0,0 +1,46 @@
+ ------
+ Introduction
+ ------
+ Vincent Siveton
+ ------
+ February 2008
+ ------
+
+~~ 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.
+
+Maven Plugin Testing Mechanism
+
+ The Maven Plugin Testing Harness provides mechanisms to manage tests on Mojo, 
i.e. by pre-constructing the
+ {{{http://plexus.codehaus.org}Plexus}} components, providing stub objects for 
Maven functionality such as projects,
+ and populating fields from an XML file that resembles the Plugin 
configuration in the POM.
+
+ The best way to start is to read the cookbook 
{{{getting-started/index.html}How to use Maven Plugin Testing Harness}}.
+
+* Examples
+
+   The following examples shows how to use the Testing Harness in more 
advanced usecases:
+
+   * {{{examples/complex-mojo-parameters.html}Testing Complex Mojo Parameters}}
+
+   * {{{examples/multiproject.html}Testing Multiproject}}
+
+   * {{{examples/repositories.html}Testing Using Repositories}}
+
+   * {{{examples/artifact.html}Testing Project Artifact}}
+
+   []

Propchange: 
maven/plugin-tools/trunk/maven-plugin-testing-harness/src/site/apt/index.apt
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: 
maven/plugin-tools/trunk/maven-plugin-testing-harness/src/site/apt/index.apt
------------------------------------------------------------------------------
    svn:keywords = "Author Date Id Revision"

Added: 
maven/plugin-tools/trunk/maven-plugin-testing-harness/src/site/fml/faq.fml
URL: 
http://svn.apache.org/viewvc/maven/plugin-tools/trunk/maven-plugin-testing-harness/src/site/fml/faq.fml?rev=629650&view=auto
==============================================================================
--- maven/plugin-tools/trunk/maven-plugin-testing-harness/src/site/fml/faq.fml 
(added)
+++ maven/plugin-tools/trunk/maven-plugin-testing-harness/src/site/fml/faq.fml 
Wed Feb 20 15:15:21 2008
@@ -0,0 +1,59 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+
+<!--
+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.
+-->
+
+<faqs id="FAQ" title="Frequently Asked Questions">
+  <part id="General">
+    <faq id="What is a Mojo Testing Harness">
+      <question>What is a Mojo Testing Harness?</question>
+      <answer>
+        <p>
+          A unit test attempts to verify a mojo as an isolated unit, by 
mocking out the rest of the Maven environment.
+          A mojo unit test does not attempt to run your plugin in the context 
of a real Maven build.
+          Unit tests are designed to be fast.
+        </p>
+        <p>
+          This testing library is <b>NOT</b> designed for integration or 
functional testing.
+        </p>
+      </answer>
+    </faq>
+    <faq id="What kinds of unit tests are supported">
+      <question>What kind of unit tests are supported?</question>
+      <answer>
+        <p>
+          <dl>
+            <dt>TestCase from JUnit</dt>
+            <dd>You could use the <a href="http://junit.org/";>JUnit 
framework</a> to test your plugin in
+              the same way you'd write any other JUnit test cases, i.e. by 
writing a test class which extends
+              <i>TestCase</i>.</dd>
+            <dt>TestCase from Plexus</dt>
+            <dd>Mojos are written to take specific advantage of the <a 
href="http://plexus.codehaus.org/";>Plexus</a>
+              container. If you need Plexus container services, you could 
write your class wich extends <i>PlexusTestCase</i>,
+              instead of <i>TestCase</i>.</dd>
+            <dt>TestCase from Testing Harness</dt>
+            <dd>If you need to inject Maven objects into your mojo, you could 
use the <i>maven-plugin-testing-harness</i>.
+              The <i>maven-plugin-testing-harness</i> is explicitly intended 
to test the
+              <i>org.apache.maven.reporting.AbstractMavenReport#execute()</i> 
implementation.</dd>
+          </dl>
+        </p>
+      </answer>
+    </faq>
+  </part>
+</faqs>
\ No newline at end of file

Propchange: 
maven/plugin-tools/trunk/maven-plugin-testing-harness/src/site/fml/faq.fml
------------------------------------------------------------------------------
    svn:keywords = "Author Date Id Revision"

Added: maven/plugin-tools/trunk/maven-plugin-testing-harness/src/site/site.xml
URL: 
http://svn.apache.org/viewvc/maven/plugin-tools/trunk/maven-plugin-testing-harness/src/site/site.xml?rev=629650&view=auto
==============================================================================
--- maven/plugin-tools/trunk/maven-plugin-testing-harness/src/site/site.xml 
(added)
+++ maven/plugin-tools/trunk/maven-plugin-testing-harness/src/site/site.xml Wed 
Feb 20 15:15:21 2008
@@ -0,0 +1,39 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+
+<!--
+  ~ 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.
+  -->
+
+<project name="Maven Plugin Testing Mechanism">
+  <body>
+    <menu name="Overview">
+      <item name="Introduction" href="index.html"/>
+      <item name="Getting Start" href="/getting-started/index.html"/>
+      <item name="FAQ" href="/faq.html"/>
+    </menu>
+
+    <menu name="Examples">
+      <item name="Testing Complex Mojo Parameters" 
href="/examples/complex-mojo-parameters.html"/>
+      <item name="Testing Multiproject" href="/examples/multiproject.html"/>
+      <item name="Testing Repositories" href="/examples/repositories.html"/>
+      <item name="Testing Project Artifact" href="/examples/artifact.html"/>
+    </menu>
+
+    <menu ref="reports" inherit="bottom" />
+  </body>
+</project>

Propchange: 
maven/plugin-tools/trunk/maven-plugin-testing-harness/src/site/site.xml
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: 
maven/plugin-tools/trunk/maven-plugin-testing-harness/src/site/site.xml
------------------------------------------------------------------------------
    svn:keywords = "Author Date Id Revision"


Reply via email to