The bnd Build aspect is capable of starting another VM to run a project (launching) and to run tests in it (testing). The testing is based on the launching model. Some examples:

bc. -runpath: org.apache.felix.main; version=latest
-runtrace: true
-runbundles: com.foo.bar;version="[1.2.3,2)", com.foo.baz; version=snapshot

This example will launch a Felix framework and then install two bundles. If a test is run, this example will use the default tester. This will launch the framework and then search for bundles that have the @Test-Cases@ header set. All class names in this header will be tested and a report can be found in the target directory.

h2. Background

As always, these facilities must work in ant, Eclipse, and other tools. As the requirements are diverse and numerous, bnd uses an extension mechanisms to allow different needs to be handled by different bundles. It also includes a default launcher and tester that have the following features:

* ee.minimum based. This means they run on minimal VMs.
* Uses JUnit 3 to also support minimal VMs
* Can launch without starting a framework. This is sometimes necessary to test launching and distributed code.
* Tester runs outside the framework, thereby not disturbing test code with extraneous bundles

However, both the launcher and tester are completely replaceable.

h2. Usage

The following properties can be used to specify the launch/test procedures.

|Option                                   |Type|Defalt|Description                                                    |
|@-runpath@                         |BUNDLES| biz.aQute.launcher|Specifies bundles on the classpath of the to be launched VM|
|@-testpath@                        |BUNDLES| biz.aQute.tester|Specifies bundles to be added to the classpath of a VM used in testing.|
|@-runvm@                           |PROPS| |Provides VM arguments for testing.|
|@-runproperties@                |PROPS| |Can be used to set general properties that are available as system properties in the launched VM|
|@-runframework@               |none or services|Is either @none@ or @services@.|
|@-runsystempackages@     |CLAUSE| |Add additional packages|
|@-runbundles@                   |BUNDLES| |A list of bundles that will be installed/updated in the launched framework.|
|@-runtrace@                        |true or false|false|If set to true will trace the launching process in detail.|

h3. @-runpath@

A list of bundle specifiers. These 'bundles' are placed on the classpath of the to be launched VM. The first bundle that specifies the @Launcher-Plugin@ manifest header is picked as the launcher.  Bundles can be specified just like the @-buildpath@ option, that is, with symbolic names and version ranges. If no launcher is specified in this list then the @biz.aQute.|auncher@ is used, which is embedded in the bnd jar. The @-runpath@ option shou|d contain the framework jar that follows the OSGi launching API. Any exports of any of the found bundles are added to the system packages that will be exported from the classpath.

h3. @-testpath@

A list of bundle specifiers. These 'bundles' are placed on the class path of the to be launched VM when a test runs. The first bundle that has the @Tester-Plugin@ manifest header is picked as the tester. If this header is empty or not specified then the default biz.aQute.tester is used.  Any exports of any of the found bundles are added to the system packages that will be exported from the classpath.

h3. @-runframework@

Specifies if the framework instance should be found with the launching API using META-INF/services or if it should not start a framework. No framework means no BundleContext availability! The no framework mode is required for certain kinds of tests.

h3. @-runsystempackages@

Packages that will be added to the org.osgi.framework.system.packages.extra property. These packages will be exported by the framework and should be available by any of the system class loader or any of the included bundles in @-runpath@ or, if applicable, @-testpath@.

This is implemented in master now. Project now has getProjectTester and getProjectLauncher. By default they return the handlers for biz.aQute.launcher and biz.aQute.junit. These can be used as examples. You can add your own jars on the -runpath (for the launcher) and -testpath (for the tester). If such a JAR has a manifest header specifying the Tester-Plugin or Launcher-Plugin then an instance of the given class is made. This instance should extend ProjectLauncher or ProjectTester. This instance can then setup the classpath, vm args, etc.

Simplest config is:

-runpath: org.apache.felix.main

The ProjectLauncher and ProjectTester base classes specify an API to control the launching. They can be used by Eclipse (e.g.) to get the VM args, classpath, etc. to obtain the settings needed in the Eclipse launcher architecture. However, the launcher and tester can work independently from this, the launcher implements a launch method and the tester implements a test method that will launch a new VM properly setup.
