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 185 Next »

A Maven 2 plugin that wraps the Cargo Java API

Functional tests

Icon

The usage of Cargo for executing functional tests on a container does 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 the Functional testing page.

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:

Then configure the Cargo plugin by specifyin a SNAPSHOT version. For example to use version 0.3-SNAPSHOT you would write in your POM:

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

<configuration>

Definition of a Configuration

(thumbs down)

Defaults to a standalone configuration if the container is of type local and a runtime one if it's of type remote

<container>

Definition of a Container

(thumbs down)

Defaults to a Jetty 5.x container if not specified

<deployer>

Definition of a Deployer

(thumbs down)

Defaults to a deployer matching the container's type if none is specified (installed local deployer for an installed container, remote deployer for a remote container and embedded local deployer for an embedded container)

wait

Tells Cargo to wait after the container is started or not

(thumbs down)

Defaults to true

<configuration> elements

Description

Mandatory?

Default value

<deployables>

List of modules to deploy when the container is started. You specify each module using a <deployable> element.

(thumbs down)

If no deployable is specified and the project's packaging is war, ear or ejb and there is no deployer specified then the generated artifact is added automatically to the list of deployables to deploy

<home>

For standalone configuration this is the location where Cargo will create the configuration and for existing configuration this is where it is located

(thumbs down)

${java.io.tmpdir}/cargo/conf

<implementation>

Full classname of a custom configuration implementation to use. In that case the custom configuration is registered with the <containerId> and <type> specified

(thumbs down)

Defaults to the Cargo-provided implementation if not specified

<properties>

Values to use for various Configuration properties

(thumbs down)

Default configuration properties

<type>

Configuration's type. Valid values are standalone, existing and runtime

(thumbs down)

standalone

<container> elements

Description

Mandatory?

Default value

<append>

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

(thumbs down)

False

<containerId>

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

(thumbs down)

jetty5x

<dependencies>

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

(thumbs down)

No default

<home>

Location where the container is installed

(thumbs down)

No default, user 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

(thumbs down)

Defaults to the Cargo-provided implementation if not specified

<log>

Path to a file where Cargo logs are saved

(thumbs down)

Logs to the Maven console if no log file is specified

<output>

Path to a file where container logs are saved

(thumbs down)

Logs to the file specified by the <log> element or to the Maven console is no such file has been specified

<systemProperties>

List of <key>value</key> pairs to be passed as System properties to the container when it is started

(thumbs down)

No default

<timeout>

The timeout after which Cargo reports an error if the container is not started

(thumbs down)

120000 ms (2 minutes)

<type>

Container's type. Valid values are installed, embedded and remote

(thumbs down)

Default value is installed unless the <containerId> has not been specified, in which case the default is to use the Jetty 5.x Embedded container

<zipUrlInstaller>

Defines the location of a container distribution zip that will be downloaded and installed

(thumbs down)

No default, a home directory for the container has to be defined in that case

<deployer> elements

Description

Mandatory?

Default value

<deployables>

A list of deployables that are going to be deployed in the container when it is started

(thumbs down)

No default

<implementation>

TODO

(thumbs down)

No default

<type>

TODO

(thumbs down)

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

(thumbs down)

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

(thumbs down)

Defaults to the project's group id

<implementation>

TODO

(thumbs down)

No default

<location>

Path location where the module can be found

(thumbs down)

Default's to the project's generated artifact location or to the specified <project>/<dependencies>/<dependency> location

<pingURL>

TODO

(thumbs down)

No default

<properties>

User-defined properties of a deployable.

(thumbs down)

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

(thumbs down)

Defaults to the project's packaging

<properties> elements

 Deployable Type

Description

Mandatory?

Default value

 <context>

WAR

The context name to use when deploying this web application.

(thumbs down)

If not specified by the user, then the default context name is computed from the name of WAR itself (without the file extension) or <project>/<build>/<finalName>

<war>

WAR

The path of the WAR being deployed.

(thumbs down)

Default's to the project's generated artifact location

<ear>

EAR

The path of the EAR being deployed.

(thumbs down)

Default's to the project's generated artifact location

<name>

EAR

The name of EAR deployable (it can be anything, there's no special rule).

(thumbs down)

If not specified, it is computed from the EAR's file name (removing the filename extension) or <project>/<build>/<finalName>

<ejb>

EJB

The path of the EJB being deployed.

(thumbs down)

Default's to the project's generated artifact location

<dependency> elements

Description

Mandatory?

Default value

<artifactId>

Maven's artifact id. This artifact id must match a specified <project>/<dependencies>/<dependency> artifact id

(thumbs down)

Defaults to the project's artifact id

<groupId>

Maven's group id. This group id must match a specified <project>/<dependencies>/<dependency> group id

(thumbs down)

Defaults to the project's group id

<type>

Maven's type. This type must match a specified <project>/<dependencies>/<dependency> type

(thumbs down)

Defaults to the project's packaging

<location>

The path of a folder or a jar file you wish to add to deployable classpath. This element can be used to explicitly add entries to the classpath. For example:

(thumbs down)

If the groupId and artifactId match those of the project then the deployable is the artifact generated by the project. Otherwise the location is the location of the dependency in your local respository.

<zipUrlInstaller> elements

Description

Mandatory?

Default value

<installDir>

TODO

(thumbs down)

TODO

<proxy>

TODO

(thumbs down)

No default

<url>

TODO

(thumbs down)

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:

Then to start the tomcat 5.x container you would type mvn -P tomcat5x install. if you want to start both containers you would type mvn -P tomcat5x,orion2x install.

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:

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,

How to get Tomcat 5 workgin with the Java 5 XML Parsers

Tip submitted by Ben P.

Imagine that you have some XML jars in the common/endorsed folder of Tomcat and you have edited your catalina.bat file to specify some extra JVM opts to specify the XML parser. Here's how to achieve the same using Cargo:

This shows how to add classpath elements to a Cargo container using the <dependencies> element.

  • No labels