Integrating with your CI build

Bullet list The JBehaveForJira plugin allows Jira users to write stories directly via the Jira's web interface. Once a story is written you would then want to run it and see the execution result directly in Jira also. For this to happen you need to integrate your testing code with the Jira plugin. To do this you need to first download and install the client library of the JBehaveForJira plugin and then update your testing code to use classes from this client library instead of the default ones provided by the JBehave library. This page describes how to accomplish these two steps. At the bottom of the page there is a link to an example project which you can use as reference. 

Contents:

Example Project

Link to a complete working - example project.

1. Install plugin client library

The plugin client library is distributed in the form of a Jar file. You simply download the file using the link below and add it to the classpath of your tests. 

Maven Users

If you are using maven then you can install the downloaded file into your local repository with the help of maven's install plugin using a command like the one below:

mvn install:install-file -Dfile=<path-to-file> -DpomFile=<path-to-pomfile>

and then in your maven project where you'd like to use the client library simply add another dependency like below

        <dependency>
            <groupId>com.jbehaveforjira</groupId>
            <artifactId>java-client</artifactId>
            <version>1.6.3</version>
        </dependency>

2. Using plugin client library classes

By 'use the plugin client library' we mean that you need to use a number of classes from the client library that implement certain interfaces from the standard JBehave library instead of the ones configured by default when you use JBehave library. The classes that we need to use are:

com.jbehaveforjira.javaclient.JiraStoryLoader implements org.jbehave.core.io.StoryLoader

com.jbehaveforjira.javaclient.JiraStoryReporter implements org.jbehave.core.reporters.StoryReporter

com.jbehaveforjira.javaclient.JiraStepDocReporter implements org.jbehave.core.reporters.StepdocReporter

// and you will need the class below also which doesn't implement any interfaces from JBehave library

com.jbehaveforjira.javaclient.JiraStoryPathsFinder 

Below sections describe how to configure each of these in turn.

JiraStoryPathsFinder

Example Code

This class takes care of finding names (or paths to be more correct) of stories to run that the users have created in Jira with the help of the plugin. You use this class while overriding storyPaths method from JUnitStories or JUnitStory base class, like shown below. 

    @Override
    protected List<String> storyPaths() {

        JiraStoryPathsFinder storyFinder = new JiraStoryPathsFinder(jiraUrl, jiraProject, jiraUsername, jiraPassword);
        List<String> paths = storyFinder.findPaths();
        return paths;
    }

Optionally you can specify additional filtering criteria to look for stories attached to jira issues with particular label, or having a particular component field, etc. 

Example below shows how to narrow down the search criteria to only include Jira issues of type Bug. 

    @Override
    protected List<String> storyPaths() {

        JiraStoryPathsFinder storyFinder = new JiraStoryPathsFinder(jiraUrl, jiraProject, jiraUsername, jiraPassword);

        storyFinder.setIssueFieldFilterParam(JiraStoryPathsFinder.IssueFilterParam.TYPE, "Bug");

        List<String> paths = storyFinder.findPaths();
        return paths;
    }

The following search criteria are supported: KEY, TYPE, STATUS, RESOLUTION, COMPONENTS, AFFECTED_VERSIONS, FIX_VERSIONS and LABELS. 

Each of those parameter values can be specified as a regular expression pattern, e.g. to match issues with stories that have either 'LabelA' or 'LabelB' in their labels field one can use parameter value 'LabelA|LabelB' or to match any label that starts with 'Label' use 'Label.*' etc. 

JiraStoryLoader

Example Code

This class does the work of transporting the stories written via the plugin in Jira to the machine where the story is actually executed, be that on the developer's local machine or on your continuous integration server. You need to create an instance of this class and then set this instance on the instance of Configuration that is being used by the JBehave Embedder (or runner). If you are using the recommended MostUsefulConfiguration class from JBehave library then you can do this like in the snippet below.

	public TestRunner() {

       	MostUsefulConfiguration configuration = new MostUsefulConfiguration();

        JiraStoryLoader jiraLoader = new JiraStoryLoader(jiraUrl, jiraProject, jiraUsername, jiraPassword,
                "target/jbehave/jira_stories", true);
        configuration.useStoryLoader(jiraLoader);

		/*
		 * further code omitted for simplicity
		 */

        useConfiguration(configuration);
    }

JiraStoryReporter

Example Code

This class takes care of uploading story execution report that gets generated after a story has run back to Jira to be shown under the Story Execution Reports tab on the view issue page. You would normally still want to see report output also in the console when running a story as well as having a HTML version of the report available in Jira. For that reason you need to configure the use of this class by overriding the StoryRerportBuilder.reporterFor method and then using that report builder again in your Configuration instance that your JBehave Embedder (runner) will use, like shown below. 

    public TestRunner() {

        MostUsefulConfiguration configuration = new MostUsefulConfiguration();

        // set custom Jira HTML output format
        configuration.useStoryReporterBuilder(
                new StoryReporterBuilder() {
                    public StoryReporter reporterFor(String storyPath, org.jbehave.core.reporters.Format format) {
                        if (format.equals(org.jbehave.core.reporters.Format.HTML)) {
                            Keywords keywords = keywords();
                            return new JiraStoryReporter(new File("target", "story_report.xml"), keywords,
                                    jiraUrl, jiraProject, jiraUsername, jiraPassword, environment);
                        } else {
                            return super.reporterFor(storyPath, format);
                        }
                    }
                }
                        .withFailureTrace(true)
                        .withFormats(
                                Format.CONSOLE,
                                Format.HTML,
                                Format.STATS
                        )
        );

       	/*
		 * further code omitted for simplicity
		 */

        useConfiguration(configuration);
    }

JiraStepDocReporter

Example Code

This class takes care of uploading step pattern information back to Jira so that the user is able to use auto completion feature on step patterns and step parameters. You need to again similarly to other classes above create an instance of this class and then set it on the Configuration instance that your JBehave Embedder (runner) will use, like shown below.

    public TestRunner() {

        MostUsefulConfiguration configuration = new MostUsefulConfiguration();

        // set Jira step doc reporter
        JiraStepDocReporter stepDocReporter = new JiraStepDocReporter(jiraUrl, jiraProject, jiraUsername, jiraPassword);
        configuration.useStepdocReporter(stepDocReporter);

		/*
		 * further code omitted for simplicity
		 */       

        useConfiguration(configuration);
    }

 You will also need to ensure that you call JBehave's Embedder reportStepdocs method which performs the actual upload. This is best configured in the finally portion of the try-finally or try-catch-finally block of your test's run method, like in example below. This is to ensure that it gets called irrespective of whether your test throws any exceptions. 

    @Test
    public void run() throws Throwable {

        Embedder embedder = configuredEmbedder();

        try {
            embedder.runStoriesAsPaths(storyPaths());
        } finally {
            // report step docs
            List<CandidateSteps> candidateSteps = embedder.stepsFactory().createCandidateSteps();
            embedder.reportStepdocs(configuration(), candidateSteps);
        }
    }