Test Containers

Pax Exam provides a selection of test containers for running your system under test and your tests in a more or less isolated environment.

The test containers differ regarding the operation mode and the degree of isolation and the communication channel between the system under test and the test driver.

Selecting a Test Container

Pax Exam selects the test container at run-time by discovering a TestContainerFactory service via the Java 6 ServiceLoader. This requires exactly one such service to be present on the classpath. Thus, to select a container for your tests, just include the corresponding pax-exam-container-* JAR in your project configuration.

See Pax Exam Maven Dependencies for more details.

OSGi Containers

Each OSGi test container is able to launch an OSGi framework and to provision bundles into the running framework.

Native Container

The Native Container runs in the same VM as the driver. This is the recommended approach for most cases.

Forked Container

The Forked Container (since Pax Exam 2.4.0) uses the OSGi Framework Launch API to launch the framework in a separate VM. It provides maximum isolation and avoids classloader issues that may arise with the Native Container. The price you have pay for this is slower start-up and remote debugging.

Pax Runner Container

The Pax Runner Container uses Pax Runner to launch the framework in a separate VM. It was the first and only container in Pax Exam 1.x. The Forked Container is now the preferred solution if you require a separate VM for your system under test.

Java EE Containers

In Java EE mode, the default reactor strategy is PerSuite. Test classes should not override the default.

GlassFish Container (since 3.0.0.M1)

The GlassFish container is rather special, given that GlassFish itself runs on top of an OSGi framework and lets you deploy not only Java EE modules but also OSGi bundles.

Pax Exam's GlassFish container is an extended version of the OSGi Native Test Container. GlassFish is running in pure OSGi mode in an OSGi framework launched by Pax Exam.

The Pax Exam driver, the OSGi framework and GlassFish all run in the same Java VM, so this is an embedded usage of GlassFish. However, this setup is sigificantly different from using an Embedded GlassFish distribution, where GlassFish is contained in a shaded JAR running in a plain old Java SE environment without any OSGi support.

Thus, Pax Exam lets you test and explore hybrid applications, a mixture of traditional Java EE modules and OSGi bundles.

This is the standard lifecycle of the GlassFish container:

If the directory configured in pax.exam.server.home is empty or does not exist, GlassFish 3.1.2 Web Profile will be downloaded and installed in that directory. If present, a configuration file src/test/resources/domain.xml will be copied to glassfish/domains/domain1/config/.
Otherwise, Pax Exam works with the existing installation in that directory, throwing an exception if the GlassFish bootstrap bundle cannot be found in the expected place.
An OSGi framework is launched.
The GlassFish bootstrap bundle is installed and started, thus starting the GlassFish server.
Any additional bundles configured by the user are installed and started.
Any Java EE modules configured by the user are deployed.
In OSGi mode, a bundle probe is built, installed and started.
In Java EE mode, a WAR probe is built and deployed.
All tests contained in the probe are executed within the container.
All Java EE modules (including the WAR probe, if any) are undeployed.
GlassFish is stopped.
The OSGi framework is stopped.
The framework storage is deleted (depending on the configuration options).

Current restrictions in M1, to be removed in future milestones:

GlassFish container runs on Equinox by default. There is no configuration option to use Felix.
Since SLF4J + logback is the preferred logging solution in Pax Exam 3, the default java.util.logging of GlassFish is redirected to SLF4J. There is no way to use Pax Logging or the default GlassFish JUL.
You can only deploy WAR modules. EARs, EJB JARs or RARs are not supported.
Pax Exam uses the default GlassFish domain domain1. This cannot be changed.
Any domain-level libraries (e.g. JDBC drivers) need to be installed manually in the appropriate subdirectory of pax.exam.server.home.

CDI Containers

In CDI mode, the default reactor strategy is PerSuite. Test classes should not override the default.

OpenWebBeans Container (since 3.0.0.M1)

Pax Exam starts an org.apache.webbeans.cditest.CdiTestContainer and uses the CDI BeanManager to fill all injection points of test classes instantiated by the driver.

Weld Container (since 3.0.0.M1)

Pax Exam starts an org.jboss.weld.environment.se.WeldContainer and uses the CDI BeanManager to fill all injection points of test classes instantiated by the driver.