JBEHAVE-829: add example how the executable can be built

examples/executable-jar/Notes.txt

@@ -0,0 +1,19 @@
+A simple example project showing how to put jbehave, your code and the
+stories inside a executable/runnable jar.
+
+The package target creates a jar file containing all classes from
+jbehave and its dependecies that can be run with
+
+jar -jar jbehave-executable-jar-example-<VERSION>-jar-with-dependencies.jar,
+this way the tests do not have any dependencies except java itself.
+
+Currently there is no way to search for stories inside the classpath,
+which means that you have to list the story files explicitly in the
+storyPaths method, either by creating a list directly or reading a
+file.
+
+When building the project with Maven, the story paths in the example
+are correct, when using the Export as Runnable Jar option in Eclipse,
+the paths change from e.g org/jbehave/path to resources/org/jbehave/path
+so the paths in the code have to changed accordingly when you want to
+use Eclipse export.

examples/executable-jar/pom.xml

@@ -0,0 +1,64 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
+  <modelVersion>4.0.0</modelVersion>
+  <parent>
+    <groupId>org.jbehave</groupId>
+    <artifactId>jbehave-examples</artifactId>
+    <version>3.7-SNAPSHOT</version>
+  </parent>
+  <artifactId>jbehave-executable-jar-example</artifactId>
+  <name>JBehave Executable-jar Example</name>
+  <build>
+    <resources>
+      <resource>
+        <directory>src/main/java</directory>
+        <filtering>true</filtering>
+        <excludes>
+          <exclude>**/*.java</exclude>
+        </excludes>
+      </resource>
+      <resource>
+        <directory>src/main/resources</directory>
+        <filtering>true</filtering>
+      </resource>
+    </resources>
+    <pluginManagement>
+      <plugins>
+        <plugin>
+          <groupId>org.apache.maven.plugins</groupId>
+          <artifactId>maven-compiler-plugin</artifactId>
+          <version>2.4</version>
+          <configuration>
+            <source>1.5</source>
+            <target>1.5</target>
+          </configuration>
+        </plugin>
+      </plugins>
+    </pluginManagement>
+    <plugins>
+      <plugin>
+        <artifactId>maven-assembly-plugin</artifactId>
+        <configuration>
+          <descriptorRefs>
+            <descriptorRef>jar-with-dependencies</descriptorRef>
+          </descriptorRefs>
+          <archive>
+            <manifest>
+              <mainClass>org.jbehave.examples.executable_jar.MyStories</mainClass>
+            </manifest>
+          </archive>
+        </configuration>
+        <executions>
+          <execution>
+            <id>make-my-jar-with-dependencies</id>
+            <phase>package</phase>
+            <goals>
+              <goal>single</goal>
+            </goals>
+          </execution>
+        </executions>
+      </plugin>
+    </plugins>
+  </build>
+</project>

examples/executable-jar/src/main/java/org/jbehave/examples/executable_jar/MyStories.java

@@ -0,0 +1,83 @@
+package org.jbehave.examples.executable_jar;
+
+import java.text.SimpleDateFormat;
+import java.util.Arrays;
+import java.util.List;
+
+import org.jbehave.core.Embeddable;
+import org.jbehave.core.configuration.Configuration;
+import org.jbehave.core.configuration.MostUsefulConfiguration;
+import org.jbehave.core.i18n.LocalizedKeywords;
+import org.jbehave.core.io.CodeLocations;
+import org.jbehave.core.io.LoadFromClasspath;
+import org.jbehave.core.junit.JUnitStories;
+import org.jbehave.core.model.ExamplesTableFactory;
+import org.jbehave.core.parsers.RegexStoryParser;
+import org.jbehave.core.reporters.StoryReporterBuilder;
+import org.jbehave.core.steps.InjectableStepsFactory;
+import org.jbehave.core.steps.InstanceStepsFactory;
+import org.jbehave.core.steps.ParameterConverters;
+import org.jbehave.core.steps.ParameterConverters.DateConverter;
+import org.jbehave.core.steps.ParameterConverters.ExamplesTableConverter;
+import org.jbehave.examples.executable_jar.steps.MySteps;
+
+import static org.jbehave.core.reporters.Format.CONSOLE;
+import static org.jbehave.core.reporters.Format.HTML;
+import static org.jbehave.core.reporters.Format.TXT;
+import static org.jbehave.core.reporters.Format.XML;
+
+/**
+ * <p>
+ * {@link Embeddable} class to run multiple textual stories via JUnit.
+ * </p>
+ * <p>
+ * Stories are specified in classpath and correspondingly the {@link LoadFromClasspath} story loader is configured.
+ * </p> 
+ */
+public class MyStories extends JUnitStories {
+
+    public MyStories() {
+        configuredEmbedder().embedderControls().doGenerateViewAfterStories(true).doIgnoreFailureInStories(true)
+        .doIgnoreFailureInView(true).useThreads(2).useStoryTimeoutInSecs(60);
+    }
+
+    @Override
+    public Configuration configuration() {
+        Class<? extends Embeddable> embeddableClass = this.getClass();
+        // Start from default ParameterConverters instance
+        ParameterConverters parameterConverters = new ParameterConverters();
+        // factory to allow parameter conversion and loading from external resources (used by StoryParser too)
+        ExamplesTableFactory examplesTableFactory = new ExamplesTableFactory(new LocalizedKeywords(), new LoadFromClasspath(embeddableClass), parameterConverters);
+        // add custom converters
+        parameterConverters.addConverters(new DateConverter(new SimpleDateFormat("yyyy-MM-dd")),
+                new ExamplesTableConverter(examplesTableFactory));
+        return new MostUsefulConfiguration()
+        .useStoryLoader(new LoadFromClasspath(embeddableClass))
+        .useStoryParser(new RegexStoryParser(examplesTableFactory)) 
+        .useStoryReporterBuilder(new StoryReporterBuilder()
+        .withCodeLocation(CodeLocations.codeLocationFromClass(embeddableClass))
+        .withDefaultFormats()
+        .withFormats(CONSOLE, TXT, HTML, XML))
+        .useParameterConverters(parameterConverters);
+    }
+
+    @Override
+    public InjectableStepsFactory stepsFactory() {
+        return new InstanceStepsFactory(configuration(), new MySteps());
+    }
+
+    /*
+     * since the files inside a jar in the classpath currently cannot be searched, you
+     * have to list the paths for the stories directly.
+     */
+
+    @Override
+    protected List<String> storyPaths() {
+        return Arrays.asList("org/jbehave/examples/executable_jar/stories/jar.story",
+                "org/jbehave/examples/executable_jar/stories/jar2.story");
+    }
+
+    public static void main(String[] args) throws Throwable {
+        new MyStories().run();
+    }
+}

examples/executable-jar/src/main/java/org/jbehave/examples/executable_jar/steps/MySteps.java

@@ -0,0 +1,19 @@
+package org.jbehave.examples.executable_jar.steps;
+
+import org.jbehave.core.annotations.Alias;
+import org.jbehave.core.annotations.Then;
+import org.jbehave.core.annotations.When;
+
+public class MySteps {
+    @When("I run this as executable jar")
+    @Alias("this")
+    public void whenIRunThisAsExecutableJar() {
+        // we don't do anything
+    }
+
+    @Then("this story should run")
+    @Alias("that")
+    public void thenThisStoryShouldRun() {
+        // we don't do anything
+    }
+}

examples/executable-jar/src/main/resources/org/jbehave/examples/executable_jar/stories/jar.story

@@ -0,0 +1,5 @@
+Scenario: This should work as executable jar
+
+When I run this as executable jar
+Then this story should run
+

examples/executable-jar/src/main/resources/org/jbehave/examples/executable_jar/stories/jar2.story

@@ -0,0 +1,5 @@
+Scenario: This should work as executable jar
+
+When this
+Then that
+

examples/pom.xml

@@ -16,6 +16,7 @@
   </properties>
 
   <modules>
+    <module>executable-jar</module>
     <module>gameoflife</module>
     <module>groovy</module>
     <module>scala</module>