Common Methods and Properties

Description

The methods and properties described in this section are common to all test objects.

Methods

Common Method CaptureBitmapSaves a screen capture of the object as a .png or .bmp image using the specified file name.
Common Method CheckChecks whether the actual value of an item matches the expected value.
Common Method CheckPropertyChecks whether the actual value of the specified object property matches the specified expected value within the specified timeout.
Common Method ChildObjectsReturns the collection of child objects contained within the object.
Common Method GetAllROProperties

Returns the collection of properties and current values from the object in the application.

Common Method GetROProperty

Returns the current value of the description property from the object in the application.

Common Method GetTOPropertiesReturns the collection of properties and values used to identify the object.
Common Method GetTOPropertyReturns the value of the specified description property from the test object description.
Common Method Highlight

Highlights the object in the application.

Common Method OutputRetrieves the current value of an item and stores it in a specified location.
Common Method RefreshObjectInstructs UFT One to re-identify the object in the application the next time a step refers to this object.
Common Method SetTOPropertySets the value of the specified description property in the test object description.
Common Method ToStringReturns a string that represents the test object.
Common Method WaitPropertyWaits until the specified object property achieves the specified value or exceeds the specified timeout before continuing to the next step.

Properties

Common Property ExistChecks whether the object currently exists in the open application.
Common Property ObjectAccesses the native methods and properties of the object.

 

Back to top

CaptureBitmap Method

Description

Saves a screen capture of the object as a .png or .bmp image using the specified file name.

Syntax

object.CaptureBitmap FullFileName, [OverrideExisting]

Arguments

ParameterDescription
FullFileName Required. A String value.
OverrideExisting Optional. A Boolean value.
Default value = False

Return Type

None

Examples

Note: The examples below are specific to a certain environment. However, the syntax and context can be applied to most other environments.


 

Back to top

Check Method

Description

Checks whether the actual value of an item matches the expected value.

Syntax

object.Check (Verify)

Arguments

ParameterDescription
Verify Required. A Variant.
The checkpoint object, which contains the expected values to be compared and verified during the test run.

Return Type

A Boolean value.

IMPORTANT

  • You create checkpoints and define the property checks for the checkpoint using one of the Insert Checkpoint options. For more information, refer to the UFT One User Guide.
  • The Check method is not supported for Insight or Text test objects.

Example

Note: The example below is specific to a certain environment=. However, the syntax and context can be applied to most other environments.


 

Back to top

CheckProperty Method

Description

Checks whether the actual value of the specified object property matches the specified expected value within the specified timeout.

Syntax

object.CheckProperty (PropertyName, PropertyValue, [TimeOut])

Arguments

ParameterDescription
PropertyName Required. A String value.

The name of the property whose value is checked. The available properties are listed in the description properties page under each test object.

PropertyValue Required. A Variant.
The expected value against which the actual property value should be checked. You can either use a simple value or you can use a comparison object together with the value to perform more complex comparisons.
TimeOut Optional. An unsigned long integer value.
The time, in milliseconds, within which UFT One should check whether the actual value of the property matches the specified expected value. If no value is specified, UFT One uses the time set in the Object Synchronization Timeout option in the Run pane of the Test Settings dialog box.
Default value = 60

Return Type

A Boolean value.

Returns TRUE if the property achieves the value, and FALSE if the timeout is reached before the property achieves the value.

A TRUE return value reports a Passed step to the run results; a FALSE return value reports a Failed step to the run results.

IMPORTANT

If the expected and actual values do not match, an error is reported and the test or component status is changed to failed.

Note: For test run synchronization, or whenever you do not want to fail the test if the expected and actual values do not match, use the WaitProperty method.

You can also use comparison objects to perform more complex value comparisons. For example, you can instruct UFT One to check whether a specific property value is greater than the specified value.

An example of the syntax required when using a comparison object is: Object.CheckProperty "items count",micGreaterThan(8)

The following comparison objects can be used:

  • micGreaterThan: Greater than; Specifies that UFT One checks whether the property value is greater than the specified value.
  • micLessThan: Less than; Specifies that UFT One checks whether the property value is less than the specified value.
  • micGreaterThanOrEqual: Greater than or equal to; Specifies that UFT One checks whether the property value is greater than or equal to the specified value.
  • micLessThanOrEqual: Less than or equal to; Specifies that UFT One checks whether the property value is less than or equal to the specified value.
  • micNotEqual: Not equal to; Specifies that UFT One checks whether the property value is not equal to the specified value.
  • micRegExpMatch: Regular expression; Specifies that UFT One checks whether the property value achieves a regular expression match with the specified value. Regular expressions are case-sensitive and must match exactly. For example, 'E.*h' matches 'Earth' but not 'The Earth' or 'earth'.

When the types of the expected value and actual value do not match, the comparisons are performed as follows (in this order):

  • Empty values: Empty values may be an uninitialized variable or field (which returns TRUE for the IsNull function in VBscript) or initialized to an empty value (which returns TRUE for the IsEmpty function is VBscript). When trying to compare two arguments when at least one is an empty value, the comparison assumes equality for two uninitialized arguments and for two empty arguments. Any other combination is considered unequal.
    For example:
    dim vEmpty
    Object.CheckProperty "text",micNotEqual
    (vEmpty) 
    will not wait for the timeout (because the 'text' property value is an empty string and the argument passed to micNotEqual is an empty value, and so micNotEqual finds them not equal and returns TRUE).
  • String values: When trying to compare a string value with non-string value, the string value is converted to the non-string type and then compared. If the string value cannot be converted to the non-string type, the comparison assumes the values are not equal.
    For example:
    Object.CheckProperty "text",micGreaterThan(8) will not wait for the timeout if the 'text' property value is '16' (because micGreaterThan finds 16 to be greater than 8 and returns TRUE), but will wait if the 'text' property value is 'a' (because 'a' cannot be converted to a number).
  • Boolean values: When trying to compare a Boolean value with non-boolean value, the non-boolean value is converted to a boolean value and then compared. The conversion method assumes that any integer value other than '0' is TRUE, and that '0' alone is FALSE. If the conversion fails to produce a boolean value (for example, if the value is 'abc'), the comparison result will be FALSE (note that for the WaitProperty method this result would instruct UFT One to keep waiting). If the conversion succeeds, the method compares the two boolean values according to the comparison logic.
  • Other value types: When other value types do not match, they are compared under the assumption that different types are not equal (nor greater than or less than each other).

Note: When working with Mobile objects, you can use this method only for a limited list of properties. See the Mobile Objects' description properties pages for details.

Examples

Note: The examples below are specific to a certain environment. However, the syntax and context can be applied to most other environments.


 

Back to top

ChildObjects Method

Description

Returns the collection of child objects contained within the object.

Syntax

object.ChildObjects ([Description])

Mobile testing: When working with iOS devices, use the following syntax:

Device.App.childobjects([Description])

Arguments

ParameterDescription
Description Required for the Mobile Add-in. Optional for all other add-ins. An Object.
The Properties (collection) object containing the description of the objects you want to find. 
Tip: You can retrieve a Properties collection using the GetTOProperties method or you can build a Properties collection object using the Description object.  For more information on the Description object, refer to the Utility Objects section of the UFT One Object Model Reference.

Return Type

An Object.

IMPORTANT

  • The method returns the child objects that fit the description specified (using the Properties object).

    When working with Android native apps, the following properties are supported: resourceid; class; text; nativeclass

  • When an object is retrieved by the ChildObjects method, UFT One accesses it directly in the application and does not save a description for the object. Therefore, you must use the object immediately after retrieving it, and before anything in the application changes.

  • The ChildObjects method is not supported for: Insight test objects, Text test objects, and flutter-based mobile applications.

  • If you use a Description object to specify a specific test object, when specifying the test object type for Mobile objects, use "class" instead of "micClass".

Examples

Note: The examples below are specific to a certain environment. However, the syntax and context can be applied to most other environments.


Back to top

GetAllROProperties Method

Description

Returns the collection of properties and current values from the object in the application.

Syntax

object.GetAllROProperties

Return Type

An Object.

IMPORTANT

GetAllROProperties differs from the GetTOProperties method. GetAllROProperties returns the collection of properties and their current values from the object in the application during the test run. GetTOProperties returns the values from the test object's description.

Example

Note: The example below are specific to a certain environment. However, the syntax and context can be applied to most other environments.


 

Back to top

GetROProperty Method

Description

Returns the current value of the description property from the object in the application.

Syntax

object.GetROProperty (Property, [PropertyData])

Arguments

ParameterDescription
Property Required. A String value.
The property to retrieve from the object.
PropertyData Optional. A Variant.
Not in use.

Return Type

A Variant.

IMPORTANT

  • GetROProperty differs from the GetTOProperty method. GetROProperty returns the current property value of the object in the application during the test run. GetTOProperty returns the value from the test object's description.
  • When working with Mobile objects, you can use this method only for a limited list of properties. See the Mobile Objects' description properties pages for details.
  • The GetROProperty method supports retrieving attribute values and style property values of a web object.

    • Use the syntax <web object>.GetROProperty("attribute/<attribute name>") to get the value of an attribute of a web object.

    • Use the syntax <web object>.GetROProperty("style/<style property name>") to get the style property value of a web object.

Examples

Note: The examples below are specific to a certain environment. However, the syntax and context can be applied to most other environments.


 

Back to top

GetTOProperties Method

Description

Returns the collection of properties and values used to identify the object.

Syntax

object.GetTOProperties

Return Type

An Object.

IMPORTANT

GetTOProperties differs from the GetROProperty method. GetTOProperties returns the values from the test object's description. GetROProperty returns the current property value of the object in the application during the test run.

Examples

Note: The examples below are specific to a certain environment. However, the syntax and context can be applied to most other environments.


 

Back to top

GetTOProperty Method

Description

Returns the value of the specified description property from the test object description.

Syntax

object.GetTOProperty (Property)

Arguments

ParameterDescription
Property Required. A String value.
Property whose value is retrieved from the object description.

Return Type

A Variant.

IMPORTANT

GetTOProperty differs from the GetROProperty method. GetTOProperty returns the value from the test object's description. GetROProperty returns the current property value of the object in the application during the test run.

You can use the GetTOProperty method to retrieve the values of only those properties that are included in the test object description. Specifying a property that is not included in the test object's description results in a warning status for the step and the test. For more details on adding properties to a test object description, see the UFT One User Guide. For details on the exact versions supported, see the UFT One Support Matrix.

Examples

Note: The examples below are specific to a certain environment. However, the syntax and context can be applied to most other environments.


Back to top

Highlight Method

Description

Highlights the object in the application.

Syntax

object.Highlight (Type)

Arguments

ParameterDescription
Type

Optional. A predefined constant or number.
The type of highlight action to perform.

Possible values: 

  • 0 or HIGHLIGHT_STATIC. Display a rectangle around the object.

  • 1 or HIGHLIGHT_FLASH (default). Display a flashing rectangle around the object.

  • 2 or HIGHLIGHT_REMOVE. Remove the highlight from the object.

Caution: A rectangle displayed using the option HIGHLIGHT_STATIC option remains on the screen. Use an object.Highlight (HIGHLIGHT_REMOVE) step to remove it explicitly.

Return Type

None.

Example

Note: The examples below are specific to a certain environment. However, the syntax and context can be applied to most other environments.


 

Back to top

Output Method

Description

Retrieves the current value of an item and stores it in a specified location.

Syntax

object.Output (Verify)

Arguments

ParameterDescription
Verify Required. A Variant.
The output object that contains the details of the data to output.

Return Type

None.

IMPORTANT

You insert output values in your test using one of the Insert Output Value options. For more information, refer to the UFT One User Guide.

Example

Note: The examples below are specific to a certain environment. However, the syntax and context can be applied to most other environments.


 

Back to top

RefreshObject Method

Description

Instructs UFT One to re-identify the object in the application the next time a step refers to this object.

Syntax

object.RefreshObject

Return Type

None.

IMPORTANT

This method should be used only prior to steps that meet both of the following conditions:

  1. The step performs an operation that references an object, but does not specify an object name from the object repository or a programmatic description. For example:

    • Steps performed under a With statement:

      With 
      	Dialog("Edit").AcxEdit("MyEdit").SetCaretPos 0    
      	Dialog("Edit").AcxEdit("MyEdit").Type "Hello."             
      End With
    • Steps performed on a variable that has been set to a test object:

      • Steps performed under a With statement:

        With 
        	Dialog("Edit").AcxEdit("MyEdit").SetCaretPos 0    
        	Dialog("Edit").AcxEdit("MyEdit").Type "Hello."             
        End With
      • Steps performed on a variable that has been set to a test object:

        Set MyEdit=Dialog("Open").AcxEdit("File")
        MyEdit.Set "document.txt"
      • Steps performed within a function on an object that was passed by the function call, such as a call to a registered (RegisterUserFunc) method.

        Function MySet (obj, x)
        dim y
        y = obj.GetROProperty("value")
        Reporter.ReportEvent micDone, "previous value", y
        MySet=obj.Set(x)
        End Function
        
  2. The object referenced by your step was refreshed, redrawn, or changed in some way in your application since the last time a step was performed on that object (but it still matches the test object description defined for the object).


Examples

Note: The examples below are specific to a certain environment. However, the syntax and context can be applied to most other environments.


 

Back to top

SetTOProperty Method

Description

Sets the value of the specified description property in the test object description.

Syntax

object.SetTOProperty (Property, Value)

Arguments

ParameterDescription
Property Required. A String value.
The property whose value to set in the test object description.
Value Required. A Variant.
The value to assign to the listed property.

Return Type

None.

IMPORTANT

SetTOProperty changes the property values used to identify an object during the test run. It has no effect on the Active Screen, the values saved in the Object Repository, or on the object in the application.

If you specify a property that is not included in the test object description, this property is added. For more information on adding properties to a test object description, see the UFT One User Guide.

Examples

Note: The examples below are specific to a certain environment. However, the syntax and context can be applied to most other environments.


 

Back to top

ToString Method

Description

Returns a string that represents the test object.

The ToString method is useful if you want to retrieve the test object name and type from within a function or keyword.

Syntax

object.ToString

Return Type

A String value.

The name of the test object and its generic type, for example, AcxButton("MyRoundButton") object returns: MyRoundButton button

IMPORTANT

Enhancements to UI Automation in UFT One 14.03 may affect tests that contain the ToString method.

If you have upgraded from a UFT One version earlier than 14.03, have the UI Automation Add-in enabled, and use the ToString method in your tests, your test may require some updates before it can run without errors.

Run your test to find the steps that require updates.

Examples

Note: The examples below are specific to a certain environment. However, the syntax and context can be applied to most other environments.


 

Back to top

WaitProperty Method

Description

Waits until the specified object property achieves the specified value or exceeds the specified timeout before continuing to the next step.

Syntax

object.WaitProperty (PropertyName, PropertyValue, [TimeOut])

Arguments

ParameterDescription
PropertyName Required. A String value.
The name of the property whose value is checked.
PropertyValue Required. A Variant.
The value to be achieved before continuing to the next step.
TimeOut Optional. A long integer value.
The time, in milliseconds, after which UFT One continues to the next step if the specified value is not achieved. If no value is specified, UFT One uses the time set in the Object Synchronization Timeout option in the Run pane of the Test Settings dialog box.
Default value = -1

Return Type

A Boolean value.

Returns TRUE if the property achieves the value, and FALSE if the timeout is reached before the property achieves the value. A FALSE return value does not indicate a failed step.

IMPORTANT

This method is useful for test run synchronization. Unlike the Exist method, the WaitProperty method enables you to synchronize the test run based on a specific object property. For example, you can instruct UFT One to wait for a particular string to appear in a static text control:
' Wait up to 30 seconds for the string "Ready" to appear in the "Status" text control.
Window("Test").Static("Status:").WaitProperty "text", "Ready", 30000

Note: UFT One must be able to identify the specified object to perform this synchronization.

You can also use comparison objects to perform more complex value comparisons. For example, you can instruct UFT One to wait until a specific property value is greater than the specified value.

An example of the syntax required when using a comparison object is: Object.WaitProperty "items count",micGreaterThan(8)

The following comparison objects can be used:

  • micGreaterThan: Greater than; Specifies that UFT One waits until the property value is greater than the specified value.
  • micLessThan: Less than; Specifies that UFT One waits until the property value is less than the specified value.
  • micGreaterThanOrEqual: Greater than or equal to; Specifies that UFT One waits until the property value is greater than or equal to the specified value.
  • micLessThanOrEqual: Less than or equal to; Specifies that UFT One waits until the property value is less than or equal to the specified value.
  • micNotEqual: Not equal to; Specifies that UFT One waits until the property value is not equal to the specified value.
  • micRegExpMatch: Regular expression; Specifies that UFT One waits until the property value achieves a regular expression match with the specified value. Regular expressions are case-sensitive and must match exactly. For example, 'E.*h' matches 'Earth' but not 'The Earth' or 'earth'.

When the types of the expected value and actual value do not match, the comparisons are performed as follows (in this order):

  • Empty values: Empty values may be an uninitialized variable or field (which returns TRUE for the IsNull function in VBscript) or initialized to an empty value (which returns TRUE for the IsEmpty function is VBscript). When trying to compare two arguments when at least one is an empty value, the comparison assumes equality for two uninitialized arguments and for two empty arguments. Any other combination is considered unequal.
    For example:
    dim vEmpty
    Object.WaitProperty "text",micNotEqual
    (vEmpty) 
    will not wait for the timeout (because the 'text' property value is an empty string and the argument passed to micNotEqual is an empty value, and so micNotEqual finds them not equal and returns TRUE).
  • String values: When trying to compare a string value with non-string value, the string value is converted to the non-string type and then compared. If the string value cannot be converted to the non-string type, the comparison assumes the values are not equal.
    For example:
    Object.WaitProperty "text",micGreaterThan(8) will not wait for the timeout if the 'text' property value is '16' (because micGreaterThan finds 16 to be greater than 8 and returns TRUE), but will wait if the 'text' property value is 'a' (because 'a' cannot be converted to a number).
  • Boolean values: When trying to compare a Boolean value with non-boolean value, the non-boolean value is converted to a boolean value and then compared. The conversion method assumes that any integer value other than '0' is TRUE, and that '0' alone is FALSE. If the conversion fails to produce a boolean value (for example, if the value is 'abc'), the comparison result will be FALSE (note that for the WaitProperty method this result would instruct UFT One to keep waiting). If the conversion succeeds, the method compares the two boolean values according to the comparison logic.
  • Other value types: When other value types do not match, they are compared under the assumption that different types are not equal (nor greater than or less than each other).

Note: When working with Mobile objects, you can use this method only for a limited list of properties. See the Mobile Objects' description properties pages for details.

Examples

Note: The examples below are specific to a certain environment. However, the syntax and context can be applied to most other environments.


 

Back to top

Exist Property

Description

Checks whether the object currently exists in the open application.

Syntax

object.Exist ([TimeOut])

Arguments

ParameterDescription
TimeOut

Optional. An unsigned long integer value.

The length of time (in seconds) to search for the object before returning a True or False value.

  • If a timeout value is specified, UFT One waits until it finds the object or until the timeout is reached.

  • If no value is specified, the value specified in the Test Settings dialog box for the Object Synchronization Timeout is used for tests. For business components, the pre-defined value of 20 seconds is used.

Note: A value of 0 is not supported for Mobile test objects.

For more information on the Object Synchronization Timeout, see the UFT One Help Center.

Value Type

Read-only property. A Boolean value

Example

Note: The example below are specific to a certain environment. However, the syntax and context can be applied to most other environments.


 

Back to top

Object Property

Description

Accesses the native methods and properties of the object.

Syntax

object.Object

Value Type

Read-only property. An Object.

IMPORTANT

  • The following add-ins do not support the .Object property:

    Delphi, Flex, Mobile, Oracle, PowerBuilder, Standard Windows, Stingray, Terminal Emulator, and VisualAge.

  • Insight and Text test objects do not support the .Object property.

  • The Internet Explorer Document Object Model (DOM) is a set of COM objects that correspond to the elements you see on a Web page. Every HTML element (<IMG>, <A>, or <TABLE>) is programmable via an object that is part of the overall object model. You can modify the appearance and behavior of an HTML element by altering an object's properties and calling its methods. In addition to methods and properties, the objects also fire events to signal user interaction or changes in the corresponding HTML element.

    To allow access to these objects, the browser creates a top-level document object for each HTML document it displays. This document object represents the entire page. From this document object you can access the rest of the object hierarchy by using properties and collections. For example, you will use the links property of the document object to retrieve the actual link collection.

    When you use the .Object property on a Web-based object in your test or component, you actually get a reference to the DOM object. This means that every operation you can perform on the DOM object, you can also perform on the Web-based object using the .Object property.SAP Solutions Add-in

  • : The .Object property is used to access the internal (native) methods and properties of the SAP Scripting API. For more information on these methods and properties, refer to your SAP Scripting API documentation.

    You can use either forms of the following syntax:

    SAPGuiObject(description).Object.Method_to_activate()

    or

    Set myObj=SAPGuiObject(description).Object
    myObj.Method_to_activate()
  • WPF Add-in: You can use the AutomationElement Property to access the common methods and properties provided by UI Automation that are specific to the element's control type.

    You can use the AutomationPattern Property to access the properties and methods provided by UI Automation for a specific instance of a Control Pattern of the element's control type.

  • Silverlight Add-in: The .Object property returns the corresponding .NET object. For example, the SelectedDate property of the Silverlight Calendar control returns an object of type DateTime.

    To retrieve a string representation of the object, you can use the ToString() method.

    Example:

    msgbox Browser("Silverlight Controls").Page("Silverlight Controls").SlvWindow("Page").SlvCalendar("datePicker").Object.SelectedDate.ToString()
  • .NET Windows Forms Add-in: If a native method's return value or a native property's value is a structure, UFT One returns a string value representing the structure (by invoking the structure's ToString method).

Example

Note: The example is specific to a certain environment. However, the syntax and context can be applied to most other environments.


See also: