This page last changed on May 01, 2011 by alitokmen.

A Maven 2 plugin that wraps the Cargo Java API

Functional tests
The usage of Cargo for executing functional tests on a container does not mandate this m2 plugin. You could also directly use the Cargo Java API from your Java unit test classes (JUnit, TestNG, etc), as described on the Functional testing page. The choice is yours, thought the Maven2 plugin is generally more straightforward to use and integrates better with the whole build process (with profiles, easier to use deployer, proxy server support, etc.)

Table of Contents

The documentatation for this Maven2 plugin includes:

  • Installation: explains how to install the plugin
  • Getting started: explains how to use the plugin on several use cases
  • Reference Guide: provide reference documentation for all configuration options
  • Tips: tips for using the plugin

Getting Started

Very quick start

The simplest Cargo configuration for your existing Maven2 Java EE project (WAR, EAR or other) would the following plugin definition:

<plugin>
  <groupId>org.codehaus.cargo</groupId>
  <artifactId>cargo-maven2-plugin</artifactId>
  <configuration>
    <container>
      <containerId>tomcat7x</containerId>
      <zipUrlInstaller>
        <url>http://archive.apache.org/dist/tomcat/tomcat-7/v7.0.12/bin/apache-tomcat-7.0.12.zip</url>
      </zipUrlInstaller>
    </container>
  </configuration>
</plugin>

And then run:

mvn clean verify cargo:run
The cargo:run MOJO
Note that cargo:run is inly available with Cargo 1.1.1 and onwards. On older versions of Cargo, please use:
mvn clean verify start -Dwait=true

This will create a default Tomcat 7.x container and start it using the Cargo Maven2 plugin with your Maven2 project's deployable (a WAR, for example) deployed to it; so you can run manual tests (as a first introduction).

What is magic is that you can replace the tomcat7x (and associated container URL, of course) with anything from other versions of Tomcat to Jetty, JBoss, JOnAS, GlassFish, WebLogic, ... and still the plugin configuration will stay the same. This reality holds even when you want to change the container's configuration (for example, its HTTP port), independently from the container.

Like it? Well, keep on reading, then!

More examples

As usual the best way to learn to use a tool is through examples. We have several Maven2 Archetypes that contain sample Maven2 projects, we would really recommend that you check them out.

In addition here are the typical uses cases covered by the plugin:

The Cargo Maven plugin in detail

Here are the different goals available to call on this plugin:

Goals Description
cargo:start Start a container. That task can optionally install and configure a container; it can also optionally deploy deployables (WAR, EAR, etc.) to it.
cargo:run Start a container and wait for the user to press CTRL + C to stop. That task can optionally install and configure a container; it can also optionally deploy deployables (WAR, EAR, etc.) to it (since v1.1.1).
cargo:stop Stop a container
cargo:configure Create the configuration for a local container, without starting it. Note that the cargo:start and cargo:run tasks will also install the container automatically (but will not call cargo:install).
cargo:package Package the local 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 (aliased to cargo:redeploy) Undeploy and deploy again a deployable
cargo:uberwar Merge several WAR files into one
cargo:install Installs a container distribution on the file system. Note that the cargo:start task will also install the container automatically (but will not call cargo:install).
cargo:help Get help (list of available goals, available options, etc.) (since v1.0.2)


The configuration elements are described in the Reference Guide section.

Document generated by Confluence on Jun 14, 2011 22:09