Overview

Starting from version 7.0 of Xray Enterprise, users can create different versions of a Test case within the same Test issue. A Test case can evolve as the requirements change or improvements are made to the application under test. Although Xray logs test specification changes in the Jira history, it is not easy to revert to a specific test case version. With Test case versioning, you can now create multiple versions of the same Test allowing you to:

• Mark specific milestones of the Test with versions
• View all previous Test versions and revert to a particular version if needed.
• Have multiple active versions simultaneously, even of different Test Types, as you can execute them all independently.

Creating Test Versions

A Test Version is composed of the following fields on a Test issue:

• Test Specification:
  • Test Steps
  • Gherkin Steps
  • Scenario type
  • Generic definition
• Test Type
• Dataset
• Preconditions

A Test Version is defined with a name. You can choose the name for the versions explicitly when creating new versions. Xray will try to generate the version name automatically based on the latest version if the name ends with a suffix that is recognized as a version number. Nevertheless, you can always change this auto-generated name. It is also possible to rename existing versions.

To create a new version:

1. Choose the "New version" option on the Actions menu next to the version number in the top right corner of the Test Details web panel on a Test issue.
    
2. A popup dialog will appear where you can set the version name and choose a base version to copy the definition from. You can also choose to make the new version the Default version.
   
3. When you press "Create", the new version is created and selected automatically on the Test Details web panel. 

The Default Version

Every Test has a default version. The default version is the one Xray chooses when you create a new Test Run for the Test without specifying any particular version. Therefore, the default version should be the most recent version ready to execute.

The default version must be set manually by users. This can be done anytime using the "Set Default" option on the Actions menu next to the version selector.

Also, the default version is the one found on the Xray custom fields:

• Manual Test Steps
• Cucumber Scenario
• Cucumber Test Type
• Generic Test Definition
• Test Type
• Pre-Conditions association with a Test

The default version of a Test can not be deleted or archived.

To set the default version:

1. Choose the "Set default" option on the Actions menu next to the version number in the top right corner of the Test Details web panel on a Test issue. 
   
2. The current version is set as default. A lozenge will appear next to the version name.

You can also set the default version through the "Manage Versions" dialog.

Viewing Test Versions

When Xray enterprise is installed, a dropdown selector field for the Test versions will be provided on the top right corner of the Test Details web panel on the Test issue. This dropdown provides all the Test versions as options and groups them into Active and Archived. The Test Type is also displayed for each version. The default version will be identified with a "default" lozenge.

When the Test issue is opened, the default version will be selected.

The Pre-Conditions web panel is also affected by the currently selected version as it only displays the Pre-Conditions associated with the selected version.

To switch between versions, you only need to choose a version from the versions dropdown selector:

1. Press the versions dropdown selector in the top right corner of the Test Details web panel on a Test issue.
   
2. Choose a particular version. The version specification will appear on the Test Details web panel. The Pre-Conditions web panel will also be updated with the Pre-Condition issues from the selected version. 

Managing Test Versions

To better view and manage all versions of a Test, you can access a dialog with a list of all the versions in the Test. Here you can do specific actions like:

• Renaming versions
• Archiving/Unarchiving versions
• Set the Default version

To open the dialog:

1. Choose the "Manage Versions" option on the Actions menu next to the version number in the top right corner of the Test Details web panel on a Test issue.
   
2. The manage versions dialog will appear. Here you can view all the Test versions and perform actions on them. You can also filter archived versions.
   

Archiving Test Versions

It is also possible to archive (and unarchive) Test versions. Archived versions can not be executed. They exist just for the historical record.

All Test runs of archived versions will remain accessible as a copy of the Test specification is always made whenever a Test Run is started.

To archive a Test version:

1. Choose the "Archive Version" option on the Actions menu next to the version number in the top right corner of the Test Details web panel on a Test issue.
   
2. Once the version is archived, a lozenge will appear next to the version name, indicating the selected version is archived.
   

The unarchive version action is the opposite of archiving and can also be found on the same Actions menu next to the version number in the top right corner of the Test Details web panel on a Test issue.

You can also archive Test versions from the manage versions dialog. 

Executing a Test version

You can create new executions of a specific version from the Test Runs web panel on the Test issue page. 

To create a new Test Execution:

1. Press the "Execute in" dropdown button on the left toolbar in the Test Runs web panel.
   
2. Choose a Test version to execute the Test.
3. Fill in the necessary fields on the Create issue dialog and press "Create"

To add a new Test Run into an existing Test Execution issue:

1. Press the "Execute in" dropdown button on the left toolbar in the Test Runs web panel.
   

You can also create new Test Runs and specify a Test version when you add Tests to a Test Execution through the Test Execution issue screen.

Delete a Test Version

You can delete versions from a given Test using the Delete action provided by Xray in the Test details section. The Default version can not be deleted.

To delete a given Test version from a Test:

1. Choose the "Delete Version" option on the Actions menu next to the version number in the top right corner of the Test Details web panel on a Test issue.
   
2. A popup confirmation dialog will be displayed. If the Test version being deleted has Test Runs, the number of Test Runs to be deleted will also be displayed to the user in the popup dialog.
3. After the user confirms, the version and any associated Test Runs will be deleted from Jira.

History Changes

All changes related to Test specification fields on Test versions are also logged to Jira History view. Nevertheless, Xray provides a new History view named "Test History" that allows you to view all changes of the Test Issue and also filter changes by Test version.