Native app steps and xPath

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.

The usage of xPath with native app steps is similar to xPath usage when testing web applications with web driver steps.

You can identify an application object by defining an absolute xPath from the application root down to a specific target object. Or you can define a relative xpath using object locators to define a starting point and then search for parents, children, and siblings to identify the specific target object.

Considerations when using xPath

There are several considerations to keep in mind when using xPath locators with native app testing:

• Speed - xPath identification by WinAppDriver is slower than using the supported locator types: id, automationID, name, or controlType.

You will find that steps using an xPath, whether relative or absolute, will take longer to run that steps using the supported locator types. This is due to WinAppDriver itself and how it searches for objects using xPath. Using xPath takes a considerable amount of overhead and directly impacts performance.

• Limited locators - Not all attributes of an object are available for use as locators when defining your xPath.

For example, a check box might have the following attribute:

Toggle.ToggleState

The xPath locators that WinAppDriver can identify do not include the attribute Toggle.ToggleState.

As a result, WinAppDriver will fail to identify the object if you use the xPath below.

And I see object "xPath://*[Toggle.ToggleState='1']" in app

• Absolute xPath vs Relative xPath - There may not be much of a performance improvement from using absolute xPath rather than using relative xPath. Using an absolute xPath may give you a slight to negligible increase in performance. But, absolute xPath can ensure you are selecting the correct object when many objects share the same locator attributes.

• Case sensitive - Letter case is important in xPath. You need to match the letter case for the locator within your xPath with the letter case as displayed in Inspect.exe.

Instructions on how to use Inspect.exe to identify locators for native app steps can be found here.

For example, the xPath below will fail because the AutomationId does not follow the letter case as seen in Inspect.exe.

And I see object "xPath://*[@automationid='my object']" in app

The WinAppDriver could identify the object using the xPath below.

And I see object "xPath://*[@AutomationId='my object']" in app

Tips for using xPath

• You can decrease the speed that WinAppDriver takes to identify an object on screen by reducing the number of objects in the open application.

For applications that return a results grid with potentially thousands of rows, this means you should use search criteria and filters to reduce the number of results in a data results grid before using xPath to identify a specific object within the application.

Remember that more objects in the app means it will take more time for WinAppDriver to find an object using xPath.

• Some applications such as the JDA WMS Client GUI allow multiple screens to be open within the GUI at one time. These screens may not be visible in the GUI, but they are still open in the application and all of the objects on those screens are still visible to WinAppDriver. This means WinAppDriver will search all of those objects when you use an xPath locator.

For example, you may have Shipment Display and Inventory Display open within the same client GUI instance. Even though you may only be able to see the Shipment Display screen, WinAppDriver will examine all of the objects within the application when using an xPath locator type. If you want to find an object in Shipment Display, WinAppDriver will search all objects in Shipment Display and Inventory Display. As more screens are opened, the step will take longer to return a result.

Limit the number of open screens at any given time to only those that are needed for the test. If more than one screen must be open, be sure to limit the number of items displayed in the data result grids by clearing the grids and/or filtering results before running the Cycle step that uses the xPath locator.

• You may notice your Cycle step is identifying objects in the wrong form or data result grid within the application. This means you will need to be more specific within your xPath to ensure WinAppDriver is looking for your object in the correct location within the application.

For example, you may identify an xPath such as the one below to locate the first cell in a data result grid.

And I see object "xPath://*[@AutomationId='Cell:Row=0,Column=0']" in app

It is possible that one screen may have multiple data result grids that all have the same AutomationId for the first cell in the grid, AutomationId='Cell:Row=0,Column=0'.

The application may also have other non-visible screens open that have data grids with the same AutomationID present in them.

In these instances, your xPath will need to be as specific as possible to ensure Cycle is interacting with the intended object.

Here is an example of a relative xPath identifying the first cell of the main data results grid on the Shipment Display screen.

And I see object "xPath://*[@AutomationId='shpmstdsp1']
//*[@AutomationId='gridMst']//*[@AutomationId='Cell:Row=0,Column=0']" in app

Alternatively, you can use absolute xPath to ensure you are selecting the correct object.

Absolute xPath requires the xPath definition starting at the root of the application all the way down to the object you want to identify.

This means absolute xPath will usually appear more complex than a relative xPath, and it can be much more difficult to write your Cycle step since you have to define the entire xPath.

The xPath below is an example of an absolute xPath that will select the first row and column in the Shipment Display main data results grid.

And I see object "xPath:/Window[@Name='JDA Solutions'][@AutomationId='frmDLx']
/Group[@AutomationId='pnlBackground']/Group[@AutomationId='pnlGradient']
/Group[@AutomationId='pnlHost']/Pane[@AutomationId='controlHost']
/Pane[starts-with(@AutomationId,'shpmstdsp')]/Custom[@AutomationId='gridMst']
/Table[@Name='MainView'][@AutomationId='GridView:Parent=Control']
/DataItem[@Name='0'][starts-with(@AutomationId,'Row:Handle=')]
/Text[@Name='0'][@AutomationId='Cell:Row=0,Column=0']" in app

• You can use the WinAppDriver UI Recorder tool running in administrator mode to find absolute xPaths or to help you construct better relative xPaths.

WinAppDriver UI Recorder can be downloaded here.