Clicknium Locator
A locator is a way to identify elements on a web page or desktop app.
Overview
Identification of the correct GUI element on a web page is pre-requisite for creating any successful automation script, where locators come into the picture. Locators are one of the essential components of Clicknium infrastructure, which help Clicknium scripts in uniquely identifying the UI elements(such as text box, button, etc.). The way to get a locator for a specific UI element is the key experience of automation framework. Before using Clicknium, you have to learn some web essential knowledge, such as XPath, CSS selector. Clicknium provides Clicknium Recorder to help you get a locator by just clicking the elements.
Operations Supported by Locators
- Open: open locator details in the VS Code edit window.
- Validate: validate the locator.
- Copy: create a same locator under the same directory.
- Copy Path: put the path of the locator in clipboard, so users can paste it directly in the Python code.
- Rename: rename the locator
- Delete: delete the locator
- Actions: take quick actions such as: click, set_text, get_text in locator details window.
- Recapture: recapture locator in ocator details window.
How to use
So, how do we get the values of these locators? And how to use locators in the automation framework?
Get a locator
Clicknium provides Clicknium Recorder to get UI locators.
- Make sure that Clicknium Python package, VS code extention, Chrome extension is installed.
- Open a Python file in VS code.
- Capture locators with Clicknium Recorder(
Ctrl + Click
).
How to Choose Locator Type
Most scenarios can be satisfied with the default setting(Auto mode). The capture technology and advanced options can be changed to meet your needs. Supported Capture Technoloy:
- Auto Detect: auto detect and choose a capture technoloy.
- Web Browser
- Chrome
- Edge
- Firefox
- UIA
- IA
- Java
- SAP
- Image(Computer Version)
For web browser, XPath is supported. You can change Advance Option
to XPath
.
For Desktop application, making a decision is simple. If you want to automat a Java or SAP application, select the corresponding technology. Otherwise, Auto Detect
would use UIA as default for Windows desktop applications. Try IA if UIA doesn't work in your case. If there is no unique attribute and hard to identity the UI element by tuning attribute, try image automation.
If you need to caputre multiple UI elements in one locator, use capture similar elements.
Use Locator in Python Code
Clicknium provides intellgent auto-complete experience. You can find the exsiting locators captured by Clicknium Recorder in VS Code. Select the locator class under the Clicknium package and reference Locator by Locator.{localorStoreName}.{folderName}.{LocatorName}
Operate locators via Python code, run and waiting for a miracle.
Locator Editor
The detailed page of locator editor is organized with two parts.
Left part: display locator tiers as XML based view
Right display the attribute details for the selected XML node on the left part.
Checkbox ①: Select the locator tier. The unchecked tier will be ignored when locating the UI element.
Checkbox ②:Select the properties for the selected locator tier. This unselected properties will be ignored when locating the UI element.
Dropdown ③: There are 4 matching operators, "equals", "contains", "startWith" and "endWith".
Input item ④:The values of the property
Notes:When the matching rule is "equals", the value supports wildcard characters.Wildcard characters Functions * Substitute one or more characters ? Substitute a character
Make locator generalized and stable
- Uncheck the atrributes without generalization that don't affect identity UI elements.
- Use patamters, refer to Parametric Locator
- Use wildcard, refer to Wildcard locator
- Use regex, some attrubutes support regex, refer to different capture technoloy.
Recapture
- Click the
Recapture
button to open the recorder and capture the locator again. - Capture the corresponding target UI element.
- When recording succeeds, return to vscode and save the newly recorded element by pressing Ctrl+S.
Locator Validation
Click Validate
button.
Validation succeeded
The recorder opens the window containing a locator and marks the corresponding element.
Within a few seconds, it automatically returns to the vscode window and marks as correct.
Validation failed
If the recorder cannot find the target element, it automatically returns to the VS Code and marks the locator tier that cannot be found.
Notes: The application will not be opened and the corresponding URL will not be entered in the verification. If the error is marked in layer one or layer two, please confirm whether the application and URL are opened.
Multiple windows exist in validation
If multiple opened windows contain the locator at the same time, a dialog will pop up for you to select the window.
After the matched window is selected, the corresponding window will be validated in a few seconds and return to vscode.
Multiple elements are located in validation
If multiple locators are matched in the window, a window will pop up for you to select the locator index.
If you switch the Index, the corresponding locator is highlighted.
If you want to update the switched Index in a locator, check
Single target
and clickOK
.After switching back to VS Code, the corresponding Index property will be updated to the last Index and checked.
Locator Error Hint
Error Type
- The UI or find_element function argument must be a locator. If it is a store or a folder, an error message will be displayed.
Locator Does Not Exsit
- If the entered locator does not exist in the referenced store, an error message is displayed.
- Select
Quick Fix
to start the recorder. After recording elements, a locator that does not exist will be named to generate a locator.
Locator Hover
- If you hover the mouse to the locator in the code, the locator content is displayed for easy identification.
Open
: Open the corresponding locator to editValidate
: Validate the locatorRecapture
: Start the recorder to capture the locator again. If the recorded locator is different from the one in the editing window, it will be saved directly.
Auto Fill
- Press the shortcut key CTRL+F10 or click
Capture
in the right menu to start the recorder. - After recording, select a locator that is required to fill in the recorder.
- After clicking
OK
, the locator will be automatically filled into the code.
Advanced Locator
Please check Locator Concept