Configuration
Pax Exam uses a combination of different configuration mechanisms:
- the classpath
- configuration properties
- Java configuration options in source code
Classpath configuration
Classpath configuration works by selecting one of a given set of alternative Pax Exam components and including it on the classpath of your project. A number of Pax Exam components provide service implementations using META-INF/services marker files. This approach is used to select the test container for your tests.
From the OSGi perspective, the Java SE ServiceLoader appears like a poor man's service registry, but not all of Pax Exam is pure OSGi: a Pax Exam driver is a Java SE component that instantiates a test container which in turn launches an OSGi framework.
Using this approach, it is possible to implement new test containers without modifying the rest of Pax Exam. The Karaf Test Container is an example of a third-party container for Pax Exam.
Configuration properties
The standard way of configuring a Pax Exam test is a @Configuration method in the test class itself. In addition, Pax Exam reads some configuration information from an optional properties file (since 2.4.0).
This mechanism is designed to handle the following use cases:
- machine-dependent configuration that should not be part of the test code
- bootstrap configuration that needs to take effect before Pax Exam evaluates
@Configurationmethods.
Property lookup
- If the system property
pax.exam.configurationis set, Pax Exam regards the value as a property file URL. - Otherwise, Pax Exam uses the URL of the classpath resource
/exam.propertiesas fallback. - If the URL resolves to a stream, Pax Exam loads properties from the given stream.
- When looking up a given property, system properties take precedence over loaded properties.
Supported properties
Property name |
Property value |
since |
Meaning |
|---|---|---|---|
pax.exam.server.home |
file path |
3.0.0.M1 |
The installation directory of the server used by the current Pax Exam Java EE test container. |
pax.exam.system |
test |
2.4.0 |
Pax Exam creates a system with an OSGi container, a bundle probe and a standard set of options (compatible with Pax Exam <= 2.3.0). |
pax.exam.system |
default |
2.4.0 |
Pax Exam creates a system with an OSGi container, a bundle probe and no preset options. |
pax.exam.system |
javaee |
3.0.0.M1 |
Pax Exam creates a system with a Java EE container and a WAR probe. |
pax.exam.system |
cdi |
3.0.0.M1 |
Pax Exam creates a system with a CDI container and no probe. |
pax.exam.tomcat.listener |
openwebbeans |
3.0.0.M3 |
Pax Exam uses OpenWebBeans as CDI provider with Tomcat 7. |
pax.exam.tomcat.listener |
weld |
3.0.0.M3 |
Pax Exam uses Weld as CDI provider with Tomcat 7. |
pax.exam.system = test is the default when the property is not set explicitly. In other words, default is not the default value. This is rather confusing, but reflects the current implementation, where the first case corresponds to PaxExamRuntime.createTestSystem() and the second case corresponds to DefaultExamSystem.create().
Please be prepared for breaking changes in future releases that will help to make this configuration clearer.
Using pax.exam.system = default, it is entirely your own responsibility to provision all of Pax Exam's own bundles and their dependencies to the test container.
See Pax Exam's own RegressionConfiguration. In this configuration, the standard Pax Logging bundle is replaced by SLF4J and logback.
Configuration options
Pax Exam is mainly configured by options specified in a fluent Java API syntax. These options are documented in detail in a separate article.