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

ignoreTheObjectState, ref

Method Summary

Modifier and Type	Method and Description
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() Finds the object in the software under test and returns a reference to it.
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.
java.lang.String	getDescriptiveName() Returns the descriptive name of the object in software under test.
DomainTestObject[]	getDomains() Returns an array of all the domains that can be tested in the system.
TestObject[]	getOwnedObjects() Returns null as owned objects are not applicable for RootTestObject
TestObject	getOwner() returns null as the RootTestObject does not have any owner.
TestObject	getParent() Returns a reference to the parent object.
static java.lang.String	getPid()
java.util.Hashtable	getProperties() Returns null , as no properties available for the RootTestObject
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.
boolean	isMappedObject() Returns true if the object contains a mapped reference.
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

exists, exists, findAndInvoke, findAndInvokeProxy, getProperty, getTestDataTypes, 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, getDomain, getField, getIndexer, getIndexer, getIndexers, getMappableChildren, getMappableParent, getMapProperties, getMethods, getNameInScript, getNonValueProperties, getObjectClassName, getObjectCustomClassName, getObjectReference, getProcess, getPropertyFromMap, getRecognitionProperties, getRecognitionPropertyWeight, getScriptCommandFlags, getStandardProperties, getTestData, getTopMappableParent, getTopParent, hashCode, invoke, invoke, invoke, invokeProxy, invokeProxy, isHtmlWebui, isLoggedDuringUnregister, isSameObject, isScreenTestObject, isTopLevelTestObject, performTest, performTest, performTest, performTest, setIndexer, setIndexer, setLoggedDuringUnregister, 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

isMappedObject

public boolean isMappedObject()

Description copied from class: TestObject

Returns true if the object contains a mapped reference. Returns false for a TestObject that is returned by reference from the software under test.

Overrides:

isMappedObject in class TestObject

getDescriptiveName

public java.lang.String getDescriptiveName()

Description copied from class: TestObject

Returns the descriptive name of the object in software under test.

Overrides:

getDescriptiveName in class TestObject

Returns:

getParent

public TestObject getParent()

Description copied from class: TestObject

Returns a reference to the parent object. The returned object can extend TestObject and support more methods. Therefore, you may want to cast the return value. The reference to the object should be released by calling one of the unregister methods.

Overrides:

getParent in class TestObject

See Also:

TestObject.unregister(), RationalTestScript.unregisterAll(), RationalTestScript.unregister(Object[]), RationalTestScript.getRegisteredTestObjects()

getOwnedObjects

public TestObject[] getOwnedObjects()

Returns null as owned objects are not applicable for RootTestObject

Overrides:

getOwnedObjects in class TestObject

See Also:

TestObject.getOwner(), TestObject.getParent(), TestObject.getChildren(), TestObject.unregister(), RationalTestScript.unregister(Object[]), RationalTestScript.unregisterAll(), RationalTestScript.getRegisteredTestObjects()

getProperties

public java.util.Hashtable getProperties()

Returns null , as no properties available for the RootTestObject

Overrides:

getProperties in class TestObject

getOwner

public TestObject getOwner()

returns null as the RootTestObject does not have any owner.

Overrides:

getOwner in class TestObject

See Also:

TestObject.getOwnedObjects(), TestObject.getParent(), TestObject.getChildren(), TestObject.getMappableParent(), TestObject.getMappableChildren(), TestObject.unregister(), RationalTestScript.unregister(Object[]), RationalTestScript.unregisterAll(), RationalTestScript.getRegisteredTestObjects()

getPid

public static java.lang.String getPid()

find

public TestObject find()

Description copied from class: ClientTestObject

Finds the object in the software under test and returns a reference to it.

Overrides:

find in class ClientTestObject

See Also:

ClientTestObject.unregister(), RationalTestScript.unregister(Object[]), RationalTestScript.unregisterAll(), RationalTestScript.getRegisteredTestObjects()

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