In mabl, you can create custom find steps that find elements on the page using a CSS query or an XPath expression. There are two types of custom find steps:
- Find a specific element: Perform an action, such as click or hover, on the first or last element that matches a CSS query or XPath expression.
- Count the number of elements: Find all elements on the page that match a CSS query or XPath expression. Make an assertion on the number of elements or store the number in a variable.
Finding elements in a shadow DOM
Only CSS queries can target elements in a shadow DOM. For more information on testing in the shadow DOM, check out this guide.
In most cases, using recorded actions and Configure Find is the preferred method for interacting with an application in the mabl Trainer. mabl's native find capabilities facilitate more resilient tests that are easier to maintain. However, if the need arises, custom find steps give you the option to find page elements using CSS or XPath.
This guide describes use cases, setup, and supported actions for custom find steps.
Use cases
Finding a specific element
Custom find steps can find the first or last element on a page that matches a CSS query or XPath expression and interact with that element. Supported custom find interactions include:
- Click actions: click, double click, right click
- Entering text
- Making an assertion
- Creating a variable
- Hover steps
- Selecting an option from a dropdown
- Sending keypresses
- File uploads
- Drag and drop actions
Try Configure Find first
Before you use a CSS query or XPath expression to find a specific element and interact with it, try using Configure Find to tell mabl what attributes the element that you are looking for should have.
Configure Find handles a lot of the same use cases as steps that use CSS or XPath while also being more maintainable, since you don't need to know CSS or XPath to troubleshoot the step if something goes wrong.
You can use custom find steps with CSS and XPath to target elements that are tricky to find, including:
- Elements whose distinguishing attributes do not appear in Configure Find
- Elements that can only be identified in relation to another, non-ancestor element, such as a
<div>that is adjacent to a<div> with a specific word in it - Elements that do not contain certain text, such as a button that does not start with the word "Submit":
//button[not(starts-with(text(),"Submit"))] - The n-th element in a set of very similar elements that frequently changes and has no other distinguishing attributes, such as the fifth row of a table with very similar rows.
Custom find limitations
Custom find steps lack the following features:
Counting the number elements
Finding all the elements that match a CSS query or XPath expression can be useful in the following testing scenarios:
| Scenario | Example |
|---|---|
| Determining the number of elements to loop over | You want to check off all the checkboxes in a list. |
| Asserting that there is a specific number of elements. | You want to confirm that the search results page displays 50 results by default. |
| Confirming that a page filter reduces a list to the correct number of elements. | You want to confirm that 20 results are displayed when you select "20" from a page filter. |
Verify that there are no elements in the page that contain specific text: //*[text()[contains(.,”{{@myVar}}”)]]
|
You want to make sure the word "journey" does not appear anywhere on the page. |
Setup
To create a custom find step in the mabl Trainer, take the following steps:
- Click on the plus sign to add a new step.
Adding a step in the mabl Trainer
- Select Find elements to open the find elements menu:
The Find Elements menu
- Select a Find type:
- "First element": find the first element that matches your CSS or XPath query.
- "Last element": find the last element that matches your CSS or XPath query.
- "Number of elements": count the number of elements that match your CSS or XPath query.
- Select a Query type: CSS or XPath.
- Enter a CSS query or XPath expression in the Query field. When you enter the query, mabl identifies matching elements on the current browser page.
Identifying matching elements in the mabl Trainer
mabl variable syntax
Custom find steps may use mabl variable syntax in the query.
For example, a query may use a variable called sample_var to find a <div> element by its class as follows:
- CSS:
div.{{@sample_var}} - XPath:
//div[@class="{{@sample_var}}"]
- Select an Action. See the following section on supported actions for more details.
Supported actions in the Find Elements menu
When you finish configuring the step, click OK to save the step and play it back in the Trainer.
Supported actions
This section outlines which actions are supported by custom find steps.
Click actions
Custom find click actions include click, double-click, and right-click. These actions require no additional steps besides providing the correct CSS or XPath query to target the correct element.
Enter text
For a custom find step that enters text, provide the text in the Text to enter field.
Make assertion
mabl supports custom find assertions for all custom find types:
- Finding a specific element: "First element" and "Last element"
- Counting the number of elements: "Number of elements."
If the custom find assertion targets a specific element with CSS or XPath, you can use the element assertion menu to configure the assertion.
If the custom find assertion counts the number of elements matching a CSS or XPath query, you can assert against the count with a string or variable.
Create variable
mabl supports custom find variables for all custom find types:
- Finding a specific element: "First element" and "Last element"
- Counting the number of elements: "Number of elements"
If the custom find variable targets a specific element with CSS or XPath, you can store a property of the target element in a variable. For example, you could target an element using CSS or XPath and store its innerText in a variable.
If the custom find variable counts the number of elements matching a CSS or XPath query, you can store the total number of matching elements in a variable.
Hover steps
Custom find hover steps require no additional steps besides providing the correct CSS or XPath query to target the correct element.
Selecting option
Custom find select actions interact with dropdowns that use the <select> and <option> tags. There are two types of custom find select actions:
- Select the <option> where the attribute
- Select any option
If you choose "Select the <option> where the attribute", you can configure the step to choose an option in the dropdown based on one of the following attributes:
- Value: Select the option whose value equals a given string or variable.
- Text: Select the option whose text equals a given string or variable.
- Position: Select the option by its order in the dropdown. For example, select the third option in the dropdown.
If you choose "Select any option", mabl selects an unspecified option from the available options.
Send keypress
To create a custom find keypress step, select "Send keypress" in the Find Elements menu and click on the Next button.
The Trainer window loads a keypress menu where you can configure the step. For more information on creating custom find keypress steps, check out the guide to recording keypresses.
Drag and drop
Drag and drop steps are supported as recorded actions in the mabl Trainer. If you need to create drag and drop actions using CSS or XPath, combine these two custom find actions:
- Click and hold: target the element that you want to move
- Release: target the element where you want the first element to move to