iOS Convenience API
Note: The iOS Convenience API is only available for the Squish for iOS editions.
Note: The Squish documentation uses the term widget when referring to GUI objects. macOS developers may be more familiar with the term view for this concept.
Here are some quick links to the iOS Convenience API's functions:
This function clears the cache for hierarchical names for objects in a WebView. This can be useful in cases where a web application removes some elements of a web page after interacting with it and then the same hierarchical name used before should find a different object. Without clearing the cache in this situation the old object will be retrieved from the cache when searching for the hierarchical name after the website has changed its content. The cache however is necessary to keep lookup for hierarchical performant and scalable for deeper hierarchies.
clickObject(objectOrName, x, y)
doubleClick(objectOrName, x, y)
This function is identical to doubleTap(objectOrName). It is kept for compatibility with older scripts.
doubleTap(objectOrName, x, y)
This function performs a double tap on the specified
By default the
objectOrName widget is double-tapped in the middle, but this can be overridden by passing object-relative coordinates,
This function plays a gesture. The specified
objectOrName can refer to any object that is visible and serves for synchronization only.
This function hides the on-screen keyboard when it is showing.
This function installs a global event handler. The script function named in
handlerFunctionName (which must be passed as a string, not as a function reference, except for Python, which supports passing a function reference, too), will be called when an event of the
eventName type occurs.
eventName can be the name of any of the following event types:
- "Crash" – occurs if the AUT crashes
- "AlertOpened" – occurs when an alert is shown
AlertOpened event occurs, the function named in
handlerFunctionName is called. The function is passed one argument—the alert object that was opened (i.e. an object of type
Note: In Python scripts, you can specify the callback function to invoke by passing an actual function or a lambda function.
For examples see How to Use Event Handlers.
installEventHandler function will only work if it is called after the AUT has been started. For example, by using the ApplicationContext startApplication(autName) function.
This function opens a gesture file from a test suite directory and returns a GestureBuilder object. This can then be passed to gesture(objectOrName, touches). The specified
gesture-file refers to the filename.
selectPickerRowInComponent(objectOrName, row, componentIndex)
This function selects an item in the specified
UIPickerView object (a picker widget is a spinning-wheel control that allows users to choose things such as dates).
row is the 0-based index position of the row that should be selected. The
componentIndex is the 0-based index position of the component (or column) that contains the row.
tapObject(objectOrName, x, y)
This function performs a tap on the specified
By default the
objectOrName widget is clicked in the middle, but this can be overridden by passing object-relative coordinates,
touchAndDrag(objectOrName, x, y, dx, dy)
This function performs a dragging gesture (also known as a panning gesture). The gesture starts at position
y relative to the
objectOrName widget and continues for
dx pixels to the righ (left if the amount is negative), and
dy pixels down (up if the amount is negative).
touchAndHold(objectOrName, x, y, duration)
This function performs a touch and hold gesture on the specified
objectOrName widget. The touch lasts for
duration seconds (use floating point numbers if you want to specify fractions of a second).
By default the
objectOrName widget is touched in the middle, but this can be overridden by passing object-relative coordinates,
This function types the specified
text (as if the user had entered the text using the on-screen keyboard) into the
objectOrName editable widget. If the text is surrounded by angle brackets (<>), it is interpreted as a special key, e.g "<Return>". The input is case-sensitive, so
type(object, "R") is different from
Currently the following special keys are supported:
- "<Return>" – the return key on the on-screen keyboard (depending on the configuration, it is not necessarily labeled Return—it might be called Done or Search or something else depending on the
- "<Backspace>" – the backspace key; this is used to delete the character to left of the cursor
This function uninstalls an event handler that has been previously installed using installEventHandler(eventName, handlerFunctionName).
Objects of this type hold the touch strokes information needed to replay gesture(objectOrName, touches). An instance of this class is returned by readGesture(gesture-file). Strokes are defined by screen coordinates points, pressure and touch size.
For examples of how
GestureBuilder objects can be used to manipulate the gesture information, see How to Use the GestureBuilder class.
The width of the area in which this gesture is defined. This will be the device or emulator screen width.
The height of the area in which this gesture is defined. This will be the device or emulator screen height.
This section lists the methods for manually creating a GestureBuilder object.
GestureBuilder(width, height, unit)
Two constructor functions for creating a GestureBuilder object. The
height are the target screen size. The
unit can be either 1 or 2, meaning respectively in millimeters or logical points. The constants
GestureBuilder.LogicalPoint can be used as well.
The second constructor function constructs a GestureBuilder object by passing a string containing XML, which should be in the same format as the recorded gesture files.
Object GestureBuilder.addStroke(x, y)
Object GestureBuilder.addStroke(startTime, x, y)
Starts a new stroke. The whole movement of one finger or pen from touch down to releasing the screen is called a stroke. The touch down coordinate is (
y). For the non-first stroke, a time offset can be specified in milliseconds using the
startTime argument. Strokes cannot be disjointed in time, at least one finger or pen has to be down during the whole gesture. The maximum simultaneous touches is device dependent.
Object GestureBuilder.curveTo(duration, controlX, controlY, endX, endy)
Object GestureBuilder.curveTo(duration, control1X, control1Y, control2X, control2Y, endX, endy)
Adds a bézier curve movement to the latest added stroke in
duration milliseconds. The curve starts with the end coordinate of the last added movement or, if none added to the stroke, the stroke touch down coordinate. The end coordinate is specified with
endY. One or two so called control points can be used.
Object GestureBuilder.lineTo(duration, endX, endy)
Adds a line movement to the latest added stroke in
duration milliseconds. The line starts with the end coordinate of the last added movement or, if none added to the stroke, the stroke touch down coordinate. The end coordinate is specified with
Creates the gesture from the added strokes and movements. After calling this method, no strokes or movements can be added.
Changes stroke speed given a factor. A factor between 0.0 and 1.0 slows down the gesture, above 1.0 will speed it up.
Object GestureBuilder.rotate(degrees, originX, originY)
Rotates the strokes. The
degrees is the agle in degrees in a counter clockwise direction. The
originY define the origin of the rotate operation. If omitted, the area center is taken as origin.
Object GestureBuilder.scale(scaleX, scaleY)
Object GestureBuilder.scale(scaleX, scaleY, originX, originY)
Changes the size of the strokes. The
scaleX is the scale factor in the horizontal direction and
scaleY in the vertical direction. The
originY define the origin of the scale operation. If omitted, the area center is taken as origin. When also
scaleY is omitted, then the scaling is homogeneous in both directions.
Object GestureBuilder.translate(x, y)
Moves the strokes. The
y specifies the movement. A positive value for
x moves the strokes to the right and a positive value for
y moves the strokes downwards.