Xray Exporter

Xray Exporter is a tool used to export test cases into Jira Xray Plugin.

Features:

  • Create and update manual and cucumber test cases

  • Set Jira labels for test cases

  • Set Jira components for test cases

  • Link test cases to stories they belong to

JIRA Configuration

The exporter requires configuration of JIRA instance to work with.

To configure connector to JIRA instance use jira. prefix followed by arbitrary sequence of alphanumerical characters that determine unique JIRA instance key and followed by the properties listed in the following table:

The properties marked with bold are mandatory.
Property Name Description

project-key-regex

The regular expression to match JIRA project keys.

endpoint

The JIRA Endpoint.

any of general, authentication or SSL handshake properties

The HTTP properties.

fields-mapping

The mapping between human-readable fields used by VIVIDUS and fields used by JIRA.
Example 1. jira.properties
jira.vividus.project-key-regex=(VIVIDUS|VSCODE|REACTAPP)
jira.vividus.endpoint=https://vividusframework.atlassian.net/
jira.vividus.http.auth.username=admin
jira.vividus.http.auth.password=5401a7d27b291c5d
jira.vividus.http.socket-timeout=10000
jira.vividus.fields-mapping.test-case-type=customfield_10002

In the example above the vividus is a key that can be used to refer this JIRA instance.

Xray Export Properties

The properties marked with bold are mandatory.

General

Property Required Description

xray-exporter.jira-instance-key

false

The key of the configured JIRA instance, in case of missing value it will be evaluated automatically based on issue keys being exported

xray-exporter.json-results-directory

true

Path to directory with test execution JSON results.

The path is managed by the bdd.report-directory property which default value is output/reports/jbehave relatively to the tests directory.

Please make sure that the bdd.configuration.formats property includes JSON value in order to generate test execution results.

xray-exporter.project-key

true

Key of a Jira project where new test cases should be created

xray-exporter.assignee

false

Username of Jira user that will be used as assignee for newly created test cases

xray-exporter.editable-statuses

false

Statuses of test cases allowed to update

xray-exporter.test-set-key

false

The key of a Test Set to which the exported test cases will be added

xray-exporter.test-case-updates-enabled

false

By default, the content of Test Cases that have associated IDs, is updated every export run, to disable this behavior set the value of this property to false

xray-exporter.test-execution.attachments

false

Comma-separated list of file and folder paths that should be uploaded to test execution as attachments. Please note that regular files like images, texts are uploaded as is, whereas folders are archived before the upload.

xray-exporter.test-execution-attachments property is deprecated in favor of xray-exporter.test-execution.attachments and will be removed in VIVIDUS 0.8.0.

xray-exporter.test-case.use-scenario-title-as-description

false

If enabled (true value), the scenario title will be used as the description, but only for newly created test cases, otherwise the description will be left empty.
Example 2. application.properties
xray-exporter.project-key=ABBA
xray-exporter.json-results-directory=/Users/happytester/Repositories/app-tests/output/results/jbehave

Test Execution

Property Required Description

xray-exporter.test-execution.key

false

The key of Test Execution which the exported test cases along with their statuses will be added to

xray-exporter.test-execution-key property is deprecated in favor of xray-exporter.test-execution.key and will be removed in VIVIDUS 0.8.0.

xray-exporter.test-execution.summary

false

The Test Execution summary

xray-exporter.test-execution-summary property is deprecated in favor of xray-exporter.test-execution.summary and will be removed in VIVIDUS 0.8.0.

xray-exporter.test-execution.description

false

The Test Execution description

Test execution import varies depending on values in xray-exporter.test-execution.key and xray-exporter.test-execution.summary, the following matrix shows this behavior change:

Configuration Result

Both xray-exporter.test-execution.key and xray-exporter.test-execution.summary are set

Test execution summary and associated test cases will be updated, the update of test cases is performed according to following rules:

  • new test cases are added to the test execution

  • statuses of existing test cases are updated

Only xray-exporter.test-execution.summary is set

New test execution will be created

Only xray-exporter.test-execution.key is set

Associated test cases will be updated according to following rules:

  • new test cases are added to the test execution

  • statuses of existing test cases are updated

Neither xray-exporter.test-execution.key nor xray-exporter.test-execution.summary are set

Text execution import is skipped

Jira Fields Mapping

The Xray is a Jira plugin that uses custom Jira fields for it’s data, one of the ways to find out custom field names for particular field used by Xray on Jira UI (if access to Jira configuration is prohibited) is to request description of some issue like https://jira.example.com/rest/api/latest/issue/DUMMY-1.

Manual Test Case Properties

Manual test case view

Index Property Description

1

jira.<jira-instance-key>.fields-mapping.test-case-type

Key of a field containing test case type

2

jira.<jira-instance-key>.fields-mapping.manual-steps

Key of a field containing collection of manual steps
Example 3. mapping.properties
jira.<jira instance key placeholder>.fields-mapping.test-case-type=customfield_10001
jira.<jira instance key placeholder>.fields-mapping.manual-steps=customfield_10002

Cucumber Test Case Properties

Cucumber test case view

Index Property Description

1

jira.<jira-instance-key>.fields-mapping.test-case-type

Key of a field containing test case type

2

jira.<jira-instance-key>.fields-mapping.cucumber-scenario-type

Key of a field containing type of cucumber scenario

3

jira.<jira-instance-key>.fields-mapping.cucumber-scenario

Key of a field containing body of cucumber scenario
Example 4. mapping.properties
jira.<jira instance key placeholder>.fields-mapping.test-case-type=customfield_10003
jira.<jira instance key placeholder>.fields-mapping.cucumber-scenario-type=customfield_10004
jira.<jira instance key placeholder>.fields-mapping.cucumber-scenario=customfield_10005

Authentication

  • If the authentication through basic schema is available on your JIRA instance use jira.<jira instance key placeholder>.http.auth.username and jira.<jira instance key placeholder>.http.auth.password properties, both properties must be set. It’s also advisible to turn the preemptive authentication on.

    jira.<jira instance key placeholder>.http.auth.username=admin
jira.<jira instance key placeholder>.http.auth.password=5401a7d27b291c5d
jira.<jira instance key placeholder>.http.auth.preemptive-auth-enabled=true

  • In case of two-factor authentication, token authentication or any other complex authentication process it’s possible to use request headers like the following example shows:

    Example 5. Authenticate using Bearer token
    jira.<jira instance key placeholder>.http.headers.Authorization=Bearer D5YY0qJDxFDOZjCEpINMTdcQQxNtATrMw/IAsyWI+CzE
    Example 6. Authenticate using session cookies
    jira.<jira instance key placeholder>.http.headers.Cookie=SESSIONID=298zf09hf012fh2
    Both jira.<jira instance key placeholder>.http.auth.username and jira.<jira instance key placeholder>.http.auth.password properties must be empty in this case.

Scenario Meta Attributes

Name Example Description

testCaseId

@testCaseId STUB-0

Map scenario to Jira test case in 1 to 1 relation

requirementId

@requirementId STUB-0

Link scenario to Jira issue with "Tests" link type in 1 to 1 relation

xray.labels

@xray.labels label-1;label-2

Set labels to the exported test case

xray.components

@xray.components component-1;component-2

Set components to the exported test case

xray.skip-export

@xray.skip-export

Skip test case while exporting

Test Case Types

This separation of automated and manual test cases by using special keywords is specific to VIVIDUS.

Automated Test Cases

Any scenario that doesn’t correspond to the manual test case rules is considered as automated test case.

Example 7. Automated.story
Scenario: Verify link
Meta: @testCaseId TEST-231

Given I am on page with URL `${vividus-test-site-url}/links.html`
When I wait until the page has the title 'Links'
Then number of elements found by `<locator>` is equal to `1`
Examples:
|locator                        |
|By.linkUrl(#ElementId)         |
|By.linkUrlPart(Element)        |
|By.linkText(Link to an element)|
Example 8. AutomatedWithManualPart.story
Scenario: Verify link
Meta: @testCaseId TEST-566

!-- Step: Open main app page
!-- Step: Wait for page with title is loaded
!-- Step: Verify number of links
!-- Data: * link url is '#ElementId'
!-- * link url part is 'Element'
!-- * link text is 'Link to an element'
!-- Result: The number of links for all locators is equal to 1

Given I am on page with URL `${vividus-test-site-url}/links.html`
When I wait until the page has the title 'Links'
Then number of elements found by `<locator>` is equal to `1`
Examples:
|locator                        |
|By.linkUrl(#ElementId)         |
|By.linkUrlPart(Element)        |
|By.linkText(Link to an element)|

Manual Test Cases

  • Scenario is considered as Manual Test Case if all of its lines start with !-- prefix.

  • The Manual Test Case step must start with Step: used to specify action to perform and can optionally contain Data: and Result: for specifying action data and action expected result respectively.

  • The Manual Test Case step parts are allowed to have multiple lines.

  • The JBehave Keywords values (e.g. Given, When, Then …​) on new lines not prefixed with Step:, Data: or Result must be escaped with - sign.

Example 9. Manual.story
Scenario: Buy an item
Meta: @testCaseId TEST-435

!-- Step: Go to the test item with the following id
!-- Data: 39914061
!-- Result: The current stock is 1

!-- Step: Add the item to the shopping cart
!-- Result: Shopping cart now displays one 39914061 item and no items in stock

!-- Step: In the backoffice app update the stock to 0 on item

!-- Step: Back in the browser, proceed to checkout.
!-- Go through all the steps and confirm the payment method.
!-- Result: Then you should get an error message mentioning that there are no more items in the stock.
!-- - Then payment method was not made

Export

  • Go to the corresponding GitHub Packages repository

  • Find the link with name vividus-to-xray-exporter-0.6.16-<timestamp>-<publishing-number>.jar

  • Click the link and download the exporter JAR-file

  • Create a new file with name application.properties in the same directory with the downloaded JAR-file

  • Put all custom properties to the created file

  • Run the following command from the directory where the JAR-file has been downloaded, make sure to replace <jar-file name> placeholder with the actual name (not path) of the JAR-file including its extension

    java -jar <jar-file name> -Dspring.config.location=classpath:/application.properties,./application.properties