Some customers and some partners may be using ScriptRunner in order to automate some tasks and even extend the features provided by Jira.
You can also do some automation related with Xray, specially because we use Jira entities and concepts.
ScriptRunner may be used in order to access existing features or even to extend the built-in features.
Let us know if you're using also ScriptRunner and your use cases so we can improve and share them with other users.
Please note
The following scripts are provided as-is, no warranties attached. Use these scripts carefully.
Please feel free to adapt them to your needs.
Note: We don't provide support for ScriptRunner; if you have doubts concerning its usage, please contact ScriptRunner's support.
Create a Test Set or a Test Plan
Sometimes you may need to create a Test Set or a Test Plan programmatically.
The following example shows how to create a Test Plan or a Test Set based on setting the value for specific Xray custom fields.
Create a Test Execution
Sometimes you may need to create a Test Execution programmatically.
Currently there is a limitation to associate the Tests by custom field. Thus, a possible workaround using Xray's REST API is shown in the following example.
Validate requirement before alowing to make a transition
Sometimes you may need to assure that the requirement is actually OK before transitioning it to some status, or before resolving it.
The following script validates the requirement based on the tests executed for the version assigned to the requirement issue.
You can either make the validation based on the existence of failed tests (i.e. requirement status is "NOK") or, in a more complete way by making sure all of them are passing (i.e. requirement status is "OK").
Reopen/transition linked Tests to a requirement
Whenever you change the specification of a requirement, you most probably will need to review the Tests that you have already specified.
The following script tries to make a transition on all linked Tests to a requirement. You can hook it to a post-function on the transition of the requirement.
Requirement projects
Although you can go to Xray settings, in the "Requirement Projects" tab, and define a project as containing requirement issues, sometimes you may want to automate this.
The following script shows several functions that you can use to obtain the list of projects with requirement coverage enabled and to set or unset a project as being a requirements project.
Create Test Execution from Test Set issue screen
In this example, we're adding a new option in the "More" menu, by adding new "web section", "web item" ScriptRunner elements.
The following script, will create a Test Execution containing all the Tests that are part of the current Test Set.
It will set some fields as read-only.
As a mere example, you can see below how it could be setup, by creating a web section and then a webitem to trigger the actual script for creating the Test Execution.
Calculate requirement status for a certain version
Xray provides the "Requirement Status" custom field that shows the calculated coverage status for some version(s) depending on the configuration of that field in Xray's Custom Fields Preferences settings.
Sometimes you may need to evaluate the calculate requirement coverage status on some specific version, based on the executions made for that version.
A possible use case could be defining a scripted field present on the requirement issue screen that calculates the coverage status for some specific hardcoded version.
Show Tests Count for a requirement
In the following example, a "script field" is used to to show the total amount of linked Tests to a given requirement.
Show Defects Count for a requirement
In the following example, a "script field" is used to to show the total amount of linked defects to a given requirement and also provide a link to easily obtain those defects in the Issue search page.
This script field is configured to generate the output as HTML.
Configured Issue Types as being requirements or defects
If you need to obtain the issue types configured as being handled as requirements or as defects by Xray, you may use the following script.
With some additional code, you may filter this out based on the issue types available in some certain project.
Trigger a Jenkins project build from a Test Plan
In scenarios with CI implemented, you may want to trigger certain Jenkins "jobs" (i.e. project build) from a Test Plan and link back the result to Xray.
In this example, we're assuming that the list of automated tests that will be run is managed in the CI side, depending on the project configuration.
The results will be submitted back to Xray, if the project is configured to do so in Jenkins.
In order to add this option in Jira's UI, we'll need to add a custom "web item" that provide an action that will interact with a custom ScriptRunner endpoint, which will be the one doing the HTTP request to the Jenkins server, passing the Test Plan issue key. In order to submit the request to Jenkins, we need to obtain Jenkins username and respective API token along with the project specific authentication token.
Example
ScripRunner configuration
Jenkins configuration
In Jenkins, we need to generate an API token for some user, which can be done from the profile settings page.
At the project level, we need to enable remote build triggers, so we can obtain an "authentication token" to be used in the HTTP request afterwards.
The project itself is a normal one; the only thing relevant to mention is that this project is a parameterized one, so it receives a TESTPLAN variable, that in our case will be coming from Jira.
The final task submits the results linking the Test Execution to the Test Plan passed as argument.
Trigger a Jenkins project build from a Test Plan, for the Tests contained in the Test Plan
This scenario is somehow similar to the previous one, except that the list of Tests that will be run in the CI side will be based on the Tests contained in the Test Plan.
The results will be submitted back to Xray, if the project is configured to do so in Jenkins.
In order to add this option in Jira's UI, we'll need to add a custom "web item" that provide an action that will interact with a custom ScriptRunner endpoint, which will be the one doing the HTTP request to the Jenkins server, passing the Test Plan issue key. In the ScriptRunner endpoint script, we'll obtain the list of Generic Tests (we're assuming that they will came from Junit, so they have a certain syntax in the Generic Test Definition field.
In order to submit the request to Jenkins, we need to obtain Jenkins username and respective API token along with the project specific authentication token.
Example
ScripRunner configuration
Jenkins configuration
In Jenkins, we need to generate an API token for some user, which can be done from the profile settings page.
At the project level, we need to enable remote build triggers, so we can obtain an "authentication token" to be used in the HTTP request afterwards.
The project itself is a normal one; the only thing relevant to mention is that this project is a parameterized one, so it receives TESTPLAN and TESTLIST variables, that in our case will be coming from Jira.
Maven is configured in order to run just the tests identified in the TESTLIST variable, using the "-Dtest" JVM option.
The final task submits the results linking the Test Execution to the Test Plan passed as argument.
Trigger a Bamboo plan build from a Test Plan
In scenarios with CI implemented, you may want to trigger certain Bamboo "plans" (i.e. builds) from a Test Plan and link back the result to Xray.
In this example, we're assuming that the list of automated tests that will be run is managed in the CI side, depending on the plan configuration.
The results will be submitted back to Xray, if the project is configured to do so in Bamboo.
In order to add this option in Jira's UI, we'll need to add a custom "web item" that provide an action that will interact with a custom ScriptRunner endpoint, which will be the one doing the HTTP request to the Bamboo server, passing the Test Plan issue key. In order to submit the request to Bamboo we just need to use the credentials of some user.
Example
ScripRunner configuration
Bamboo configuration
The project itself is a normal one; the only thing relevant to mention is that this project is a parameterized one, so it receives a TESTPLAN variable, that in our case will be coming from Jira.
The final task submits the results linking the Test Execution to the Test Plan passed as argument.
Trigger a Bamboo plan/stage build from a Test Plan, for the Tests contained in the Test Plan
This scenario is somehow similar to the previous one, except that the list of Tests that will be run in the CI side will be based on the Tests contained in the Test Plan.
The results will be submitted back to Xray, if the project is configured to do so in Bamboo.
In order to add this option in Jira's UI, we'll need to add a custom "web item" that provide an action that will interact with a custom ScriptRunner endpoint, which will be the one doing the HTTP request to the Bamboo server, passing the Test Plan issue key. In the ScriptRunner endpoint script, we'll obtain the list of Generic Tests (we're assuming that they will came from Junit, so they have a certain syntax in the Generic Test Definition field.
In order to submit the request to Bamboo, we need to the credentials of some Bamboo user.
Example
ScripRunner configuration
Bamboo configuration
The project itself is a normal one; the only thing relevant to mention is that this project is a parameterized one, so it receives TESTPLAN and TESTLIST variables, that in our case will be coming from Jira.
Maven is configured in order to run just the tests identified in the TESTLIST variable, using the "-Dtest" JVM option.
The final task submits the results linking the Test Execution to the Test Plan passed as argument.
Extending REST API for interacting with requirement projects
In this example, we'll be creating some endpoints for obtaining the requirement projects and also for enabling or disabling requirement coverage for a certain project.
This makes use of ScriptRunner's custom REST API capabilities.
Example of requests
Obtaining all projects with requirement coverage enabled
curl -u admin:admin "http://yourjiraserver/rest/scriptrunner/latest/custom/requirementProjects"
[ { "id":10300, "key": "CALC", "name":"Calculator" }, { "id":10501, "key": "DEMO", "name":"Demonstration" } ]
Enabling requirement coverage for a project
curl -u admin:admin -X POST -d "@data.json" -H "Content-Type: application/json" "http://yourjiraserver/rest/scriptrunner/latest/custom/requirementProjects"
{ "key": "CALC" }
Disabling requirement coverage for a project
curl -u admin:admin -X DELETE "http://yourjiraserver/rest/scriptrunner/latest/custom/requirementProjects/CALC"