Ranorex Spy - The path editor | Ranorex Studio User Guide
Help CenterUser GuideRanorex Studio advanced

The path editor

The path editor is the second main working environment in Ranorex Spy. It’s where you specify and edit the RanoreXPath of identified UI elements from the element tree. The path editor has several helpful functions to assist you in creating RanoreXPaths that fit your needs.

On this page, you’ll find out how the path editor works and what functions it offers.

In this chapter

    tipp icon

    Screencast

    The screencast “The path editor” walks you through information found in this chapter.:

    Watch the screencast now

    Access the path editor

    You can access the path editor in two ways: from the working environment selector within Spy, or directly from an opened repository.

    From Spy

    In the element tree, select a UI element.
    In the working environment selector, click PATH EDITOR.
    The path editor working environment appears with the UI element highlighted in the path tree section.

    Accessing path editor from within Spy

    From a repository

    In a repository, select a repository item and…

    click EDIT IN SPY.
    …right-click it and click Edit in Spy….

    Accessing path editor from within Studio

    Element could not be found

    A common error message that occurs when opening a UI element in the path editor as explained above is that the element couldn’t be found. This usually happens because the application containing the UI element isn’t currently running.

    Initial situation

    In a repository, select a repository item.
    Click EDIT IN SPY.
    The path editor opens with an error message and the path tree displays red marks, indicating that the respective UI elements specified by the RanoreXPath could not be found.

    Could not find element error

    Could not find element error

    Red symbols indicating that the respective UI elements specified by the RanoreXPath could not be found.
    Error message in the status bar of Spy indicating that the UI element could not be found.

    Solution

    Start the application containing the UI element(s).
    In the path editor, click the Refresh button to update the references to the UI elements.

    Solution to UI-element not found error

    Locked tree steps

    When opening a repository item in the path editor, its parent repository item limits what part of the RanoreXPath you can edit and what UI elements you can track. Any components of the RanoreXPath that specify the parent and above cannot be edited. UI elements at the same level or above the parent cannot be tracked.

    This is because changes at these locked levels would affect other repository items and potentially break existing RanoreXPaths. If you need to make changes to the parent repository item or above, edit those items specifically.

    Locked path editor tree level - part II

    EDIT IN SPY opens the repository item for editing in the path editor.
    The changes you can make to the RanoreXPath are limited by the parent repository item.

    Locked path editor tree level - part III

    The browser & results working environment displays the repository item in the element tree.
    The parent of the repository item has been set as the root element automatically. This element represents the limit for tracking and editing.
    In the path editor, all elements above and including the root element are locked for tracking and editing.
    All items below the root element can be tracked and edited.

    Path editor working environment

    The path editor working environment consists of the two basic Spy sections (red frame), two specific path editor sections (green frame), and a status indicator (orange frame).

    Path editor working environment

    Track button and RanoreXPath field. Explained in >Introduction.
    Working environment selector
    Path tree
    Displays the components of a UI element’s RanoreXPath in a tree structure.
    Refresh: Updates the tree to reflect changes in the respective application.
    Highlight: Highlights the UI element in the respective application.
    Both fail if the application isn’t running.

    Attribute specification
    Lists available UI-element attributes, operators, and values for use in the RanoreXPath.

    Status indicator
    Indicates how many UI elements the current RanoreXPath identifies.

    Edit the RanoreXPath

    The main application of the path editor is to support you in editing the RanoreXPath so as to make it more general or specific, depending on your needs. The section where you make the actual changes to the path is the RanoreXPath field. We’ve touched on it in the introduction to this chapter, but we’ll go into more detail here. Depending on whether you edit a UI element from the element tree or an already existing repository item from a repository, editing is a little different.

    When editing UI elements from the element tree, the path editor functions more like a search and allows you to easily see what UI elements a given RanoreXPath will identify. You can consider it a sandbox environment that doesn’t affect your test, unless you start adding identified UI elements to your repository.

    When editing existing repository items, you change your test. Therefore, the RanoreXPath field is a little more complex when doing so, as shown in the image below:

    Path editor line components

    The main yellow field is where you edit the RanoreXPath.
    The line below it displays the currently applied (valid) RanoreXPath specification, i.e. as it was before you started making changes.
    Parts of the RanoreXPath may be grayed out in the yellow field. This indicates they are locked and cannot be edited (see topic Locked tree steps further above).
    The APPLY button replaces the currently applied RanoreXPath (lower line) with the currently edited RanoreXPath (yellow field), closes Spy and returns to Ranorex Studio, where you will see the new path reflected in the repository item.

    RanoreXPath syntax support

    RanoreXPath syntax is fairly complex. The path editor has built-in syntax support to make editing easier.

    While editing aRanoreXPath, press Ctrl+Space.

    A drop-down list opens with semantically possible RanoreXPath syntax parts.

    Path editor RanoreXPath syntax support

    Selecting/deselecting path components

    Using the path tree, you can easily include or exclude specific components from a RanoreXPath. Simply select or deselect them and the path will be updated automatically. However, there are some limitations (see below).

    Selecting/deselcting path editor tree elements

    Checkboxes to select/deselect path components

    Try the following to see the effect this has:

    Select a component. It’s included in the RanoreXPath.
    Deselect the component. It’s excluded from the RanoreXPath, but also loses information, i.e. the adapter type and attribute.
    Re-select the component. The lost information is not recovered; the component is now a placeholder for any UI elements between the tabpage and radiobutton .

    Re-selection of path editor tree elements

    If information is lost this way, you can either retrack the UI element or add the information again manually.

    Tree context menu

    The context menu for components in the path tree lets you specify them in several ways:

    Path editor specifying tree elements

    Optional (?)
    Declares the component as optional, indicated by a ? in the RanoreXPath before the modified component. When a component is optional, it isn’t required for the path to work, i.e. the path will still work if nothing is found for the component. When placed between an adapter and an attribute, both become optional, meaning the path will work if both, just one, or neither identify a UI element.

    Axis
    Axes are relationship operators. They allow you to select UI elements by way of their relation to other UI elements.
    Possible axes:

    child Selects all children of the current node.
    descendant-or-self Selects all descendants (children, grandchildren, etc.) of the current node, and the node itself.
    ancestor Selects all ancestors (parents, grandparents, etc.) of the current node.
    self Selects the current node.
    descendant Selects all descendants (children, grandchildren, etc.) of the current node.
    parent Selects the parent of the current node.
    ancestor-or-self Selects all ancestors (parents, grandparents, etc.) of the current node, and the current node itself.
    preceding-sibling Selects all siblings before the current node.
    following-sibling Selects all siblings after the current node.

    Further reading

    Optional components and axes are part of RanoreXPath and explained in

    Ranorex Studio advanced > ⇢ RanoreXPath.

    Node name
    Allows you to assign a specific adapter to an element.

    Further reading

    Adapters, attributes, and values are explained in

    Ranorex Studio advanced > ⇢ UI elements.