When working with automated tests, there are two critical pieces:
- Selecting the right element to interact with and
- Performing the interaction successfully (clicking, inputing text, etc)
Why Selectors?
Although we always attempt to select the correct element, websites can be constructed in countless ways where this doesn't always happen as expected (as with every tool). One of our core differentiators from every other kind of automation product is that we do not simply use a selector, or even a dozen selectors to find an element; we use hundreds of thousands of pieces of data, per step, in order to reconstruct the user's interaction with the website. This is how we are able to Self-Heal so robustly. Of course, there are times when the user may not want us to try to self-heal, or times when we don't execute as expected due to site changes, or particularly unusual websites. We offer three options to customize and force certain types of selection methods.
What is a Selector?
There are two types of selectors that we support: CSS and XPath. If unfamiliar with how to create selectors to select elements, we have created a video: How to Create a Selector Directly with the Chrome Dev Tools. This method is fine as needed, but can be brittle depending on the selector. Here are a few resources for learning about how to create good selectors.
- CSS Selector Reference: https://www.w3schools.com/cssref/css_selectors.asp
- Try Out How to Use a Selector to Locate an Element here: https://www.w3schools.com/cssref/trysel.asp
- XPath Syntax: https://www.w3schools.com/xml/xpath_syntax.asp
NOTE: This is used as a backup method to the default machine learning-based selection. You can enter a selector to attempt to try a specific element first or to force that specific item to exist. Typically this is just used as a backup option.
Accessing Selector Options
You can access our Selector options when recording your tests in Architect, when editing on the Test Detail page, or while viewing execution results in Slider View.
Architect
- Launch Architect by creating a New Test.
- While recording, open an Action by clicking the white circle on the left. Select the ADV Selector tab.
Test Detail
- Open your Test.
- While on the Actions tab or a Browser Results tab, expand the Action to see the Action Settings. Select the Advanced tab.
Slider View
- Open Slider View for your Test.
- Click the gear icon on an Action to open the Action Settings window. Select the Advanced tab.
Selector Options in Action Settings
Selectors offer more control over elements that should be identified with stricter rules. The Selector Type tile in Action Settings has three options: ML Selection (default), Selector, and JS Override Selector.
ML selection
This is our machine learning based selector which is enabled by default.
Selector
Define a specific CSS or XPath Selector for your element. If your specified input selector cannot be found during execution, the search will fall back to ML selection.
When Force is checked, the test will fail during execution if the selector is not found.
Sample selectors include:
CSS selector: #popover_p4q3jyvdfh > div
XPath Selector: //*[@id="popover_p4q3jyvdfh"]
Selector Snippets
We also provide a list of automatically populated unique selector snippet options rather than writing selectors from scratch. As with writing your own selector, if a snippet is used and cannot be found during execution, the search will fall back to ML selection.
When Force is checked, the test will fail during execution if the selector is not found.
JS Override Selector
Sometimes a basic selector is not enough to find an element on the page. In some scenarios you may want to calculate what to select or look for something that may not just jump around on the page, but change every time! Examples could range from drastically different A/B behavior to data that needs to be calculated. In these cases, we support writing your own JavaScript to return the desired element. 
Selector Options in Architect
Architect test creation offers the same options as found in Action Settings as well as a few more. Plus you have the advantage of seeing if your Selectors need adjustment as you set them to interact with exactly the right element.
NOTE: You may want to open the Chrome Developer Tools panel to assist in capturing XPath or CSS selectors for your elements if needed.
- Launch Architect by creating a New Test.
- While recording, open an Action by clicking the white circle on the left.
- Select the ADV Selector tab.
- Select the DOM panel or the Override panel. We'll go over each below.
DOM Panel
The DOM panel holds two options for fine-tuning your element selection which can be used in concert with each other to aid in precision.
Manual DOM Walk
- Select an element near the target element.
- Click the arrow icons to walk the DOM from the current element to your target element regardless of size or other overlapping elements. The Current Element box will update as you change your selection on the page. Click Save.
Define Selector
- Using Chrome Dev tools, copy the preferred selector (ID, Query Selector, CSS Class, etc.) of your element. If your specified input selector cannot be found during execution, the search will fall back to ML selection.
- In the text box, enter the copied selector. Click the Search button to verify. Click Save.
Define Selector + Manual DOM Walk
- Use them together! Enter a nearby element's selector in the text box, click Search to verify the choice. Then use the arrows to manually walk the DOM to the target element. Click Save.
Override Panel
The Override panel holds three options which can be used to override our machine learning selector if needed.
ML Selector
ML selector is our machine-learning based selector. It is enabled by default.
Specify Selector
Choose Specify Selector to identify another selector to use to locate the element. Define a specific CSS or XPath Selector for your element in the provided text box. If your specified input selector cannot be found during execution, the search will fall back to ML selection.
Where this differs from the DOM tab is the additional options of Snippet and Force. The Snippet button provides a list of automatically populated unique Selector Snippet options rather than writing selectors from scratch. When Force is enabled, the test will fail during execution if the selector is not found.
Define Selector
- Choose Specify Selector.
- Enter the desired element's selector in the text box. Click Validate to ensure you have the correct query selector. Click Save.
Selector Snippets
- Choose Specify Selector. Select your element on the site under test.
- Click the Snippet button to open the list of selectors provided for the element.
- Choose from the list of unique selectors provided in the Insert Selector window.
- The snippet will populate the text box. Selecting from the list of unique selectors does not require a validation. Click Save.
Force Selector
- Choose Specify Selector.
- Select your element on the site under test or define your own selector.
- Check the Force box. Click Save.
- When your test is executed, if the forced selector does not match to test creation, the Action will Fail.
JS Override Selector
- Choose JS Override Selector radio button to use a JavaScript selector.
- Click Edit to input the JS selector. The default code supports the element that you have selected as a starting point. We offer dynamic code here to assist in a JavaScript Override if there is ever an element selection issue.
- Input JavaScript to select the element used in this action. The example below has copied the JS path selector into the JavaScript Override field. This must return the JavaScript element that the script should interact with.
- Click Validate button to confirm the code returns the desired element. Click Save to return to the ADV Selector tab.
- Click Save in the ADV Selector tab to return to recording your test.
