AIUtil Object

UFT One AI-based testing support:

UFT One versionMobile appsDesktop web
15.0SupportedNot supported
15.0.1Supported Technical preview
15.0.2SupportedSupported

Description

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

IMPORTANT

  • AI objects are supported in UFT One only when:

    • The UFT One Web Add-in or Mobile Add-in are 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, this 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.

Property AIObjectCreates an AIObject for the specified control. The control can be specified by type, and for some control types, by the object text.
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.
Property IsMobileContext

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

Supported in UFT One versions 15.0.1 and later.

Method RegisterCustomClass

Registers a custom class described by an image file.

Supported in UFT One versions 15.0.2 and later.

Property RunSettings

Returns the AIRunSettings object to use for the current test.

Supported in UFT One versions 15.0.2 and later.

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

 

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. A String value.
The text to use to identify the control. 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.

Versions earlier than 15.0.2: Use micNoText instead of micAnyText.

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: micFromTopmicFromLeft, 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 an AI object (AITextObject Object or AIObject Object) that belongs 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.

UFT One 15.0: 

  • The locator and locatorData parameters are named Orientation and Occurrence, respectively.
  • AI objects can be located by their ordinal location only, not their proximity to other AI objects.

Example

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.

UFT One 15.0.2 or later: 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: micFromTopmicFromLeft, 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 an AI object (AITextObject Object or AIObject Object) that belongs 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.

IMPORTANT

UFT One 15.0: 

  • The locator and locatorData parameters are named Orientation and Occurrence, respectively.
  • AI objects can be located by their ordinal location only, not their proximity to other AI objects.

Example

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. A String value.
The text block to find.

UFT One 15.0.2 or later: 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: micFromTopmicFromLeft, 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 an AI object (AITextObject Object or AIObject Object) that belongs 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.

IMPORTANT

UFT One 15.0: 

  • The locator and locatorData parameters are named Orientation and Occurrence, respectively.
  • AI objects can be located by their ordinal location only, not their proximity to other AI objects.

Example

Back to top

IsMobileContext Property

Supported in UFT One versions 15.0.1 and later.

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

Back to top

 

RegisterCustomClass Method

Supported in UFT One versions 15.0.2 and later.

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 use RegisterCustomClass to override a class supported by AI, such as button, the specified image is used to identify that type of control instead of AI identification. For a list of supported classes, see the UFT One Help Center.

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

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

    Back to top

     

    RunSettings Property

    Supported in UFT One versions 15.0.2 and later.

    Description

    Returns the AIRunSettings object to use for the current test.

    Syntax

    AIUtil.RunSettings 

    Return Type

    An AIRunSettings Object.

    Example

    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

    UFT One 15.0: The AI context must be a mobile Device test object that exists in your object repository.

    UFT One 15.0.1 or later: 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.

    Example

    Back to top