Overview of the Locator Keyword

Traditional Silk Test Classic scripts that use the Classic Agent use hierarchical object recognition. When you record a script that uses hierarchical object recognition, Silk Test Classic creates an include (.inc) file that contains window declarations and tags for the GUI objects that you are testing. Essentially, the INC file serves as a central global, repository of information about the application under test. It contains all the data structures that support your test cases and test scripts.

When you record a test case with the Open Agent, Silk Test Classic creates locator keywords in an INC file to create scripts that use dynamic object recognition and window declarations. The locator is the actual name of the object, as opposed to the identifier, which is the logical name. Silk Test Classic uses the locator to identify objects in the application when executing test cases. Test cases never use the locator to refer to an object; they always use the identifier.

You can also manually create test cases that use dynamic object recognition without locator keywords. Dynamic object recognition uses a Find or FindAll function and an XPath query to locate the objects that you want to test. No include file, window declaration, or tags are required.

The advantages of using locators with an INC file include:

You combine the advantages of INC files with the advantages of dynamic object recognition. For example, scripts can use window names in the same manner as traditional, Silk Test Classic tag-based scripts and leverage the power of XPath queries.
Enhancing legacy INC files with locators facilitates a smooth transition from using hierarchical object recognition to new scripts that use dynamic object recognition. You use dynamic object recognition but your scripts look and feel like traditional, Silk Test Classic tag-based scripts that use hierarchical object recognition.
You can use AutoComplete to assist in script creation. AutoComplete requires an INC file.

Syntax

The syntax for the locator keyword is:

[gui-specifier] locator locator-string

where locator-string is an XPath string. The XPath string is the same locator string that is used for the Find or FindAll functions.

Example

The following example shows a window declaration that uses locators:

window MainWin TestApplication
  locator "//MainWin[@caption='Test Application']"
  
  // The working directory of the application when it is invoked
  const sDir = "{SYS_GetEnv("SEGUE_HOME")}"
  
  // The command line used to invoke the application
  const sCmdLine = """{SYS_GetEnv("SEGUE_HOME")}testapp.exe"""
  
  Menu Control
    locator "//Menu[@caption='Control']"
    MenuItem CheckBox
      locator "//MenuItem[@caption='Check box']"
    MenuItem ComboBox
      locator "//MenuItem[@caption='Combo box']"
    MenuItem ListBox
      locator "//MenuItem[@caption='List box']"
    MenuItem PopupList
      locator "//MenuItem[@caption='Popup list']"
    MenuItem PushButton
      locator "//MenuItem[@caption='Push button']"
    MenuItem RadioButton
      locator "//MenuItem[@caption='Radio button']"
    MenuItem ListView
      locator "//MenuItem[@caption='List view']"
    MenuItem PageList
      locator "//MenuItem[@caption='Page list']"
    MenuItem UpDown
      locator "//MenuItem[@caption='Up-Down']"
    MenuItem TreeView
      locator "//MenuItem[@caption='Tree view']"
    MenuItem Textfield
      locator "//MenuItem[@caption='Textfield']"
    MenuItem StaticText
      locator "//MenuItem[@caption='Static text']"
    MenuItem TracKBar
      locator "//MenuItem[@caption='Track bar']"
    MenuItem ToolBar
      locator "//MenuItem[@caption='Tool bar']"
    MenuItem Scrollbar
      locator "//MenuItem[@caption='Scrollbar']"

  DialogBox CheckBox
    locator "//DialogBox[@caption='Check Box']"
    CheckBox TheCheckBox
      locator "//CheckBox[@caption='The check box']"
    PushButton Exit
      locator "//PushButton[@caption='Exit']"

For example, if the script uses a menu item like this:

TestApplication.Control.TreeView.Pick()

Then the menu item is resolved by using dynamic object recognition Find calls using XPath locator strings.

The above statement is equivalent to:

Desktop.Find(“//MainWin[@caption='Test Application']
  //Menu[@caption='Control']//MenuItem[@caption='Tree view']”).Pick()

Locator String Syntax

For convenience, you can use shortened forms for the XPath locator strings. Silk Test Classic automatically expands the syntax to use full XPath strings when you run a script. You can omit:

The hierarchy separator, “.//”. Silk Test Classic defaults to using “//”.
The class name. Silk Test Classic defaults to the class name of the window that contains the locator.
The surrounding square brackets of the attributes,"[ ]".
The “@caption=’” if the xPath string refers to the caption.

The following locators are equivalent:

Menu Control
  //locator "//Menu[@caption='Control']"
  //locator "Menu[@caption='Control']"
  //locator "[@caption='Control']"
  //locator "@caption='Control'"
  locator "Control"

You can use shortened forms for the XPath locator strings only when you use an INC file. For scripts that use dynamic object recognition without an INC file, you must use full XPath strings.

Window Hierarchies

You can create window hierarchies without locator strings. In the following example, the “Menu Control” acts only as a logical hierarchy, used to provide the INC file with more structure. “Menu Control” does not contribute to finding the elements further down the hierarchy.

window MainWin TestApplication
  locator "//MainWin[@caption='Test Application']"
  Menu Control
    MenuItem TreeView
      locator "//MenuItem[@caption='Tree view']"

In this case, the statement:

TestApplication.Control.TreeView.Pick()

is equivalent to:

Desktop.Find(“.//MainWin[@caption='Test Application']
  //MenuItem[@caption='Tree view']”).Pick()

Including Locators and Tags in the Same Window Declaration

You can include locators and tags in the same window declaration. For example:

window MainWin TestApplication
  locator "Test Application"
  tag "Test Application"
  Menu Control
    tag "Control"
    MenuItem TreeView
      locator "Tree view"
      tag "Tree view"

The following rules determine if locators or tags are used for resolving the window at runtime:

When replaying a script on the Classic Agent, only tags are used. Locators are never used with the Classic Agent.
When replaying a script on the Open Agent, locators are used if a locator is present for the bottom-most window in the hierarchy and the Prefer Locator check box is checked in the General Options dialog box. By default, the Prefer Locator check box is checked.
If the top-most window specifies a locator, the Open Agent is used.

In the preceding example, TestApplication.Control.Open() uses tags for resolving because the Menu Control does not specify a locator.

TestApplication.Control.TreeView.Pick() uses locators for resolving because the MenuItem TreeView specifies a locator and the Prefer Locator check box is checked.

Expressions

You can use expressions in locators. For example, you can specify:

STRING getSWTVersion()
  return SYS_GETENV("SWT_VERSION")
window Shell SwtTestApplication
  locator "SWT {getSWTVersion()} Test Application"

Comparing the Locator Keyword to the Tag Keyword

The syntax of locators is identical to the syntax of the tag keyword.

The overall rules for locators are the same as for tags. There can be only one locator per window, except for different gui-specifiers, in this case there can be only one locator per gui-specifier.

You can use expressions in locators and tags.

The locator keyword requires a script that uses the Open Agent while the tag keyword requires a script that uses the Classic Agent.