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.
Jar
pom.xml
Compatibility
Version Notes
JBehave 5.0 compatibility
- Aligns Jira HTML reporter implementation to the JBehave API version 5.0
Jira plugin minimum version - 5.0.7
-
support for using JQL filter when searching for Jira issues with stories
-
ability to specify socket timeout period for REST calls
-
fix for duplicate reporting of scenarios with examples
-
improved scenario examples reporting
-
fix for project keys with numbers
-
fix for using issue filter parameters
-
fix for reporting the underlying error message returned from Jira plugin in case of Rest call issues
-
BUG: not possible to use any issue filter parameters
-
minor update for compatibility with jbehave-core 4.7 version
Jira plugin minimum version - 4.0.0
JBehave core minimum version - 4.7
-
jbehave-core dependency upgraded to version 4.7
-
supports OAuth 1.0a
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:
-DpomFile=]]>
and then in your maven project where you'd like to use the client library simply add another dependency like below
com.jbehaveforjira
java-client
1.6.3
]]>
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:
Below sections describe how to configure each of these in turn.
JiraStoryPathsFinder
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.
storyPaths() {
JiraStoryPathsFinder storyFinder = new JiraStoryPathsFinder(jiraUrl, jiraProject, jiraUsername, jiraPassword);
List 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.
storyPaths() {
JiraStoryPathsFinder storyFinder = new JiraStoryPathsFinder(jiraUrl, jiraProject, jiraUsername, jiraPassword);
storyFinder.setIssueFieldFilterParam(JiraStoryPathsFinder.IssueFilterParam.TYPE, "Bug");
List 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
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.
JiraStoryReporter
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.
JiraStepDocReporter
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.
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.
candidateSteps = embedder.stepsFactory().createCandidateSteps();
embedder.reportStepdocs(configuration(), candidateSteps);
}
}]]>