Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 104 Next »

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

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


There is no installation necessary. The Cargo artifacts are hosted on ibiblio.

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:


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 coverer by the plugin:




Start a container and optionally deploy deployables (WAR, EAR, etc)


Stop a container


Deploy a J2EE archive to a running container

The configuration elements are described in the configuration section.

Start/stop a container

Ability to start/stop a container (possibly deploying some deployables to it as it starts). In this scenario Maven 2 is used as a convenience to easily and quickly start a container.

Example of a minimalist configuration:

Yes, you've read it right, there's no <configuration> element in this example! When you use this setup the Cargo m2 plugin will use a Jetty container by default. You can start the container with mvn cargo:start and stop it with mvn cargo:stop.

Example of a lightweight configuration:

This minimal configuration allows you to configure a default Tomcat 5.x standalone configuration (when the configuration type is not defined as above, the plugin will use a standalone configuration by default) in ${basedir}/target/resin.

Example of a full-fledged m2 configuration:

This example shows the usage of a standalone configuration for configuring Orion 2.x. Note that it's possible to define deployables in the <configuration> element and they'll be deployed before the container starts (this is what we call static deployment). We have also defined some configuration properties to tell Cargo to configure Orion 2.x to start on port 8080 and to output highly verbose logs (useful for debugging).

If you have a container that is already installed and configured, say with other deployables already in there, you may want to use an existing configuration. This done by specifying <type>existing</type>. In that case you won't be able to control the configuration from Cargo (like port to use, logging levels, etc) as it'll be defined externally.

Automatic deploymeny of project's artifact (for J2EE projects)

If your project is a J2EE project (i.e. of type <packaging>war</packaging>, <packaging>ear</packaging>, etc) and you use the Cargo m2 plugin on that project then the generated artifact will be automatically added to the list of deployables to deploy. You can control the location of the artifact by using the <location> element (it defaults to ${}/${}.${project.packaging}). In addition if you want to wait for the deployment to be finished you can specify a <pingURL> (none is used by default). Here's an example:

Deploy to a running container

Cargo supports deploying to an already running container. This feature is called hot deployment). You call it by using the (cargo:deploy) goal (e.g. mvn cargo:deploy).

Note that you can also do static deployment by simply defining the deployables to deploy in the <configuration> element as shown above. In that case the deployables will be deployed before the container starts.

Not all containers have a Deployer implemented


We haven't finished implementing Deployers for all containers yet. Please check if your favorite container has it implemented. If not you'll need to deploy your deployables by defining them in a standalone local configuration as shown in the start/stop a container use case above.

Using a local deployer

A local deployer is a deployer that deploys deployables on a local container (i.e. a container installed on the same machine where the deployer is executing). Thus you'll need to use a local container id in <containerId>. You can check that by reviewing the supported container list and selecting the container you wish to use.

Example of doing a local deploy to an existing configuration:

As for the <code>cargo:start</code> goal if your project is a J2EE project then the generated artifact will be automatically added to the list of deployables to deploy.

Using a remote deployer

A remote deployer is a deployer that deploys deployables on a remote container (i.e. a container that is running and that has been started externally from Cargo). Thus you'll need to use an id for a remote container in <containerId> and a runtime configuration.

Example of doing a remote deploy using a runtime configuration:

As you can see the information to connect and do the deployment to the remote container is specified in the runtime configuration (cargo.tomcat.manager.context, cargo.tomcat.manager.username and cargo.tomcat.manager.password). The properties to define are deployer-dependent. (TODO: Add link to reference documentation for specific remote deployers once it exists...)

Generate container configuration deployment structure

Ability to create a fully working custom configuration and possibly package some deployables in it. Then deliver this configuration as an artifact (cargo:package).



Work in progress...


This section is not finished and does not represent the full list of configuration options. In the meantime please check the samples on this page for examples of configurations.

Top level configuration elements


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

<container> elements


Default value


If true then the file specified by <output> will not be erased across different runs.



Id of the container to use. Valid values can be found in the description page for each container



List of extra dependencies that will be added to the container execution classpath

No default


Location where the container is installed

No default, must define either a zipUrlInstaller or a home element


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


Path to a file where Cargo logs are saved

No logs are saved


Path to a file where container logs are saved.

No logs are saved


Container's type. Valid values are local, remote.



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


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:

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:

TODO: Show how to share configuration data between profiles (this should work by defining the default config data in the <build> element).

  • No labels