Legacy | Select image

  • Command: image

  • Subcommand: select

  • Supported Platforms: Native (legacy), UFT (legacy), Selenium, Appium

    All commands must be executed using the same framework. Sharing the execution ID between different frameworks is not possible. This means that if you work with a Selenium/Appium driver, you need to call the commands using the Selenium/Appium driver (or, in the case of Reporting commands, through the Reporting SDK that works with the driver) and not as part of a UFT test or another framework.

  • Supported OS: Android, iOS

Description

Clicks on the image (needle) in the PNG file whose name is indicated by the content parameter. Store the image in the repository prior to running this command.

By default, the select image function searches for the text on the current screen. If there is a possibility that the selected text is not on the current screen, enable the Scroll and search parameter. When enabled, the default scroll direction is down. For iOS devices, the default scroll direction is right. To change the scroll direction to down, select body in the Search area parameter.

This command should be used in combination with Visual Relations.

For more information on how to use the Next parameter, see Create custom swipe gestures

Parameters

Name Value Default Description
deviceId*     The device for this command.
content*    

The image to search for.

The image can be taken from the device screen using the preview tool or selected from the media repository.

If selected from the repository the image must be a JPEG, PNG or BMP file.

context

all (all)

body (body)

lowerPanel ()

upperPanel ()

 

Defines the screen region where to look for the needle.

source

primary (Primary)

camera (Camera)

secondary ()

 

The source for retrieving the screen content.

Primary - Digital screen image

Camera - Analog screen image

timeout

 

0

The time, in seconds, to wait for the needle to appear.

For a dynamic screen, specify the expected waiting time for the needle to appear.

For example, the page loading time.

The timeout contains the system analysis time, for this reason it is recommended to specify at least 20 seconds.

The default, defined as 0, is a single attempt to find the needle.

screen.top

   

The top value of the screen area where to search for the needle.

Values can be in pixels or in percentage of screen width (0-100). For percentage, use the % sign. Example: 20%

Default is to search the entire screen.

It is recommended to use the percentage value as it does not rely on the screen resolution.

screen.height

   

The height value of the screen area where to search for the needle.

Values can be in pixels or in percentage of screen width (0-100). For percentage, use the % sign. Example: 20%

Default is to search the entire screen.

It is recommended to use the percentage value as it does not rely on the screen resolution.

screen.left

   

The left value of the screen area where to search for the needle.

Values can be in pixels or in percentage of screen width (0-100). For percentage, use the % sign. Example: 20%

Default is to search the entire screen.

It is recommended to use the percentage value as it does not rely on the screen resolution.

screen.width

   

The width value of the screen area where to search for the needle.

Values can be in pixels or in percentage of screen width (0-100). For percentage, use the % sign. Example: 20%

Default is to search the entire screen.

It is recommended to use the percentage value as it does not rely on the screen resolution.

image.top

   

The top value of the image area defining the needle.

Value is in pixels. Default is the entire image.

image.height

   

The height value of the image area defining the needle.

Value is in pixels. Default is the entire image.

image.left

   

The left value of the image area defining the needle.

Value is in pixels. Default is the entire image.

image.width

   

The width value of the image area defining the needle.

Value is in pixels. Default is the entire image.

threshold

   

The acceptable match level percentage, between 20 and 100.

Too low values can lead to a false positive result, while too high values can lead to a false negative result.

duration

 

0

The duration, in seconds, the found needle should remain on the haystack.

interval

  0

The minimum time interval, in seconds, for a single analysis.

If the analysis operation takes less than the interval, wait the remaining time before the next analysis operation.

backlight

   

The key sequence to perform the backlight operation.

Example - VOL_UP

For best practice, use a key that will not change the screen.

scrolling

noscroll (False)

scroll (True)

False

Scroll until the needle is found.

Scroll cannot be used together with a positive Timeout, because they dictate a different behavior when the needle is not found. When scrolling is enabled, the timeout must be zero.

maxscroll

 

5

The maximum number of scroll actions to perform before returning.

Finding the needle will stop the scrolling.

Effective values are in the range of 0-100.

next

SWIPE_UP (SWIPE_UP)

SWIPE_DOWN (SWIPE_DOWN)

SWIPE_RIGHT (SWIPE_RIGHT)

SWIPE_LEFT (SWIPE_LEFT)

UP (UP)

DOWN (DOWN)

RIGHT (RIGHT)

LEFT (LEFT)

 

The key sequence to perform the scroll operation.

For more information, see the Create Custom Swipe Gestures post.

shift

none (None)

above (Above)

below (Below)

left (Left)

right (Right)

leftmost (Leftmost)

rightmost (Rightmost)

 

The direction to move the touch location, relative to the center of the found needle.

To use, select the direction and the Position value distance.

By default the touch operation position is at the center of the matched needle.

For Leftmost and Rightmost, the value represents the distance from screen edge.

offset

   

The distance from the center of the found needle to the location of the touch operation. Used alongside the Touch position parameter.

Values can be in pixels or in percentage of screen width (0-100). For percentage, use the % sign. Example: 20%

operation

single (Single tap)

double (Double tap)

long (Long tap)

roll (Trackball roll)

none (No touch)

 

The touch operation to perform on the found label location.

repeat

 

1

The number of times to repeat the operation. Relevant for tap and double tap actions only.

match

identical (Same size)

similar (Any size)

bounded (Bounded size)

 

The needle comparison method.

Same Size - needle and haystack are from the same origin (device screen) and size, matching is faster and simpler

Any Size - needle and haystack are either not from the same origin (needle is from another device or other source) or not in the same size (different ratio or size), matching is slower and more complex. Selecting Any Size increases the analysis time. The timeout values should respectively be increased.

Bounded Size - same as Any Size with restrictions on possible needle sizes. This mode allows decrease the any size analysis time by using apriori knowledge on needle sizes or by decreasing the size of a haystack.

matchGeneric

   

A generic image compare parameter.

Use this to provide additional image compare specifications that are not exposed as function parameters.

Examples:

matchMethod=TM_SQDIFF_NORMED

matchMethod=TM_CCORR_NORMED

report

screenshot (Screenshot)

screenshot-on-error (Screenshot on error)

none (None)

Screenshot

The value to display in the report.

Screenshot - display screenshot

Screenshot on error - display screenshots only for actions in error

None - display nothing

It is recommended to reduce the resolution in very long scripts that result in large report files.

report.resolution

high (High)

medium (Medium)

low (Low)

High

The image resolution.

It is recommended to reduce the resolution in very long scripts that result in large report files.

grid

   

The column name to be used for grid view in the report.

Selecting this parameter creates the grid report.

relation.direction

left (Left)

right (Right)

above (Above)

below (Below)

left-above (Left-Above)

left-below (Left-Below)

right-above (Right-Above)

right-below (Right-Below)

inside (Inside)

 

The direction of the related region, stored in memory from the last found needle, in relation to the searched needle.

For more information see the Visual Relations series.

Left - The related region is to the left of the searched needle

Right - The related region is to the right of the searched needle

Above - The related region is above the searched needle

Below - The related region is below the searched needle

Left-Above - The related region is to the left and above the searched needle

Left-Below - The related region is to the left and below the searched needle

Right-Above - The related region is to the right and above the searched needle

Right-Below - The related region is to the right and below to the searched needle

Inside - The searched needle is inside the related region boundaries of the related region

relation.inline

horizontal (Horizontal)

vertical (Vertical)

 

The search area is in-line with the related region, stored in memory from the last found needle.

For more information, see the Visual Relations series.

Horizontal - The needle is within the height (top to button) boundaries of the related region

Vertical - The needle is within the width (left to right) boundaries of the related region

imageBounds.needleBound

   

The ratio in percentage by which the original needle width may vary. The ratio is defined as a (100 - specified percentage) / 100.

Needle sizes to be checked by the analysis will be limited to the range from original needle width multiplied by the ratio to the original needle width divided by the ratio.

To use this parameter, Match mode must be bounded size.

imageBounds.haystackArea

 

786432

The size of haystack to be used for the analysis.

The haystack image will be scaled before being analyzed so its area does not exceed the specified value.

Haystack images that do not exceed the value will stay unchanged.

To use this parameter, Match mode must be bounded size.

* Mandatory parameter

Request & Response

Copy

Request

https://mycloud.perfectomobile.com/services/executions/john@perfectomobile.com_controller_16-11-07_09_33_20_237?operation=command&securityToken=<your_token>&command=image&subcommand=select&param.deviceId=T062800NO1&param.content=PRIVATE:temp%20media\wifi-icon.png
Copy

JSON response

 {
  "reason": "Success",
  "timer.elapsed": "2060",
  "testGridReportUrl": "https://mycloud.reporting-stg.perfectomobile.com?externalId[0]=john@perfectomobile.com_controller_16-11-07_09_33_20_237",
  "screenAnalysis.analyzedRegion.height": "1280",
  "description": "Success",
  "timer.system": "2060",
  "completed": "true",
  "screenAnalysis.analyzedRegion.left": "0",
  "flowEndCode": "SUCCEEDED",
  "screenAnalysis.analyzedRegion.top": "0",
  "screenAnalysis.resultRegion.left": "26",
  "screenAnalysis.resultRegion.height": "64",
  "screenAnalysis.resultRegion.top": "297",
  "executionId": "john@perfectomobile.com_controller_16-11-07_09_33_20_237",
  "timer.ux": "0",
  "screenAnalysis.resultPoint.x": "55",
  "singleTestReportUrl": "https://mycloud.perfectomobile.com/nexperience/singletest/report/?reportRepositoryKey=PRIVATE:controller/161107/controller_16-11-07_09_33_20_237.xml&ownerId=john@perfectomobile.com&sharingCode=13248201-5736-4265-883e-4d24dd27a6c4",
  "screenAnalysis.resultPoint.y": "329",
  "screenAnalysis.analyzedRegion.width": "720",
  "screenAnalysis.resultRegion.width": "58",
  "reportKey": "PRIVATE:controller/161107/controller_16-11-07_09_33_20_237.xml",
  "screenAnalysis.grade": "100",
  "timer.device": "0"}