Automation Guide Action-based testing language Built-in actions User Interface actions Picture Handling

 click picture

click picture

Description

Check a bitmap area of the AUT’s current display for the presence of a given instance of a specified target image.If found, simulate a mouse click on the image.

Arguments

• picture

  Identifying name of a regular or shared picture check, a collection of one or more baseline images to be used for comparison with the AUT display.

• window

  (Optional) TA name of the window.

• control

  (Optional) TA name of the control.

• rect

  (Optional) Specifies the dimensions of a rectangular area which, in combination with the active UI element (as determined by the window and control arguments), defines the active area. Scanning for thebaseline image or object is then limited to this active area (see Notes below). Values specifying the location of the rect area are relative to the active UI element.

  The rect argument consists of four comma-separated values:

  • left: Specifies the left border of the rect area relative to the left edge of the active UI element (screen, window or control – see Notes below). (Units: pixels; default=0)
  • top: Specifies the top border of the rect area relative to the top edge of the active UI element. (Units: pixels; default=0)
  • width: Specifies the width of the rect area. (Units: pixels; the default is that value which causes the right border of the active area to coincide with the right edge of the active UI element.)
  • height: Specifies the height of the rect area. (Units: pixels; the default is that value which causes the lower border of the active area to coincide with the lower edge of the active UI element.)
    
    

  The above figure illustrates the active area that applies when both the window and control arguments have been specified (establishing a picture control as the active UI element), and the values for rect are such that it covers both a portion of the active UI element as well as an area outside of it. In such a case, the active area is the area of overlap between the UI element and the rect area. (See related note below.)

  Notes: 
  Any of the four sub-arguments of rect may be omitted, but all values must maintain their comma-delimited places to ensure correct assignment.(For example, setting rect to (, , 100, 50) specifies an active area of width=100, height=50, whose top-left corner coincides with that of the active UI element.)

• index

  (Optional) Specifies a particular instance of the target image in the active area, in case more than one match is expected.

  The index of a given matching image is determined by its position, relative to other matching images in the active area, in a left-to-right, top-to-bottom ordering, as in the manner of reading a book. (Indexing starts at 1; default = 1.)

• x

  (Optional) Horizontal position of effective click on the picture, specified as distance in pixels from left edge of the active area. (Defaults to horizontal center of area.)

• y

  (Optional) Vertical position of effective click on the picture, specified as distance in pixels from top edge of the active area. (Defaults to vertical center of area.)

• click type

  (Optional) Type of mouse click.

  Allowable values:

  • left

    (Default) Single left-click.

  • right

    Single right-click.

  • double

    Double left-click.

Valid contexts

This action may be used within the following project items: test modules and user-defined actions.

Notes

• Built-in UI actions applied to iOS devices specify screen coordinates in points rather than pixels. (For further details, refer to the built-in action get screen resolution.)

• As a convenience when editing, you may drag the appropriate picture check node from the Picture Checks folder (in the TestArchitect explorer tree) into this action’spicture argument.

• By default this built-in action applies a pixel-by-pixel image comparison technique. To switch to a keypoint detection image comparison, refer to picture algorithm and Key Points Modification tool for details.

• Note that if the referenced picture check holds multiple baseline images, each one is tested against the AUT bitmap until (and if) a match is found. Only a single “hit” is required for a match to be considered found.

• This action is applied to that part of the captured bitmap identified as the active area, with the remainder of the image ignored. The active area is determined by the combination of the window, control and rect arguments. To begin with, window and control determine the active UI element, which can be a control, window, or the full screen, as follows:

  window argument	control argument	active UI element is…
  omitted	omitted	entire screen (i.e., entire captured test image
  specified	omitted	entire application window
  specified	specified	specified control

  With the active UI element established, the rect argument then (optionally) specifies a rectangular active area relative to the active UI element. (If no rect argument is specified, the active UI element itself is the active area.)

• In most cases, the rect area, if specified, defines a sectional area whose borders reside within the active UI element, so that the rect area itself is the active area. But that is not necessarily the case. The following three images illustrate the general case for how the active area is determined when the rect area is specified.
  
  

  The general rule for determining the active area is as follows:

  rect area:	resulting active area:
  not specified	the active UI element
  overlaps the active UI element	the intersection space (Cases 1 & 2 above)
  no overlap with active UI element	the active UI element (Case 3 above)

• If the action fails to find the specified instance of the target image, an error is generated.

• Android: This built-in action, when applied to a connected Android device, requires that the TestArchitect Agent service be running. Note also that, if and when an Android device is restarted, TestArchitect Agent is then stopped. Should this be the case, it is essential that you reactivate the service by observing the following steps:

  1. Connect the Android device to the test controller through a USB cable (not Wi-Fi), if not already so connected.
  2. Open the Android Instrumentation Tool dialog box.
  3. Click the Refresh devices list button.

• This action supports the <ignore> modifier. If the string <ignore> is present as the value of any of the arguments, or any argument contains an expression that evaluates to <ignore>, the action is skipped during execution.

Applicable Built-In Settings

The following settings are applicable to this action: case sensitive, remove double quotes from cells, standard ASCII only, object wait, window wait, picture algorithm.

Example - Case 1: The window and control arguments are specified

Action Lines

Result

Effect

Example - Case 2: The rect argument is specified

Action Lines

Result

Effect

Related concepts

Image comparison techniques