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

java.lang.Object
  com.rational.test.ft.object.interfaces.TestObject
      com.rational.test.ft.object.interfaces.ClientTestObject
          com.rational.test.ft.object.interfaces.RootTestObject

public class RootTestObject
extends ClientTestObject

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.

Field Summary

Fields inherited from class com.rational.test.ft.object.interfaces.TestObject

ref

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
java.awt.image.BufferedImage	getScreenSnapshot(java.awt.Rectangle rect, boolean clipToVisibleArea) Takes a snapshot (screen capture) of the specified portion of the desktop *
java.awt.image.BufferedImage	getScreenSnapshot(java.awt.Rectangle rect, java.lang.String fname) Takes a snapshot (screen capture) of the specified portion of the desktop If a custom imaging solution is provided, a temporary file name with full path should be passed.
static ScreenTestObject	getScreenTestObject()
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.ClientTestObject

find, findAndInvoke, findAndInvokeProxy, invoke, invokeProxy, unregister, waitForExistence

Methods inherited from class com.rational.test.ft.object.interfaces.TestObject

compare, compare, compareAndLog, compareAndLog, equals, findAndInvoke, getActualData, getChildren, getDescribedObject, getDescribedObjects, getDescriptiveName, getDomain, getField, getIndexer, getIndexer, getIndexers, getMappableChildren, getMappableParent, getMapProperties, getMethods, getNameInScript, getNonValueProperties, getObjectClassName, getObjectCustomClassName, getObjectReference, getOwnedObjects, getOwner, getParent, getProcess, getProperties, getProperty, getPropertyFromMap, getRecognitionProperties, getRecognitionPropertyWeight, getScriptCommandFlags, getStandardProperties, getTestData, getTestDataTypes, getTopMappableParent, getTopParent, hashCode, invoke, invokeProxy, isMappedObject, isSameObject, isScreenTestObject, isTopLevelTestObject, performTest, performTest, performTest, performTest, setIndexer, setIndexer, setMapProperties, setProperty, toString, updateTestData, waitForExistence

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Method Detail

getRootTestObject

public static RootTestObject getRootTestObject()

Gets the RootTestObject.

Since:

RFT2.0

getScreenTestObject

public static ScreenTestObject getScreenTestObject()

exists

public boolean exists()

The RootTestObject is always available. This method always returns true.

Overrides:

exists in class ClientTestObject

Since:

RFT2.1

See Also:

ClientTestObject

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:

• atProperty- A name/value pair representing a TestObject property.

• atChild- Contains one or more properties that must be matched against the direct child of the starting TestObject.

• atDescendant- Contains one or more properties that can be matched against any child of the starting TestObject.

• atList- Used to specify a sequential list of properties to match against. Subitems that are valide for atList are:

  • 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.

There are particular properties that apply to a RootTestObject find, including:

• .processName- As a top-level property this has two functions:

  • To dynamically enable the processes with that processName for testing.

  • To constrain the find to only look in processes with that name for testing.

• .processId- As a top-level property this has two functions:

  • To dynamically enable the processes with that process id (pid).

  • To constrain the find to only look in processes with that process id (pid).

• .domain- Only search in top-level domains matching the .domain property.

• .hWnd- along with the hWnd property being used for the search, if the .domain "Win" is also specified the matching window will be enabled for testing.

• Handle- along with the window handle property being used for the search, if the .domain "Net" is also specified the matching window will be enabled for testing.

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:

ClientTestObject.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:

• atProperty- A name/value pair representing a TestObject property.

• atChild- Contains one or more properties that must be matched against the direct child of the starting TestObject.

• atDescendant- Contains one or more properties that can be matched against any child of the starting TestObject.

• atList- Used to specify a sequential list of properties to match against. Subitems that are valide for atList are:

  • 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.

There are particular properties that apply to a RootTestObject find, including:

• .processName- As a top-level property this has two functions:

  • To dynamically enable the processes with that processName for testing.

  • To constrain the find to only look in processes with that name.

• .processId- As a top-level property this has two functions:

  • To dynamically enable the processes with that process id (pid) for testing.

  • To constrain the find to only look in processes with that process id (pid).

• .domain- Only search in top-level domains matching the .domain property.

• .hWnd- along with the hWnd property being used for the search, if the .domain "Win" is also specified the matching window will be enabled for testing.

• Handle- along with the window handle property being used for the search, if the .domain "Net" is also specified the matching window will be enabled for testing.

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 ClientTestObject

Parameters:

properties - The property set to match against.

mappableOnly - Whether to search all children or just mappable children

Since:

RFT2.0

See Also:

ClientTestObject.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

getScreenSnapshot

public java.awt.image.BufferedImage getScreenSnapshot(java.awt.Rectangle rect,                                                       boolean clipToVisibleArea)

Takes a snapshot (screen capture) of the specified portion of the desktop *

Throws:

CoordinateOffScreenException

Parameters:

rect - The portion of the screen to capture

clipToVisibleArea - If true, the method will consider only visible portion of the screen, otherwise throws CoordinateOffScreenException.

Since:

RFT 8.1.0.3

getScreenSnapshot

public java.awt.image.BufferedImage getScreenSnapshot(java.awt.Rectangle rect,                                                       java.lang.String fname)

Takes a snapshot (screen capture) of the specified portion of the desktop If a custom imaging solution is provided, a temporary file name with full path should be passed. Otherwise, the second parameter can be null

Parameters:

rect - The portion of the screen to capture

Since:

RFT2.1