Image Modified

...

The installation is made manually. For more information on how to install add-ons, please refer to how to install add-ons.

...

1. Configuration alias
2. Server Address: The address of the Jira Server where Xray is running
3. Authentication:
   
   1. User: username
   2. Password.

note: the Configuration ID is not editable. This value can be used in the pipelines scripts.

...

Image Added

Creating a new Project

The project is where the work that should be performed by Jenkins is configured.

For this app, you should can configure:

• Freestyle projects
• Maven Projects
• Multi-configuration Projects
• Pipeline Projects

a "Freestyle project". In the home page, clicking for example New Item > Freestyle project, provide a name, and then click OK.

Image RemovedImage Added

Build Steps

Build steps are the building blocks of the build process. These need to be defined in the project configuration.

The app provides

• one build step for exporting Cucumber Scenario/Scenario Outlines from Jira as .feature files

...

• one build step for importing Cucumber Tests from existing Cucumber features into Jira.
• one post-build action which publishes the execution results back to Jira, regardless of the build process status.

...

It invokes Xray's Export Cucumber Tests REST API endpoint (see more information here).

Configuration

Some fields need to be configured in order to export the Cucumber Tests. As input, you can either specify issue keys (see the endpoint documention here) or the ID of the saved filter in Jira.

Xray: Cucumber Features Import Task

This build step will import existing cucumber Tests from existing Cucumber feature files into Xray issues. This Task will import from .feature files and also from .zip files.

It invokes Xray's Import Cumcumber Tests REST API endpoint (see more information here)

Xray: Results Import Task

The app provides easy access to Xray's Import Execution Results REST API endpoints (see more information here). Therefore, it mimics the endpoints input parameters.

It supports importing results in Xray's own JSON format, Cucumber, Behave, JUnit, and NUnit, among others.

Using a glob expression, you can import multiple results files in the following formats:

• JUnit
• TestNG
• NUnit
• Robot framework

For those formats, the file path needs to be relative to the workspace.

Configuration 

Additional fields

Depending on the chose test result format and endpoint, some additional fields may need to be configured.

...

To start the configuration, add the build step Xray: Cucumber Features Export Task.

Image RemovedImage Added

After that, configure it.

In this example, we configured the task to extract the features from a set of issues (PROJ-78 and PROJ-79) to the folder that holds the Cucumber project.

Image Added

Importing Cucumber features

To start the configuration, add the build step Xray: Cucumber Features Import Task.

Image Added

After that, configure it.

In this example, we configured the task to import to the Project IF of the Xray instance all the .features and .zip files that are contained in \Cucumber directory and sub directories, which were modified in the last 3 hours.

Image AddedImage Removed

Importing the execution results

To start the configuration, add the post-build action Xray: Results Import Task.

Image RemovedImage Added

After that, configure it.

In this example, we configured the task to import the Cucumber JSON results back to Jira.

Image RemovedImage Added

Once all configurations are done, click Save at the bottom of the page.

After running the job, the expected result is a new Test Execution issue created in the Jira instance.

Image RemovedImage Added

Importing the execution results with user-defined field values

...

And configured the task to import the Cucumber JSON Multipart results back to Jira.

Image RemovedImage Added

Once all configurations are done, click Save at the bottom of the page.

After running the job, the expected result is a new Test Execution issue created in the Jira instance, with the Test Execution fields as specified in the Jenkins build step configuration.

Image RemovedImage Added

JUnit

Apart from supporting Cucumber natively, Xray enables you to take advantage of many other testing frameworks like JUnit. In this sense, Xray for Jenkins lets you import results in other formats besides Cucumber JSON.

...

To start the configuration, add the post-build action Xray: Results Import Task.

Image RemovedImage Added

After that, configure it.

In this example, we have a configuration where the JUnit XML format is chosen.

Image RemovedImage Added

After running the plan, the expected result is a new Test Execution issue created in the JIRA instance.

Image Added

You can also import multiple results using a glob expression, like in the following example

Image Added

Pipeline projects support

Xray for Jenkins provides support for pipelines projects, allowing you to use Xray specific tasks.

Image Added

Here is a simple example of a pipeline script using the Xray: Cucumber Features Export Task 

pipeline {
    agent any
    stages {
        stage('Export Cucumber') {
            steps {
               step([$class: 'XrayExportBuilder', filePath: '\\features', issues: 'IF-1', serverInstance: '2ffc3a3e-9e2f-4279-abcd-e9301fe47bed'])
            }
        }
    }
}

Examples

JUnit

This is a declarative example, for JUnit based tests.

pipeline {
    agent any
    stages {
        stage('Compile'){
            steps {
                checkout([$class: 'GitSCM', branches: [[name: '*/master']], doGenerateSubmoduleConfigurations: false, extensions: [[$class: 'SparseCheckoutPaths', sparseCheckoutPaths: [[path: 'java-junit-calc/']]]], submoduleCfg: [], userRemoteConfigs: [[credentialsId: 'a3285253-a867-4ea7-a843-da349fd36490', url: 'ssh://git@localhost/home/git/repos/automation-samples.git']]])
                sh "mvn clean compile -f java-junit-calc/pom.xml"
            }
        }
        
        stage('Test'){
            steps{
                sh "mvn test -f java-junit-calc/pom.xml"
            }
        }
        
        stage('Import results to Xray') {
            steps {
                step([$class: 'XrayImportBuilder', endpointName: '/junit', fixVersion: 'v3.0', importFilePath: 'java-junit-calc/target/surefire-reports/*.xml', importToSameExecution: 'true', projectKey: 'CALC', serverInstance: '552d0cb6-6f8d-48ba-bbad-50e94f39b722'])
            }
        }
    }
}

Cucumber ("standard" workflow)

This is a declarative example, for Cucumber tests using the "standard" workflow (see Testing with Cucumber).

pipeline {
    agent any
    stages {
        stage('Export features from Xray'){
            steps {
                checkout([$class: 'GitSCM', branches: [[name: '*/master']], doGenerateSubmoduleConfigurations: false, extensions: [], submoduleCfg: [], userRemoteConfigs: [[credentialsId: 'a3285253-a867-4ea7-a843-da349fd36490', url: 'ssh://git@localhost/home/git/repos/automation-samples.git']]])
                step([$class: 'XrayExportBuilder', filePath: 'cucumber_xray_tests/features', filter: '11400', serverInstance: '552d0cb6-6f8d-48ba-bbad-50e94f39b722'])
            }
        }
        
        stage('Test'){
            steps{
                sh "cd cucumber_xray_tests && cucumber -x -f json -o data.json"
            }
        }
        
        stage('Import results to Xray') {
            steps {
                step([$class: 'XrayImportBuilder', endpointName: '/cucumber', importFilePath: 'cucumber_xray_tests/data.json', serverInstance: '552d0cb6-6f8d-48ba-bbad-50e94f39b722'])
            }
        }
    }
}

Cucumber ("VCS/Git based" workflow)

This is a declarative example, for Cucumber tests using the "VCS/Git based" workflow (see Testing with Cucumber).

pipeline {
    agent any
    stages {
         stage('Synch (update) recent tests to Xray'){
            steps {
                checkout([$class: 'GitSCM', branches: [[name: '*/master']], doGenerateSubmoduleConfigurations: false, extensions: [], submoduleCfg: [], userRemoteConfigs: [[credentialsId: 'a3285253-a867-4ea7-a843-da349fd36490', url: 'ssh://git@localhost/home/git/repos/automation-samples.git']]])
                step([$class: 'XrayImportFeatureBuilder', folderPath: 'cucumber_xray_tests/features', lastModified: '10', projectKey: 'CALC', serverInstance: '552d0cb6-6f8d-48ba-bbad-50e94f39b722'])
            }
        }
        
        stage('Export features from Xray'){
            steps {
                checkout([$class: 'GitSCM', branches: [[name: '*/master']], doGenerateSubmoduleConfigurations: false, extensions: [], submoduleCfg: [], userRemoteConfigs: [[credentialsId: 'a3285253-a867-4ea7-a843-da349fd36490', url: 'ssh://git@localhost/home/git/repos/automation-samples.git']]])
                sh "rm -rf cucumber_xray_tests/features"
                step([$class: 'XrayExportBuilder', filePath: 'cucumber_xray_tests/features', filter: '11400', serverInstance: '552d0cb6-6f8d-48ba-bbad-50e94f39b722'])
            }
        }
        
        stage('Test'){
            steps{
                sh "cd cucumber_xray_tests && cucumber -x -f json -o data.json"
            }
        }
        
        stage('Import results to Xray') {
            steps {
                step([$class: 'XrayImportBuilder', endpointName: '/cucumber', importFilePath: 'cucumber_xray_tests/data.json', serverInstance: '552d0cb6-6f8d-48ba-bbad-50e94f39b722'])
            }
        }
    }
}

Recommendations

You can automatically generate your step scripts using the Jenkins Snippet Generator.

Image Added

Image Added

This is the simplest way to generate your step script, and we strongly recommend the use of this snippet due to the complexity of some task related parameters. Image Removed

Troubleshooting

...

When you check the log, it has the following:

Image RemovedImage Added

By default, when you successively try to log into Jira with the wrong credentials, the Jira instance will prompt you to provide a CAPTCHA the next time you try to log in. It is not possible to provide this information via the build process, so it will fail with status code 403 Forbidden.

You will need to log into Jira via the browser and provide the CAPTCHA.

Image RemovedImage Added

If you are a Jira administrator, you can go to Jira administration > User Management and reset the failed login.

Image RemovedImage Added