Gestures & keys

Taps, swipes, drags and pinches, plus hardware buttons and the keyboard. Coordinates can be points or 0–1 screen ratios; directional swipes re-randomise the start point, distance, angle and duration every time and follow a hand-like path.

At a glance

·The swipe family uses the W3C channel with human-like paths; the drag family uses WDA's native channel for better compatibility
·Directional swipes avoid the screen edges by default; pass 'edge' when you want a system edge gesture such as swipe-back
·Every duration is in seconds

client.click#

Tap at a coordinate; with a duration it holds for that many seconds before releasing (a long press).

typescript

client.click(x: number, y: number, duration?: number): object;

Parameters

Name	Type	Required	Default	Description
`x`	`number`	Yes	—	Horizontal position: a 0–1 screen ratio, or points.
`y`	`number`	Yes	—	Vertical position: a 0–1 screen ratio, or points.
`duration`	`number`	No	—	Seconds to hold. Omit for a plain tap.

Returns

Type	Description
`object`	The raw WDA response; rarely needed.

Throws

Error	Raised when
`WDAError`	Ratio coordinates were given but the screen size could not be read (the WDA session is unhealthy).

Notes

When x and y both fall between 0 and 1 they are screen ratios (0.5, 0.5 is the centre); otherwise they are points. The conversion needs the screen size and throws if it cannot be read.

Example

javascript

client.click(0.5, 0.5);        // 屏幕正中 / screen centre
client.click(200, 640);        // point
client.click(0.5, 0.9, 1.2);   // 长按 1.2 秒 / long press

client.swipe#

Swipe from (x1, y1) to (x2, y2). The end points are exact; the path between them is hand-like — a slight random curve, slow then fast, with small jitter.

typescript

client.swipe(x1: number, y1: number, x2: number, y2: number, durationSec?: number): object;

Parameters

Name	Type	Required	Default	Description
`x1`	`number`	Yes	—	Start x.
`y1`	`number`	Yes	—	Start y.
`x2`	`number`	Yes	—	End x.
`y2`	`number`	Yes	—	End y.
`durationSec`	`number`	No	`0`	Seconds from the start of the movement to lift-off. 0 picks a random duration based on the distance.

Returns

Type	Description
`object`	The raw WDA response; rarely needed.

Throws

Error	Raised when
`WDAError`	Ratio coordinates were given but the screen size could not be read (the WDA session is unhealthy).

Notes

When x and y both fall between 0 and 1 they are screen ratios (0.5, 0.5 is the centre); otherwise they are points. The conversion needs the screen size and throws if it cannot be read.

Example

javascript

client.swipe(0.5, 0.8, 0.5, 0.2);        // 往上滑 / swipe up
client.swipe(0.5, 0.8, 0.5, 0.2, 0.6);   // 指定 0.6 秒 / take 0.6 seconds

client.drag#

A native WDA drag from (x1, y1) to (x2, y2). The system generates the path and speed; in some apps (custom-drawn views, older iOS) it is more reliable than swipe.

typescript

client.drag(x1: number, y1: number, x2: number, y2: number, durationSec?: number): object;

Parameters

Name	Type	Required	Default	Description
`x1`	`number`	Yes	—	Start x.
`y1`	`number`	Yes	—	Start y.
`x2`	`number`	Yes	—	End x.
`y2`	`number`	Yes	—	End y.
`durationSec`	`number`	No	`0`	Seconds to hold the start point before dragging — not the duration of the drag itself. 0 drags immediately.

Returns

Type	Description
`object`	The raw WDA response; rarely needed.

Throws

Error	Raised when
`WDAError`	Ratio coordinates were given but the screen size could not be read (the WDA session is unhealthy).

Notes

When x and y both fall between 0 and 1 they are screen ratios (0.5, 0.5 is the centre); otherwise they are points. The conversion needs the screen size and throws if it cannot be read.

Example

javascript

client.drag(0.2, 0.5, 0.8, 0.5, 0.3);

client.swipeUp#

Move the finger up (content moves up, revealing what is below). The start point, distance (35–55% of the screen), angle (±5°) and duration are randomised every time, and by default the gesture stays at least 8% away from the screen edges so it never triggers a system edge gesture. Uses the W3C gesture channel with a hand-like path: a slight random curve, slow then fast, with small jitter.

typescript

client.swipeUp(from?: "edge"): object;

Parameters

Name	Type	Required	Default	Description
`from`	`"edge"`	No	—	Omit it for a normal swipe; pass 'edge' to start at the screen edge: starts at the bottom edge, which is the system's go-home gesture — rarely what you want.

Returns

Type	Description
`object`	The raw WDA response; rarely needed.

Throws

Error	Raised when
`WDAError`INVALID_ARGUMENT	The argument is neither omitted nor 'edge' (for example an old-style { fromEdge: true }).

Notes

For the short, quick swipe from the lower screen used to scroll a feed, call client.swipeUpFromBottom(); swipeDownFromBottom, dragUpFromBottom and dragDownFromBottom are also available.

Example

javascript

client.swipeUp();

See also client.swipe

client.swipeDown#

Move the finger down (content moves down, revealing what is above). The start point, distance (35–55% of the screen), angle (±5°) and duration are randomised every time, and by default the gesture stays at least 8% away from the screen edges so it never triggers a system edge gesture. Uses the W3C gesture channel with a hand-like path: a slight random curve, slow then fast, with small jitter.

typescript

client.swipeDown(from?: "edge"): object;

Parameters

Name	Type	Required	Default	Description
`from`	`"edge"`	No	—	Omit it for a normal swipe; pass 'edge' to start at the screen edge: starts at the top edge, which pulls down Notification Centre.

Returns

Type	Description
`object`	The raw WDA response; rarely needed.

Throws

Error	Raised when
`WDAError`INVALID_ARGUMENT	The argument is neither omitted nor 'edge' (for example an old-style { fromEdge: true }).

Example

javascript

client.swipeDown();

See also client.swipe

client.swipeLeft#

Move the finger from right to left. The start point, distance (35–55% of the screen), angle (±5°) and duration are randomised every time, and by default the gesture stays at least 8% away from the screen edges so it never triggers a system edge gesture. Uses the W3C gesture channel with a hand-like path: a slight random curve, slow then fast, with small jitter.

typescript

client.swipeLeft(from?: "edge"): object;

Parameters

Name	Type	Required	Default	Description
`from`	`"edge"`	No	—	Omit it for a normal swipe; pass 'edge' to start at the screen edge: starts at the right edge.

Returns

Type	Description
`object`	The raw WDA response; rarely needed.

Throws

Error	Raised when
`WDAError`INVALID_ARGUMENT	The argument is neither omitted nor 'edge' (for example an old-style { fromEdge: true }).

Example

javascript

client.swipeLeft();

See also client.swipe

client.swipeRight#

Move the finger from left to right. The start point, distance (35–55% of the screen), angle (±5°) and duration are randomised every time, and by default the gesture stays at least 8% away from the screen edges so it never triggers a system edge gesture. Uses the W3C gesture channel with a hand-like path: a slight random curve, slow then fast, with small jitter.

typescript

client.swipeRight(from?: "edge"): object;

Parameters

Name	Type	Required	Default	Description
`from`	`"edge"`	No	—	Omit it for a normal swipe; pass 'edge' to start at the screen edge: starts at the left edge, which is the system's swipe-back gesture.

Returns

Type	Description
`object`	The raw WDA response; rarely needed.

Throws

Error	Raised when
`WDAError`INVALID_ARGUMENT	The argument is neither omitted nor 'edge' (for example an old-style { fromEdge: true }).

Example

javascript

client.swipeRight();          // 普通右滑 / a normal swipe
client.swipeRight('edge');    // 返回上一页 / go back

See also client.swipe

client.dragUp#

Move the finger up (content moves up). The start point, distance (35–55% of the screen), angle (±5°) and duration are randomised every time, and by default the gesture stays at least 8% away from the screen edges so it never triggers a system edge gesture. Uses WDA's native drag channel and holds the start point for a random 0.05–0.2 seconds before moving. Switch to this family when swipe has no effect in an app.

typescript

client.dragUp(from?: "edge"): object;

Parameters

Name	Type	Required	Default	Description
`from`	`"edge"`	No	—	Omit it for a normal swipe; pass 'edge' to start at the screen edge: starts at the bottom edge.

Returns

Type	Description
`object`	The raw WDA response; rarely needed.

Throws

Error	Raised when
`WDAError`INVALID_ARGUMENT	The argument is neither omitted nor 'edge' (for example an old-style { fromEdge: true }).

Example

javascript

client.dragUp();

See also client.drag

client.dragDown#

Move the finger down (content moves down). The start point, distance (35–55% of the screen), angle (±5°) and duration are randomised every time, and by default the gesture stays at least 8% away from the screen edges so it never triggers a system edge gesture. Uses WDA's native drag channel and holds the start point for a random 0.05–0.2 seconds before moving. Switch to this family when swipe has no effect in an app.

typescript

client.dragDown(from?: "edge"): object;

Parameters

Name	Type	Required	Default	Description
`from`	`"edge"`	No	—	Omit it for a normal swipe; pass 'edge' to start at the screen edge: starts at the top edge.

Returns

Type	Description
`object`	The raw WDA response; rarely needed.

Throws

Error	Raised when
`WDAError`INVALID_ARGUMENT	The argument is neither omitted nor 'edge' (for example an old-style { fromEdge: true }).

Example

javascript

client.dragDown();

See also client.drag

client.dragLeft#

Move the finger from right to left. The start point, distance (35–55% of the screen), angle (±5°) and duration are randomised every time, and by default the gesture stays at least 8% away from the screen edges so it never triggers a system edge gesture. Uses WDA's native drag channel and holds the start point for a random 0.05–0.2 seconds before moving. Switch to this family when swipe has no effect in an app.

typescript

client.dragLeft(from?: "edge"): object;

Parameters

Name	Type	Required	Default	Description
`from`	`"edge"`	No	—	Omit it for a normal swipe; pass 'edge' to start at the screen edge: starts at the right edge.

Returns

Type	Description
`object`	The raw WDA response; rarely needed.

Throws

Error	Raised when
`WDAError`INVALID_ARGUMENT	The argument is neither omitted nor 'edge' (for example an old-style { fromEdge: true }).

Example

javascript

client.dragLeft();

See also client.drag

client.dragRight#

Move the finger from left to right. The start point, distance (35–55% of the screen), angle (±5°) and duration are randomised every time, and by default the gesture stays at least 8% away from the screen edges so it never triggers a system edge gesture. Uses WDA's native drag channel and holds the start point for a random 0.05–0.2 seconds before moving. Switch to this family when swipe has no effect in an app.

typescript

client.dragRight(from?: "edge"): object;

Parameters

Name	Type	Required	Default	Description
`from`	`"edge"`	No	—	Omit it for a normal swipe; pass 'edge' to start at the screen edge: starts at the left edge.

Returns

Type	Description
`object`	The raw WDA response; rarely needed.

Throws

Error	Raised when
`WDAError`INVALID_ARGUMENT	The argument is neither omitted nor 'edge' (for example an old-style { fromEdge: true }).

Example

javascript

client.dragRight();

See also client.drag

client.scroll#

Let WDA scroll the current screen in a direction. XCUITest computes the amount, which makes it more reliable than a swipe for lists and other scroll views.

typescript

client.scroll(direction: "up" | "down" | "left" | "right", distance?: number): object;

Parameters

Name	Type	Required	Default	Description
`direction`	`"up" \| "down" \| "left" \| "right"`	Yes	—	The direction to scroll.
`distance`	`number`	No	`1.0`	How far to scroll; 1.0 is roughly one screen.

Returns

Type	Description
`object`	The raw WDA response; rarely needed.

Example

javascript

client.scroll('down', 1.0);

client.pinch#

A two-finger pinch: a scale above 1 spreads the fingers (zoom in), below 1 pinches them together (zoom out).

typescript

client.pinch(scale: number, velocity?: number): object;

Parameters

Name	Type	Required	Default	Description
`scale`	`number`	Yes	—	The scale factor.
`velocity`	`number`	No	`1`	The speed; pass a negative value when pinching in (scale below 1).

Returns

Type	Description
`object`	The raw WDA response; rarely needed.

Example

javascript

client.pinch(2, 1);      // 放大 / zoom in
client.pinch(0.5, -1);   // 缩小 / zoom out

client.hideKeyboard#

Dismiss the keyboard; client.isKeyboardShown() tells whether it is up.

typescript

client.hideKeyboard(): boolean;
client.isKeyboardShown(): boolean;

Returns

Type	Description
`boolean`	hideKeyboard: true once the keyboard is gone (also when it was never up); isKeyboardShown: true while the keyboard is visible.

Example

javascript

if (client.isKeyboardShown()) {
  client.hideKeyboard();
}

client.tapHold#

Press and hold at a point, then release (a long press).

typescript

client.tapHold(x: number, y: number, duration?: number): object;

Parameters

Name	Type	Required	Default	Description
`x`	`number`	Yes	—	Horizontal position: a 0–1 screen ratio, or points.
`y`	`number`	Yes	—	Vertical position: a 0–1 screen ratio, or points.
`duration`	`number`	No	`1.0`	Seconds to hold.

Returns

Type	Description
`object`	The raw WDA response; rarely needed.

Throws

Error	Raised when
`WDAError`	Ratio coordinates were given but the screen size could not be read (the WDA session is unhealthy).

Notes

When x and y both fall between 0 and 1 they are screen ratios (0.5, 0.5 is the centre); otherwise they are points. The conversion needs the screen size and throws if it cannot be read.

Example

javascript

client.tapHold(0.5, 0.5, 1.5);

client.home#

Go to the Home Screen.

typescript

client.home(): void;

Example

javascript

client.home();

client.press#

Press a hardware button: home, volumeUp or volumeDown.

typescript

client.press(name: "home" | "volumeUp" | "volumeDown"): object;

Parameters

Name	Type	Required	Default	Description
`name`	`"home" \| "volumeUp" \| "volumeDown"`	Yes	—	The button name.

Returns

Type	Description
`object`	The raw WDA response; rarely needed.

Throws

Error	Raised when
`Error`	The name is not one of the three.

Example

javascript

client.press('volumeUp');

client.sendKeys#

Type into the focused text field, character by character through the keyboard. Tap the field first so it has focus.

typescript

client.sendKeys(value: string): object;

Parameters

Name	Type	Required	Default	Description
`value`	`string`	Yes	—	The text to type; non-ASCII text is supported.

Returns

Type	Description
`object`	The raw WDA response; rarely needed.

Example

javascript

clickElement('accessibilityId', 'search_field', 5);
client.sendKeys('hello');

client.lock#

Lock the screen; client.unlock() unlocks it and client.locked() tells whether it is locked.

typescript

client.lock(): object;
client.unlock(): object;
client.locked(): boolean;

Returns

Type	Description
`object \| boolean`	lock / unlock return the raw WDA response; locked returns true while the screen is locked.

Notes

Unlocking only works on devices without a passcode.

Example

javascript

if (client.locked()) {
  client.unlock();
}