In a nutshell 

1. Overview

• Add multiple locators for an element, and also group them under their corresponding page name

• Save frequently used components like submit buttons and search bars

• Reference a web component or locators using its identifier any place in the test script

• Avoid test script rewrite when an element, its locator value, or locator type changes 

2. Creating Elements  

• Using the recorder

• Manual Entry

• Using Refer Elements
  

Using the recorder

1. After recording the test case, the Add Element pop-up lists all the interactive web or mobile elements, along with their locators.
   
   

2. The recorder saves the page name, locator type, and the locators. Uncheck the elements that are not required.

• Page Name - For webpages, the default name of the page is determined by the <title> tag, while for mobile apps, it is referred from its screens, with each having a unique identifier used by the app's code. All the elements of the corresponding page will be accessed under this attribute.
  

• Element Name - This attribute is used to refer the element inside a test case. You can configure how the element should be named using the Configure Locator Strategies.
  

• Type - Specifies the nature of the recorded web or mobile elements, such as Button, Check, Date, Dropdown, Email, File, Generic Element, Image, Input, Label, Number, Password, Radio, Select, Span, Submit, Table, Text, Textarea, a, div, li, ol, td, th, and ul.
  

• Locator Type - A method used to identify and locate a specific element within a webpage or mobile app. A single element can store multiple locators. Set up element recording strategies through the Configure Locator Strategies option. Supported locator types for web include: Xpath, ID, Name, and CSS Selector, while for Android and iOS: Xpath, ID, Text, CSS Selector, Accessibility ID, and Class Name.
  

• Locator - Stores the value of the locators for an element, provided they are available in the HTML DOM.
  

3. You can edit these fields, if necessary.

• Click on the edit icon near the page name to rename it. Click on the save icon to save the changes.
  
  To make changes to the elements:

• From the drop-down, hover on the required element and click the edit icon to make changes to the element name, element type, locator type, and locators. Click on the save icon to save the changes.
  

  
  

  

  
  

  Note: Additionally, you can perform edit actions on elements by accessing Settings > Elements.

4. After making the necessary changes and selecting the required locators for the interacted elements, click Save.
   

Configure Locator Strategies

1. To set the order, rearrange the locator attributes.

2. Use the toggle on/off switches to enable or disable the locator attributes.

3. Click Done to save the changes.
   
   

1. Click on +Add Custom Attribute and provide the name for your custom locator attribute. Click Save.

2. Set the order by rearranging the locator attributes.

3. When you're finished making changes, click Done. 
   
   
   

1. Hover over the locator you wish to make changes to, then click either the edit or delete icon.

2. Click Done to update all the changes.

Similarly, the Element Name section allows you to set the order of attributes that decide how to name the locators while recording.

Manual Entry

1. Navigate to Settings > Elements.
   
   

2. Click +Create Element. In the popup that appears, enter the relevant details:
   
   

1. Page Name - A suitable name to categorize elements based on the web pages or mobile application screens they belong to. All the elements of the corresponding page will be accessible under this attribute.
   

2. Element Name - This attribute can be used to refer the element inside a test case. The element name should be unique within web, Android, and iOS platforms.

   Note: Element Name only allows the use of underscore (_). Spaces and other special characters are not allowed. They can't have more than 30 characters.

3. Type - Specifies the nature of the recorded web or mobile elements, such as Button, Check, Date, Dropdown, Email, File, Generic Element, Image, Input, Label, Number, Password, Radio, Select, Span, Submit, Table, Text, Textarea, a, div, li, ol, td, th, and ul. Choose the desired type from the drop-down.
   

4. Locator Type - Method used to locate a specific element within a webpage or mobile app. Mention the locator type to be used for that element from the drop-down, and one element can store multiple locators. For web, the locator types supported are: Xpath, ID, Name, CSS Selector. For Android and iOS, the locator types supported are: Xpath, ID, Text, CSS Selector, Accessibility ID, Class Name.
   

5. Locator - The value of the web components or locators for an element, provided are available in the HTML DOM.

3. Fill all the fields and click Create.

Note: Switch between tabs to manually enter or access elements on Android and iOS platforms.

Using Refer Elements

In addition to using the Settings page, you can create new elements using the Refer Elements feature. To create a new element, click +Add inside the Refer Elements option on the test case editor page. You'll get access to the Create Element pop-up, in which you need to perform the same steps as in manual entry. Once the required elements are created, access them inside Refer Elements.

3. Using Elements 

Editor mode

1. Inside Editor mode, select the task you want to use to interact with the element, such as "Click", "Set Value", and so on.

2. To refer to elements inside the tasks, type in the keyword ui. , then select the required page and element from the suggested list.

3. Click Save once the test script is created.

Builder mode

In Builder mode, use the set expression pop up, to use elements inside the tasks. The Elements section inside the pop-up contains the list of all the elements created for that project.

1. Select the task you want to use to interact with the element, such as "Click", "Set Value", and so on.

2. For the tasks, pass the arguments in the panel on the right side. As you click on the placeholder for the arguments, the set expression pop-up will be accessed.
   

3. Select the required element from the list inside the element section. The set expression input field will be auto populated with the selected element, in the format ui.<page_name>.<element_name>.
   
   

   
   

   Note: Alternatively, you can hard code the element locators to be used inside the respective tasks, using the set expression input field. Input the locator in the format ui.<page_name>.<element_name> or use the Refer Elements option to copy the element locator to be used.

4. Click Done to save the changes.

4. Managing Elements

4.1 Editing and Deleting Elements 

1. Navigate to Settings > Elements. You'll see the list of all saved elements.
   
   

2. Hover over the required element and click the edit or delete icon.
   
   

• To perform the edit action:
  The Edit Element pop-up allows you to edit or create a new page name and edit the element name and its type, locators and their type.
  
  
  
  To edit the page name alone, hover over the page name and click the edit icon. To delete all the elements saved under the selected page name, click the delete icon.
  
  
  
  To make changes to locators:
  
  To delete individual element locators, hover over it and click the delete icon. Additionally, to add new locators, click the {+} icon to add a new row, and reorder them however required.
  
  

• To perform the delete action:
  Click on the delete icon. Then, click Delete to remove the element.
  

3. To confirm the changes, click Update. 

Note: If the locator you tried deleting is referred to inside any of the test cases, remove its usage in the respective test cases, then continue to perform the deletion.

4.2 Importing elements  

QEngine allows you to import elements into your project from another QEngine project, by uploading an .json file.

1. Click the dropdown next to +Create Element, then click Import Elements.
   
   
   
   

2. Upload your JSON file that contains the elements you want to import.
   
   
   
   

   Note: The import file must be in JSON format and cannot exceed 250 MB in size.

3. Select the target platform from the following options: All Platforms, Web, Android, and iOS. If your JSON file includes elements for multiple platforms, you can select the platform to which the elements should be uploaded.
   

4. Choose how to handle duplicate elements. If you select ignore duplicates, your existing elements remain unchanged, and any duplicates in the import file are not added. If you select overwrite, your existing elements are replaced with the versions from the import file.
   
   

5. Click Import.
   

Note: If your import didn’t succeed, it may be due to one of the following reasons:

• The uploaded file isn't in JSON format.
• The JSON file is missing required fields such as element name, element type, locator type, and locator values, such as ID, Name, XPATH, and so on.
• The JSON file contains elements that are not compatible with the selected platform. For example, the file may have required elements for the Android platform, but is uploaded with the target platform set to iOS, the upload will fail.

4.3 Exporting elements  

You can export existing elements in any platform for backup, migration, or sharing purposes.

1. Click Export in the Elements tab.
   
   
   
   
2. Select the target platform from the following options: All Platforms, Web, Android, or iOS.
   
   
   
   
3. Click Export to download the file. The downloaded JSON file will include the elements from the selected platform.
   

4.4 Reference 

1. Locate the element for which you want to view references, then click the Reference icon {} next to the element name.
   
   
   
   
2. In the References pop-up window, you can view:
   

• Element Name – Displayed above the list of test cases and functions.
  
• Functions – All functions where the element is used, with their status (Ready, Draft) and platform type (Web, Android, or iOS).
• Test Cases – All test cases where the element is used, with their status and platform type.
  
  

3. Click OK.