Codehaus Cargo > Features > Extensions > Maven 3 Plugin
 
A Maven 3 plugin that wraps the Cargo Java API. Though there are no minimum version requirements, all building, continous testing and release activities are performed using Maven 3.2.5 and onwards so we would recommend you have that installed.

Functional tests

The usage of Cargo for executing functional tests on a container does not mandate this Maven 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, though the Maven 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.)


Reg. Lifetime of our Maven 2 plugin

Please be aware that the Maven 2 / Maven 3 plugin of Codehaus Cargo has been retired with our version 1.9.0 and has been superseded by a Maven 3 only plugin.

Table of Contents

The documentation for this Maven 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

Codehaus Cargo can be directly run on any existing Maven J2EE, Java EE or Jakarta EE project (WAR, EAR or other) by running:

mvn clean verify org.codehaus.cargo:cargo-maven3-plugin:run

This will create a default Jetty 9.x installed local container and start it using the Cargo Maven 3 plugin with your Maven 3 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 if you now want to run the same tests with Tomcat 9.x you simply need to run (in one line):

mvn clean verify org.codehaus.cargo:cargo-maven3-plugin:run
    -Dcargo.maven.containerId=tomcat9x

That command will automatically:

  • Download the Maven artifact for the version of Tomcat 9.x that our Continous Integration has validated as working fine
  • Instantiate the container
  • Create a local configuration with your application
  • ... and, run it

To use a specific version of Tomcat 9.x, you simply need to run (in one line):

mvn clean verify org.codehaus.cargo:cargo-maven3-plugin:run
    -Dcargo.maven.containerId=tomcat9x
    -Dcargo.maven.containerUrl=https://repo.maven.apache.org/maven2/org/apache/tomcat/tomcat/9.0.45/tomcat-9.0.45.zip

This time, the command will automatically download Tomcat 9.0.45 from the specified URL instead, taking into account any proxy server setting you would have in Maven 3, and will it in the default directory (see the Maven 3 Plugin Reference Guide for details), so it won't get downloaded when you run the same command twice.

If you now want to run this time on WildFly 20.x with with the HTTP port set to 9000, run:

mvn clean verify org.codehaus.cargo:cargo-maven3-plugin:run
    -Dcargo.maven.containerId=wildfly20x
    -Dcargo.maven.containerUrl=https://download.jboss.org/wildfly/20.0.1.Final/wildfly-20.0.1.Final.zip
    -Dcargo.servlet.port=9000

As you can see, Codehaus Cargo's main advantage is that the commands and configuration remains the same for any version of any supported container - be it Tomcat, Jetty, JBoss, JOnAS, GlassFish, WebLogic, WildFly, etc.

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 Maven 3 Archetypes that contain sample Maven 3 projects with different use cases for the Codehaus Cargo Maven 3 plugin, we would really recommend that you check them out. For more details, read here: Maven 3 Archetypes.

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 goal will:

    • If the plugin configuration requires so, installs the container.
    • If the plugin configuration defines a container with a standalone local configuration, it will create the configuration.
    • If the plugin configuration contains one or more deployables, it will deploy these to the container automatically.
    • If the plugin configuration contains no deployables but the project's packaging is J2EE, Java EE or Jakarta EE (WAR, EAR, etc.), it will deploy the project's deployable to to the container automatically.
    • And, of course, start the container.

Note: A container that's started with cargo:start will automatically shut down as soon as the parent Maven instance quits (i.e., you see a BUILD SUCCESSFUL or BUILD FAILED message). If you want to start a container and perform manual testing, see our next goal cargo:run.

cargo:run

Start a container and wait for the user to press CTRL + C to stop. That goal will:

    • If the plugin configuration requires so, installs the container.
    • If the plugin configuration defines a container with a standalone local configuration, it will create the configuration.
    • If the plugin configuration contains one or more deployables, it will deploy these to the container automatically.
    • If the plugin configuration contains no deployables but the project's packaging is J2EE, Java EE or Jakarta EE (WAR, EAR, etc.), it will deploy the project's deployable to to the container automatically.
    • And, of course, start the container and wait for the user to press CTRL + C to stop.

cargo:stop

Stop a container.

cargo:restart

 Stop and start again a container. If the container was not running before calling cargo:restart, it will simply be started.

cargo:configure

Create the configuration for a local container, without starting it.

Note: If the plugin configuration requires so, the cargo:start goal automatically installs the container.

cargo:package

Package the local container.
cargo:daemon-start

Start a container via the daemon. Read more on: Cargo Daemon

Note: The daemon:start goal is actually equivalent to a restart in Codehaus Cargo's terms; in the case a container with the same cargo.daemon.handleid already exists then it will be stopped first before your container is started. This also implies that in the case the new container fails to start, the old one will not be restarted.
cargo:daemon-stop Stop a container via the daemon. Read more on: Cargo Daemon

cargo:deployer-deploy (aliased to cargo:deploy)

Deploy a deployable to a running container.

Note: The cargo:start and cargo:run do already deploy the deployables specified in the configuration to the container; as a result calling cargo:deploy for a container which has been started by Codehaus Cargo in the same Maven project will most likely cause a second deployment of the same deployables (and might even fail).

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. If the deployable was not deployed before calling cargo:deployer-redeploy (or its alias cargo:redeploy) it will simply be deployed.

cargo:uberwar

Merge several WAR files into one.

cargo:install

Installs a container distribution, either downloaded using a URL or defined as a Maven artifact, on the file system.

Note: If the plugin configuration requires so, the cargo:start and cargo:run goals automatically install the container but will not call cargo:install.

cargo:help

Get help (list of available goals, available options, etc.).


The configuration elements are described in the Reference Guide section.
Copyright 2004-2024. All rights reserved unless otherwise noted.
 Click here to read our privacy and cookie policy