Why You Might Use WinAppDriver (WAD) UIRecorder

Cycle native app steps using WinAppDriver allow for the use of several object locator types to identify objects within the app.

Whenever possible, it is best to identify application objects using the WinAppDriver supported locator types: id, automationID, name, or controlType. However, sometimes you may find it necessary to identify native app objects using the xPath locator type when the supported locator types are not unique for a specific application object.

For example, there may be several objects using the same locators within the same application but in different forms, panes, or data grids. In those instances, you will more than likely need to use xPath to identify the location of those objects and ensure Cycle is interacting with the correct object.

The syntax of xPath in native app steps is similar to the syntax in web steps. Tools such as the Inspect Console within the Chrome web browser are useful to help construct and validate xPaths for web driver steps, but there is no similar tool included in Inspect.exe.

There is a separate tool called WinAppDriver (WAD) UI Recorder that can be used to retrieve an absolute xPath that WinAppDriver can use to locate an object. WAD UI Recorder will record the absolute xPath for an application object on mouse hover or click. You can then make some slight modifications to the recorded absolute xPath for use within your Cycle step.

You can also use the absolute xPath recorded in WAD UI Recorder to help you construct a relative xPath that may be more readable and manageable within your Cycle steps.

The WAD UIRecorder download can be found here.

Steps for Recording an Absolute xPath

It is important to always run WAD UI Recorder as administrator. You may not be able to record object xPaths in some applications if you are not running WAD UI Recorder as admin.

The absolute xPath recorded by the tool is not immediately usable in your Cycle step. There are some modifications that need to be made to the xPath to make it usable within Cycle.

• Run WAD UI Recorder as administrator. The application window below will open on your desktop.

The top panel will display the absolute xPath recorded by the application. This is where the xPath we will use in Cycle is generated.

The bottom panel displays xPath node information.

There are also buttons located at the bottom of the window used to Record and Clear the panels. The Record button will change to a Pause button while recording is in progress.

• Click the Record button to start recording xPath. The WAD UI Recorder will now start recording xPaths of any object you interact with on your desktop.

• Hover your mouse over or click on the object in your target application to generate the absolute xPath. The xPath appears in the top panel of WAD UI Recorder. Clicking Pause will stop WAD UI Recorder from recording xPath for any additional objects clicked on your desktop.

Object clicked:

xPath recorded in WAD UI Recorder:

"/Window[@Name='JDA Solutions'][@AutomationId='frmDLx']
/Group[@AutomationId='pnlBackground']/Group[@AutomationId='pnlGradient']
/Group[@AutomationId='pnlHost']/Pane[@AutomationId='controlHost']
/Pane[starts-with(@AutomationId,'shpmstdsp')]/Pane[@AutomationId='pnlRecord']
/Tab[@AutomationId='tabDtl']/Pane[@Name='Inventory']
[@AutomationId='tabInventory']/Custom[@AutomationId='gridInvLoads']
/Table[@Name='MainView'][@AutomationId='GridView:Parent=Control']
/DataItem[@Name='0'][starts-with(@AutomationId,'Row:Handle=')]
/Text[@Name='0'][@AutomationId='Cell:Row=0,Column=0']"

The absolute xPath will need to be modified in order to use it in your Cycle native app step. You will need to replace the escaped double quote characters with single quotes and change the starting point of the xPath.

• Copy the xPath from the top panel of WAD UIRecorder and paste it into your text editor of choice.

• Find all instances of escaped double quotes (  \" ) and replace with single quotes ( ' )

• Remove the "Desktop" portion from the absolute xPath. This portion of the xPath is not necessary and will cause WinAppDriver to not find the object because you have already connected directly to the application within Cycle.

The portion of the xPath you need to remove is highlighted below:

The xPath should look like this after modification:

• Copy and paste the xpath into your Cycle step. Be sure to include the 'xPath:' locator type before the xPath itself.

• The Cycle can now find your object within the application.

Creating a Relative xPath

You can also use WAD UI Recorder to help you build a relative xPath. You may find relative xPath to be easier to read and manage within your features.

Follow the steps above to format the absolute xPath properly for your Cycle step. Then search for opportunities to eliminate unnecessary portions of the xPath while still ensuring your relative xPath will allow Cycle to identify the correct object.

Here is a relative xPath identifying the same application object that we identified using the absolute xPath we previously recorded.

"//*[@Name='JDA Solutions']//*[starts-with(@AutomationId,'shpmstdsp')]
//*[@AutomationId='tabInventory']//*[@AutomationId='gridInvLoads']
//*[@Name='MainView']//*[@AutomationId='Cell:Row=0,Column=0']" 

Copy and paste the relative xPath into your Cycle step.

Cycle can now see the object using the relative xPath.