UIItem Identification
Managed UI applications have a mechanism for identifying controls by specifying them names. These names are available for finding controls on using UIAutomation API. Name property used while developing application show up as AutomationId when using UIA API.
Un-managed applications donot have such feature. In these applications the controls are usually identified by text (white terminology) (name in UIA terminology).
Within a window any UIItem can be identified based combination following criteria.
1. AutomationId is the programmatic identifier specified by the AppDeveloper. In WinForm and WPF this is the name supplied to the control. This is not present for SWT and Win32 applications. (applies only to .NET applications WinForm, WPF, Silverlight.)
For managed applications:
SearchCriteria searchCriteria = SearchCriteria.ByAutomationId("btnOK");
Button button = window.Get<Button>("btnOK"); //default search mechanism is by automation id
button = window.Get<Button>(searchCriteria); // is same as above
For un-managed applications:
Button button = window.Get<Button>("OK"); //default search mechanism is by UIAutomation name
button = window.Get<Button>(SearchCriteria.ByText("OK")); // same as above
2. UIItem type (e.g. Button, ComoboBox)
Button button = window.Get<Button>("btnOK"); //<Button> acts as criteria as well as the return type
button=(Button)window.Get(SearchCriteria.ByAutomationId("btnOK").AndControlType(typeof(Button))); // same as above
3. ControlType is the ControlType defined in UIAutomation. Since this is same as above these shouldn't be a reason to use this
button=(Button)window.Get(SearchCriteria.ByControlType(ControlType.Button).AndAutomationId("btnOK"));
4. Text is the additional property defined for accessibility purposes. This property maps to some attribute on UIItem which is visible on the control. Find the detailed map here:
button = window.Get<Button>(SearchCriteria.ByText("OK")); //OK is the display text on the button.
This is much more readable from testing point of view, as it is obvious which button we are interested in. The problem is that in an evolving application the text changes more frequently than the automation id.
5. Zero based Index of UIItem in case multiple UIItems have same identification based on other parameters. Index is measured from top left corner of the window X first and Y second.
// if there are two buttons with the same automation id.
button = window.Get<Button>(SearchCriteria.ByAutomationId("btnOK").AndIndex(1));
6. Searching based on any UIA property.
button=window.Get<Button>(SearchCriteria.ByNativeProperty(AutomationElement.AutomationIdProperty, "btnOK"));
The Get method on window can be used only to find PrimaryUIItems. All the primary UIItems are shown with Object Structure. The idea behind the API is to find the primary UIItems first and then work with their specific child items if any.