README.md

#JBehave OGSi

JBehave OGSi was created to able the execution of JBehave BDD like stories inside any OSGi environment. You can use it to test any kind of OSGi applications that requires to be executed inside an OSGi Container as an Eclipse RCP/SWT applications, OSGi Services, etc. It can be used with:

• Tycho or Pax-Exam in a Maven building;
• inside any IDE that provides a Junit OSGi environment as Eclipse PDE JUnit Plug-in Test;
• Interactively inside any OSGi Container that uses Felix GoGo commands;

It is composed by these components:

• jbehave-osgi-bundles/org.jbehave.osgi.core. A bundle that wraps the JBehave Core API and exposes its functionalities; This is a required bundle on all cases.

• jbehave-osgi-bundles/org.jbehave.osgi.paxexam. This is not a bundle but a jar containing some Pax-Exam integration utilities.

• jbehave-osgi-bundles/org.jbehave.osgi.logging. A bundle containing a simple implementation of the OSGi LogListener that prints outputs to console.

• jbehave-osgi-bundles/org.jbehave.osgi.web. A bundle that wraps the JBehave Web API plus Selenium and its non-OSGi dependencies. It should be used when you need to run test for web applications.

• jbehave-osgi-equinox, which supply Equinox p2 repository containing specific features.

• the minimum OSGI version needed is 4.3.

Bulding JBehave for OSGi

The JBehave-OSGi components uses different approach to being built.

All projects inside jbehave-osgi-bundles are using POM-first approach. That means that all information needed in the build is taken from the POM file and an OSGi manifest file is generated by the maven-bundle-plugin that is based on the BND tool.

Equinox components are using a MANIFEST-first approach. That mean that all information needed in the build is taken from a existent bundle manifest. So they need to be built using Eclipse Tycho.

Its not possible to run both methods together in the same Maven reactor (in the same running job), so the buildin must be done in two phases. First, all POM-first projects than the MANIFEST-first projects.

Getting the source code

1. Clone the JBehave-OSGi git repository into your machine:

   git clone git://github.com/jbehave/jbehave-osgi.git

Building POM-first projects:

2. Go to the root folder where you have cloned the project:

   cd /yourprojects/jbehave-osgi

3. Start the maven profile named bundles

   mvn clean install -P bundles

   This will install the built bundles in your local maven repository. In order to run the integration tests you can use:

   mvn clean install -P bundles -Dpax.exam.framework=equinox-kepler (run tests inside an Equinox Kepler container) or

   mvn clean install -P bundles -Dpax.exam.framework=felix (run tests inside a Felix container)

Building the MANIFEST-first projects:

4. Go to root folder where you have cloned the project

   cd /yourprojects/jbehave-osgi

5. Start the maven profile named distribution-equinox:

   mvn clean verify -P distribution-equinox

This will create the p2 repository using the Luna repository inside the the folder /org.jbehave.osgi.equinox.p2/target/repository.

In case you need to copy the generated p2 folder to another place, you can use:

mvn clean verify -P distribution-equinox -Djbehave.distr.p2.location=/home/jbehave/p2

This will generate the P2 repository in the target folder and then will copy the contents of repository folder to the /home/jbehave/p2 folder.

The generated P2 repository will contain Jbehave-OSGi features and almost all bundles dependencies needed for JBehave-OSGi to be executed on Equinox.

Setup Eclipse Development Environment for the JBehave-OSGi

In order to work with the source code we recommend you to use the latest Eclipse with M2e plug-in (plus Tycho extension) installed.

After have started Eclipse:

1. Preferably, choose a new workspace with a proper name. eg: jbehave-osgi

2. Import the projects using the Maven Import into the workspace. After the import, you should see compile errors due to missing dependencies. That is normal since you don't setup the target platform yet.

3. Setup the Target Platform of the new workspace:

   • Go to /jbehave-osgi/jbehave-osgi-equinox/eclipse__targets folder and open the target file proper for your environment. eg: jbehave-osgi-kepler_local.target. The eclipse will resolve its contents.
   • After Eclipse has been resolved the target definition file click in the Set as Target Platform link. Eclipse must resolve all compile errors.

Working with the examples

We provided some OSGi projects that exemplify how you could use JBehave-OSGi.

Each provided example has an Eclipse launcher file that will facilitate their execution.

1. Go to menu "Run", then "Run Configurations..."

2. Select one of the launcher files that start with the 'Example-' word and watch the results in console view.

JBehave-OSGi : Interactive Mode

JBehave-OSGi provides a way for you to execute your stories inside an OSGi container in an interactive way.

What interactive means?

It means that after you have started your OSGi container and have installed the org.jbehave.osgi.core bundle then whenever you install and activate a bundle whose manifest file contains the JBehave-StoryRunner and/or JBehave-StepFactory headers then one or more StoryRunnerService and InjectableStepsFactoryService instances will be created depending on the values specified. This way you can use the provided GoGo commands in the console to interact with those registered services.

• In case of you are using Equinox you can install the org.jbehave.osgi.equinox.commands bundle that provides an auto-completion feature.

Take a look in the org.jbehave.osgi.examples.trader.pomfirst.itests project manifest:

Manifest-Version: 1.0
Bundle-ActivationPolicy: lazy
Bundle-ManifestVersion: 2
Bundle-Name: JBehave OSGi :: POM-First Trader Example : JBehave Story an
d Steps Bundle
Bundle-SymbolicName: org.jbehave.osgi.examples.trader.pomfirst.itests
Bundle-Version: 1.0.0.SNAPSHOT
Export-Package: org.jbehave.osgi.examples.trader.pomfirst.itests.convert
 ers;version="1.0.0.SNAPSHOT",org.jbehave.osgi.examples.trader.pomfirst.
 itests.embedders;uses:="org.jbehave.osgi.examples.trader.pomfirst.itest
 s.steps1,org.osgi.framework";version="1.0.0.SNAPSHOT",org.jbehave.osgi.
 examples.trader.pomfirst.itests.steps1;uses:="org.osgi.framework";versi
 on="1.0.0.SNAPSHOT",org.jbehave.osgi.examples.trader.pomfirst.itests.st
 eps2;version="1.0.0.SNAPSHOT",org.jbehave.osgi.examples.trader.pomfirst
 .itests.stories;version="1.0.0.SNAPSHOT"
Import-Package: org.apache.commons.lang;version="[2.6,3)",org.junit,org.
 osgi.framework;version="[1.6,2)",com.thoughtworks.paranamer
JBehave-StepFactory: stepFactory1:org.jbehave.osgi.examples.trader.pomfi
 rst.itests.steps1.*,stepFactory2:org.jbehave.osgi.examples.trader.pomfi
 rst.itests.steps2.*
JBehave-StoryRunner: org.jbehave.osgi.examples.trader.pomfirst.itests.em
 bedders.TraderAnnotatedPathRunnerOsgi,org.jbehave.osgi.examples.trader.
 pomfirst.itests.embedders.TraderAnnotatedPathRunnerOsgiWithStepFactoryS
 erviceFilter,org.jbehave.osgi.examples.trader.pomfirst.itests.embedders
 .TraderAnnotatedPathRunnerOsgiWithStepFactoryServiceFilter2
Require-Bundle: org.jbehave.osgi.core;bundle-version="[1.0.0,2.0.0)",org
 .hamcrest.integration;bundle-version="1.3.0"

The header JBehave-StoryRunner tells to JBehave-OSGi that it must create one StoryRunnerService instance for each specified class. Those classes have two requirements: They must be annotated with JBehave's @Configure and @UsingPaths annotations. The @Embedder is optional.

The header JBehave-StepFactory tells to JBehave-OSGi that is must create one InjectableStepsFactoryService instance for every group of step classes specified. Each group must have one identifier and one or more step classes.

Running the test examples using JBehave-OSGi interactive commands locally

We provided three Eclipse launchers that exemplify its use:

• JBehave OSGi - Interactive run example - local console. This one is to be used inside the Eclipse IDE. its input and output is handled by the internal console.

• JBehave OSGi - Interactive run example - remote console telnet.launch. This one is to be used outside eclipse using a telnet connection.

• JBehave OSGi - Interactive run example - remote console telnet + debug. This one is to be used outside eclipse using a telnet connection and adds a way to debug the code inside the IDE.

Let's see how to use the first one:

1. Go to menu "Run", then "Run Configurations..."

2. Select JBehave OSGi - Interactive run example - local console.

3. After Equinox have started you can test JBehave OSGi Services with this command:

   osgi> help -scope jbehave

You should see the JBehave-OSGi Interactive help:

str - Manage registered JBehave's StoryRunner services.
      A short version of storyRunner command.
   scope: jbehave
   options:
      -o, --output   sets the reporting output directory only for one run. [optional]
   parameters:
      String   StoryRunner services actions are:(list - all registered services| details | output | run | stories)
      StoryRunnerService[]   One or more registered StoryRunner services.

str - Manage registered JBehave's StoryRunner services.
      Without parameter is like as 'str list'
   scope: jbehave

stf - Manage registered JBehave's InjectableStepsFactory services.
      Without parameter is like as 'stf list'
   scope: jbehave

stf - Manage registered JBehave's InjectableStepsFactory services.
      A short version of stepsFactory command.
   scope: jbehave
   parameters:
      String   StepsFactory services actions are:(list - all registered services| details)
      InjectableStepsFactoryService[]   One or more registered StepFactory services

stepsFactory - Manage registered JBehave's InjectableStepsFactory services.
   scope: jbehave
   parameters:
      String   StepsFactory services actions are:(list - all registered services| details)
      InjectableStepsFactoryService[]   One or more registered StepFactory services

storyRunner - Manage registered JBehave's StoryRunner services.
   scope: jbehave
   options:
      -o, --output   sets the reporting output directory only for one run. [optional]
   parameters:
      String   StoryRunner services actions are:(list - all registered services| details | output | run | stories)
      StoryRunnerService[]   One or more registered StoryRunner services.

4. List the StoryRunnerService instances that was registered:

   osgi> str or osgi> str list

you will see that one StoryRunnerService instance was registered for the bundle org.jbehave.osgi.examples.trader.equinox.it:

StoryRunners: 
    1) org.jbehave.osgi.examples.trader.it.embedder.TraderAnnotatedPathRunnerOsgi <org.jbehave.osgi.examples.trader.equinox.it>

5. List the InjectableStepsFactoryService instances registered:

   osgi> stf or osgi> stf list

you will see that two InjectableStepsFactoryService instances was registered:

StepsFactories: 
    1) stepFactoryDef <org.jbehave.osgi.examples.trader.equinox.it.steps1:1.0.0.qualifier>
    2) default <org.jbehave.osgi.examples.trader.equinox.it.steps2:1.0.0.qualifier>

6. Run the StoryRunner service:

   osgi> str run 1 or osgi> storyrunner run org.jbehave.osgi.examples.trader.it.embedder.TraderAnnotatedPathRunnerOsgi