Author: tchemit Date: 2009-09-27 21:16:22 +0200 (Sun, 27 Sep 2009) New Revision: 597 Added: trunk/src/site/apt/mojoTestFramework.apt Modified: trunk/src/site/apt/index.apt trunk/src/site/site.xml Log: add documentation for Mojo Test Framework Modified: trunk/src/site/apt/index.apt =================================================================== --- trunk/src/site/apt/index.apt 2009-09-27 19:15:24 UTC (rev 596) +++ trunk/src/site/apt/index.apt 2009-09-27 19:16:22 UTC (rev 597) @@ -45,6 +45,8 @@ Test toolkit overview + * {{{mojoTestFramework.html}Mojo test framework}}. + see test-javadoc. <<A faire>> Added: trunk/src/site/apt/mojoTestFramework.apt =================================================================== --- trunk/src/site/apt/mojoTestFramework.apt (rev 0) +++ trunk/src/site/apt/mojoTestFramework.apt 2009-09-27 19:16:22 UTC (rev 597) @@ -0,0 +1,175 @@ +---- +Test framework api +---- +---- +2009-08-22 +---- + +Introduction + + This document explains to mojo test framework api of <maven-helper-plugin>. + + The <mojo test framework> aims to simplify the writing of tests on a mojo. + + To use this framework, your mojo classes <<MUST>> implement the contract + <<org.nuiton.plugin.Plugin>>. + + The framework use these technologies : + + * <<java 6>> + + * <<junit 4.7>> + + * <<maven-plugin-testing-harness 1.2>>. + +How to use it + + For each mojo you want to test, implements the <<org.nuiton.plugin.AbstractMojoTest>> + class. + + For each mojo's invocation you want to test : + + * write a method with a Junit <<Test>> annotation. + + * write the pom file corresponding to the mojo's invocation to test. + +Directory layout of a mojo test + + The mojo test framework api follows a simple directory layout convention : + + * the mojo test class is in the same package as the mojo (respect JUnit convention) + + * the pom files to use for tests are in the sub package with the name of the + plugin test class of the test class's package. + + * each test method's name is the file name (suffixed by <.xml>) of the pom to use. + +Example + + Having a <<org.nuiton.test.plugin.MyMojo>> class to test, and wants to do + two tests <firstTest> and <secondTest>. + + Here is the test class code to produce : + +-------------------------------------------------------------------------------- +package org.nuiton.test.plugin; + +import static org.junit.Assert.*; +import org.junit.Test; +import org.nuiton.plugin.AbstractMojoTest; + +public class MyMojoTest extends AbstractMojoTest<MyMojo> { + + @Override + protected String getGoalName(String methodName) { + return "my-goal"; + } + + @Test + public void firstTest() throws Exception { + + MyMojo mojo = getMojo(); + + mojo.execute(); + + // do my assertions after the goal be executed + } + + @Test + public void seconTest() throws Exception { + + MyMojo mojo = getMojo(); + + mojo.execute(); + + // do my assertions after the goal be executed + } +} +-------------------------------------------------------------------------------- + + and writes two pom files names <firstTest.xml> and <secondTest.xml> in directory + +-------------------------------------------------------------------------------- +src/test/resources/org/nuiton/test/plugin/MyMojoTest +-------------------------------------------------------------------------------- + + Finally, the next directory tree is what you should have for the example project : + +-------------------------------------------------------------------------------- +maven-test-plugin +|-- pom.xml +`-- src + |-- main + | |-- java + | | `-- org + | | `-- nuiton + | | `-- test + | | `-- plugin + | | `-- MyMojo.java + `-- test + |-- java + | `-- org + | `-- nuiton + | `-- test + | `-- plugin + | `-- MyMojoTest.java + `-- resources + `-- org + `-- nuiton + `-- test + `-- plugin + `-- MyMojoTest + |-- firstTest.xml + `-- secondTest.xml +-------------------------------------------------------------------------------- + +Go deeper in AbstractMojoTest + + Often, we could want to do some extra initialization on the mojo before + executing it. + + <Note:> There is some limitations of the <maven-plugin-testing-harness> and + this is not a real maven execution environement, for example you can not + defined in the pom file some properties... + + You can then override the <<setupMojo>> method, lie in the next example : + +-------------------------------------------------------------------------------- + + @Override + protected void setUpMojo(MyMojoTest mojo, File pomFile) throws Exception { + super.setUpMojo(mojo, pomFile); + + // do your extra pom customization + } +-------------------------------------------------------------------------------- + +* Changing the default behaviour + + If you do not want to follow the default behaviour, you can override some + methods to make the test fits your needs. + + <<Note:>> this is not a good idea to change the default behaviour, since it + would be nice that every mojo test respect the conventions to make it easier + for every developper (and not only the one who wrote the test case...) + + +-------------------------------------------------------------------------------- + + @Override + protected MyMojo createMojo(File pomFile, String goalName) throws Exception { + return super.createMojo(pomFile, goalName); + } + + @Override + protected File getPomFile(File testDir, String methodName, String goalName) { + return super.getPomFile(testDir, methodName, goalName); + } + + @Override + protected File getTestDir(String methodName, String goalName) { + return super.getTestDir(methodName, goalName); + } +-------------------------------------------------------------------------------- + + For more explanations, see the test-javadoc. Modified: trunk/src/site/site.xml =================================================================== --- trunk/src/site/site.xml 2009-09-27 19:15:24 UTC (rev 596) +++ trunk/src/site/site.xml 2009-09-27 19:16:22 UTC (rev 597) @@ -52,6 +52,7 @@ </menu> <menu name="Développeur"> + <item name="Mojo test framework" href="mojoTestFramework.html"/> <item name="A faire" href="Todo.html"/> </menu>