Configuration
- Harald Wellmann
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. For example, the Karaf Test Container was originally created as a third-party extension. It has now been integrated into Pax Exam for a while.
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.
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 | Containers | Meaning |
|---|---|---|---|---|
pax.exam.glassfish.config.dir | file path | 3.0.0 | Embedded GlassFish | Directory containing configuration data to be copied to the GlassFish domain configuration directory. The default value is src/test/resources/glassfish-config. |
pax.exam.logging | pax-logging | 3.0.0 | Forked | pax-logging: provision Pax Logging along with Pax Exam bundles (default) |
pax.exam.osgi.unresolved.fail | false | 3.0.0 | Forked | Fail the test if one of the provisioned bundles is unresolved. The default is false. |
pax.exam.reactor.strategy | PerSuite | 3.0.0 | Forked | Sets the default reactor strategy to be used when no explicit strategy is defined in the test class. |
pax.exam.service.timeout | duration in ms | 3.0.0 | Forked | default timeout for OSGi service lookup to satisfy @Inject targets |
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 |
| Pax Exam creates a system with a Java EE container and a WAR probe. |
pax.exam.system | cdi | 3.0.0 |
| Pax Exam creates a system with a CDI container and no probe. |
pax.exam.tomcat.listener | openwebbeans | 3.0.0 | Tomcat | Pax Exam uses OpenWebBeans as CDI provider with Tomcat 7. |
pax.exam.tomcat.listener | weld | 3.0.0 | Tomcat | Pax Exam uses Weld as CDI provider with Tomcat 7. |
| pax.exam.wildfly80.* | WildFly 8.x | Proprerties for the WildFly 8.x test container. See corresponding properties named | ||
| pax.exam.wildfly90.config.dir | file path | 4.0.0 | WildFly 9.x | Directory with configuration files to be copied to Default: |
| pax.exam.wildfly90.config.overwrite | false | 4.0.0 | WildFly 9.x | Should Pax Exam overwrite existing files in Default: false |
| pax.exam.wildfly90.dist.url | artifact URL | 4.0.0 | WildFly 9.x | URL of WIldFly distribution ZIP archive. Default: |
| pax.exam.wildfly90.modules | list of artifact URLs | 4.0.0 | WildFly 9.x | Comma-separated list of URLs.of additional WildFly modules to be installed. Each URL refers to a zipped module structure which will be unpacked under |
| pax.exam.wildfly90.remote.host | hostname | 4.8.0 | WildFly 9.x | Host name of a running WIldFly server. If this is set, Pax Exam will not start an embbeded server (remote mode). Default: none (i.e. embedded mode) |
| pax.exam.wildfly90.remote.http.port | port number | 4.8.0 | WildFly 9.x | HTTP port of remote WildFly server. Default: 8080 |
| pax.exam.wildfly90.remote.mgmt.port | port number | 4.8.0 | WildFly 9.x | HTTP management port of remote WildFly server. Default: 9990 |
| pax.exam.wildfly90.remote.password | 4.8.0 | WildFly 9.x | Password for management connection to remote WildFly server. Default: none | |
| pax.exam.wildfly90.remote.username | 4.8.0 | WildFly 9.x | Username for management connection to remote WildFly server. Default: none. | |
| pax.exam.wildfly90.system.packages | 4.0.0 | WildFly 9.x | Comma-separated list of package names of JBoss Module loader system packages. Classes from these packages will be loaded from the system class loader. Each comma may be followed by whitespace. Default: | |
| pax.exam.wildfly90.system.properties | 4.0.0 | WildFly 9.x | Configuration property for system properties to be loaded before starting WildFly |
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.