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()

Window Declarations

A window declaration in Silk Test Classic cannot be executed for both agent types, Classic Agent and Open Agent, during the execution of a test. The window declaration will only be executed for one of the agent types.

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.