Using bytext and byname locators

byname and bytext is universal feature common for Web, UI Automation and WinForms (Managed) targets.

byname

Suppose we have an object for the learned CE button in the Windows Calculator:

CE Button

We used UI Automation library for recording and got learned object like this:

CE Button Locator

We can see that location No id/No id/No id[1]/Clear entry contains objects without Name/ID. However the object we look for does have Name (ID). So we may make location simpler:

CE Button ByName

This will find the object with same 'Name' (Automation ID, if matching) value in the UI Automation tree:

UIA Name

This locator will survive if application structure changes but object name stays the same.

Sometimes elements tree is very deep and whole search for the object may take long time. For this case there is special syntax:

byname:N where N is an integer number defining the depth. By default byname logic assumes that default depth is 10. Sometimes you may need to have deeper search, i.e. byname:25 and sometimes it makes sense to limit the depth like byname:5.

bytext

For UI Automation the 'Text' property of the learned object is always empty. However one may set it and set locator to search for it using statement bytext, i.e.:

CE Button ByText

API Use

Similar functionality may be accessed from API. For example, to speed up the search we may learn some container object and then search for an item within it. For example, we just learned library navigation pane of the Windows Media player:

WMP

An object learned as follows:

WMPPaneObject

It contains a number of items. We may find and click node by its name using DoFindByText entry point:

var found = SeS('Library_Navigation_Pane').DoFindByText('Videos');
    
if(found)
{
    found.DoClick();
}

This piece of script will find 'Videos' node within 'Library_Navigation_Pane' object. If it is found, then we click on it.