Searching for test objects

You can search for one or more test objects that match specified search criteria. The search is based on name/value pairs that represent properties of the test object or test objects you are looking for. The search can either be global, or limited to children of a parent test object.

A RootTestObject object represents a global view of the software being tested. To perform a global search, you invoke the find method on the RootTestObject object. Invoking a find method on a test object only searches the children of that test object.

The first argument in the find method is a subitem for the search properties. The second optional argument is a flag that indicates whether only children that might be included in the test object map should be searched. The following values for the property subitems are valid:

  • atProperty -- A name/value pair representing a test object property
  • atChild -- One or more properties that must be matched against the direct child of the starting test object
  • atDescendant -- One or more properties that can be matched against any child of the starting test object
  • atList -- A sequential list of properties to match against. These subitems for the atList value are valid:
    • atChild
    • atDescendant
    • atProperty
  • The first list item is matched against to get a list of candidates, and out of those candidates, their descendants are matched against for the next list item, and so on.

Special properties apply to the RootTestObject.find method, including these properties:

  • .processName : This top-level property has two functions:
    • Dynamically enable the processes with that process name
    • Constrain the find method to only look in processes with that name
  • .processId: This top-level property has two functions:
    • Dynamically enable the processes with that process ID (pid)
    • Constrain the find to only look in processes with that process ID (pid)
    Note: The .processId property is valid for dynamically enabled domains like Microsoft .NET and Windows. It is not valid for enabled domains, such as HTML and Java.
  • .domain: This flag specifies to only search in top-level domains that match the domain property
  • .hWnd: When the hWnd property is used for the search, if the "Win" .domain property is also specified, the matching window is enabled for testing with the Windows® domain.
  • Handle: When the window handle property is used for the search, if the "Net" .domain property is also specified, the matching window is enabled for testing with the Microsoft .NET domain.
Examples:

TestObject[] foundTOs ;
RootTestObject root = RootTestObject.getRootTestObject() ;
// Find all top-level windows in the Windows domain that have the caption "My Document"
CaptionText caption = new CaptionText("My Document") ;
foundTOs = root.find(atChild(".domain", "Win", ".caption",
     caption)) ;

// Find any dialogs, and then return their children "OK" buttons.
RegularExpression dialogRE = new
     RegularExpression("*dialog", false) ;
RegularExpression buttonRE = new
     RegularExpression("*button", false) ;
foundTOs = root.find(atList(atDescendant(".class",
                     dialogRE), 
                     atChild(".class", buttonRE,".value", 
                     "OK"))) ;

// Start Notepad, dynamically enable that process, find its top-level window that matches the process ID and get its descendant text window.
	ProcessTestObject p1 = StartApp("Notepad") ;
	Integer pid = new Integer((int)p1.getProcessId()) ;
	foundTOs = root.find(atList(atProperty(".processId",
     pid), atDescendant(".class", ".text"))) ;
 
// This enables a Windows application with the provided window handle and returns a test object that represents the window.
Long hWnd = getAppsHwnd();
foundTOs = root.find(atChild(".hwnd", hWnd, ".domain", "Win"));

// This enables a .NET application  with the provided window handle and returns a test object that represents the window.
Long handle = getAppsHwnd();
foundTOs = root.find(atChild("Handle", handle, ".domain", "Net"));

Test UI dynamically enables the Windows and .NET applications by using the .processName property. To find the required test object on a Windows or .NET application, use the .processName property in the query.

Example: The following example code finds the number 9 button in a calculator and then clicks it.
 Property[] props = new Property[4];
        // Find the top-level window of calculator application
        props[0] = new Property(".processName", "calc.exe");
        props[1] = new Property(".class","SciCalc");
        props[2] = new Property(".name", "Calculator");
        props[3] = new Property(".text", "Calculator");
        TestObject[] tos = find(atChild(props));
       
        if(tos.length > 0)
        {
            // Find button that contains the text 9
            props = new Property[3];
            props[0] = new Property(".class","Button");
            props[1] = new Property(".name", "9");
            props[2] = new Property(".text", "9");
            TestObject[] tos9 = tos[0].find(atChild(props));

            if(tos9.length > 0)
            {
                // Click button 9
                ((GuiTestObject)tos9[0]).click();
							//unregister
							tos9[0].unregister();
            }
        }
You can use this sample code to verify the number of open browser instances, the state of each browser instance, and the number of open browser tabs in each browser instance:
public class BrowserLength extends BrowserLengthHelper
{
    /**
     * Script Name   : BrowserLength     
	 * Generated      : Mar 2, 2012 6:09:06 PM     
	 * Description   : Functional Test Script      
	 * Original Host : WinNT Version 5.1  Build 2600 (S)      
	 *       
	 * @since  2012/03/02      
	 * @author      Functional Test User
	 */     
	public void testMain(Object[] args)      
{                  
			findNumberofBrowser_tab();                  
			}           
	private void findNumberofBrowser_tab() {         
		// TODO Auto-generated method stub         
		TestObject[] browsers = RootTestObject.getRootTestObject().find(atChild(".class","Html.HtmlBrowser"));         
		System.out.println("No. of browser instances found: "+browsers.length);                  
		for(int i=0;i<browsers.length;i++){
			 sleep(5);
            BrowserTestObject browser = (BrowserTestObject) browsers[i];
            System.out.println("State of the browser instance "+ " is: "+browser.getProperty(".readyState").toString());
            TestObject[] t = browser.find(atDescendant(".class", "Html.HtmlBrowser.Tab"));
            System.out.println("No. of Html.HtmlBrowser.Tab found in the browser instance "+ " is: "+(t.length-1));
                    
    }
    }
}
This code returns these results:

Number of browser instances found:

State of the browser instance <instance number> is:

Number of Html.HtmlBrowser.Tab values found in the browser instance <instance number> is: