Elements | Ranorex Webtestit User Guide
WebtestitUser GuideElements


Each website or application consists of UI building blocks or elements. There are different forms of elements, like images, text, links, buttons, and so on. The UI logic defines the interaction possibilities with those elements. Your website’s or application’s business logic defines under which condition elements are visible, clickable, hidden, etc. We already noticed in the introduction, that the automation framework is in charge to identify the elements you want to inspect and either manipulate or assert them. To achieve this each element is identified by a selector.
Structure of this chapter


    Selectors are element locators within your website’s or app’s visual structure. In most modern UI description languages (like HTML) this structure is hierarchical. If you pass a selector to the automation framework, it will apply its rules to the currently active page and attempt to locate the element described by it.
    Note icon


    If an element can’t be located, it does not automatically have to result in a failed test. However, for reliable test execution, it is crucial to have robust selectors for your elements.
    Ranorex Webtestit supports your work with selectors in the following ways:
    • The Elements tab enables you to define and organize selectors of your Page Objects
    • You can validate existing selectors with Ranorex Selocity
    Each selector is represented as a string value that follows certain rulesets. Those rulesets are referred to as strategies.

    Types of selectors

    What does it take to locate an object reliably in your website or application? You might think that the easiest way would be to refer to each element through its unique ID. We totally agree on this one with you as well! But in reality there are often situations in which this does not work:
    • In many websites and applications the ID is not provided for every element
    • Some UI frameworks assign auto-generated, random IDs to each element
    • Dynamically generated objects in your applications can’t have fixed IDs
    For those cases where you can’t rely on the ID alone there are selector strategies in place that help you to locate an element depending on its placement within the UI hierarchy, or by other attributes it bears. Ranorex Webtestit supports the following selector strategies:
    • XPath – The XPath strategy allows you to traverse an HTML document hierarchically. It is based on the fact that each level of the HTML structure is analogous to a folder structure in your file system. For this reason, you can traverse the document top-down in order to locate an element. Find examples and a tutorial for XPath here.
    • CSS – You can use an element’s style description to locate it within the UI. CSS selectors are basically the same as you’d use to define styles for a website or application. You can find examples for CSS here.
    • link-text – A very simple strategy is link-text. It scans the contents of <a> tags in your application and searches for complete or partial matches. Note that this only works for hyperlinks.
    tipp icon


    The recommended order of element selectors is id > name > CSS > XPath. Keep this in mind to generate robust selectors for your tests.
    To create a selector you can use different approaches. Browsers like Google Chrome enable you to copy selectors to the clipboard from within their dev tools. You can also attempt to write them yourself by analyzing the website’s or app’s HTML structure. We strongly recommend you to use Ranorex Selocity. With the help of Ranorex Selocity you not only can create reliable selectors in a matter of seconds, but also verify if existing selectors still work. If you don’t have Ranorex Selocity installed yet, you can get help doing so by following ⇢ this guide.

    Creating and editing selectors with Ranorex Selocity

    To create a selector in Ranorex Selocity Open your SUT in Google Chrome Press F12 on your keyboard to open the DevTools Click the element select tool and select the item you would like to inspect In DevTools, switch to the Elements tab, there you’ll find the Ranorex Selocity tab You will see a list of selectors for your element

    The number next to each selector displays the number of matching elements for the specific strategy.

    You can edit a selector in Ranorex Selocity by clicking the Edit icon Modify and test selector section above and you can edit it freely.
    If you have Ranorex Webtestit running as well, you can click the Connect button in the bottom area to connect both applications. You can then use the button to send the selector  directly to Ranorex Webtestit. Elements and selectors are managed within the Elements tab in Ranorex Selocity.
    tipp icon


    In order to send a selector to Ranorex Webtestit you need to have an active Page Object opened. Read more about Page Objects here.
    Note icon


    When you use Ranorex Selocity to send your selector to Ranorex Webtestit, you will not only get an element automatically created for you, but also get a screenshot of it.


    Like to know more about Ranorex Selocity? Head over to the official site here.

    The elements tab in Ranorex Webtestit

    The Elements tab is used to manage the elements and selectors within a Page Object. It is synced with the currently open Page Object.
    + button Click to create a new element+ button Click to create a new element Element Click the name to expand the element’s Attributes Name: the name of the element when referred to in code Selector: the selector used to locate the element Strategy: the selector strategy used to locate the element Screenshot Indicator If enabled, indicates that there is a screenshot available for this element. Hover the mouse over this indicator to see the screenshot. Click to open the screenshot. Code reference Click to jump to the definition of the element in code. Delete button Click to delete the element. This only works if the element is not used anywhere in your project. Edit with Ranorex Selocity Click to send the element’s selector to Ranorex Selocity. You can use Ranorex Selocity to modify and test the selector. This only works if Ranorex Webtestit is connected to Ranorex Selocity. Close button Click to close the element’s details. Ranorex Selocity Connection Indicates the status of the connection between Ranorex Webtestit and Ranorex Seloctiy.

    Adding an element manually

    To add a new element to the currently active Page Object file
    Click the + button In the newly created element stub:

    Provide the Name

    Fill in the Selector

    Select the Strategy to use

    Click the Close button

    Managing multiple selectors for CSS strategies

    If you are using CSS as a strategy, you can specify multiple selectors to identify your element within your SUT. You will notice there is an Additional Selector field located. You can click the + button to add even more selectors if needed. You can click the button to remove the selector in that respective line.

    File synchronization

    The Elements tab in Ranorex Webtestit is synched with the Page Object file. As an alternative to using the UI, you can edit the Page Object file directly. The changes are being reflected back to the Elements tab as you type.

    Providing screenshots manually

    You can provide your own screenshots for manual and/or automatically generate elements. There is a screenshots folder in your project structure, which contains all the screenshots that are being generated automatically. You can provide your own screenshots in this folder, or specify a different location.
    tipp icon


    If you don’t see the screenshots folder in your project, click the button in the Project tab to show all files. If you still don’t see the folder, it’s because you don’t have any screenshots yet. Create the folder manually in this case.

    To add a screenshot for an element

    Locate the element in the Page Object’s source code Add a decorator comment above it: // Additional data: {"img":"your/path/your_filename.png"} Replace your/path/your_filename.png with the actual location of your screenshot If the path to the image file can be resolved successfully, Ranorex Webtestit will immediately activate the screenshot Indicator for the element you just edited.