1. Introduction
Xray is the fastest growing cloud app for Jira, and it’s a full-featured tool that lives inside and seamlessly integrates with Jira. With Xray, managers can enhance agile boards by tracking the requirement status and test execution progress in real-time. It can also generate advanced reporting that can be exported to Docx, xlsx, or pdf using Xporter.
A proper test management tool will help you meet your testing requirements in different environments on any device, in any browser, and at any testing stage. Xray for Jira also provides traceability between requirements, tests, and defects while assisting with the root cause analysis that identifies the real cause of a problem or a bug. Tests can be manual or automated. With automated tests, you need to choose your test automation platforms like Cucumber, Robot Framework, or Selenium amongst others, and connect it with Xray using the REST API. (Reference: Xray)
GitLab – is a GitHub-like service that organizations can use to provide internal management of git repositories. It is a self-hosted Git-repository management system that keeps the user code private and can easily deploy the changes of the code.
Features:
- GitLab hosts your (private) software projects for free.
- GitLab is a platform for managing Git repositories.
- GitLab offers free public and private repositories, issue-tracking, and wikis.
- GitLab is a user friendly web interface layer on top of Git, which increases the speed of working with Git.
GitLab provides its own Continuous Integration (CI) system for managing the projects and provides a user interface along with other features of GitLab.
2. GitLab Integration with Xray
GitLab Integration with Xray Cloud is easy to set up, but there is not available plugin yet.
For that reason, Xray provides a full REST API, and with that REST API, there is a possibility to interact with Xray. There are two ways:
- JUnit
- Cucumber (two ways):
- Standard workflow (Xray as master)
- VCS workflow (Git as master)
This time we will try to use the Cucumber example.
2.1 Pre-settings in Xray
As we mentioned previously Xray supports integration with Continuous Integration tools. In this sample we have prepared automated tests, so we will use a test automation platform like Cucumber, and connect it with Xray (cloud instance of Jira set up with Xray plugin) using its REST API. So the first step will be creating an issue with issue type ‘Test’ as in Image 1:
So the next step is adding Gherkin reference in the Scenario section, more precisely in ‘Test Details’ we are choosing Cucumber, and in the ‘Scenario’ section we are writing our Cucumber Test scenario, Image 2:
Cucumber feature files can be exported from XRay UI, Figure 3:
And there is another way of exporting through the command line and executing externally, with this curl command for exporting the features for the above issue:
curl -H “Content-Type: application/json” –output features.zip -X GET -H “Authorization: Bearer ${token}” https://xray.cloud.xpand-it.com/api/v1/export/cucumber?keys= GIT-4The following feature file is exported from the sample above:
Feature: SignIn - Cucumber Test
@TEST_GIT-4
Scenario: SignIn - Cucumber Test
Given User is on Home Page
When User Navigate to SignIn Page
And User enters valid UserName and valid Password
Then User should be successfully logged in and see MyAccount
Then End test by closing the window
2.2 GitLab Settings
The first step here is to get an account in GitLab, so for that reason, we will navigate to the Gitlab Registration page, where we can start a free trial, Image 4:
The next step is creating our New Project on GitLab, by choosing ‘Create blank project’ and adding a name for that project like in Image 5:
Our test scenario should explain managing the specification of Cucumber Scenarios. For that reason, we need to extract specifications from Jira run it in GitLab, and submit the results back to JIRA with GitLab.
We will achieve that by creating the GitLab configuration file .gitlab-ci.yml (Image 6), which contains the definition of the build steps, including extracting the cucumber specification from Xray, running the automated test, and submitting the results back.
In this .gitlab-ci.yml file we are using variables that are defined in the variables section in the CI/CD project-level settings as secret values. Client_id and client_secret are credential values needed for authorization on our JIRA instance. Cucumber_keys variable is the name of the issue in the JIRA where the feature file is exported from.
image: markhobson/maven-chrome:jdk-11
stages:
- build
- test
variables:
MAVEN_OPTS: "-Dmaven.repo.local=.m2/repository"
cache:
paths:
- .m2/repository/
- target/
build:
stage: build
script:
- mvn compile
test:
stage: test
script:
- |
export token=$(curl -H "Content-Type: application/json" -X POST --data "{\"client_id\": \"$client_id\", \"client_secret\": \"$client_secret\" }" https://xray.cloud.xpand-it.com/api/v1/authenticate| tr -d '"')
curl -H "Content-Type: application/json" --output features/features.zip -X GET -H "Authorization: Bearer ${token}" "https://xray.cloud.xpand-it.com/api/v1/export/cucumber?keys=$cucumber_keys"
mkdir -p features
rm -f features/*.feature
unzip -o features/features.zip -d features/
mvn test -DCucumber.options='--glue src/test/java/'
curl -H "Content-Type: application/json" -X POST -H "Authorization: Bearer ${token}" --data @target/cucumber.json "https://xray.cloud.xpand-it.com/api/v1/import/execution/cucumber"
And finally, we can see that the cucumber.json result output file, generated by the Test runner class, is used to be sent back to the Xray issue and will create Test Execution type issue with the automatically generated name “Execution results $timestamp” and will be related to the Cucumber Test that we pulled the feature file (“GIT-4”) as on Image 7:
Conclusion
Xray for Jira project management tool is a highly recommended plugin for all integration developers because of the easy usage and possibility for integration with a lot of applications/tools. One of the abilities of Xray is integration with GitLab and its Continuous Integration tools, thanks to the Xray REST API. With such integration, we succeed to track all the changes, modifications, or regressions in one place. By creating an Xray issue, for example with Gherkin kind reference, we can automatically run and have execution status updated with minimal or no human effort. The automation process is done by GitLab pipeline by pulling the features, executing the test, and sending the results back to the Xray – by creating a Test Execution for the related issue.
If you want to discuss the integration of Xray with GitLab, you can contact us at sales@iwconnect.com.
