The Automated Steps Library is a project-level steps library organization for Cucumber Tests/Pre-Conditions, containing all the Gherkin steps referred by all those Tests/Pre-Conditions belonging to that project.

Thus, it provides an overview of all the automated (Gherkin) steps used in the context of each project, allowing users to easily refactor the steps.

The library is automatically populated with all the steps upon the creation/update of Cucumber Tests/Pre-Conditions.

Gherkin reserved keywords (e.g. Given, When, Then, And) are not stored in the library.


Learn more

Please refer to Gherkin Tests on how to define Gherkin Tests using the Automated Steps Library



Overview of the Automated Steps UI

The Automated Steps Library screen can be accessed from the project left sidebar by choosing the Automated Steps Librar icon.

The image below depicts the several key areas of the Automated Steps Library screen.



A: Steps section

    • A1: search step based on given content
    • A2: restrict searching of steps to the givel labels 
    • A3: list of steps maching search criteria defined by A1 and A2

B: Step content section

    • B1: step content (i.e. Gherkin sentence without the Gherkin reserved keywords)
    • B2: information about the Test(s)/Pre-Condition(s) using the selected step
    • B3: labels assigned to the step

Actions

A step can be selected by clicking on it. Once selected, you may update it, for example.

Multiple selection is possible by using the "Ctrl" key (on Windows) or the "Cmd" key (on OS X). If you want to select more than one step  and the steps are listed consecutively, use the "Shift" key to quickly select an entire group. Click the first step in the list you want to select, hold down the "Shift" key, scroll down to the last step you want and click it. This selects the first item, the last item and all items in between.

Search steps

Steps can easily be searched using autocomplete, further restricted by some given labels. 

Step 1: Write part of the step content (you may click on the search icon to enforce a search if needed).

Step 2: Select the labels to filter out the steps just containing the identified labels; this can be done before or after writting the step content to search for.
If more than one label is specified, then only steps containing all those labels are shown.

   


Merge / Refactor multiple steps

In order to keep your Automated Steps Library clean and sane, you'll need to do refactoring quite often

It may happen that you have redundant, similar steps. Thus, you may merge those steps and avoid duplicated specification & related code.


Please note

Upon a steps merge operation, all Tests and Pre-Conditions using it are updated accordingly.

Only non-readonly Tests/Pre-Conditions that the user is allowed to edit are updated; the other ones will remain as-is, leading to the simultaneous existence of original steps along with the merged one in the library, in this case.

A merge operation may require some manual reviewing on the destination affected Tests/Pre-Conditions.


Example: two steps are merged to one having the content: "Given I have a turned on calculator"


Original Test/Pre-Condition contentUpdated Test/Pre-Condition content
Given I have a calculator

Given I have a turned on calculator

Given I have a turned on calculator

And the calculator is turned on


As you can see from this example, in which the original Test/Pre-Condition contains the original steps, the merge operation does not remove duplicated steps in the destination Cucumber Scenario/Background.

Thus, a manual process should be done on the affected issues in order to review the specification and remove the steps where desired.


To merge similar redundant steps:

Step 1: Select the steps (see Actions above for information on multi-selection).

Step 2: Use the context action "Merge".

Step 3: Edit the merged step content on the right side; on the left side you can see the temporary merged step until you save it.


Step 4: Click on Save.

Find Tests and Pre-Conditions using a step

To find all the Tests or Pre-Conditions using a given step:

Step 1: Click on the step.

Step 2: Click on the number shown below the step content box.

Step 3: The issues search will show all related issues.

Update / Refactor a step

The step content can be updated (i.e. renaming the step) directly in the Automated Steps Library for easy refactoring; all updatable Tests/Pre-Conditions will be updated accordingly.

Only non-readonly Tests/Pre-Conditions that the user is allowed to edit are updated; the other ones will remain as-is, leading to the simultaneous existence of original step along with the updated one in the library, in this case.


Please note

It is also possibile to indirectly update steps during the edition of Cucumber Tests/Pre-Conditions; however, this inhibits refactoring.

Whenever editing Cucumber Tests/Pre-Conditions, if the changed steps aren't being used elsewhere, then the existing steps will be updated accordingly; otherwise, new steps will be created. In other words, the library will contain all the steps, including the new/changed ones along with the "original" ones that being used in other issues. Thus, some care should be taken whenever editing Cucumber Tests/Pre-Conditions in order to avoid proliferation of similar steps.


To update the content of an existing step (i.e. refactor it):

Step 1: Click on the step.

Step 2: Edit the step content on the right side.

Step 3: Click on Save.

Add Label

Label your steps so you can easily group similar steps and find them afterwards whenever you need them. Since steps may be related with different things simultaneously, you may add more than one label.

To add a label to an existing step:

Step 1: Click on the step.

Step 2: Click on labels input box to enter a new label or use the arrow dropdown to pick an existing one.

Step 3: Click on Save.

Remove Label

To remove a label from an existing step:

Step 1: Click on the step.

Step 2: Click on the cross of the label in the labels input box or use the backspace after positioning the cursor after the desired label.

Step 3: Click on Save.


Settings

Enable/Disable

Upon installation of Xray or the upgrade from an earlier version of Xray, the Automated Steps Library is enabled by default.

Xray allows you to globally enable/disable the Automated Steps Library though.

A setting availabe in Xray Miscellaneous allows the administrator to enable/disable the library.


Whenever enabled, there's an additional performance overhead on the creation/update of Cucumber Tests/Pre-Conditions and upon the refactoring of existing steps within the Automated Steps Library UI. 

On the other hand, disabling the library will avoid that additional processing overhead.


Please note

if you disable the Automated Steps Library, all new steps that you added meanwhile or, in general, any changes that you have made to your existing Cucumber Tests/Pre-Conditions afterwards will not be synchronized to the library. This means that the Automated Steps Library may be out-of-synch.

Synchronizing your existing steps with the library can be done with the Integrity Checker.


Maintenance

Using the JIRA administration

Integrity Checker may be used to force a per-project synchronization of steps, in case you find orphaned or missing steps in the library.

Using project settings

An action is available in the project settings to force a per-project synchronization of steps.

Step 1: Go to project settings, Summary section.

Step 2: Go to Actions, at the top-right corner and choose "Import Automated Steps to Library".