IBM Rational Functional Tester
Version 6.1
IBM Rational Functional Tester API Reference

Project Version 2.0

com.rational.test.ft.object.interfaces
Class RootTestObject

java.lang.Object
  extended bycom.rational.test.ft.object.interfaces.TestObject
      extended bycom.rational.test.ft.object.interfaces.RootTestObject

public class RootTestObject
extends TestObject

The RootTestObject represents a global view of the system being tested. It does not represent an actual TestObject in the software under test, but rather it provides access to system-wide functionality, such as finding an arbitrary TestObject based on properties, location, or getting the DomainTestObject.


Method Summary
 void emitLowLevelEvent(LowLevelEvent event)
          Plays back a low level event.
 void emitLowLevelEvent(LowLevelEvent[] events)
          Plays back a sequence of low level events.
 boolean enableForTesting(int processId)
          Enables the process with processId for testing.
 boolean enableForTesting(long windowHandle)
          Enables the process with window windowHandle for testing.
 boolean enableForTesting(java.lang.String processName)
          Enables the process(es) with name processName for testing.
 boolean exists()
          The RootTestObject is always available.
 TestObject[] find(Subitem properties)
          Finds all candidates that match given search criteria.
 TestObject[] find(Subitem properties, boolean mappableOnly)
          Finds all candidates that match the given search criteria.
 DomainTestObject[] getDomains()
          Returns an array of all the domains that can be tested in the system.
static RootTestObject getRootTestObject()
          Gets the RootTestObject.
 IScreen getScreen()
          Returns an interface to the screen object.
 java.awt.image.BufferedImage getScreenSnapshot()
          Takes a snapshot (screen capture) of the entire desktop
 java.awt.image.BufferedImage getScreenSnapshot(java.awt.Rectangle rect)
          Takes a snapshot (screen capture) of the specified portion of the desktop
 IWindow[] getTopWindows()
          Returns an array of IWindows.
 GuiTestObject objectAtPoint(java.awt.Point screenPt)
          Returns a GuiTestObject for the object at the specified screen location.
 
Methods inherited from class com.rational.test.ft.object.interfaces.TestObject
equals, find, findAndInvoke, findAndInvoke, findAndInvokeProxy, getChildren, getDescribedObject, getDescribedObjects, getDomain, getField, getIndexer, getIndexer, getIndexers, getMappableChildren, getMappableParent, getMethods, getNameInScript, getNonValueProperties, getObjectClassName, getObjectReference, getOwnedObjects, getOwner, getParent, getProcess, getProperties, getProperty, getPropertyFromMap, getRecognitionProperties, getRecognitionPropertyWeight, getScriptCommandFlags, getStandardProperties, getTestData, getTestDataTypes, getTopMappableParent, getTopParent, invoke, invoke, invokeProxy, invokeProxy, isMappedObject, isSameObject, setIndexer, setIndexer, setProperty, toString, unregister, updateTestData, waitForExistence, waitForExistence
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Method Detail

getRootTestObject

public static RootTestObject getRootTestObject()
Gets the RootTestObject.

Since:
RFT2.0

exists

public boolean exists()
The RootTestObject is always available. This method always returns true.

Overrides:
exists in class TestObject
Since:
RFT2.1

objectAtPoint

public GuiTestObject objectAtPoint(java.awt.Point screenPt)
Returns a GuiTestObject for the object at the specified screen location.

Since:
RFT2.0

getScreen

public IScreen getScreen()
Returns an interface to the screen object. This method is never recorded. Any script that uses this method will likely be platform specific.

Since:
RFT2.0

getTopWindows

public IWindow[] getTopWindows()
Returns an array of IWindows. The IWIndow interface provides access to the native windowing layer. This method is never recorded. Any script that uses this method will likely be platform specific. If there are no top windows (an unlikely situation), a zero-length array is returned.

Since:
RFT2.0

getDomains

public DomainTestObject[] getDomains()
Returns an array of all the domains that can be tested in the system.

Since:
RFT2.0

find

public TestObject[] find(Subitem properties)
Finds all candidates that match given search criteria. Valid values for the property subitems are: There are particular properties that apply to a RootTestObject find, including: Examples:
	
  TestObject[] foundTOs ;
	RootTestObject root = RootTestObject.getRootTestObject() ;
	
	// This finds all top-level windows in the Windows domain with caption "My Document".
  CaptionText caption = new CaptionText("My Document") ;
	foundTOs = root.find(atChild(".domain", "Win", ".caption", caption)) ;
	
	// This finds any dialogs and returns 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"))) ;
									
	// This starts Notepad, dynamically enables that process, finds its toplevel window that
	// matches the process id, and gets 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 app with the provided window handle and returns a
	// TestObject representing the window.
	Long hWnd = getAppsHwnd(); 
	foundTOs = root.find(atChild(".hwnd", hWnd, ".domain", "Win"));

	// This enables a .NET app with the provided window handle and returns a
	// TestObject representing the window.
	Long handle = getAppsHwnd(); 
	foundTOs = root.find(atChild("Handle", handle, ".domain", "Net"));	 
 	 
 

Overrides:
find in class TestObject
Parameters:
properties - The property set to match against.
Since:
RFT2.0
See Also:
TestObject.unregister(), RationalTestScript.unregister(Object[]), RationalTestScript.unregisterAll(), RationalTestScript.getRegisteredTestObjects()

find

public TestObject[] find(Subitem properties,
                         boolean mappableOnly)
Finds all candidates that match the given search criteria. Valid values for the property subitems are: There are particular properties that apply to a RootTestObject find, including: Examples:
	
  TestObject[] foundTOs ;
  RootTestObject root = RootTestObject.getRootTestObject() ;
 
	
	// This will find all toplevel windows in the Windows domain with caption "My Document"
	CaptionText caption = new CaptionText("My Document") ;
	foundTOs = root.find(atChild(".domain", "Win", ".caption", caption)) ;
  
	
	// This will find any dialogs, 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"))) ;
  									
	// This will start Notepad, dynamically enable that process, find its toplevel 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 app with the provided window handle and returns a
	// TestObject representing the window.
	Long hWnd = getAppsHwnd(); 
	foundTOs = root.find(atChild(".hwnd", hWnd, ".domain", "Win"));

	// This enables a .NET app with the provided window handle and returns a
	// TestObject representing the window.
	Long handle = getAppsHwnd(); 
	foundTOs = root.find(atChild("Handle", handle, ".domain", "Net"));	 	 
  	 	 
	

Overrides:
find in class TestObject
Parameters:
properties - The property set to match against.
mappableOnly - Whether to search all children or just mappable children
Since:
RFT2.0
See Also:
TestObject.unregister(), RationalTestScript.unregister(Object[]), RationalTestScript.unregisterAll(), RationalTestScript.getRegisteredTestObjects()

enableForTesting

public boolean enableForTesting(java.lang.String processName)
Enables the process(es) with name processName for testing.

Parameters:
processName - the name of the process(es) to enable.
Since:
RFT2.0

enableForTesting

public boolean enableForTesting(int processId)
Enables the process with processId for testing.

Parameters:
processId - the pid of the process to enable.
Since:
RFT2.0

enableForTesting

public boolean enableForTesting(long windowHandle)
Enables the process with window windowHandle for testing.

Parameters:
windowHandle - the handle of a window in the process to enable..
Since:
RFT2.0

emitLowLevelEvent

public void emitLowLevelEvent(LowLevelEvent event)
Plays back a low level event. Low level events are primitive system level events that are played back "to the screen" unlike conventional actions that are played back to a TestObject. These actions are further broken down into more basic parts, so rather than something like TestObject.click() which is comprised of a move, a mouse button down, and a mouse button up, you deal with each of those sub actions individually.

Parameters:
event - the LowLevelEvent to be played back.
Since:
RFT2.0
See Also:
SubitemFactory.keyDown(String), SubitemFactory.keyUp(String), SubitemFactory.leftMouseButtonDown(), SubitemFactory.leftMouseButtonUp(), SubitemFactory.middleMouseButtonDown(), SubitemFactory.middleMouseButtonUp(), SubitemFactory.rightMouseButtonDown(), SubitemFactory.rightMouseButtonUp(), SubitemFactory.mouseMove(Point), SubitemFactory.mouseWheel(int), SubitemFactory.delay(int), LowLevelEvent

emitLowLevelEvent

public void emitLowLevelEvent(LowLevelEvent[] events)
Plays back a sequence of low level events. Low level events are primitive system level events that are played back "to the screen" unlike conventional actions that are played back to a TestObject. These actions are further broken down into more basic parts, so rather than something like TestObject.click() which is comprised of a move, a mouse button down, and a mouse button up, you deal with each of those sub actions individually.

Parameters:
events - the array of LowLevelEvents to be played back.
Since:
RFT2.0
See Also:
SubitemFactory.keyDown(String), SubitemFactory.keyUp(String), SubitemFactory.leftMouseButtonDown(), SubitemFactory.leftMouseButtonUp(), SubitemFactory.middleMouseButtonDown(), SubitemFactory.middleMouseButtonUp(), SubitemFactory.rightMouseButtonDown(), SubitemFactory.rightMouseButtonUp(), SubitemFactory.mouseMove(Point), SubitemFactory.mouseWheel(int), SubitemFactory.delay(int), LowLevelEvent

getScreenSnapshot

public java.awt.image.BufferedImage getScreenSnapshot()
Takes a snapshot (screen capture) of the entire desktop

Since:
RFT2.1

getScreenSnapshot

public java.awt.image.BufferedImage getScreenSnapshot(java.awt.Rectangle rect)
Takes a snapshot (screen capture) of the specified portion of the desktop

Parameters:
rect - The portion of the screen to capture
Since:
RFT2.1