You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@maven.apache.org by be...@apache.org on 2008/08/03 00:39:07 UTC
svn commit: r682076 - in /maven/plugins/trunk/maven-invoker-plugin/src:
main/java/org/apache/maven/plugin/invoker/InvokerMojo.java
site/apt/usage.apt.vm
Author: bentmann
Date: Sat Aug 2 15:39:07 2008
New Revision: 682076
URL: http://svn.apache.org/viewvc?rev=682076&view=rev
Log:
o Improved documentation
Modified:
maven/plugins/trunk/maven-invoker-plugin/src/main/java/org/apache/maven/plugin/invoker/InvokerMojo.java
maven/plugins/trunk/maven-invoker-plugin/src/site/apt/usage.apt.vm
Modified: maven/plugins/trunk/maven-invoker-plugin/src/main/java/org/apache/maven/plugin/invoker/InvokerMojo.java
URL: http://svn.apache.org/viewvc/maven/plugins/trunk/maven-invoker-plugin/src/main/java/org/apache/maven/plugin/invoker/InvokerMojo.java?rev=682076&r1=682075&r2=682076&view=diff
==============================================================================
--- maven/plugins/trunk/maven-invoker-plugin/src/main/java/org/apache/maven/plugin/invoker/InvokerMojo.java (original)
+++ maven/plugins/trunk/maven-invoker-plugin/src/main/java/org/apache/maven/plugin/invoker/InvokerMojo.java Sat Aug 2 15:39:07 2008
@@ -125,18 +125,21 @@
private File projectsDirectory;
/**
- * Directory to which projects should be cloned prior to execution.
- *
+ * Directory to which projects should be cloned prior to execution. If not specified, each integration test will be
+ * run in the directory in which the corresponding IT POM was found. In this case, you most likely want to configure
+ * your SCM to ignore <code>target</code> and <code>build.log</code> in the test's base directory.
+ *
* @parameter
* @since 1.1
*/
private File cloneProjectsTo;
/**
- * Some files are normally excluded when copying from the projectsDirectory
- * to the "cloneProjectsTo" directory (.svn, CVS, *~, etc). Setting this parameter to true
- * will cause all files to be copied to the cloneProjectsTo directory.
- *
+ * Some files are normally excluded when copying the IT projects from the directory specified by the parameter
+ * projectsDirectory to the directory given by cloneProjectsTo (e.g. <code>.svn</code>, <code>CVS</code>,
+ * <code>*~</code>, etc). Setting this parameter to <code>true</code> will cause all files to be copied to the
+ * cloneProjectsTo directory.
+ *
* @parameter default-value="false"
* @since 1.2
*/
@@ -159,14 +162,15 @@
private List pomIncludes = Collections.singletonList( "*/pom.xml" );
/**
- * Excludes for searching the integration test directory. This parameter is meant to be set from the POM.
- *
+ * Excludes for searching the integration test directory. This parameter is meant to be set from the POM. By
+ * default, no POM files are excluded.
+ *
* @parameter
*/
private List pomExcludes = Collections.EMPTY_LIST;
/**
- * The comma-separated list of goals to execute on each project. Default is 'package'.
+ * The list of goals to execute on each project. Default value is: <code>package</code>.
*
* @parameter
*/
@@ -245,7 +249,7 @@
private boolean noLog;
/**
- * List of profileId's to explicitly trigger in the build.
+ * List of profile identifiers to explicitly trigger in the build.
*
* @parameter
* @since 1.1
@@ -253,7 +257,7 @@
private List profiles;
/**
- * List properties which will be used to interpolate goal files.
+ * List of properties which will be used to interpolate goal files.
*
* @parameter
* @since 1.1
Modified: maven/plugins/trunk/maven-invoker-plugin/src/site/apt/usage.apt.vm
URL: http://svn.apache.org/viewvc/maven/plugins/trunk/maven-invoker-plugin/src/site/apt/usage.apt.vm?rev=682076&r1=682075&r2=682076&view=diff
==============================================================================
--- maven/plugins/trunk/maven-invoker-plugin/src/site/apt/usage.apt.vm (original)
+++ maven/plugins/trunk/maven-invoker-plugin/src/site/apt/usage.apt.vm Sat Aug 2 15:39:07 2008
@@ -27,19 +27,39 @@
~~ http://maven.apache.org/doxia/references/apt-format.html
Usage
-
-* How to use the Invoker Plugin
- This page provides general usage information along with some basic examples. The plugin
- is commonly used to run and verify integration tests for a project. This is done using
- the <<<{{{run-mojo.html} invoker:run }}>>> goal.
+ This page provides general usage information along with a basic example. The plugin
+ is commonly used to run and verify integration tests for a project, say a Maven plugin. This is done using
+ the <<<{{{run-mojo.html} invoker:run }}>>> goal. And as a preparation for the integration tests, one usually wants to
+ stage the artifacts under tests into a testing repository. For this job, the
+ <<<{{{install-mojo.html} invoker:install }}>>> goal can be used.
* Basic Example
- The following example shows basic plugin configuration for running integration tests.
- The project's directory (<<<src/it>>>) is the location where the plugin will look for test projects
- to execute. The plugin is set to find and run all <<<pom.xml>>> files in this directory.
-
+ The following example demonstrates a basic plugin configuration for running integration tests. Let's assume the following
+ directory structure of your project:
+
+-------------------
+./
++- pom.xml
++- src/
+ +- it/
+ +- settings.xml
+ +- first-it/
+ +- pom.xml
+ +- src/
+ +- second-it/
+ +- pom.xml
+ +- invoker.properties
+ +- test.properties
+ +- verify.bsh
+ +- src/
+-------------------
+
+ In this example, the directory <<<src/it>>> is the location where all the IT projects reside. You simply put each
+ integration test into a distinct sub directory, like shown by <<<first-it>>> and <<<second-it>>>. The plugin
+ configuration for this example would like this:
+
-------------------
<project>
...
@@ -52,13 +72,17 @@
<execution>
<id>integration-test</id>
<goals>
+ <goal>install</goal>
<goal>run</goal>
</goals>
<configuration>
<projectsDirectory>src/it</projectsDirectory>
+ <cloneProjectsTo>\${project.build.directory}/it</cloneProjectsTo>
<pomIncludes>
- <pomInclude>**/pom.xml</pomInclude>
+ <pomInclude>*/pom.xml</pomInclude>
</pomIncludes>
+ <localRepositoryPath>target/local-repo</localRepositoryPath>
+ <postBuildHookScript>verify.bsh</postBuildHookScript>
</configuration>
</execution>
</executions>
@@ -68,4 +92,37 @@
...
</project>
-------------------
-
\ No newline at end of file
+
+ Now, to get things going, just tell Maven to execute the lifecycle phase <<<integration-test>>>:
+
+-------------------
+ mvn integration-test
+-------------------
+
+ First, the <<<invoker:install>>> goal will be executed during the phase <<<pre-integration-test>>> and will copy the
+ main artifact of the project along with any attached artifacts over to <<<target/local-repo>>>. Furthermore, any
+ locally reachable parent POMs of the project will be copied to the staging repository. Last but not least, if you are
+ running a reactor build, all project dependencies that reside in the reactor will be staged, too.
+
+ Next up, the <<<invoker:run>>> goal will execute during the phase <<<integration-test>>> and will use the configured
+ include/exclude patterns to search the directory <<<src/it>>> for IT POMs. Every directory where an IT POM is found
+ will be copied over to <<<target/it>>>. Additionally, the IT POMs will be filtered, i.e. expressions like
+ <<<@pom.version@>>> will be replaced with the corresponding values from the POM. This is especially handy to make
+ sure your IT POMs always reference the currently build version of the project artifact. You can also define other
+ properties via the plugin configuration that you which to use for filtering.
+
+ Once the IT POMs have been filtered, a Maven build will be started on them. By default, the Invoker Plugin will execute the
+ phase <<<package>>> on the IT POMs but that can be changed globally in the plugin configuration or for an individual
+ integration test by using the <<<invoker.properties>>> as done in the example for <<<second-it>>>. Likewise, system
+ properties can be passed to the IT builds via the file <<<test.properties>>>. And the file <<<src/it/settings.xml>>>
+ can be used to specify custom user settings for the tests. Among others, this allows you to make the integration
+ tests use your local repository as a remote repository, avoiding time-consuming downloads from <<<central>>> in order
+ to fill up the initially empty staging repository. Please see the example {{{examples/fast-use.html}Fast Invoker Plugin Configuration}}
+ for more details on this technique. The output of the IT builds is written to a log file named <<<build.log>>> (e.g.
+ <<<target/it/first-it/build.log>>>) and allows diagnostics in case an integration test failed.
+
+ When an integration test has finished, the plugin will invoke an optional post build hook script. In the example,
+ this is the case for <<<second-it>>> where <<<verify.bsh>>> will be run. The purpose of this script is usally to
+ check that the build of the integration test did not only succeed but also produced the intended output. To allow the
+ script to locate the IT project's output, the Invoker Plugin will inject the variable <<<basedir>>> into the script.
+ Have a look at the example {{{examples/post-build-script.html}Using a Post Build Script}} for a code snippet.