Device Object

Description

A mobile device.

Operations

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

Note: You can also view a list and descriptions of the Device description properties, for use in object repository descriptions, programmatic descriptions, checkpoint and output value steps, and as argument values for the GetTOProperty and GetROProperty methods.

Methods

Method BackPresses the device's Back button. (Android Only)
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 specified object property achieves the specified value within the specified timeout.
Common Method ChildObjectsReturns the collection of child objects contained within the object.
Method ClickOnTextClicks the specified location on the device, relative to the recognized text string.
Method CloseViewer

Closes the Digital Lab remote access window.

You can use this method together with the OpenViewer method to open and close the remote access window during a run session.

For example, if you run your tests silently (configured in Tools > Options > GUI Testing > Digital Lab), you can open the remote access window to do the following:

- Run steps on Insight objects

- Perform bitmap checkpoints

- Record and run analog steps via UFT One (not relevant for analog steps via the Digital Lab Options panel).

Then you can close the window after the steps run to continue running the test silently.

For more details, see the Digital Lab Help.

Common Method
EnterKeys

Uses the device’s keyboard to enter information.

Common Method GetAllROProperties

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

Common Method GetROPropertyReturns the current value of the specified 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 HighlightHighlights the object in the application.
Method GPSRelocateSimulates a change in the device's GPS location. (Android Only)
Method HomePresses the device's Home button.
Method IncomingCallSimulates an incoming call and optionally sends the app to the background for the specified number of seconds.
Method IncomingSMSSimulates an incoming SMS and optionally sends the app to the background for the specified number of seconds.
Method MenuPresses the device's Menu button. (Android Only)
MediaFileExistChecks if the file for sensor simulation exists on the Digital Lab server.
Method OpenViewer

Opens the Digital Lab remote access window. You can use this method together with the CloseViewer method to open and close the remote access window during a run session. For example, if you run your tests silently (configured in Tools > Options > GUI Testing > Digital Lab), you can open the remote access window to run steps on Insight objects, perform bitmap checkpoints, or record and run analog steps via UFT One (not relevant for analog steps via the Digital Lab Options panel). Then you can close the window after the steps run to continue running the test silently.

For more details, see the Digital Lab Help.

Common Method OutputRetrieves the current value of an item and stores it in a specified location.
Method Pan

Performs a Pan gesture on the object.

Method RecentAppsOpens the list of recent applications. (Android Only)
Common Method RefreshObjectInstructs UFT One to re-identify the object in the application the next time a step refers to this object.
Method SetOrientationSets the device orientation.
Common Method SetTOPropertySets the value of the specified description property in the test object description.
Method StartNVStarts the Network Virtualization service using the specified network profile.
Method StopNVStops the Network Virtualization service.
Method SwipeSwipes the device in the specified direction.
Common Method ToStringReturns a string that represents the current test object.
Method TouchTouches the device at the specified coordinates. (Android Only)
Method UnlockUnlocks the device.
UploadMediaUploads a file for sensor simulation to the Digital Lab server.
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 device currently exists in the Mobile server.

Back to top

 

Back Method

Description

Presses the device's Back button. (Android Only)

Syntax

object.Back

Return Type

None

Back to top

 

ClickOnText Method

Description

Clicks the specified location on the device, relative to the recognized text string.

Syntax

object.ClickOnText Text, [index], [offsetX], [offsetY]

Arguments

ParameterDescription
Text Required. A String value.
The text string recognized by the OCR mechanism.
index Optional. An integer value.

The instance number of the recognized text string. The default value is the first instance of the string.


Default value = 0
offsetX Optional. A Single Value.

The offset on the x-axis from the recognized text string, in bitmap percentage values.

This percentage is used to determine the x-coordinate of the clickpoint.

The default value is at the center of the recognized string.


Default value = 0
offsetY Optional. A Single Value.

The offset on the y-axis from the recognized text string, in bitmap percentage values.

This percentage is used to determine the y-coordinate of the clickpoint.

The default value is at the center of the recognized string.


Default value = 0

Return Type

None

IMPORTANT

This method depends on UFT One's OCR mechanism. For details, see the section on Guidelines for Text Recognition in the UFT One Help Center.

Example

                    'The following examples clicks to the right of the second instance of the recognized "Switch" string.
'In this example, the click point is determined by placing the "Switch" text string in the center of the bitmap.

Device("Device").ClickOnText "Switch",1,50,1

Back to top

 

CloseViewer Method

Description

Closes the Digital Lab remote access window.

You can use this method together with the OpenViewer method to open and close the remote access window during a run session.

For example, if you run your tests silently (configured in Tools > Options > GUI Testing > Mobile / Digital Lab), you can open the remote access window to do the following:

- Run steps on Insight objects

- Perform bitmap checkpoints

- Record and run analog steps via UFT One (not relevant for analog steps via the Digital Lab Options panel).

Then you can close the window after the steps run to continue running the test silently.

For more details, see the Digital Lab Help.

Syntax

object.CloseViewer

Return Type

None

Back to top

EnterKeys Method

Description

Uses the device’s keyboard to enter information.

Syntax

object.EnterKeys InputKeyType, value

Arguments

ParameterDescription
InputKeyType

Required. An enumeration.
The type of value sent to Digital Lab for the device input.

Possible values:

  • typeValue (0)
  • typeKey (1)
value

Required. A string.
The string to enter in the device.

Possible key values for iOS:

  • Enter.
  • Return. Functions as the Enter key does. Recording not supported.
  • Backspace.
  • Delete.

Possible key values for Android:

  • Enter.
  • Backspace.
  • Delete.
  • Tab.
  • Escape.
  • PageUp.
  • PageDown.
  • End.
  • Home. Used to scroll or move the cursor to the start of a line or the top of a list, and not the same as the Device.Home method.
  • Left.
  • Right.
  • Up.
  • Down.

Back to top

 

GPSRelocate Method

Description

Simulates a change in the device's GPS location. (Android Only)

Syntax

object.GPSRelocate Latitude, Longitude

Arguments

ParameterDescription
Latitude Required. A double floating value.
The latitude coordinate of the new location.
Longitude Required. A double floating value.
The longitude coordinate of the new location.

Return Type

None

Example

'The following example simulates setting the GPS coordinates of a Device.

Device("Device").GPSRelocate 37.500000,-120.300000

Back to top

 

Home Method

Description

Presses the device's Home button.

Syntax

object.Home

Return Type

None

Back to top

 

IncomingCall Method

Description

Simulates an incoming call and optionally sends the app to the background for the specified number of seconds.

Syntax

object.IncomingCall From, [TimeInBackground], [RespondToEvent]

Arguments

ParameterDescription
From Required. A String value.
The caller ID of the incoming call.
TimeInBackground Optional. An integer value.

The amount of time (in seconds) that the application remains in the background when an incoming call step is run.

Relevant only if the RespondToEvent argument is set to True.


Default value = 10
RespondToEvent Optional. A Boolean value.
Indicates whether the application should be sent to the background for the number of seconds specified in the TimeInBackground argument.
Default value = False

Return Type

None

IMPORTANT

This method is supported only on packaged apps.

Example

'The following example simulates receiving a phone call on a Mobile device.

Device("Device").App("UICatalog").MobileList("list").Select 10
Device("Device").IncomingCall "180080808080",5,False

Back to top

 

IncomingSMS Method

Description

Simulates an incoming SMS and optionally sends the app to the background for the specified number of seconds.

Syntax

object.IncomingSMS From, Text, [TimeInBackground], [RespondToEvent]

Arguments

ParameterDescription
From Required. A String value.
The caller ID of the incoming SMS message.
Text Required. A String value.
The text of the incoming SMS message.
TimeInBackground Optional. An integer value.

The amount of time (in seconds) that the application remains in the background when an incoming SMS step is run.

Relevant only if the RespondToEvent argument is set to True.


Default value = 10
RespondToEvent Optional. A Boolean value.
Indicates whether the application should be sent to the background for the number of seconds specified in the TimeInBackground argument.
Default value = False

Return Type

None

IMPORTANT

This method is supported only on packaged apps.

Example

'The following example simulates receiving an SMS on a Mobile device.

Device("Device").App("UICatalog").MobileList("list").Select 10
Device("Device").IncomingSMS "1800859645","Hello There",5,False

Back to top

 

Menu Method

Description

Presses the device's Menu button. (Android Only)

Syntax

object.Menu

Return Type

None

Back to top

MediaFileExist Method

Description

Checks if the file for sensor simulation exists on the Digital Lab server.

Syntax

object.MediaFileExist ReferenceName, [FilePath]

Arguments

ReferenceName

Required. A string value.

The reference name of the uploaded file returned when running a UploadMedia step.

FilePath

Optional. A string value.

The path to one image or video file. This value can be a URL or the file system path of the file.

Return Type

None

Back to top

 

OpenViewer Method

Description

Opens the Digital Lab remote access window. You can use this method together with the CloseViewer method to open and close the remote access window during a run session. For example, if you run your tests silently (configured in Tools > Options > GUI Testing > Digital Lab), you can open the remote access window to run steps on Insight objects, perform bitmap checkpoints, or record and run analog steps via UFT One (not relevant for analog steps via the Digital Lab Options panel). Then you can close the window after the steps run to continue running the test silently.

For more details, see the Digital Lab Help.

Syntax

object.OpenViewer

Return Type

None

IMPORTANT

An app must be open on the device before running an OpenViewer step. You can do this by specifying the app in the Record and Run Settings or by adding a Device.App.Launch step prior to the Device.OpenViewer step.

Back to top

 

Pan Method

Description

Performs a Pan gesture on the device.

Syntax

object.Pan StartX, StartY, EndX, EndY, [XVelocity], [YVelocity], [Gesture]

Arguments

ParameterDescription
StartX

Required. An integer value.

The x-coordinate at which to start the pan gesture. Note that the specified coordinates are relative to the upper left corner of the device.

StartY

Required. An integer value.

The y-coordinate at which to start the pan gesture. Note that the specified coordinates are relative to the upper left corner of the device.

EndX

Required. An integer value.

The x-coordinate at which to end the pan gesture. Note that the specified coordinates are relative to the upper left corner of the device.

EndY

Required. An integer value.

The y-coordinate at which to end the pan gesture. Note that the specified coordinates are relative to the upper left corner of the device.

XVelocity

Optional. A double floating value.

The horizontal velocity of the pan gesture.

Default value = -9999

YVelocity

Optional. A double floating value.

The vertical velocity of the pan gesture.

Default value = -9999

Gesture

Optional. A String value.

The gesture class designed by the mobile application developer to handle this gesture on this device. (relevant for iOS only)

Default value = ""

Note:

This argument is necessary only if the application developer overrode the default iOS gesture class.

Return Type

None

IMPORTANT

  • Use this method when the MobileObject.Pan method cannot perform the pan gesture interaction you want.

  • This method is not recorded in a recording session. You can manually add it to the test.

Example

Copy code
'The following performs a pan gesture on the device.
Device("Device").Pan 108,863,193,865

 

RecentApps Method

Description

Opens the list of recent applications. (Android Only)

Syntax

object.RecentApps

Return Type

None

Back to top

 

Unlock Method

Description

Unlocks and releases the device, such as after completing the relevant test steps for that device, in a script that tests multiple devices.

Syntax

object.Unlock

Return Type

None

IMPORTANT

This method is not supported as the first step in your script.

Example

Device("device1").App("Company").MobileButton("xxxx1").pinch

Device("device1").App("Company").MobileButton("xxxx2").pinch

Device("device1").App("Company").MobileButton("xxxx3").pinch

Device("device1").Unlock

Device("device2").App("Company").MobileButton("xxxx1").pinch

Device("device2").App("Company").MobileButton("xxxx2").pinch

Device("device2").App("Company").MobileButton("xxxx3").pinch

Device("device2").Unlock

Back to top

 

SetOrientation Method

Description

Sets the device orientation.

Syntax

object.SetOrientation Orientation

Arguments

ParameterDescription
Orientation Required. A String value.

The orientation to set on the device.

Possible values:

  • LandscapeRight
  • Portrait

Return Type

None

Example

                    'The following example sets the correct orientation for a Device object.

Device("Device").SetOrientation "LandscapeLeft"

Back to top

 

StartNV Method

Description

Starts the Network Virtualization service using the specified network profile.

Syntax

object.StartNV Profile

Arguments

ParameterDescription
Profile Required. A String value.
The name of the profile containing the conditions that you want to apply to the virtualized network. The profile must be set up on the Network Virtualization product.

Return Type

None

Back to top

 

StopNV Method

Description

Stops the Network Virtualization service.

Syntax

object.StopNV

Return Type

None

IMPORTANT

This method also adds a line to the run results, indicating where the network virtualization results file is located on the Network Virtualization server. This file contains traffic and performance information and analysis.

Back to top

 

Swipe Method

Description

Swipes the device in the specified direction.

Syntax

object.Swipe Direction, [x], [y]

Arguments

ParameterDescription
Direction Required. A String value.

The direction in which to swipe the device.

Possible values:
- up
- down
- left
- right

x Optional. An integer value.

The x-coordinate at which to start the swipe. Note that the specified coordinates are relative to the upper left corner of the device. The default value is the center of the device.


Default value = -9999
y Optional. An integer value.

The y-coordinate at which to start the swipe. Note that the specified coordinates are relative to the upper left corner of the device.

The default value is the leading edge of the element / device.


Default value = -9999

Return Type

None

IMPORTANT

During recording sessions on Android devices, this method is not recorded. You can add it to the test manually.

Back to top

 

Touch Method

Description

Touches the device at the specified coordinates. (Android Only)

Syntax

object.Touch x, y

Arguments

ParameterDescription
x Required. An integer value.

The x-coordinate of the touch. Note that the specified coordinates are relative to the upper left corner of the device.

y Required. An integer value.

The y-coordinate of the touch. Note that the specified coordinates are relative to the upper left corner of the device.

Return Type

None

IMPORTANT

To record Touch steps on a device, switch the Digital Lab to Analog recording mode. This is supported for Android devices only. To switch the recording mode, use the control on the left side of the remote access window displaying the device's interface.

Example

                    'The following example performs a Touch on a Device object.

Device("Device").Touch 111.849998,995.410034

Back to top

UploadMedia Method

Description

Uploads a file for sensor simulation to the Digital Lab server.

Syntax

object.UploadMedia ReferenceName, FilePath, [SaveToPic, Overwrite]

Arguments

ParameterDescription
ReferenceName

Required. A string.

The identical name of the file.

When recording this method, the parameter is automatically generated by Digital Lab.

FilePath

Required. A string value.

The path to one image or video file. This value can be a URL or the file system path of the file.

SaveToPic

Optional. A boolean value.

Instructs Digital Lab to save the image to the device's default picture folder.

Overwrite

Optional. A boolean value.

Instructs UFT One to send the file to Digital Lab.

Return Type

None

Back to top

See also: