AIUtil Object

Description

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

IMPORTANT

AI-based testing is supported on web and mobile applications.

  • 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, 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. 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.

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 (such as AITextObject Object, AIObject Object, or AICalendar 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.

Example

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: 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 (such as AITextObject Object, AIObject Object,AICalendar Object, or AITable 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 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

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

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: 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, AICalendar Object, or AITable 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.

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.

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 (such as AITextObject Object, AIObject Object, AICalendar Object, or AITable 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.

Example

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

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

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 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

     

    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.

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

    Example

    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

    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

    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: 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 (such as AITextObject Object, AIObject Object, AICalendar Object, or AITable 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 AITable Object.

    Back to top