Overview

Test cases evolve when 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.


Jira versions and Xray Test versioning

Please refer to this article: TTT - Test Versioning if you're wondering how to use Jira versions and Xray Test case versioning.

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. When you create a Test, Xray automatically set the v1 as default.

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.

To make sure you always run your Test with the version you aim, usually the most up-to-date one, you can manually mark a version as the default one. Note that there can be multiple versions active but only one can be marked the default one; therefore the "default" version is your preferred version.



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 Preconditions web panel is also affected by the currently selected version as it only displays the Preconditions 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 Preconditions web panel will also be updated with the Precondition 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. The create Test Execution popup dialog will appear.
  2. Choose a Test version to execute the Test and fill in the necessary fields.
  3. Press "Create" to create the Test Execution issue with the selected version.


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 and choose "Existing test execution..."

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.

When deleting a Test Version, all Test Runs executed for that version will also be deleted from Jira. 


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 the Xray History view. You can also filter history changes by Test version.