A Pax Exam test is configured either by means of configuration methods annotated by @Configuration
with return type Option[]
, or by a ConfigurationFactory
, see next section.
Option
is nothing but a marker interface. Options are created by static methods in org.ops4j.pax.exam.CoreOptions
. Pax Exam users should never directly work with classes implementing Option
.
Options can be container-specific. In particular, there is a large number of options for the Pax Runner Container which directly correspond to Pax Runner command line arguments. These options are just syntactic sugar for rawPaxRunnerOption(arg)
.
Pax Exam containers log a warning for each unsupported option type. Make sure to set up logging correctly to avoid missing these warnings.
Roughly speaking, options can be categorized into
Provisioning options are used to provision bundles to the OSGi framework under test. Usually, each provisioning option (e.g. bundle()
) provisions a single bundle, but there are some convenience options (e.g. junitBundles()
) which provision groups of related bundles.
Property options are used to set system properties, OSGi framework properties or VM arguments for a forked Java Virtual Machine, where applicable.
Framework selection options can be used to define the OSGi framework(s) for running the tests. This does not apply to the Native Container, where the OSGi framework is determined by the first FrameworkFactory
found on the classpath by means of Java SE 6 service lookup.
Pax Runner options wrap Pax Runner command line arguments, as you may have guessed, and they only apply to the Pax Runner Container.
As of Pax Exam 2.3.0, this page fully documents all options for the Native Test Container. Pax Runner Test Container options are now considered legacy and most of these are likely to be deprecated and dropped in future releases of Pax Exam. Documenting these options would require digging into the (somewhat outdated and incomplete) Pax Runner documentation and/or the source code. This is not very likely to happen, unless someone volunteers to do it. |
Containers: Pax Runner
allEquinoxVersions() |
Containers: Pax Runner
allFelixVersions() |
Containers: Pax Runner
allFrameworks() |
Containers: Pax Runner
allFrameworksVersions() |
Containers: Pax Runner
allKnopflerfishVersions() |
Containers: Pax Runner
autoWrap() |
Alternatively, you can use wrapBundle()
for individual JARs, which also works for the Native Container.
Containers: Pax Runner
Containers: Pax Runner
Containers: Native, Pax Runner
org.osgi.framework.bootdelegation
framework property.
bootDelegationPackage("sun.*") |
Containers: Native, Pax Runner
org.osgi.framework.bootdelegation
framework property.
bootDelegationPackages( "sun.*", "com.sun.*" ) |
Containers: Native, Pax Runner
You can provision any bundle by its URL (any known protocols are accepted):
bundle("http://repository.ops4j.org/maven2/org/ops4j/pax/url/pax-web-service/0.5.1/pax-web-service-0.5.1.jar") |
bundle("file:/home/adreghiciu/development/pax-web-service-0.5.1.jar") |
Containers: Native, Pax Runner
cleanCaches() |
cleanCaches(true) |
cleanCaches(false) |
The last case is equivalent to keepCaches()
Containers: Pax Runner
Containers: Native, Pax Runner
public static Option baseBundles() { return combine( mavenBundle("com.example.foo", "common", "1.0.0"), mavenBundle("com.example.foo", "util", "1.0.0")); } |
Containers: Pax Runner
Containers: Pax Runner
customFramework("equinox", "http://download.eclipse.org/equinox/drops/S-3.8M1-201108031800/org.eclipse.osgi_3.8.0.v20110726-1606.jar", "Equinox 3.8M1") |
This only works for unknown versions of known frameworks (i.e. Equinox, Felix or Knopflerfish), but not for unknown frameworks.
Containers: Pax Runner
Containers: Pax Runner
Containers: Native, Pax Runner
Containers: Pax Runner
equinox() |
equinox().version("1.0.4") |
equinox().version("3.5.0"), equinox().version("3.6.2") |
Containers: Pax Runner
Containers: Pax Runner
felix() |
felix().version("1.0.4") |
felix().version("1.0.4"), felix().version("1.4.0") |
Containers: Pax Runner
Containers: Native, Pax Runner
frameworkStartLevel(6) |
Containers: Native, Pax Runner
jmockBundles() |
Containers: Native, Pax Runner
junitBundles() |
The current default is org.junit:com.springsource.org.junit:4.9.0
which embeds the Hamcrest dependency.
This option is recommended when using the JUnit driver. If you wish to use a different version, replace this option by any other provisioning option specifying an explicit version of an OSGified JUnit artifact.
Containers: Native, Pax Runner
keepCaches() |
This is equivalent to cleanCaches(false)
.
Containers: Pax Runner
knopflerfish() |
knopflerfish().version("2.2.0") |
knopflerfish().version("2.1.1"), knopflerfish().version("2.2.0") |
Containers: Pax Runner
Containers: Pax Runner
Containers: Native, Pax Runner
maven().groupId("postgresql").artifactId("postgresql").version("8.4-701.jdbc4") |
maven("postgresql", "postgresql", "8.4-701.jdbc4") |
maven().groupId("postgresql").artifactId("postgresql") |
maven("postgresql", "postgresql") |
Containers: Native, Pax Runner
You can provision a bundle in terms of its Maven coordinates. Pax Exam uses the official Maven APIs to resolve an artifact from its coordinates from any of the repositories configured in Maven settings or by other Pax Exam options.
This option makes use of Mvn Protocol url protocol handler.
mavenBundle().groupId("org.ops4j.pax.web").artifactId("pax-web-service").version("0.5.1") |
mavenBundle().groupId("org.ops4j.pax.web").artifactId("pax-web-service").version("0.5.2-SNAPSHOT") |
mavenBundle().groupId("org.ops4j.pax.web").artifactId("pax-web-service") |
This will make maven url handler to search for the latest released version.
mavenBundle().groupId("org.ops4j.pax.web").artifactId("pax-web-service").version("[0.1.0,1.0.0)") |
This will make maven url handler to search for the highest released version between 0.1.0 (inclusive) and 1.0.0 (exclusive).
All provisioning options (as the ones above) support setting up of:
mavenBundle().groupId("org.ops4j.pax.web").artifactId("pax-web-service").noStart() |
noStart()
is used then the bundle will not be started. By default ( = noStart()
not used) the bundle will be started.mavenBundle().groupId("org.ops4j.pax.web").artifactId("pax-web-service").update() |
update()
is used then the bundle will be updated, meaning that the content of the bundle will be re-read from the original source (url). By default ( = update()
not used) the bundle will not be updated, meaning that a cached bundle will be used from a previous run. There is one exception to this rule. If the provisioning option is a Maven bundle and the version is a SNAPSHOT version, by default the bundle will be updated automatically even if the update()
is not used.update()
method.mavenBundle().groupId("org.ops4j.pax.web").artifactId("pax-web-service").startLevel(10) |
startLevel(<level>)
the bundle will be started at the specified start level, in this example the start level of the bundle will be 10.Legacy option, not currently supported.
Containers: Native, Pax Runner
mockitoBundles() |
Containers: Pax Runner
Containers: Native, Pax Runner
Instead of using a URL, you can directly provision a bundle from an input stream. The stream content will be copied to the install area of the framework. This option is particularly useful in combination with Tinybundles.
provision(inputStream) |
provision(is1, is2, is3) |
Containers: Pax Runner
Containers: Pax Runner
Containers: Pax Runner
Containers: Pax Runner
Containers: Pax Runner
Containers: Pax Runner
Containers: Pax Runner
Containers: Pax Runner
Containers: Pax Runner
Containers: Pax Runner
Containers: Pax Runner
Containers: Native, Pax Runner
org.osgi.framework.system.packages
framework property.
systemPackage("javax.rmi") |
Containers: Native, Pax Runner
org.osgi.framework.system.packages
framework property.
systemPackages("javax.naming", "javax.rmi") |
Containers: Native, Pax Runner
System.setProperty()
in the running VM, which may or may not have the same effect as a -Dkey=value
VM argument for some properties defined in the JRE API.
systemProperty("org.osgi.service.http.port").value("8080") |
systemProperty("org.osgi.service.http.port").value("8080"), systemProperty("org.osgi.service.http.port.secure").value("8443") |
Containers: Native, Pax Runner
Specifies a timeout in milliseconds which is used by Pax Exam when waiting for a service to become available or for the framework to reach the requested start level
systemTimeout(5000) |
The default value is 3 minutes.
Containers: Native, Pax Runner
A synonym for bundle()
.
Containers: Pax Runner
Specifies an argument passed to the Java VM spawned by Pax Runner, e.g.
vmOption("-Xmx512M") vmOption("-Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=5005") |
vmOption("-Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=5005") |
Containers: Pax Runner
vmOptions("-Xmx1G", "-XX:MaxPermSize=128M") |
Containers: Pax Runner
Containers: Native, Pax Runner
There might be cases when you have to use certain options only under specific conditions as for example you would like to enable debugging only when you set a system property. In order to fulfill such an requirement you can use optional composite option as in the following example:
@Configuration public static Option[] configure() { return options( when( Boolean.getBoolean( "isDebugEnabled" ) ).useOptions( vmOption( "-Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=5005" ), timeout( 0 ))); } |
In the above example the vmOption
and timeout
options will be included only when there is a system property named isDebugEnabled
with a value of true
.
If you are using Maven you can then use the following to switch the debug options on:
mvn install -DisDebugEnabled=true |
The condition is not limited to just system properties. You can use any expression that evaluates to a boolean
or define your own condition.
Containers: Native, Pax Runner
workingDirectory("/home/hwellmann/pax-exam") |
By default, Pax Exam will use a temporary directory created in ${java.io.tmpdir
}.
Containers: Native, Pax Runner
In some cases you may have a standard JAR that you may need to make OSGi compatible in order to deploy it. You can do this on the fly by using the wrapping provisioning option that makes use of Wrap Protocol url protocol handler.
wrappedBundle("http://repo2.maven.org/maven2/javax/servlet/servlet-api/2.5/servlet-api-2.5.jar") |
In this case the servlet api specified as a plain url will be downloaded and transformed into an OSGi bundle by adding the necessary metadata.
wrappedBundle(mavenBundle().groupId("javax.servlet").artifactId("servlet-api").version("2.5")) |
In this case the same transformation will be applied but downloading (resolving the artifact) will use the maven option explained above.
The wrappedBundle() option supports a number of additional arguments which are specified in fluent API syntax, e.g.
wrappedBundle(mavenBundle("javax.servlet", "servlet-api","2.5") .bundleSymbolicName("javax.servlet.api") .bundleVersion("2.5") |
Bundle-SymbolicName
of the wrapped bundle
bundleSymbolicName(String) |
Bundle-Version
of the wrapped bundle
bundleVersion(String) |
exports(String...) |
imports(String...) |
instructions(String...) |
wrappedBundle(mavenBundle("junit", "junit-dep", "4.8.1")).exports("*;version=4.8.1")); |