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

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

Direct Known Subclasses:

ClientTestObject, CrossDomainContainer, DomainTestObject, ProcessTestObject, SAPGuiApplicationTestObject, SAPGuiConnectionTestObject, SAPGuiSessionTestObject

public class TestObject
extends java.lang.Object

Provides access to objects in the software under test. A TestObject contains a reference to an object in the software under test, either referencing the object directly, or by using a reference to a MappedTestObject. The recognition algorithm is the work of the ObjectManager.

A TestObject is generally in a process separate from the software under test. If a method is called on such a TestObject and if the object returned by the method can be recreated in the process of the script, the object is considered a value class. If the object returned by the method cannot be recreated in the script process, the script is given an object that provides remote access to the object in the software under test. This remote object must be explicitly unregistered.

All the Java primitives and java.lang.String are value classes. Many other classes, such as java.lang.Rectangle are also considered to be values. Most graphical objects, such as java.awt.Component, are not values. Class is a value class if it has a value manager. A value manager supports the IManageValueClass interface, which contains the methods persistIn, persistOut, and compare.

The method getProperties() returns a Hashtable containing all the value properties of a TestObject. It does not return properties that are non-value classes. You can find the non-value properties by calling getNonValueProperties(). You can use the getProperty method to access both value and non-value properties. If you access a non-value property, the property returns a TestObject that contains a reference to the (non-value) object in the software under test. This object gets registered on your behalf, thus keeping a reference to that object in the software under test. A TestObject containing a reference is referred to as a registered object reference. An object in the software under test that has been registered is referred to as a registered object.

Do not use a registered object reference after the object it refers to has been disposed of. For example, if the reference is to a JButton in a Frame and the Frame is closed, you should not use the reference any longer. In fact, the underlying object, that is, the JButton, may be accessible, but may be in an unreliable state. Release any references that has been registered on your behalf so that when the playback session terminates, all objects that you have registered get released.

To release a reference, unregister it. When a script terminates, objects are not automatically unregistered. There are a variety of methods for unregistering an object - see unregister(), RationalTestScript.unregisterAll, and RationalTestScript.unregister(Object[]). You can also get an array of TestObjects that you have registered by calling RationalTestScript.getRegisteredTestObjects.

Two intertwined hierarchies of objects are supported: the parent-child hierarchy and the owner-owned hierarchy. An object cannot have both a parent and an owner. For GUI objects, the parent-child hierarchy implies containment of the child's GUI within the parent. The ownership relationship is used for a different hierarchy, for example, the relationship between a dialog box and a top-level window.

Since:

RFT1.0

Field Summary

protected com.rational.test.ft.object.TestObjectReference

ref

Constructor Summary

TestObject()
Deprecated. use ClientTestObject

TestObject(com.rational.test.ft.sys.RegisteredObjectReference ror)
Deprecated. use ClientTestObject

TestObject(com.rational.test.ft.object.map.SpyMappedTestObject mappedObject)
Deprecated. use ClientTestObject

TestObject(com.rational.test.ft.object.map.SpyMappedTestObject mappedObject, TestObject anchor)
Deprecated. use ClientTestObject

TestObject(com.rational.test.ft.object.map.SpyMappedTestObject mappedObject, TestObject anchor, long scriptCommandFlags)
Deprecated. use ClientTestObject

TestObject(TestObject obj)
Deprecated. use ClientTestObject

TestObject(com.rational.test.ft.object.TestObjectReference ref)
Deprecated. use ClientTestObject

Method Summary

boolean	compare(IFtVerificationPoint baseline) Compares the baseline, that is, expected data to the actual data.
boolean	compare(IFtVerificationPoint baseline, double delayBetweenRetries, double maximumTestTime) Compares the expected result with the actual result.
boolean	compareAndLog(IFtVerificationPoint baseline) Compares the baseline, that is, expected data to the actual data and logs the result to the script log.
boolean	compareAndLog(IFtVerificationPoint baseline, boolean compareTrueEqualsPass) Allows failing verification points to return and log a passing result.
boolean	equals(java.lang.Object other) Returns true if the two objects are equal.
boolean	exists() Returns true if the object exists now, false otherwise.
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 starting at this TestObject.
TestObject[]	find(Subitem properties, boolean mappableOnly) Finds all candidates that match given search criteria starting at this TestObject.
java.lang.Object	findAndInvoke(Subitem properties, java.lang.String methodName) Finds a TestObject based on find(Subitem) and invokes the supplied method on the TestObject (invoke(String)).
java.lang.Object	findAndInvoke(Subitem properties, java.lang.String methodName, java.lang.String methodSignature, java.lang.Object[] args, boolean mappableOnly) Finds a TestObject based on find(Subitem, boolean) and invokes the supplied method on the TestObject (invoke(String, String, Object[])).
java.lang.Object	findAndInvokeProxy(Subitem properties, java.lang.String methodName, java.lang.String methodSignature, java.lang.Object[] args, boolean mappableOnly) Finds a TestObject based on find(Subitem, boolean) and invokes the supplied method on the TestObject's proxy (invoke(String, String, Object[])).
java.lang.Object	getActualData(IFtVerificationPoint baseline) Enables access to the actual, that is, currently active data associated with a verification point.
TestObject[]	getChildren() Returns an array of references to the object's children.
protected TestObject	getDescribedObject(CrossDomainContainer describedTestObject) Used to bind a described object returned by proxy into the corresponding bound TestObject
protected TestObject[]	getDescribedObjects(TestObject[] testObject) Given an array of TestObjects, find any described objects and turn them into bound test objects.
java.lang.String	getDescriptiveName() Returns the descriptive name of the object in software under test.
DomainTestObject	getDomain() Returns the domain for the current object.
java.lang.Object	getField(java.lang.String fieldName) Returns the value of a field of the object in the SUT encapsulated by this TestObject.
java.lang.Object	getIndexer(java.lang.String name, java.lang.Object index) Returns the value of a TestObject's indexer at the given index.
java.lang.Object	getIndexer(java.lang.String name, java.lang.Object[] indexes) Same as getIndexer(String, Object) but used for multidimensional indexers.
IndexerInfo[]	getIndexers() Returns information about the TestObject's indexers, if applicable.
TestObject[]	getMappableChildren() Returns an array of references to the object's mappable children.
TestObject	getMappableParent() Returns a reference to the parent object that appears in the object map.
com.rational.test.ft.object.map.IObjectMapPropertySet	getMapProperties()
MethodInfo[]	getMethods() Returns a an array of MethodInfo objects describing the methods supported by the object.
java.lang.String	getNameInScript()
java.util.Hashtable	getNonValueProperties() Returns a Hashtable containing names of properties whose values are not value classes.
java.lang.String	getObjectClassName() Returns the complete class name for the object in the software under test.
java.lang.String	getObjectCustomClassName() Returns the custom class name for the object in the software under test.
com.rational.test.ft.object.TestObjectReference	getObjectReference() Returns the object reference.
TestObject[]	getOwnedObjects() Returns an array of references to the objects owned by this object.
TestObject	getOwner() Returns a reference to the owner object.
TestObject	getParent() Returns a reference to the parent object.
ProcessTestObject	getProcess() Returns a ProcessTestObject for the object in the software under test.
java.util.Hashtable	getProperties() Returns a Hashtable containing properties.
java.lang.Object	getProperty(java.lang.String propertyName) Returns the value of the specified property.
java.lang.Object	getPropertyFromMap(java.lang.String propertyName) Returns a property value from the map.
java.util.Hashtable	getRecognitionProperties() Returns the properties that are useful for recognition.
int	getRecognitionPropertyWeight(java.lang.String propertyName) Returns an indication of how useful this property is for recognition.
ScriptCommandFlags	getScriptCommandFlags() Returns an active state value that reflects the state of the TestObejct at the time of the call.
java.util.Hashtable	getStandardProperties() Returns a complete set of standard properties for the associated TestObject.
ITestData	getTestData(java.lang.String testDataType) Constructs the specified verification data object.
java.util.Hashtable	getTestDataTypes() Returns a Hashtable of data type descriptions of the verification point data available with the associated object in the software under test.
TestObject	getTopMappableParent() Returns a reference to the topmost mappable parent for an object.
TestObject	getTopParent() Returns a reference to the topmost parent for an object.
int	hashCode() Returns Using TestObject in hash functions is discouraged.
java.lang.Object	invoke(java.lang.String method) Invokes a method with no arguments on the object in the software under test.
java.lang.Object	invoke(java.lang.String method, java.lang.String methodSignature, java.lang.Object[] args) Invokes a method on the object in the software under test.
protected java.lang.Object	invokeProxy(java.lang.String method) Invokes a method on the object in the software under test.
protected java.lang.Object	invokeProxy(java.lang.String method, java.lang.String methodSignature, java.lang.Object[] args) Invokes a method on the proxy for an object in the software under test.
boolean	isMappedObject() Returns true if the object contains a mapped reference.
boolean	isSameObject(TestObject other) Returns true if the supplied TestObject represents the same underlying object in the software under test.
protected boolean	isScreenTestObject() Check to see if this TestObject is indeed the Screen.
boolean	isTopLevelTestObject() Check to see if this TestObject is indeed the Top Level Test Object.
boolean	performTest(IFtVerificationPoint baseline) Captures, compares and logs active data available relative to this object instance against the supplied baseline data.
boolean	performTest(IFtVerificationPoint baseline, boolean compareTrueEqualsPass) Captures, compares and logs active data available relative to this object instance against the supplied baseline data.
boolean	performTest(IFtVerificationPoint baseline, double delayBetweenRetries, double maximumTestTime) Captures, compares and logs active data available relative to this object instance against the supplied baseline data.
boolean	performTest(IFtVerificationPoint baseline, double delayBetweenRetries, double maximumTestTime, boolean compareTrueEqualsPass) Captures, compares and logs active data available relative to this object instance against the supplied baseline data.
void	setIndexer(java.lang.String name, java.lang.Object[] indexes, java.lang.Object value) Same as setIndexer(String, Object[], Object) but used for multidimensional indexers.
void	setIndexer(java.lang.String name, java.lang.Object index, java.lang.Object value) Sets the value of a TestObject's indexer.
void	setMapProperties(com.rational.test.ft.object.map.IObjectMapPropertySet propSet)
void	setProperty(java.lang.String propertyName, java.lang.Object value) Sets the specified property to the specified value.
java.lang.String	toString() Returns a string describing the TestObject, not a string describing the object in the software under test.
void	unregister() Unregisters a TestObject reference.
ITestData	updateTestData(java.lang.String testDataType, ITestData testData) Updates the supplied test data object and returns it.
void	waitForExistence() Waits the default time until an object exists.
void	waitForExistence(double maximum_find_object_time, double find_object_wait_between_retry) Waits until an object exists.

Methods inherited from class java.lang.Object

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

Field Detail

ref

protected com.rational.test.ft.object.TestObjectReference ref

Constructor Detail

TestObject

public TestObject()

Deprecated. use ClientTestObject

For internal use.

Since:

RFT1.0

TestObject

public TestObject(com.rational.test.ft.object.map.SpyMappedTestObject mappedObject)

Deprecated. use ClientTestObject

For internal use.

Since:

RFT1.0

TestObject

public TestObject(com.rational.test.ft.object.map.SpyMappedTestObject mappedObject,                   TestObject anchor)

Deprecated. use ClientTestObject

For internal use.

Since:

RFT1.0

TestObject

public TestObject(com.rational.test.ft.object.map.SpyMappedTestObject mappedObject,                   TestObject anchor,                   long scriptCommandFlags)

Deprecated. use ClientTestObject

For internal use.

Since:

RFT1.0

TestObject

public TestObject(com.rational.test.ft.object.TestObjectReference ref)

Deprecated. use ClientTestObject

For internal use.

Since:

RFT1.0

TestObject

public TestObject(TestObject obj)

Deprecated. use ClientTestObject

Constructs one TestObject from another. Both are references to the same object.

Since:

RFT1.0

TestObject

public TestObject(com.rational.test.ft.sys.RegisteredObjectReference ror)

Deprecated. use ClientTestObject

For internal use.

Since:

RFT1.0

Method Detail

setMapProperties

public void setMapProperties(com.rational.test.ft.object.map.IObjectMapPropertySet propSet)

getMapProperties

public com.rational.test.ft.object.map.IObjectMapPropertySet getMapProperties()

getObjectReference

public com.rational.test.ft.object.TestObjectReference getObjectReference()

Returns the object reference. This method is used internally and should not be used by test scripts.

Since:

RFT1.0

toString

public java.lang.String toString()

Returns a string describing the TestObject, not a string describing the object in the software under test.

Overrides:

toString in class java.lang.Object

hashCode

public int hashCode()

Returns Using TestObject in hash functions is discouraged. It works but the performance could be bad. The equals method on the TestObject calls the remote process to find out if the objects are really equal. This function doesn't make a remote call but ensures the java rule which says hashCode should return the same value for those objects if equals return true. Performance of hash functions on this object will not be good if used

Overrides:

hashCode in class java.lang.Object

Since:

RFT1.0

isScreenTestObject

protected boolean isScreenTestObject()

Check to see if this TestObject is indeed the Screen. By default this returns false. This is here for compatibility. Please refer to ScreenTestObject for the actual implementation for a Screen Test Object.

Returns:

See Also:

ScreenTestObject

equals

public boolean equals(java.lang.Object other)

Returns true if the two objects are equal.

Overrides:

equals in class java.lang.Object

Since:

RFT1.0

getPropertyFromMap

public java.lang.Object getPropertyFromMap(java.lang.String propertyName)

Returns a property value from the map. If the TestObject does not contain a mapped reference, throws RationalTestException. If the property is not found, it returns null. It does not throw PropertyNotFoundException.

Since:

RFT1.0

isMappedObject

public boolean isMappedObject()

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

Since:

RFT1.0

isSameObject

public boolean isSameObject(TestObject other)

Returns true if the supplied TestObject represents the same underlying object in the software under test. This method is different from equals in that it represents an "==" of the object in the software under test rather than an "equals" of these objects.

Since:

RFT1.0

getDomain

public DomainTestObject getDomain()

Returns the domain for the current object.

Since:

RFT1.0

getObjectClassName

public java.lang.String getObjectClassName()

Returns the complete class name for the object in the software under test.

Since:

RFT1.0

getObjectCustomClassName

public java.lang.String getObjectCustomClassName()

Returns the custom class name for the object in the software under test. For the proxy test object if any other custom property got defined along with the .class property for the proxy mapping or object recognition properties mapping this method should be defined. It will take care to highlight the control with the custom class name as a tooltip when the object is selected with Object Recognition properties/VP/Insert TestObject wizard.

Since:

RFT8.1

getDescriptiveName

public java.lang.String getDescriptiveName()

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

Returns:

getProcess

public ProcessTestObject getProcess()

Returns a ProcessTestObject for the object in the software under test.

Since:

RFT1.1

getParent

public TestObject getParent()

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.

Since:

RFT1.0

See Also:

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

getMappableParent

public TestObject getMappableParent()

Returns a reference to the parent object that appears in the object map. 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.

Since:

RFT1.0

See Also:

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

getChildren

public TestObject[] getChildren()

Returns an array of references to the object's children. The returned objects can be derived from TestObject and support more methods. Therefore, you may want to cast the return values. The references to the objects should be released by calling one of the unregister methods. If the object has no children, a 0-length array of TestObjects will be returned.

Since:

RFT1.0

See Also:

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

getMappableChildren

public TestObject[] getMappableChildren()

Returns an array of references to the object's mappable children. These are the children that may appear in an associated object map. The returned objects can be derived from TestObject and support more methods. Therefore, you may want to cast the return values. The references to the objects should be released by calling one of the unregister methods. If the object has no mappable children, a 0-length array of TestObjects will be returned.

Since:

RFT1.0

See Also:

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

getTopParent

public TestObject getTopParent()

Returns a reference to the topmost parent for an object. If the object has no parent, the object itself is returned. The reference to the object should be released by calling one of the unregister methods.

Since:

RFT1.0

See Also:

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

getTopMappableParent

public TestObject getTopMappableParent()

Returns a reference to the topmost mappable parent for an object. This is the topmost parent that appears in an associated object map. If the object has no parent, the object itself is returned. The reference to the object should be released by calling one of the unregister methods.

Since:

RFT1.0

See Also:

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

getProperty

public java.lang.Object getProperty(java.lang.String propertyName)

Returns the value of the specified property. If the property type is not a value class, getProperty registers the object in the software under test and returns a reference to the object. Registered object references are released by calling one of the unregister methods.

If the property is not defined on the object, a PropertyNotFoundException is thrown.

Parameters:

propertyName - the name of the property

Since:

RFT1.0

See Also:

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

setProperty

public void setProperty(java.lang.String propertyName,                         java.lang.Object value)

Sets the specified property to the specified value. Note that this directly modifies the object in the software under test; therefore, it should be done with extreme care. Avoid using setProperty whenever possible because it allows you to modify the software under test in ways that a typical user cannot. If you use this method, be sure to discuss its use with the developers of the software you are testing.

A common use for this method is to set the text value of an input or edit control. This may be simpler and more reliable than playing back a sequence of keys to update the control. However, you should be aware that even in this simple use case, there may be problems. For example, the developer may watch the keys going to the control and may have code to prevent certain characters from appearing. By setting the property directly, you may be circumventing the normal error handling.

Most commonly, the value is a value class - an object that can be recreated in the process of the software under test. However, the value can also be a TestObject containing a reference to an object in the software under test, for example, a TestObject returned by a previous call to getProperty.

Parameters:

propertyName - the name of the property

value - the value used to set the property

Since:

RFT1.0

getProperties

public java.util.Hashtable getProperties()

Returns a Hashtable containing properties. Note that this is an extended Hashtable and can have null values. The keys are strings that represent property names; they are never null. This method does not return registered object references to objects in the software under test; it only returns properties that are value classes.

Since:

RFT1.0

getStandardProperties

public java.util.Hashtable getStandardProperties()

Returns a complete set of standard properties for the associated TestObject. For HTML objects, standard properties are those properties that exist regardless of the platform that the TestObject is running on. Further, the values for these properties are normalized across platforms. These properties exist regardless of the browser, operating system, or software platform version (such as the version of the JDK). These properties are a subset of the properties returned by getProperties.

The meaning of a property is specific to the test domain and the TestObject. Typically, this is a set of name/value pairs that describe the TestObject and its active state. Properties such as font, colors, and coordinate information are typically associated with a GUITestObject. Associated data and state information can also be returned, depending on the TestObject.

For Java, getStandardProperties and getProperties behave the same.

Returns:

The set of standard properties associated with a TestObject

Since:

RFT1.0

See Also:

getProperty(String), setProperty(String,Object), getProperties(), getNonValueProperties()

getNonValueProperties

public java.util.Hashtable getNonValueProperties()

Returns a Hashtable containing names of properties whose values are not value classes. These properties are not returned by getProperties(). These properties can be accesssed using getProperty, which returns a TestObject containing a registered object reference to the object in the software under test. Whenever such a property value is returned, a reference to the object in the software under test is maintained until the reference is released by calling unregister(). The keys in the Hashtable are strings representing the property names. The values in the Hashtable are the class names for the property values.

Since:

RFT1.0

getIndexer

public java.lang.Object getIndexer(java.lang.String name,                                    java.lang.Object index)

Returns the value of a TestObject's indexer at the given index. If the value has a value class then the value class is returned, otherwise a TestObject is registered and returned. Information about a TestObject's indexer properties can be obtained via getIndexers().

Parameters:

name - the name of the indexer

index - the index to get the value of

Since:

RFT2.0

getIndexer

public java.lang.Object getIndexer(java.lang.String name,                                    java.lang.Object[] indexes)

Same as getIndexer(String, Object) but used for multidimensional indexers. The first element in the array of indexes is used for the first rank of the indexer, etc.

Parameters:

name - the name of the indexer

indexes - the indexes to get the value of

Since:

RFT2.0

getIndexers

public IndexerInfo[] getIndexers()

Returns information about the TestObject's indexers, if applicable.

Since:

RFT2.0

See Also:

IndexerInfo

setIndexer

public void setIndexer(java.lang.String name,                        java.lang.Object index,                        java.lang.Object value)

Sets the value of a TestObject's indexer.

Parameters:

name - the name of the indexer

index - the index to set the value of

value - the value to set the index to

Since:

RFT2.0

setIndexer

public void setIndexer(java.lang.String name,                        java.lang.Object[] indexes,                        java.lang.Object value)

Same as setIndexer(String, Object[], Object) but used for multidimensional indexers. The first element in the array of indexes is used for the first rank of the indexer, etc.

Parameters:

name - the name of the indexer

indexes - the indexes to set the value of

value - the value to set the index to

Since:

RFT2.0

exists

public boolean exists()

Returns true if the object exists now, false otherwise. If the TestObject contains a mapped reference and there are multiple matching objects (that is, the recognition is ambiguous), exists returns true. This method does not wait for the object to come into existence. This method does not raise ambiguous recognition events or object-not-found events.

Since:

RFT1.0, RFT8.1.1 returns a default value of false. This method maybe overridden by a specialized TestObject.

See Also:

ClientTestObject

find

public TestObject find()

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

Since:

RFT1.0, RFT8.1.1 Please refer to ClientTestObject for the functionality.

See Also:

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

find

public TestObject[] find(Subitem properties)

Finds all candidates that match given search criteria starting at this TestObject. Valid values for the property sub-items 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. AtList valid sub-items are atChild, atDescendant, and atProperty. The first list item is matched against to get a list of candidates, and out of those candidates their descendants is matched against for the next list item, and so on.

Examples:

  
        TestObject[] foundTOs ;
        
        // Given Notepad's outer window, this will find its text window.
        foundTOs = Notepad_Form().find(atDescendant(".class", ".text")) ;
        
        // This will find all the forms in the given browser, and return the forms
        // direct children that are buttons with text "Submit"
        foundTOs = Browser_htmlBrowser().find(atList(
                                                                                        atDescendant(".class", "Html.FORM"),                                                                                         atChild(".class", "Html.INPUT.submit",                                                                                                                 ".value", "Submit"))) ;
                                                                                                                
        // This will find all the forms in the  given browser, and return all forms
        // "INPUT" elements, of any type.
        RegularExpression inputRE = new RegularExpression("*INPUT*", false) ;
        foundTOs = Browser_htmlBrowser().find(atList(
                                                                                        atDescendant(".class", "Html.FORM"),                                                                                         atChild(".class", inputRE)))    

 
 

Parameters:

properties - The property set to match against.

Since:

RFT2.0

See Also:

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

find

public TestObject[] find(Subitem properties,                          boolean mappableOnly)

Finds all candidates that match given search criteria starting at this TestObject. Valid values for the property sub-items 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. atList valid sub-items are atChild, atDescendant, and atProperty. The first list item is matched against to get a list of candidates, and out of those candidates their descendants is matched against for the next list item, and so on.

Examples:

  
        TestObject[] foundTOs ;
        
        // Given Notepad's outer window, this will find its text window.
        foundTOs = Notepad_Form().find(atDescendant(".class", ".text")) ;
        
        // This will find all the forms in the given browser, and return the forms
        // direct children that are buttons with text "Submit"
        foundTOs = Browser_htmlBrowser().find(atList(
                                                                                        atDescendant(".class", "Html.FORM"),                                                                                         atChild(".class", "Html.INPUT.submit",                                                                                                                 ".value", "Submit"))) ;
                                                                                                                
        // This will find all the forms in the  given browser, and return all forms
        // "INPUT" elements, of any type.
        RegularExpression inputRE = new RegularExpression("*INPUT*", false) ;
        foundTOs = Browser_htmlBrowser().find(atList(
                                                                                        atDescendant(".class", "Html.FORM"),                                                                                         atChild(".class", inputRE))) ;  

 
 

Parameters:

properties - The property set to match against.

mappableOnly - Whether to search all children or just mappable children

Since:

RFT2.0, RFT8.1.1 Please refer to ClientTestObject for the functionality.

See Also:

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

findAndInvoke

public java.lang.Object findAndInvoke(Subitem properties,                                       java.lang.String methodName)

Finds a TestObject based on find(Subitem) and invokes the supplied method on the TestObject (invoke(String)). The found TestObject is automatically unregistered (unregister()) during the transaction. If no candidates are found an ObjectNotFoundException is thrown. If more than one candidate is found an AmbiguousRecognitionException is thrown. If the specified method does not exist on the found TestObject a MethodNotFoundException is thrown.

Parameters:

properties - The property set to match against

methodName - The method to invoke

Returns:

The return value of the invoke, if applicable.

Since:

RFT2.0

See Also:

find(Subitem), invoke(String)

findAndInvoke

public java.lang.Object findAndInvoke(Subitem properties,                                       java.lang.String methodName,                                       java.lang.String methodSignature,                                       java.lang.Object[] args,                                       boolean mappableOnly)

Finds a TestObject based on find(Subitem, boolean) and invokes the supplied method on the TestObject (invoke(String, String, Object[])). The found TestObject is automatically unregistered (unregister()) during the transaction. If no candidates are found an ObjectNotFoundException is thrown. If more than one candidate is found an AmbiguousRecognitionException is thrown. If the specified method does not exist on the found TestObject a MethodNotFoundException is thrown.

Parameters:

properties - The property set to match against

methodName - The method to invoke

methodSignature - The JNI signature of the method to invoke

args - An array of arguments to pass to the invoked method

mappableOnly - Boolean indicating whether only mappable children of the TestObject should be considered.

Returns:

The return value of the invoke, if applicable.

Since:

RFT2.0, RFT8.1.1 Please refer to ClientTestObject for the functionality.

See Also:

find(Subitem, boolean), invoke(String, String, Object[]), ClientTestObject

findAndInvokeProxy

public java.lang.Object findAndInvokeProxy(Subitem properties,                                            java.lang.String methodName,                                            java.lang.String methodSignature,                                            java.lang.Object[] args,                                            boolean mappableOnly)

Finds a TestObject based on find(Subitem, boolean) and invokes the supplied method on the TestObject's proxy (invoke(String, String, Object[])). The found TestObject is automatically unregistered (unregister()) during the transaction. If no candidates are found an ObjectNotFoundException is thrown. If more than one candidate is found an AmbiguousRecognitionException is thrown. If the specified method does not exist on the found TestObject a MethodNotFoundException is thrown.

Parameters:

properties - The property set to match against

methodName - The method to invoke

methodSignature - The JNI signature of the method to invoke

args - An array of arguments to pass to the invoked method

mappableOnly - Boolean indicating whether only mappable children of the TestObject should be considered.

Returns:

The return value of the invoke, if applicable.

Since:

RFT2.0, RFT8.1.1 Please refer to ClientTestObject for the functionality.

See Also:

find(Subitem, boolean), invoke(String, String, Object[]), ClientTestObject

getRecognitionProperties

public java.util.Hashtable getRecognitionProperties()

Returns the properties that are useful for recognition. Note that this is an extended Hashtable and has null values. The keys, which are strings that represent property names, are never null. This method does not return references to objects in the software under test; it only returns properties that are value classes.

Since:

RFT1.0

getRecognitionPropertyWeight

public int getRecognitionPropertyWeight(java.lang.String propertyName)

Returns an indication of how useful this property is for recognition. A value of 0 indicates not useful at all, and a value of 100 indicates that the property is extremely useful for recognition. This method must return a value greater than or equal to zero and less than or equal to 100.

Parameters:

propertyName - the name of the recognition property to return a weight value for

Since:

RFT1.1

See Also:

getRecognitionProperties()

getTestDataTypes

public java.util.Hashtable getTestDataTypes()

Returns a Hashtable of data type descriptions of the verification point data available with the associated object in the software under test. The Hashtable keys are String objects that are used as the verification point type in the associated test data. The type is a simple value that is different from other type values associated with this object under test. The type keys map to a verbose description of the test data. This is reasonable for presentation to a user.

Returns:

A Hashtable of type/description pairs used to describe the verification data available from this proxy.

Since:

RFT1.0

See Also:

getTestData(String), ITestData

getTestData

public ITestData getTestData(java.lang.String testDataType)

Constructs the specified verification data object. The testDataType parameter is one of the Hashtable keys returned by getTestDataTypes.

Parameters:

testDataType - a test data type supplied by getTestDataTypes

Since:

RFT1.0

See Also:

getTestDataTypes(), ITestData

updateTestData

public ITestData updateTestData(java.lang.String testDataType,                                 ITestData testData)

Updates the supplied test data object and returns it. The testDataType parameter is one of the Hashtable keys returned by getTestDataTypes. The testData is a previously supplied ITestData object that must be updated to reflect the current state of the associated TestObject.

Parameters:

testDataType - a test data type supplied by getTestDataTypes

testData - the test database object that requires updating

Since:

RFT1.0

See Also:

getTestDataTypes(), ITestData

waitForExistence

public void waitForExistence(double maximum_find_object_time,                              double find_object_wait_between_retry)

Waits until an object exists.

Throws:

ObjectNotFoundException

AmbiguousRecognitionException

Parameters:

maximum_find_object_time - the maximum amount of time (in seconds) to wait while finding the object

find_object_wait_between_retry - the amount of time (in seconds) to wait between attempts to find the object

Since:

RFT1.0, RFT8.1.1 Please refer to ClientTestObject for the functionality.

See Also:

ClientTestObject

waitForExistence

public void waitForExistence()

Waits the default time until an object exists. The maximum time spent finding the object is specified by the option rt.time.maximum_wait_for_existence_time. The time to delay between retries is specified by the option rt.time.wait_for_existence_delay_between_retries.

Throws:

ObjectNotFoundException

AmbiguousRecognitionException

Since:

RFT1.0

getScriptCommandFlags

public ScriptCommandFlags getScriptCommandFlags()

Returns an active state value that reflects the state of the TestObejct at the time of the call. The state includes values such as ENABLED and SHOWING and allows the find algorithm to wait until a required state is achieved.

Returns:

An object that reflects the active state of the represented TestObject

unregister

public void unregister()

Unregisters a TestObject reference.

Since:

RFT1.0, RFT8.1.1 Please refer to ClientTestObject for the functionality.

See Also:

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

getOwner

public TestObject getOwner()

Returns a reference to the owner object. The owner-owned relationship is a hierarchical relationship similar to the parent-child relationship. An object can have an owner or a parent, but not both. An object can have both children and owned objects. For example, a dialog box is commonly owned by a top-level window. The returned object can extend TestObject and support more methods. The reference to the object should be released by calling one of the unregister methods.

Since:

RFT1.0

See Also:

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

getOwnedObjects

public TestObject[] getOwnedObjects()

Returns an array of references to the objects owned by this object. The returned objects can be derived from TestObject and can support more methods. The references to the objects should be released by calling one of the unregister methods. If the object has no owned objects, a 0-length array of TestObjects will be returned.

Since:

RFT1.0

See Also:

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

getField

public java.lang.Object getField(java.lang.String fieldName)

Returns the value of a field of the object in the SUT encapsulated by this TestObject.

Parameters:

fieldName - The name of the field to retrieve.

Since:

RFT2.0

getMethods

public MethodInfo[] getMethods()

Returns a an array of MethodInfo objects describing the methods supported by the object. Note that many of the methods are property methods. These methods can be invoked by using the invoke(String, String, Object[]) method. If the object has no methods, a 0-length array of TestObjects is returned.

Since:

RFT1.0

invoke

public java.lang.Object invoke(java.lang.String method,                                java.lang.String methodSignature,                                java.lang.Object[] args)

Invokes a method on the object in the software under test. Note that this can directly modify the object in the software under test. You should therefore be extremely careful when you do this. Whenever possible, avoid using invoke, which allows you to modify the software under test in ways that a typical user cannot. If you use this method, be sure to discuss its use with the developers of the software you are testing.

If the returned object is not a value class, invoke registers the object and returns a reference to the object in the software under test. Registered object references are released by calling one of the unregister methods.

The methodSignature uses JNI syntax to describe the parameter types and optionally the return value types for the method. The general syntax has the parameter types in parentheses, followed by the return type: (parameterTypes)returnType. Note that the returnType is not a required part of the signature - it can be omitted. There are specific encodings for the primitive types, and then a general encoding for class types.

Code	Type
Z	boolean
B	byte
C	char
S	short
I	int
J	long
F	float
D	double
V	void
Lfully-qualified-class;	For example: Ljava.lang.String;

In addition, arrays are specified by combining the brace character '[' with another type. For example, [I is an array of integers, [[I is an array of arrays of integers and [Ljava.lang.Object; is an array of Objects. Another example:

void myMethod(long n, String s, int[] arr)

has the following signature:

(JLjava.lang.String;[I)V

Parameters:

method - the name of the method to be called

methodSignature - the signature of the method to be called (using standard JNI syntax)

args - the arguments to be passed to the method

Since:

RFT1.0

See Also:

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

invoke

public java.lang.Object invoke(java.lang.String method)

Invokes a method with no arguments on the object in the software under test. Note that this can directly modify the object in the software under test. You should therefore be extremely careful when you do this. Whenever possible, you should avoid using invoke, which allows you to modify the software under test in ways that a typical user cannot. If you use this method, be sure to discuss its use with the developers of the software you are testing.

If the returned object is not a value class, invoke registers the object and returns a reference to the object in the software under test. Registered object references are released by calling one of the unregister methods.

Parameters:

method - the name of the method to be called

methodSignature - the signature of the method to be called (using standard JNI syntax)

Since:

RFT1.0

See Also:

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

invokeProxy

protected java.lang.Object invokeProxy(java.lang.String method,                                        java.lang.String methodSignature,                                        java.lang.Object[] args)

Invokes a method on the proxy for an object in the software under test. Note that this can directly modify the object in the software under test. You should therefore be extremely careful when you do this. Whenever possible, avoid using invoke, which allows you to modify the software under test in ways that a typical user cannot. If you use this method, be sure to discuss its use with the developers of the software you are testing.

If the returned object is not a value class, invoke registers the object and returns a reference to the object in the software under test. Registered object references are released by calling one of the unregister methods.

Parameters:

method - the name of the method to be called

methodSignature - the signature of the method to be called (using standard JNI syntax)

args - the arguments to be passed to the method

Since:

RFT1.0

See Also:

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

invokeProxy

protected java.lang.Object invokeProxy(java.lang.String method)

Invokes a method on the object in the software under test. Note that this can directly modify the object in the software under test. You should therefore be extremely careful when you do this. Whenever possible, avoid using invoke, which allows you to modify the software under test in ways that a typical user cannot. If you use this method, be sure to discuss its use with the developers of the software you are testing.

If the returned object is not a value class, invoke registers the object and returns a reference to the object in the software under test. Registered object references are released by calling one of the unregister methods.

Parameters:

method - the name of the method to be called

methodSignature - the signature of the method to be called (using standard JNI syntax)

Since:

RFT1.0

See Also:

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

getDescribedObject

protected TestObject getDescribedObject(CrossDomainContainer describedTestObject)

Used to bind a described object returned by proxy into the corresponding bound TestObject

Parameters:

describedTestObject - - CrossDomainContainer identifying the described object

Returns:

TestObject

getDescribedObjects

protected TestObject[] getDescribedObjects(TestObject[] testObject)

Given an array of TestObjects, find any described objects and turn them into bound test objects.

Parameters:

testObject - - original set of TestObjects

Returns:

TestObject[] with described objects bound to TestObject

performTest

public boolean performTest(IFtVerificationPoint baseline)

Captures, compares and logs active data available relative to this object instance against the supplied baseline data.

Returns:

A true value is returned if the passing result is logged, otherwise false is returned.

Since:

RFT1.0

See Also:

performTest(IFtVerificationPoint,boolean), performTest(IFtVerificationPoint,double,double), performTest(IFtVerificationPoint,double,double,boolean)

performTest

public boolean performTest(IFtVerificationPoint baseline,                            boolean compareTrueEqualsPass)

Captures, compares and logs active data available relative to this object instance against the supplied baseline data. Allows failing verification points to return and log a passing result.

Parameters:

compareTrueEqualsPass - If true the expected and actual data must match to get a passing result. If false the expected and actual data must NOT match to get a passing result.

Returns:

A true value is returned if the passing result is logged, false is returned for a failing result.

Since:

RFT1.1

See Also:

performTest(IFtVerificationPoint), performTest(IFtVerificationPoint,double,double), performTest(IFtVerificationPoint,double,double,boolean)

performTest

public boolean performTest(IFtVerificationPoint baseline,                            double delayBetweenRetries,                            double maximumTestTime)

Captures, compares and logs active data available relative to this object instance against the supplied baseline data. Allows failing verification points to retry until a passing result can be returned or the retry timeout is reached.

Parameters:

delayBetweenRetries - the delay in seconds after a failed result is recaptured and tested again.

maximumTestTime - the maximum time in seconds spent attempting to receive a passing result. Note that at least one attempt will be made to return a failed result, even if this value is a zero or negative value.

Returns:

A true value is returned if the passing result is logged, false is returned for a failing result.

Since:

RFT2.0

See Also:

performTest(IFtVerificationPoint), performTest(IFtVerificationPoint,boolean), performTest(IFtVerificationPoint,double,double,boolean)

performTest

public boolean performTest(IFtVerificationPoint baseline,                            double delayBetweenRetries,                            double maximumTestTime,                            boolean compareTrueEqualsPass)

Captures, compares and logs active data available relative to this object instance against the supplied baseline data. Allows failing verification points to retry until a passing result can be returned or the retry timeout is reached. Also allows failing verification points to return and log a passing result.

Parameters:

delayBetweenRetries - the delay in seconds after a failed result is recaptured and tested again.

maximumTestTime - the maximum time in seconds spent attempting to receive a passing result. Note that at least one attempt will be made to return a failed result, even if this value is a zero or negative value.

compareTrueEqualsPass - If true the expected and actual data must match to get a passing result. If false the expected and actual data must NOT match to get a passing result.

Returns:

A true value is returned if the passing result is logged, false is returned for a failing result.

Since:

RFT2.0

See Also:

performTest(IFtVerificationPoint), performTest(IFtVerificationPoint,boolean), performTest(IFtVerificationPoint,double,double)

compare

public boolean compare(IFtVerificationPoint baseline)

Compares the baseline, that is, expected data to the actual data. Note that the actual data is captured if it is not available. The result reflects the value-class comparison of the data.

Since:

RFT8.1.0.1

See Also:

compare(IFtVerificationPoint,double,double)

compare

public boolean compare(IFtVerificationPoint baseline,                        double delayBetweenRetries,                        double maximumTestTime)

Compares the expected result with the actual result. If the compare fails, the actual value will be automatically recaptured and recompared when appropriate. The actual data cannot be recaptured with a manual verification point, which makes the retry irrelevant.

Parameters:

delayBetweenRetries - the delay in seconds after a failed result is recaptured and retested

maximumTestTime - the maximum time in seconds spent attempting to receive a passing result. Note that at least one attempt will be made to return a failed result, even if this value is a zero or negative value.

Since:

RFT8.1.0.1

See Also:

compare(IFtVerificationPoint)

compareAndLog

public boolean compareAndLog(IFtVerificationPoint baseline)

Compares the baseline, that is, expected data to the actual data and logs the result to the script log. Note that the actual data is captured if it is not available. This action extends the compare(com.rational.test.ft.vp.IFtVerificationPoint) method so that it too automatically logs the result in the script log.

Returns:

A true value is returned if the passing result is logged, false is returned if a failing result is logged.

Since:

RFT8.1.0.1

See Also:

compareAndLog(IFtVerificationPoint,boolean)

compareAndLog

public boolean compareAndLog(IFtVerificationPoint baseline,                              boolean compareTrueEqualsPass)

Allows failing verification points to return and log a passing result.

Parameters:

compareTrueEqualsPass - If true, the expected and actual data must match to get a passing result. If false, the expected and actual data must NOT match to get a passing result.

Returns:

A true value is returned if the passing result is logged, false is returned if a failing result is logged.

Since:

RFT8.1.0.1

See Also:

compareAndLog(IFtVerificationPoint)

getActualData

public java.lang.Object getActualData(IFtVerificationPoint baseline)

Enables access to the actual, that is, currently active data associated with a verification point. Regarding the recorded (not the manual) data, the actual data is captured if it is not available and if the baseline data exists.

Since:

RFT8.1.0.1

getNameInScript

public java.lang.String getNameInScript()

Since:

RFT2.0

isTopLevelTestObject

public boolean isTopLevelTestObject()

Check to see if this TestObject is indeed the Top Level Test Object. The default is false unless a specialized class which happens to be the parent class returns otherwise, when its true

Returns: