Share this page
AITextObject Object
Description
An internal object used to perform operations on text identified using AI.
IMPORTANT
AI-based testing is supported on the following technologies:
UFT One versions 2022 and later: Web, mobile, and SAP GUI for Windows.
UFT One versions 2021 R1 and earlier: Web and mobile.
AI objects are supported in UFT One only when:
- The UFT One Web Add-in, Mobile Add-in, or SAP Solutions Add-in is installed and loaded.
- The UFT One AI Features are installed and AI is enabled in the UFT One options. For details, see the UFT One Help Center.
To retrieve an AITextObject object, use the AIUtil.FindText or AIUtil.FindTextBlock property.
Operations
The sections below list the built-in methods and properties that you can use as operations for the AITextObject object.
Note: You can also view a list and descriptions of the AITextObject properties that you can retrieve using the GetObjectProperty and GetAllProperties methods. You can then use the properties to check the object's location or content.
Methods
 CaptureBitmap | Saves a screen capture of the object as a .png or .bmp image using the specified file name. Supported on UFT One versions 2021 R1 and later. |
| CheckExists | A checkpoint that checks whether the object currently exists in the set context. |
| Click | Clicks the text. |
| DoubleClick | Double-clicks the AI text object. Supported on UFT One versions 2021 R1 and later. |
| GetAllProperties | Retrieves all of the AITextObject's properties and their values from the application. Supported on UFT One versions 2023 and later. |
| GetObjectProperty | Retrieves the value of the specified object property from the application. Supported on UFT One versions 2023 and later. |
| GetText | Retrieves the object’s text. |
| GetValue | Retrieves the object’s value. |
| Highlight | Highlights the text in the application. |
| Hover | Holds the cursor over the text. |
| LongClick | Presses and holds the AI text object for a specified number of seconds. Supported on UFT One versions 2021 R1 and later. |
| MultiClick | Clicks the AI text object the specified number of times. Supported on UFT One versions 2021 R1 and later. |
| RightClick | Right-clicks the AI text object. Supported on UFT One versions 2021 R1 and later. |
| Type | Types the specified string in an input or edit box identified as text. |
| TypeSecure | Types the specified encoded string in an input or edit box identified as text. |
Properties
 Exist | Checks whether the object currently exists in the set context. |
CaptureBitmap Method
Supported on UFT One versions 2021 R1 and later.
Description
Saves a screen capture of the object as a .png or .bmp image using the specified file name.
Syntax
AIUtil.FindText(text, [locator], [locatorData]).CaptureBitmap FullFileName, [OverrideExisting]
Arguments
| Parameter | Description |
|---|---|
| FullFileName | Required. A String value. The path to the file to store the screen capture. The file extension indicates whether to save the capture as a .png or .bmp file. |
| OverrideExisting | Optional. A Boolean value. Indicates what to do if a file by the specified name already exists: True: Replace the existing file with the new capture. False (Default): The step fails if a file by the specified name already exists. |
Return Type
None
Examples
Capture an image of a holiday greeting'The following example uses the CaptureBitmap method to capture an image of the
' holiday greeting.
AIUtil.SetContext Browser("creationtime:=0")
AIUtil.FindText("Happy New Year").CaptureBitmap "c:\greeting.bmp"
CheckExists Method
Description
A checkpoint that checks whether the object currently exists in the set context.
Syntax
AIUtil.FindText(text, [locator], [locatorData]).CheckExists expected
Arguments
| Parameter | Description |
|---|---|
| expected | A Boolean value. Specifies whether this checkpoint expects the object to exist. Possible values: true. The checkpoint passes if the object is found within the set context before the timeout expires. false. The checkpoint passes if the object is not found by the time the timeout expires. |
Remarks
This method uses the timeout defined in the Object Synchronization Timeout option in the Run pane of the Test Settings dialog box.
UFT One directly performs this method without verifying object identification even if you enable it in Options > GUI Testing > AI or use the AIUtil.RunSettings.VerifyIdentification.Enable step.
Return Type
A Boolean value.
Returns TRUE if the checkpoint passes, otherwise FALSE.
A TRUE return value reports a Passed step to the run results; a FALSE return value reports a Failed step to the run results.
Example
Verify that a specific string is displayed in the application (VBScript)'The following example checks for the "New version available" text in the application AIUtil.SetContext Device("device") 'Set the context for AI AIUtil.FindText("New version available").CheckExists true
Click Method
Description
Clicks the AI text object.
Syntax
AIUtil.FindText(text, [locator], [locatorData]).Click [x], [y]
Arguments
| Parameter | Description |
|---|---|
| x |
Optional. An integer value. The x-coordinate of the click. Note that the specified coordinates are relative to the upper left corner of the object. The default value is the middle of the object (-9999). |
| y |
Optional. An integer value. The y-coordinate of the click. Note that the specified coordinates are relative to the upper left corner of the object. The default value is the middle of the object (-9999). |
Return Type
None
Example
Click a specific point in the specified text (VBScript)'The following example clicks on the user name and login texts on the screen AIUtil.SetContext Device("device") 'Set the context for AI AIUtil.FindText("User Name").Click AIUtil.FindText("LogIn").Click 10, 10 'Click the 10,10 point in the LogIn text
DoubleClick Method
Supported on UFT One versions 2021 R1 and later.
Description
Double-clicks the AI text object.
Syntax
AIUtil.FindText(text, [locator], [locatorData]).DoubleClick [x], [y]
Arguments
| Parameter | Description |
|---|---|
| x |
Optional. An integer value. The x-coordinate of the double-click. Note that the specified coordinates are relative to the upper left corner of the object. The default value is the middle of the object (-9999). |
| y |
Optional. An integer value. The y-coordinate of the double-click. Note that the specified coordinates are relative to the upper left corner of the object. The default value is the middle of the object (-9999). |
Return Type
None
IMPORTANT
The DoubleClick method is not supported on mobile applications.
Example
Double-click a specific point in the specified text (VBScript)'The following example double-clicks the 10,10 point in the "Open" text. AIUtil.SetContext Device("device") 'Set the context for AI AIUtil.FindText("Open").DoubleClick 10, 10
GetAllProperties Method
Supported on UFT One versions 2023 and later.
Description
Retrieves all of the AITextObject's properties and their values from the application.
Syntax
AIUtil.FindText(text, [locator], [locatorData]).GetAllProperties
Return Type
A Dictionary object
Example
Get all of a text object's properties 'The following example retrieves the properties of an AITextObject and prints them. AIUtil.SetContext Browser("creationtime:=0") 'Set the context for AI Set properties = AIUtil.FindText("Open").GetAllProperties For i = 0 To properties.count - 1 print properties.keys()(i) & ":" & properties.items()(i) Next 'Print just one of the retrieved properties. print "height:'" & properties("height") & "'"
GetObjectProperty Method
Supported on UFT One versions 2023 and later.
Description
Retrieves the value of the specified object property from the application.
Syntax
AIUtil.FindText(text, [locator], [locatorData]).GetObjectProperty (property)
Arguments
| Parameter | Description |
|---|---|
| property | Required. A String. The name of the property whose value to return. |
Return Type
A Variant.
Example
Get the height property of a text object'The following example retrieves the height property of an AITextObject and prints it. AIUtil.SetContext Browser("creationtime:=0") 'Set the context for AI print "height:'" & AIUtil.FindText("Open").GetObjectProperty ("height") & "'"
GetText Method
Description
Retrieves the object’s text.
Syntax
AIUtil.FindText(text, [locator], [locatorData]).GetText
Return Type
String
Example
Retrieve the text near the Total Price label (VBScript)'The following example prints the price displayed to the right of the Total Price label AIUtil.SetContext Device("device") 'Set the context for AI Set anchor = AIUtil.FindText("Total Price") price = AIUtil.FindText(micAnyText, micWithAnchorOnLeft, anchor).GetText MsgBox price
You can consolidate the last lines into one:
'The following example prints the price displayed to the right of the Total Price label AIUtil.SetContext Device("device") 'Set the context for AI MsgBox AIUtil.FindText(micAnyText, micWithAnchorOnLeft, AIUtil.FindText("Total Price")).GetText
GetValue Method
Description
Retrieves the object’s value.
Syntax
AIUtil.FindText(text, [locator], [locatorData]).GetValue
Return Type
String
Example
Get the value of a text block'The following example retrieves the value of a text block AIUtil.SetContext Browser("creationtime:=0") 'Set the context for AI Print AIUtil.FindTextBlock("TABLETS").GetValue
Highlight Method
Description
Highlights the text in the application.
Syntax
AIUtil.FindText(text, [locator], [locatorData]).Highlight
Return Type
None
Example
Highlight text (VBScript)'The following example draws a rectangle that flashes for a second around ' the identified text. AIUtil.SetContext Device("device") 'Set the context for AI AIUtil.FindText("User Name").Highlight
Hover Method
Description
Holds the cursor over the text.
Syntax
AIUtil.FindText(text, [locator], [locatorData]).Hover [duration]
Arguments
| Parameter | Description |
|---|---|
| duration |
Optional. An Integer value. The time period (in whole seconds) to hold the cursor over the object. Default: 2 seconds. |
Return Type
None
IMPORTANT
This method is supported only on Web applications running in a Web browser on a Desktop computer and not on mobile devices.
Before a Hover step, use the AIUtil.IsMobileContext to make sure the current AI context is a desktop web browser.
Designing your test this way makes it easier to use the same test for your web application on various platforms.
Example
Hover over a menu and select a displayed item (VBScript)'The following example checks that the browser is not on a ' mobile device before performing a Hover step. AIUtil.SetContext Browser("browser") 'Set the context for AI IsMobile = AIUtil.IsMobileContext If IsMobile = False Then AIUtil.FindText("Categories").Hover 'Hover over the menu AIUtil.FindText ("Clothing").Click 'Click a menu item EndIf
LongClick Method
Supported on UFT One versions 2021 R1 and later.
Description
Presses and holds the AI text object for a specified number of seconds.
Syntax
AIUtil.FindText(text, [locator], [locatorData]).LongClick [duration], [x], [y]
Arguments
| Parameter | Description |
|---|---|
| duration | Optional. A double floating value. The number of seconds to press the object. Default: 2 seconds |
| x |
Optional. An integer value. The x-coordinate of the long click. Note that the specified coordinates are relative to the upper left corner of the object. The default value is the middle of the object (-9999). |
| y |
Optional. An integer value. The y-coordinate of the long click. Note that the specified coordinates are relative to the upper left corner of the object. The default value is the middle of the object (-9999). |
Return Type
None
Example
Press and hold the 'menu' text (VBScript)'The following example long-clicks the 'menu' text for 1.5 seconds. AIUtil.SetContext Browser("MyBrowser") 'Set the context for AI AIUtil.FindText("menu").LongClick 1.5
MultiClick Method
Supported on UFT One versions 2021 R1 and later.
Description
Clicks the AI text object the specified number of times.
Syntax
AIUtil.FindText( text, [locator], [locatorData]).MultiClick [numberOfClicks ], [interval], [x], [y]
Arguments
| Parameter | Description |
|---|---|
| numberOfClicks | Required. An integer value. The number of times to click. |
| interval | Optional. A double floating value. The number of seconds between clicks. The default value is 0.5 seconds. |
| x |
Optional. An integer value. The x-coordinate of the clicks. Note that the specified coordinates are relative to the upper left corner of the object. The default value is the middle of the object (-9999). |
| y |
Optional. An integer value. The y-coordinate of the clicks. Note that the specified coordinates are relative to the upper left corner of the object. The default value is the middle of the object (-9999). |
Return Type
None
Example
Click a text string 3 times (VBScript)'The following example clicks the magic text 3 times, with half a second between each click AIUtil.SetContext Device("device") 'Set the context for AI AIUtil.FindText("magic").MultiClick 3
RightClick Method
Supported on UFT One versions 2021 R1 and later.
Description
Right-clicks the AI text object.
Syntax
AIUtil.FindText( text, [locator], [locatorData]).RightClick [x], [y]
Arguments
| Parameter | Description |
|---|---|
| x |
Optional. An integer value. The x-coordinate of the long click. Note that the specified coordinates are relative to the upper left corner of the object. The default value is the middle of the object (-9999). |
| y |
Optional. An integer value. The y-coordinate of the long click. Note that the specified coordinates are relative to the upper left corner of the object. The default value is the middle of the object (-9999). |
Return Type
None
IMPORTANT
The RightClick method is not supported on mobile applications.
Example
Right-click a text (VBScript)'The following example right-clicks the library text. AIUtil.SetContext Browser("MyBrowser") 'Set the context for AI AIUtil.FindText("library").RightClick
Type Method
Description
Types the specified string in an input or edit box identified as text.
Syntax
AIUtil.FindText(text, [locator], [locatorData]).Type [text]
Arguments
| Parameter | Description |
|---|---|
| text |
Required. A String value. The string to type. |
Return Type
None
Example
Type in an edit box (VBScript)'The following example types a user name in the edit box. AIUtil.SetContext Device("device") 'Set the context for AI AIUtil.FindText("USER NAME").Type "AIUser"
TypeSecure Method
Description
Types the specified encoded string in an input or edit box identified as text.
Syntax
AIUtil.FindText(text, [locator], [locatorData]).TypeSecure [text]
Arguments
| Parameter | Description |
|---|---|
| text |
Required. A String value. The encoded string to type. |
Return Type
None
IMPORTANT
To find the encoded value to use as the argument for the TypeSecure method, use the Password Encoder utility (Start > All Programs > Micro Focus > Password Encoder) or parameterize the argument and use the Data Table encryption option (right-click each unencrypted value in the password column and choose Data > Encrypt). For more information, see the UFT One Help Center.
Note: While the TypeSecure method enables you to hide passwords on the screen when running a test, it is not intended to be a secure way to protect password information.
Example
Type an encoded password in an edit box (VBScript)'The following example types an encoded password in the edit box. AIUtil.SetContext Device("device") 'Set the context for AI AIUtil.FindText("PASSWORD").TypeSecure "5cfe0d56013bbd8b5742b597cadc92352a6c"
Exist Property
Description
Checks whether the object currently exists in the set context.
Syntax
AIUtil.FindText(text, [locator], [locatorData]).Exist([TimeOut])
Arguments
| Parameter | Description |
|---|---|
| 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.
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. |
Remarks
The Exist property can only be used in statements that use its return value. For example, assignment, print, and if statements.
UFT One directly performs this method without verifying object identification even if you enable it in Options > GUI Testing > AI or use the AIUtil.RunSettings.VerifyIdentification.Enable step.
Return Type
A Boolean value
Example
Check whether a string exists in the application screen (VBScript)'The following example checks whether the "wrong password" 'string exists in the application screen. AIUtil.SetContext Device("device") 'Set the context for AI If AIUtil.FindText("wrong password").Exist Then MsgBox "login failed." End If
See also:
