This page last changed on Mar 22, 2006 by vmassol.
A Maven 2 plugin that wraps the Cargo Java API
 | Functional tests
The usage of Cargo for executing functional tests on a container do not need this m2 plugin. You should directly use the Cargo Java API from your Java unit test classes (JUnit, TestNG, etc), as described on http://tinyurl.com/btmwa. |
Table of Contents
This page documents the following:
- Installation: explains how to install the plugin
- Features: explains how to use the plugin on several use cases
- Configuration: provide reference documentation for all configuration options
- Tips: tips for using the plugin
Installation
There is no installation necessary. The Cargo artifacts are hosted on ibiblio. Note that you may also find older artifacts on ibiblio but those shouldn't be used and won't work with this plugin.
Note that the Cargo project has a snapshot repository on Codehaus. If you want use snapshot versions of the Cargo m2 plugin you'll need to add this definition in your POM or settings file:
<pluginRepositories>
<pluginRepository>
<id>cargo m2 snapshot repository</id>
<url>http://cargo.codehaus.org/dist2-snapshot</url>
<releases>
<enabled>true</enabled>
</releases>
</pluginRepository>
</pluginRepositories>
Features
As usual the best way to learn to use a tool is through examples. We have several sample projects that we use as our internal functional tests suite. We'd really recommend that you check them out. In addition here are the typical uses cases covered by the plugin:
Goals |
Description |
cargo:start |
Start a container and optionally deploy deployables (WAR, EAR, etc) |
cargo:stop |
Stop a container |
cargo:deployer-deploy (aliased to cargo:deploy) |
Deploy a deployable to a running container |
cargo:deployer-undeploy (aliased to cargo:undeploy) |
Undeploy a deployable from a running container |
cargo:deployer-start |
Start a deployable already installed in a running container |
cargo:deployer-stop |
Stop a deployed deployable without undeploying it |
cargo:deployer-redeploy |
Undeploy and deploy again a deployable |
cargo:uberwar |
Merge several WAR files into one |
The configuration elements are described in the configuration section.
Configuration
These are the various XML configuration elements that you can use to configure the Cargo Maven2 plugin. Make sure you also check the use cases which show how to use them.
Top level configuration elements |
Description |
Mandatory? |
Default value |
|
Definition of a Configuration |
|
No default, cannot call cargo:start or cargo:stop if not defined |
|
Definition of a Container |
|
Defaults to a Jetty 5.x container if not specified |
|
Definition of a Deployer |
|
No default, cannot call cargo:deploy and cargo:undeploy if not defined |
** elements |
Description |
Mandatory? |
Default value |
|
List of modules to deploy when the container is started. You specify each module using a element |
|
No default |
<home> |
For standalone configuration this is the location where Cargo will create the configuration and for existing configuration this is where it is located |
|
${java.io.tmpdir}/cargo/<some unique directory> |
<implementation> |
Full classname of a customer configuration implementation to use. In that case the custom configuration is registered with the <containerId> and <type> specified |
|
No default |
|
Values to use for various Configuration properties |
|
Default configuration properties |
<type> |
Configuration's type. Valid values are standalone, existing and runtime |
|
standalone |
<container> elements |
Description |
Mandatory? |
Default value |
<append> |
If true then the file specified by <output> will not be erased across different runs |
|
False |
<containerId> |
Id of the container to use. Valid values can be found in the description page for each container |
|
jetty5xEmbedded |
<dependencies> |
List of extra dependencies that will be added to the container execution classpath |
|
No default |
<home> |
Location where the container is installed |
|
No default, must define either a zipUrlInstaller or a home element |
<implementation> |
Full classname of a custom container implementation to use. In that case, the custom container is registered with the <containerId> and <type> specified |
|
No default |
<log> |
Path to a file where Cargo logs are saved |
|
No logs are saved |
<output> |
Path to a file where container logs are saved |
|
No logs are saved |
> |
List of <key>value</key> pairs to be passed as System properties to the container when it is started |
|
No default |
|
The timeout after which Cargo reports an error if the container is not started |
|
120000 ms (2 minutes) |
|
Container's type. Valid values are local, remote |
|
local |
> |
Defines the location of a container distribution zip that will be downloaded and installed |
|
No default, a home directory for the container has to be defined in that case |
<deployer> elements |
Description |
Mandatory? |
Default value |
<deployables> |
TODO |
|
No default |
<implementation> |
TODO |
|
No default |
<type> |
TODO |
|
local |
<deployable> elements |
Description |
Mandatory? |
Default value |
<artifactId> |
Maven artifact id for the module. This artifact id must match either the project's artifact id if your project generates a J2EE artifact (WAR, EAR, EJB and RAR) or it must match a specified <project>/<dependencies>/<dependency> artifact id |
|
Defaults to the project's artifact id |
<groupId> |
Maven group id for the module. This group id must match either the project's group id if your project generates a J2EE artifact (WAR, EAR, EJB and RAR) or it must match a specified <project>/<dependencies>/<dependency> group id |
|
Defaults to the project's group id |
<implementation> |
TODO |
|
No default |
<location> |
Path location where the module can be found |
|
Default's to the project's generated artifact location or to the specified <project>/<dependencies>/<dependency> location |
<pingURL> |
TODO |
|
No default |
<properties> |
TODO |
|
No default |
<type> |
Maven type for the module. This type must match either the project's packaging if your project generates a J2EE artifact (WAR, EAR, EJB and RAR) or it must match a specified <project>/<dependencies>/<dependency> type |
|
Defaults to the project's packaging |
<properties> elements |
Description |
Mandatory? |
Default value |
<[property's name]> |
TODO |
|
Default property value if any |
<dependencies> elements |
Description |
Mandatory? |
Default value |
<artifactId> |
Maven's artifact id. This artifact id must match a specified <project>/<dependencies>/<dependency> artifact id |
|
Defaults to the project's artifact id |
<groupId> |
Maven's group id. This group id must match a specified <project>/<dependencies>/<dependency> group id |
|
Defaults to the project's group id |
<type> |
Maven's type. This type must match a specified <project>/<dependencies>/<dependency> type |
|
Defaults to the project's packaging |
<zipUrlInstaller> elements |
Description |
Mandatory? |
Default value |
<installDir> |
TODO |
|
TODO |
<proxy> |
TODO |
|
No default |
<url> |
TODO |
|
No default |
Tips
Starting mutiple containers conditionally
Maven 2 supports the notion of profiles which can be used with Cargo to decide for example when to run tests on a specific container. Here's how you could use the Cargo m2 plugin to that effect:
<project>
[...]
<profiles>
<profile>
<id>tomcat5x</id>
<build>
<plugins>
<plugin>
<groupId>org.codehaus.cargo</groupId>
<artifactId>cargo-maven2-plugin</artifactId>
<executions>
<execution>
<id>tomcat-execution</id>
<!-- Ideally this would be bound to some integration-test-prepare phase but
that do not exist yet. See http://jira.codehaus.org/browse/MNG-1628 -->
<phase>package</phase>
<goals>
<goal>start</goal>
</goals>
<configuration>
<wait>false</wait>
<container>
<containerId>tomcat5x</containerId>
<zipUrlInstaller>
<url>http://www.apache.org/dist/jakarta/tomcat-5/v5.0.30/bin/jakarta-tomcat-5.0.30.zip</url>
<installDir>${installDir}</installDir>
</zipUrlInstaller>
</container>
<configuration>
<home>${project.build.directory}/tomcat5x/container</home>
</configuration>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>
</profile>
<profile>
<id>orion2x</id>
<build>
<plugins>
<plugin>
<groupId>org.codehaus.cargo</groupId>
<artifactId>cargo-maven2-plugin</artifactId>
<executions>
<execution>
<id>orion-execution</id>
<!-- Ideally this would be bound to some integration-test-prepare phase but
that do not exist yet. See http://jira.codehaus.org/browse/MNG-1628 -->
<phase>package</phase>
<goals>
<goal>start</goal>
</goals>
<configuration>
<wait>false</wait>
<container>
<containerId>orion2x</containerId>
<zipUrlInstaller>
<url>http://www.orionserver.com/distributions/orion2.0.5.zip</url>
<installDir>${installDir}</installDir>
</zipUrlInstaller>
</container>
<configuration>
<home>${project.build.directory}/orion2x/container</home>
</configuration>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>
</profile>
</profiles>
</project>
Then to start the tomcat 5.x container you would type mvn -P tomcat5x integration-test. if you want to start both containers you would type mvn -P tomcat5x,orion2x integration-test.
If you want to define a profile as the default you can use the <activation> element with an activation strategy. For example if you want a profile to be always on, use:
<profiles>
<profile>
<id>tomcat5x</id>
<activation>
<activeByDefault>true</activeByDefault>
</activation>
[...]
TODO: Show how to share configuration data between profiles (this should work by defining the default config data in the <build> element).
Starting Tomcat in security mode
Cargo supports passing system properties Passing system properties. So, to start Tomcat in security mode, you need to specify two system properties:
- java.security.manager
- java.security.policy
For instance,
[...]
<plugins>
[...]
<plugin>
<groupId>org.codehaus.cargo</groupId>
<artifactId>cargo-maven2-plugin</artifactId>
<configuration>
<container>
<containerId>tomcat5x</containerId>
<home>${catalina.home}</home>
[...]
<systemProperties>
<java.security.manager>default</java.security.manager>
<java.security.policy>${catalina.home}\conf\catalina.policy</java.security.policy>
</systemProperties>
</container>
</configuration>
</plugin>
[...]
</plugins>
[...]
|