AIUtil Object

Description

A utility object for Artificial-Intelligence-based (AI-based) testing.

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.

  • Use AIUtil to access all the AI functionalities.

    Always use the SetContext method to set the context for AI operations before using any AI steps.

  • The AIUtil object has a default property, AIObject, which returns an AIObject Object.

    You can therefore omit the word AIObject in the syntax using statements such as this one to access AIObject's methods and properties:

    'Click on the hamburger menu.
AIUtil("hamburger_menu").click

Operations

The sections below list the built-in methods and properties that you can use as operations for the AIUtil object.

Methods

Method RegisterCustomClass

Registers a custom class described by an image file.

Method SetContextSets the top-level test object in which to use AI.
Method ScrollPerforms a scroll operation at the current location.
Method ScrollOnObjectPerforms a scroll operation over the specified object.

Properties

Property AIObjectCreates an AIObject object for the specified control. The control can be specified by type, and for some control types, by the object text.

Property Calendar

(Tech preview) Creates an AICalendar object for the specified calendar control.

Property Context

Returns the ContextSettings object to use for the current test run.

Syntax

AIUtil.Context

Property FindTextCreates an AITextObject object for the specified text. This may be partial text within a larger block of text.
Property FindTextBlockCreates an AITextObject object for the specified text block.
PropertyIsMobileContext

Indicates whether the AIUtil context is currently on a mobile device.

PropertyRunSettings

Returns the AIRunSettings object to use for the current test.

Property Table

(Tech preview) Creates an AITable object for the specified table control.

 

AIObject Property

Description

Creates an AIObject Object for the specified control. The control can be specified by type, and for some control types, by the object text.

If there are multiple similar objects on one page in the application, use the object's relative location in the application to describe it uniquely.

Syntax

One of: 

AIUtil ControlType, [AIText], [locator], [locatorData]

AIUtil.AIObject ControlType, [AIText], [locator], [locatorData]

Arguments

ParameterDescription
ControlType Required. A String value.
The type of the control. For a list of supported control types, see the UFT One Help Center.
AIText

Optional. The text to use to identify the control.

UFT One version 2022 and earlier: A String value.

UFT One versions 2023 and later: A Variant value. You can provide a text string, or an AIRegex object, containing a regular expression that describes the pattern the text must match.

For a list of control types that support recognition by text, see the UFT One Help Center.
Enter the micAnyText constant if you want to ignore this parameter and provide values for locator and locatorData.

locator

Optional. A predefined constant or string value. Mandatory if you specify a value for the locatorData parameter.

Used to describe the unique location of an object that may appear multiple times in the application. The location can be ordinal, relative to similar objects in the application, or proximal, relative to a different AI object, considered an anchor.

  • For ordinal location, the locator represents the direction in which to count.

    Possible values: 
    Strings: "FromTop", "FromLeft", "FromRight", "FromBottom".
    Constant values: micFromTop, micFromLeft, micFromRight, micFromBottom.

  • For proximity to a different AI object, the locator represents the direction of the anchor object.
    Possible values 
    Strings: "WithAnchorOnLeft", "WithAnchorOnRight", "WithAnchorAbove", "WithAnchorBelow".
    Constant values: micWithAnchorOnLeft, micWithAnchorOnRight, micWithAnchorAbove ,micWithAnchorBelow.
locatorData

Optional. An Integer value or an AI object. Mandatory if you specify a value for the locator parameter.

  • For ordinal location, the locatorData provides the ordinal number of the object, starting with 1 for the first object.
    UFT One counts the objects that match the description, in the direction specified in the locator parameter.
  • For proximity to a different AI object, the locatorData specifies the AI object to use as an anchor.
    The anchor must be one of the AI object types, and must belong to the same context as the object you are describing.
    The anchor can also be described by its location.
    UFT One returns the AI object that matches the description and is closest and most aligned with the anchor, in the specified direction.

Return Type

An AIObject Object.

IMPORTANT

The AIObject property is the default property for the AIUtil object.

You can therefore omit the word AIObject in the syntax, and perform AIObject methods directly on the returned object within the same statement, as you can see in the example below.

Example

'The following example clicks a menu on a mobile device and then types a user name 
'in the appropriate field. Both controls are identified using AI.
' Next, the example clicks the second button from the left.
AIUtil.SetContext Device("device") 'Set the context for AI
AIUtil("hamburger_menu").click
AIUtil("input", "USER NAME").Type "admin"
AIUtil("button", micAnyText, "FromLeft", 2).click

Back to top

 

Calendar Property

Description

Creates an AICalendar Object for the specified control. If there are multiple similar objects on one page in the application, use the object's relative location in the application to describe it uniquely.

Syntax

One of: 

AIUtil.Calendar [locator], [locatorData]

Arguments

ParameterDescription
locator

Optional. A predefined constant or string value. Mandatory if you specify a value for the locatorData parameter.

Used to describe the unique location of an object that may appear multiple times in the application. The location can be ordinal, relative to similar objects in the application, or proximal, relative to a different AI object, considered an anchor.

  • For ordinal location, the locator represents the direction in which to count.

    Possible values 
    Strings: "FromTop", "FromLeft", "FromRight", "FromBottom".
    Constant values: micFromTop, micFromLeft, micFromRight, micFromBottom.

  • For proximity to a different AI object, the locator represents the direction of the anchor object.
    Possible values 
    Strings: "WithAnchorOnLeft", "WithAnchorOnRight", "WithAnchorAbove", "WithAnchorBelow".
    Constant values: micWithAnchorOnLeft, micWithAnchorOnRight, micWithAnchorAbove ,micWithAnchorBelow.
locatorData

Optional. An Integer value or an AI object. Mandatory if you specify a value for the locator parameter.

  • For ordinal location, the locatorData provides the ordinal number of the object, starting with 1 for the first object.
    UFT One counts the objects that match the description, in the direction specified in the locator parameter.
  • For proximity to a different AI object, the locatorData specifies the AI object to use as an anchor.
    The anchor must be one of the AI object types, and must belong to the same context as the object you are describing.
    The anchor can also be described by its location.
    UFT One returns the AI object that matches the description and is closest and most aligned with the anchor, in the specified direction.

Return Type

An AICalendar Object.

Back to top

ContextSettings Object

Description

This object controls settings that are related to the context of the current test run.

Important

To retrieve a ContextSettings object, use the AIUtil.Context property.

Methods

The following table lists the methods you can call to control the run time context settings:

Method Freeze

Freezes the current context. Subsequent steps use cached inspection data instead of reinspecting.

Important

Use this method to improve performance if the controls used in subsequent steps are not expected to change.

Use the Unfreeze method to instruct UFT One to reinspect the application before attempting to identify additional objects.

Syntax

AIUtil.Context.Freeze

MethodGetBrowserScope

Indicates whether the AI Context is the browser window or only the web page.

Syntax

AIUtil.Context.GetBrowserScope 

Important

This method is relevant only if you previously set the context to a Browser test object.

Possible values

  • WebPage

  • BrowserWindow

Method SetBrowserScope

Specifies whether the web AI Context is the browser window or only the web page.

Important

This method is relevant only if you previously set the context to a Browser test object.

Syntax

AIUtil.Context.SetBrowserScope browserScope

Arguments

browserScope. Required. A number.

Possible values:

  • 0 = WebPage. AI inspects only the web page for objects. (Default)

  • 1 = BrowserWindow. AI inspects the whole browser window for objects. Useful, for example, when you need to respond to a pop up dialog box that opens in the browser. Note that UFT One cannot identify any pop-up dialog boxes hidden behind the browser window.

Method Unfreeze

Unfreezes the context. Subsequent steps reinspect the application before attempting to identify objects.

Important

This method is relevant only if you froze the context in previous steps.

Syntax

AIUtil.Context.Unfreeze

Example

'The following example avoids unnecessarily re-inspecting the application between steps
AIUtil.Context.Freeze 
AIUtil("input", "Username").Type "appsadmin"
AIUtil("input", "Password").TypeSecure "611a16018c9b9e4b03ceeff7783455fdcd1d00496a8d8bca"
AIUtil("button", "Log In").Click
AIUtil.Context.Unfreeze 

'The following example clicks on the 'Open' text and the OK button that pops up.
AIUtil.SetContext Browser("MySite")  'Set the context for AI
AIUtil.FindText("Open").Click
'Set the browser scope so AI sees the pop up dialog box
AIUtil.Context.SetBrowserScope BrowserWindow 
AIUtil("button", "OK").Click
AIUtil.Context.SetBrowserScope WebPage

Back to top

FindText Property

Description

Creates an AITextObject Object for the specified text. This may be partial text within a larger block of text.

If there are multiple similar objects on one page in the application, use the object's relative location in the application to describe it uniquely.

Syntax

AIUtil.FindText AIText, [locator], [locatorData]

Arguments

ParameterDescription
AIText

Required. A String value.
The text to find.

Enter the micAnyText constant if you want to ignore this parameter and provide values for locator and locatorData. This is useful when you want to identify an object by its location and later retrieve the text from the object.

locator

Optional. A predefined constant or string value. Mandatory if you specify a value for the locatorData parameter.

Used to describe the unique location of an object that may appear multiple times in the application. The location can be ordinal, relative to similar objects in the application, or proximal, relative to a different AI object, considered an anchor.

  • For ordinal location, the locator represents the direction in which to count.

    Possible values 
    Strings: "FromTop", "FromLeft", "FromRight", "FromBottom".
    Constant values: micFromTop, micFromLeft, micFromRight, micFromBottom.

  • For proximity to a different AI object, the locator represents the direction of the anchor object.
    Possible values 
    Strings: "WithAnchorOnLeft", "WithAnchorOnRight", "WithAnchorAbove", "WithAnchorBelow".
    Constant values: micWithAnchorOnLeft, micWithAnchorOnRight, micWithAnchorAbove ,micWithAnchorBelow.
locatorData

Optional. An Integer value or an AI object. Mandatory if you specify a value for the locator parameter.

  • For ordinal location, the locatorData provides the ordinal number of the object, starting with 1 for the first object.
    UFT One counts the objects that match the AIText parameter, in the direction specified in the locator parameter.
  • For proximity to a different AI object, the locatorData specifies the AI object to use as an anchor.
    The anchor must be one of the AI object types, and must belong to the same context as the object you are describing.
    The anchor can also be described by its location.
    UFT One returns the AI object that matches the AIText parameter and is closest and most inline with the anchor, in the specified direction.

Return Type

An AITextObject Object.

Example

'The following example clicks on the user name and login texts.  
'Next, it clicks the third place from the top of the App that says 'ON'.
AIUtil.SetContext Device("device")  'Set the context for AI
AIUtil.FindText("User Name").Click
AIUtil.FindText("Log in").Click 10, 10 'Click the 10,10 point in the LogIn control
AIUtil.FindText("ON", "FromTop", 3).Click

Back to top

FindTextBlock Property

Description

Creates an AITextObject Object for the specified text block.

If there are multiple similar objects on one page in the application, use the object's relative location in the application to describe it uniquely.

Syntax

AIUtil.FindTextBlock AIText, [locator], [locatorData]

Arguments

ParameterDescription
AIText

Required. The text block to find.

UFT One version 2022 and earlier: A String value.

UFT One versions 2023 and later: A Variant value. You can provide a text string, or an AIRegex object, containing a regular expression that describes the pattern the text must match.

Enter the micAnyText constant if you want to ignore this parameter and provide values for locator and locatorData. This is useful when you want to identify an object by its location and later retrieve the text from the object.

locator

Optional. A predefined constant or string value. Mandatory if you specify a value for the locatorData parameter.

Used to describe the unique location of an object that may appear multiple times in the application. The location can be ordinal, relative to similar objects in the application, or proximal, relative to a different AI object, considered an anchor.

  • For ordinal location, the locator represents the direction in which to count.

    Possible values 
    Strings: "FromTop", "FromLeft", "FromRight", "FromBottom".
    Constant values: micFromTop, micFromLeft, micFromRight, micFromBottom.

  • For proximity to a different AI object, the locator represents the direction of the anchor object.
    Possible values 
    Strings: "WithAnchorOnLeft", "WithAnchorOnRight", "WithAnchorAbove", "WithAnchorBelow".
    Constant values: micWithAnchorOnLeft, micWithAnchorOnRight, micWithAnchorAbove ,micWithAnchorBelow.
locatorData

Optional. An Integer value or an AI object. Mandatory if you specify a value for the locator parameter.

  • For ordinal location, the locatorData provides the ordinal number of the object, starting with 1 for the first object.
    UFT One counts the objects that match the AIText parameter, in the direction specified in the locator parameter.
  • For proximity to a different AI object, the locatorData specifies the AI object to use as an anchor.
    The anchor must be one of the AI object types, and must belong to the same context as the object you are describing.
    The anchor can also be described by its location.
    UFT One returns the AI object that matches the AIText parameter and is closest and most inline with the anchor, in the specified direction.

Return Type

An AITextObject Object.

Example

'The following example clicks on the user name to the right of the 2nd "Profile"
' text from the top. Then it clicks on the login text.
AIUtil.SetContext Device("device")  'Set the context for AI
Set secondProfileFromTop = AIUtil.FindText("Profile", micFromTop, 2) 'Describe the anchor object
AIUtil.FindText("User Name",micWithAnchorOnLeft, secondProfileFromTop).Click
AIUtil.FindTextBlock("Log In With Your App").Click 10, 10 'Click the 10,10 point in the LogIn text

Back to top

IsMobileContext Property

Description

Indicates whether the AIUtil context is currently on a mobile device.

Syntax

AIUtil.IsMobileContext 

Return Type

Boolean

True. If the current AIUtil context is a Device object, or a Browser object on a mobile device.

False. If the current AIUtil context is a desktop web Browser.

IMPORTANT

If your AIUtil context is a top-level Browser object, it may be a desktop web browser or a mobile web browser.

Some methods, such as Hover, are supported only on desktop web browsers. Before performing such an operation, use 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

'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
Set IsMobile = AIUtil.IsMobileContext 
If IsMobile = False Then
    AIUtil("menu").Hover
    AIUtil.FindText ("Clothing").Click 'Click the menu item displayed when hovering
EndIf

Back to top

 

RunSettings Property

Description

Returns the AIRunSettings object to use for the current test.

Syntax

AIUtil.RunSettings 

Return Type

An AIRunSettings Object.

Example

'The following example scrolls down (based on the default settings) to highlight  
' the SEE OFFER button, and then scrolls back up to highlight the SPEAKERS text
AIUtil.SetContext Browser("creationtime:=0")
Browser("creationtime:=0").Navigate "https://www.advantageonlineshopping.com"
AIUtil("button", "SEE OFFER").highlight
AIUtil.RunSettings.AutoScroll.Enable "up", 2
AIUtil.FindTextBlock("SPEAKERS").highlight

Back to top

 

RegisterCustomClass Method

Description

Registers a custom class described by an image file.

Syntax

AIUtil.RegisterCustomClass className, imagePath

Arguments

ParameterDescription
className

Required. A String value.

The class name to register. Once registered, you can use this name as a control type in AI test steps. The AIObject identified by this class supports the same methods as any AIObject Object.

If you override an existing AI class, the image you provided is used to identify that class.

Note: 

  • The following names are reserved for internal UFT One use: text, text_block.

  • UFT One versions 2022 and later: className is case-insensitive. For example, registering a new class smile overrides a previously registered class Smile.

For a list of supported classes, see the UFT One Help Center.

imagePath

Required. A String value.

The path to an image file with an exact image of the control that you want to associate with the className class. (.jpg or .png image files work best).

The path can be a full path, or a path relative to the test folder.

Note: To capture an image of your control from a mobile application, do not take a screen capture of the remote access screen. Instead do one of the following: 

  • Capture the image directly on the device

  • In the remote access window, press Take Screenshot, then capture the image of the control from the screenshot.

Remarks

You cannot use a registered class as an anchor to identify another registered class by proximity.

Return Type

None.

Example

'The following example registers a "door" custom class and then clicks one door control, then 
'the second door from the top, and then highlight the profile control to the left of the door control 
AIUtil.SetContext Browser("creationtime:=0")
AIUtil.RegisterCustomClass "door", "door.PNG"
AIUtil("door").Click
AIUtil("door", micAnyText, micFromTop, 1).Click
AIUtil("profile", micAnyText, micWithAnchorOnRight, AIUtil("door")).Highlight

Back to top

 

SetContext Method

Description

Sets the top-level test object in which to use AI.

Always set the AI context before using any AI operations.

Syntax

AIUtil.SetContext AIContext

Arguments

ParameterDescription
AIContext Required. A top-level test object.
The top-level test object to use for the context.

Return Type

None.

IMPORTANT

  • The AI context can be one of the following: 

    • A mobile Device test object stored in your object repository.

    • A web Browser test object stored in your object repository or described using descriptive programming.

      The web Browser can run on a Desktop or Mobile device, and be opened manually or from the Record and Run settings.

    • UFT One 2022 and later: An SAPGUISession test object stored in your object repository or described using descriptive programming.

  • The SetContext method also clears any previously set context settings.

Example

'The following example clicks on the 'Open' text and the LogIn button.
AIUtil.SetContext Device("device")  'Set the context for AI
AIUtil.FindText("Open").Click
AIUtil("button", "LogIn").Click 10, 10 'Click the 10,10 point on the LogIn button

Back to top

 

Scroll Method

Description

Performs a scroll operation at the current location.

Syntax

AIUtil.Scroll direction, amountToScroll

Arguments

ParameterDescription
direction

Required. The direction in which to scroll.

Possible values:  up, down, left, right.

amountToScroll

Required. A number. The distance to scroll.

On non-mobile applications, the distance is measured in mouse wheel ticks.

On mobile applications, the distance is measured in short pan lengths, each unit approximately one tenth of the screen.

Return Type

None.

IMPORTANT

On non-mobile applications, this method performs a mouse-wheel scroll at the current mouse location.

On mobile applications, the method performs a pan operation from the middle of the current screen.

Example

'The following example clicks on a table cell and then performs a mouse-wheel scroll at that location.
AIUtil.SetContext Browser("Chrome")  'Set the context for AI
AIUtil.AITable.Cell(3,4).Click
AIUtil.Scroll "right", 3

Back to top

 

ScrollOnObject Method

Description

Performs a scroll operation over the specified object.

Syntax

AIUtil.ScrollOnObject object, direction, amountToScroll

Arguments

ParameterDescription
object

Required. An object identified using AI, such as an AIObject, an AITextObject, and AICalendar.

The object on which to perform the scroll operation.

direction

Required. The direction in which to scroll.

Possible values:  up, down, left, right.

amountToScroll

Required. A number. The distance to scroll.

On non-mobile applications, the distance is measured in mouse wheel ticks.

On mobile applications, the distance is measured in short pan lengths, each unit approximately one tenth of the screen.

Return Type

None.

IMPORTANT

On non-mobile applications, this method first moves the mouse to the specified object and then performs a mouse-wheel scroll.

On mobile applications, the method performs a pan operation starting from the object's location.

Example

'The following example scrolls the navigation pane using one of the objects in it.
AIUtil.SetContext Browser("Chrome")  'Set the context for AI
AIUtil.ScrollOnObject AIUtil.FindText("HTML Styles"), "down", 2

Back to top

 

Table Property

Description

Creates an AITable Object for the specified control.

If there are multiple similar objects on one page in the application, use the object's relative location in the application to describe it uniquely.

Syntax

One of: 

AIUtil.Table [locator], [locatorData]

Arguments

ParameterDescription
locator

Optional. A predefined constant or string value. Mandatory if you specify a value for the locatorData parameter.

Used to describe the unique location of an object that may appear multiple times in the application. The location can be ordinal, relative to similar objects in the application, or proximal, relative to a different AI object, considered an anchor.

  • For ordinal location, the locator represents the direction in which to count.

    Possible values 
    Strings: "FromTop", "FromLeft", "FromRight", "FromBottom".
    Constant values: micFromTop, micFromLeft, micFromRight, micFromBottom.

  • For proximity to a different AI object, the locator represents the direction of the anchor object.
    Possible values 
    Strings: "WithAnchorOnLeft", "WithAnchorOnRight", "WithAnchorAbove", "WithAnchorBelow".
    Constant values: micWithAnchorOnLeft, micWithAnchorOnRight, micWithAnchorAbove ,micWithAnchorBelow.
locatorData

Optional. An Integer value or an AI object. Mandatory if you specify a value for the locator parameter.

  • For ordinal location, the locatorData provides the ordinal number of the object, starting with 1 for the first object.
    UFT One counts the objects that match the description, in the direction specified in the locator parameter.
  • For proximity to a different AI object, the locatorData specifies the AI object to use as an anchor.
    The anchor must be one of the AI object types, and must belong to the same context as the object you are describing.
    The anchor can also be described by its location.
    UFT One returns the AI object that matches the description and is closest and most aligned with the anchor, in the specified direction.

Return Type

An AITable Object.

Back to top

See also: