From 91e9bef3bbb8d55d3e1cd5bb1f80ecf5a7bb174a Mon Sep 17 00:00:00 2001 From: Vincent Siveton Date: Wed, 20 Feb 2008 23:15:21 +0000 Subject: [PATCH] o first draft of documentation git-svn-id: https://svn.apache.org/repos/asf/maven/plugin-tools/trunk@629650 13f79535-47bb-0310-9956-ffa450edef68 --- .../src/site/apt/examples/artifact.apt | 216 ++++++++++++++++++ .../apt/examples/complex-mojo-parameters.apt | 186 +++++++++++++++ .../src/site/apt/examples/multiproject.apt | 123 ++++++++++ .../src/site/apt/examples/repositories.apt | 138 +++++++++++ .../src/site/apt/getting-started/index.apt | 186 +++++++++++++++ .../src/site/apt/index.apt | 46 ++++ .../src/site/fml/faq.fml | 59 +++++ .../src/site/site.xml | 39 ++++ 8 files changed, 993 insertions(+) create mode 100644 maven-plugin-testing-harness/src/site/apt/examples/artifact.apt create mode 100644 maven-plugin-testing-harness/src/site/apt/examples/complex-mojo-parameters.apt create mode 100644 maven-plugin-testing-harness/src/site/apt/examples/multiproject.apt create mode 100644 maven-plugin-testing-harness/src/site/apt/examples/repositories.apt create mode 100644 maven-plugin-testing-harness/src/site/apt/getting-started/index.apt create mode 100644 maven-plugin-testing-harness/src/site/apt/index.apt create mode 100644 maven-plugin-testing-harness/src/site/fml/faq.fml create mode 100644 maven-plugin-testing-harness/src/site/site.xml diff --git a/maven-plugin-testing-harness/src/site/apt/examples/artifact.apt b/maven-plugin-testing-harness/src/site/apt/examples/artifact.apt new file mode 100644 index 0000000..1ab5d18 --- /dev/null +++ b/maven-plugin-testing-harness/src/site/apt/examples/artifact.apt @@ -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 + + <>: 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 ); + } + + /** {@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; + } + + /** {@inheritDoc} */ + 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 ); + + ... + } + + ... +} +----- diff --git a/maven-plugin-testing-harness/src/site/apt/examples/complex-mojo-parameters.apt b/maven-plugin-testing-harness/src/site/apt/examples/complex-mojo-parameters.apt new file mode 100644 index 0000000..cbc2816 --- /dev/null +++ b/maven-plugin-testing-harness/src/site/apt/examples/complex-mojo-parameters.apt @@ -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 + + <>: 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 <<>>, <<>> or + <<>>. You could use them by defining stubs. + + Suppose that you have the following dependencies in the maven-my-plugin pom: + +----- + + ... + + + org.apache.maven + maven-artifact + 2.0.8 + + + org.apache.maven + maven-project + 2.0.8 + + ... + + +----- + + You will add the following in the <<>>: + +----- +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 <<>>. By convention, the package name should + reflect the stubs, i.e. in our case <<>>. + +----- +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 ); + } + + /** {@inheritDoc} */ + public File getBasedir() + { + return new File( super.getBasedir() + "/src/test/resources/unit/project-to-test/" ); + } +} +----- + +----- +public class SettingsStub + extends Settings +{ + /** {@inheritDoc} */ + public List getProxies() + { + return Collections.EMPTY_LIST; + } +} +----- + +* Configuring <<>> pom + +----- + + ... + + + + maven-my-plugin + + + target/test-harness/project-to-test + + + ${localRepository} + + + + + + + + +----- diff --git a/maven-plugin-testing-harness/src/site/apt/examples/multiproject.apt b/maven-plugin-testing-harness/src/site/apt/examples/multiproject.apt new file mode 100644 index 0000000..541ada0 --- /dev/null +++ b/maven-plugin-testing-harness/src/site/apt/examples/multiproject.apt @@ -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 + + <>: 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 ); + } + + /** {@inheritDoc} */ + 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 <<>> pom + +----- + + ... + + + + maven-my-plugin + + ... + + + + + + + + + + +----- diff --git a/maven-plugin-testing-harness/src/site/apt/examples/repositories.apt b/maven-plugin-testing-harness/src/site/apt/examples/repositories.apt new file mode 100644 index 0000000..e95e261 --- /dev/null +++ b/maven-plugin-testing-harness/src/site/apt/examples/repositories.apt @@ -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 + + <>: 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() + { + ... + } + + /** {@inheritDoc} */ + public List getRemoteArtifactRepositories() + { + ArtifactRepository repository = new DefaultArtifactRepository( "central", "http://repo1.maven.org/maven2", + new DefaultRepositoryLayout() ); + + return Collections.singletonList( repository ); + } +} +----- + +* Configuring <<>> pom + +----- + + ... + + + + maven-my-plugin + + + ${basedir}/target/test-harness/project-to-test + + + ${localRepository} + + + + + + + +----- + +** Execute test + + Calling <<>> will create <<<$\{basedir\}/target/local-repo/junitjunit/3.8.1/junit-3.8.1.jar>>> file. diff --git a/maven-plugin-testing-harness/src/site/apt/getting-started/index.apt b/maven-plugin-testing-harness/src/site/apt/getting-started/index.apt new file mode 100644 index 0000000..000f4ad --- /dev/null +++ b/maven-plugin-testing-harness/src/site/apt/getting-started/index.apt @@ -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 <<>> from + <<>> 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 <<>> dependency + + As usually, just add <<>> as following in your pom. Be sure to specify <<>> scope. + +----- + + ... + + + org.apache.maven + maven-plugin-testing-harness + test + + ... + + ... + +----- + +** Create a <<>> + + Create a <<>> (by convention) class in <<>> directory. + This class should extends <<>> from <<>>. + +----- +public class MyMojoTest + extends AbstractMojoTestCase +{ + /** {@inheritDoc} */ + protected void setUp() + throws Exception + { + // required + super.setUp(); + + ... + } + + /** {@inheritDoc} */ + 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, <<>> will test <<>> against a Maven project called <<>>. + + <>: By convention, Mojo unit tests should be in the test resources directory. + +** Configuring <<>> pom + + Just create a pom as usual. The names for groupId and artifactId don't really care since this project will not be deployed. + +----- + + 4.0.0 + + org.apache.maven.plugin.my.unit + project-to-test + 1.0-SNAPSHOT + jar + Test MyMojo + + + + junit + junit + 3.8.1 + test + + + + + + + maven-my-plugin + + + target/test-harness/project-to-test + + + + + +----- + +** 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}} + + [] diff --git a/maven-plugin-testing-harness/src/site/apt/index.apt b/maven-plugin-testing-harness/src/site/apt/index.apt new file mode 100644 index 0000000..3c24409 --- /dev/null +++ b/maven-plugin-testing-harness/src/site/apt/index.apt @@ -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}} + + [] diff --git a/maven-plugin-testing-harness/src/site/fml/faq.fml b/maven-plugin-testing-harness/src/site/fml/faq.fml new file mode 100644 index 0000000..a10d24f --- /dev/null +++ b/maven-plugin-testing-harness/src/site/fml/faq.fml @@ -0,0 +1,59 @@ + + + + + + + + What is a Mojo Testing Harness? + +

+ 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. +

+

+ This testing library is NOT designed for integration or functional testing. +

+ + + + What kind of unit tests are supported? + +

+

+
TestCase from JUnit
+
You could use the JUnit framework 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 + TestCase.
+
TestCase from Plexus
+
Mojos are written to take specific advantage of the Plexus + container. If you need Plexus container services, you could write your class wich extends PlexusTestCase, + instead of TestCase.
+
TestCase from Testing Harness
+
If you need to inject Maven objects into your mojo, you could use the maven-plugin-testing-harness. + The maven-plugin-testing-harness is explicitly intended to test the + org.apache.maven.reporting.AbstractMavenReport#execute() implementation.
+
+

+ + + + \ No newline at end of file diff --git a/maven-plugin-testing-harness/src/site/site.xml b/maven-plugin-testing-harness/src/site/site.xml new file mode 100644 index 0000000..838dd85 --- /dev/null +++ b/maven-plugin-testing-harness/src/site/site.xml @@ -0,0 +1,39 @@ + + + + + + + + + + + + + + + + + + + + + +