0
# Mobile Automation
1

2
Complete mobile automation support through Appium integration, including touch gestures, app management, context switching, and mobile-specific interactions.
3

4
## Capabilities
5

6
### Touch Gestures
7

8
Mobile-specific touch interactions and gestures.
9

10
```typescript { .api }
11
/**
12
 * Perform touch action sequences on mobile devices
13
 * @param action - Touch action configuration or sequence
14
 * @returns Promise that resolves when touch action is complete
15
 */
16
touchAction(action: object): Promise<void>;
17

18
/**
19
 * Perform swipe gesture across the screen
20
 * @param xStart - Starting X coordinate
21
 * @param yStart - Starting Y coordinate  
22
 * @param xEnd - Ending X coordinate
23
 * @param yEnd - Ending Y coordinate
24
 * @returns Promise that resolves when swipe is complete
25
 */
26
swipe(xStart: number, yStart: number, xEnd: number, yEnd: number): Promise<void>;
27

28
/**
29
 * Tap on specific coordinates or element
30
 * @param x - X coordinate or element reference
31
 * @param y - Y coordinate (if x is coordinate)
32
 * @returns Promise that resolves when tap is complete
33
 */
34
tap(x: number | WebdriverIO.Element, y?: number): Promise<void>;
35
```
36

37
**Usage Examples:**
38

39
```typescript
40
// Simple tap gesture
41
await browser.touchAction('tap');
42

43
// Complex touch sequence
44
await browser.touchAction([
45
  { action: 'press', x: 100, y: 200 },
46
  { action: 'wait', duration: 500 },
47
  { action: 'moveTo', x: 300, y: 200 },
48
  { action: 'release' }
49
]);
50

51
// Swipe gestures
52
await browser.swipe(100, 500, 100, 100); // Swipe up
53
await browser.swipe(300, 200, 100, 200); // Swipe left
54

55
// Tap on coordinates
56
await browser.tap(150, 300);
57

58
// Tap on element
59
const button = await browser.$('~mobile-button');
60
await browser.tap(button);
61
```
62

63
### Element-Level Mobile Gestures
64

65
Touch gestures specific to mobile elements.
66

67
```typescript { .api }
68
/**
69
 * Perform touch action on a specific element
70
 * @param action - Touch action configuration
71
 * @returns Promise that resolves when touch action is complete
72
 */
73
element.touchAction(action: object): Promise<void>;
74

75
/**
76
 * Long press on an element
77
 * @param duration - Duration of the long press in milliseconds
78
 * @returns Promise that resolves when long press is complete
79
 */
80
element.longPress(duration?: number): Promise<void>;
81

82
/**
83
 * Drag and drop for mobile elements
84
 * @param target - Target element or coordinates
85
 * @returns Promise that resolves when drag and drop is complete
86
 */
87
element.dragAndDrop(target: WebdriverIO.Element | {x: number, y: number}): Promise<void>;
88

89
/**
90
 * Tap on a mobile element
91
 * @returns Promise that resolves when tap is complete
92
 */
93
element.tap(): Promise<void>;
94

95
/**
96
 * Pinch gesture on an element (zoom out)
97
 * @param scale - Scale factor for pinch
98
 * @returns Promise that resolves when pinch is complete
99
 */
100
element.pinch(scale: number): Promise<void>;
101

102
/**
103
 * Zoom gesture on an element (zoom in)
104
 * @param scale - Scale factor for zoom
105
 * @returns Promise that resolves when zoom is complete
106
 */
107
element.zoom(scale: number): Promise<void>;
108
```
109

110
**Usage Examples:**
111

112
```typescript
113
const image = await browser.$('~image-view');
114

115
// Long press on element
116
await image.longPress(1000);
117

118
// Pinch to zoom out
119
await image.pinch(0.5);
120

121
// Zoom in
122
await image.zoom(2.0);
123

124
// Tap element
125
await image.tap();
126

127
// Complex touch action on element
128
await image.touchAction([
129
  { action: 'press' },
130
  { action: 'wait', duration: 100 },
131
  { action: 'moveTo', x: 50, y: 0 },
132
  { action: 'release' }
133
]);
134
```
135

136
### App Context Management
137

138
Manage mobile app contexts and switch between native and web views.
139

140
```typescript { .api }
141
/**
142
 * Get the current context (NATIVE_APP or WEBVIEW)
143
 * @returns Promise resolving to the current context name
144
 */
145
getContext(): Promise<string>;
146

147
/**
148
 * Get all available contexts
149
 * @returns Promise resolving to array of available context names
150
 */
151
getContexts(): Promise<string[]>;
152

153
/**
154
 * Switch to a specific context
155
 * @param context - Context name to switch to (e.g., 'NATIVE_APP', 'WEBVIEW_1')
156
 * @returns Promise that resolves when context switch is complete
157
 */
158
switchContext(context: string): Promise<void>;
159
```
160

161
**Usage Examples:**
162

163
```typescript
164
// Get current context
165
const currentContext = await browser.getContext();
166
console.log('Current context:', currentContext);
167

168
// Get all available contexts
169
const contexts = await browser.getContexts();
170
console.log('Available contexts:', contexts);
171
// Output: ['NATIVE_APP', 'WEBVIEW_chrome']
172

173
// Switch to native app context
174
await browser.switchContext('NATIVE_APP');
175

176
// Switch to web view context
177
await browser.switchContext('WEBVIEW_chrome');
178

179
// Switch back to native
180
await browser.switchContext('NATIVE_APP');
181
```
182

183
### App Lifecycle Management
184

185
Control mobile application lifecycle and state.
186

187
```typescript { .api }
188
/**
189
 * Relaunch the currently active application
190
 * @returns Promise that resolves when app is relaunched
191
 */
192
relaunchActiveApp(): Promise<void>;
193

194
/**
195
 * Handle deep links and URL schemes
196
 * @param url - Deep link URL to open
197
 * @returns Promise that resolves when deep link is handled
198
 */
199
deepLink(url: string): Promise<void>;
200

201
/**
202
 * Get current app state
203
 * @returns Promise resolving to app state information
204
 */
205
getAppState(): Promise<object>;
206

207
/**
208
 * Launch a specific app by bundle ID or package name
209
 * @param bundleId - App bundle identifier
210
 * @returns Promise that resolves when app is launched
211
 */
212
launchApp(bundleId: string): Promise<void>;
213

214
/**
215
 * Close/terminate a specific app
216
 * @param bundleId - App bundle identifier
217
 * @returns Promise that resolves when app is terminated
218
 */
219
terminateApp(bundleId: string): Promise<void>;
220
```
221

222
**Usage Examples:**
223

224
```typescript
225
// Relaunch current app
226
await browser.relaunchActiveApp();
227

228
// Handle deep links
229
await browser.deepLink('myapp://profile/123');
230
await browser.deepLink('https://example.com/app-link');
231

232
// App lifecycle management
233
await browser.launchApp('com.example.myapp');
234
await browser.terminateApp('com.example.myapp');
235

236
// Get app state
237
const appState = await browser.getAppState();
238
console.log('App state:', appState);
239
```
240

241
### Device Interaction
242

243
Interact with device-specific features and hardware.
244

245
```typescript { .api }
246
/**
247
 * Simulate device orientation change
248
 * @param orientation - Device orientation ('PORTRAIT' or 'LANDSCAPE')
249
 * @returns Promise that resolves when orientation change is complete
250
 */
251
setOrientation(orientation: 'PORTRAIT' | 'LANDSCAPE'): Promise<void>;
252

253
/**
254
 * Get current device orientation
255
 * @returns Promise resolving to current orientation
256
 */
257
getOrientation(): Promise<string>;
258

259
/**
260
 * Simulate device shake gesture
261
 * @returns Promise that resolves when shake is complete
262
 */
263
shake(): Promise<void>;
264

265
/**
266
 * Lock device orientation
267
 * @param orientation - Orientation to lock to
268
 * @returns Promise that resolves when orientation is locked
269
 */
270
lock(orientation: string): Promise<void>;
271

272
/**
273
 * Unlock device orientation
274
 * @returns Promise that resolves when orientation is unlocked
275
 */
276
unlock(): Promise<void>;
277
```
278

279
**Usage Examples:**
280

281
```typescript
282
// Change device orientation
283
await browser.setOrientation('LANDSCAPE');
284
await browser.setOrientation('PORTRAIT');
285

286
// Check current orientation
287
const orientation = await browser.getOrientation();
288
console.log('Current orientation:', orientation);
289

290
// Device gestures
291
await browser.shake();
292

293
// Lock/unlock orientation
294
await browser.lock('PORTRAIT');
295
await browser.unlock();
296
```
297

298
### Mobile Element Interactions
299

300
Mobile-specific element interaction patterns.
301

302
```typescript { .api }
303
/**
304
 * Scroll to an element in a scrollable view
305
 * @param element - Element to scroll to
306
 * @param options - Scroll options
307
 * @returns Promise that resolves when scrolling is complete
308
 */
309
scrollToElement(element: WebdriverIO.Element, options?: object): Promise<void>;
310

311
/**
312
 * Find element by accessibility ID (mobile-specific selector)
313
 * @param accessibilityId - Accessibility identifier
314
 * @returns Promise resolving to the element
315
 */
316
$accessibility(accessibilityId: string): Promise<WebdriverIO.Element>;
317

318
/**
319
 * Find elements by accessibility ID
320
 * @param accessibilityId - Accessibility identifier
321
 * @returns Promise resolving to array of elements
322
 */
323
$$accessibility(accessibilityId: string): Promise<WebdriverIO.Element[]>;
324
```
325

326
**Usage Examples:**
327

328
```typescript
329
// Mobile-specific selectors
330
const button = await browser.$accessibility('submit-button');
331
const allButtons = await browser.$$accessibility('button');
332

333
// iOS-specific selectors
334
const iosElement = await browser.$('-ios predicate string:name == "Login"');
335
const iosElements = await browser.$$('-ios class chain:**/XCUIElementTypeButton[`name == "Login"`]');
336

337
// Android-specific selectors  
338
const androidElement = await browser.$('android=new UiSelector().text("Login")');
339
const androidElements = await browser.$$('android=new UiSelector().className("android.widget.Button")');
340

341
// Scroll to element
342
const targetElement = await browser.$accessibility('target-element');
343
await browser.scrollToElement(targetElement, {
344
  direction: 'down',
345
  maxSwipes: 5
346
});
347
```
348

349
### Platform-Specific Features
350

351
Features specific to iOS and Android platforms.
352

353
```typescript { .api }
354
// iOS-specific capabilities
355
/**
356
 * iOS-specific element selection using predicate strings
357
 * @param predicate - iOS predicate string
358
 * @returns Promise resolving to matching element
359
 */
360
$ios(predicate: string): Promise<WebdriverIO.Element>;
361

362
// Android-specific capabilities  
363
/**
364
 * Android-specific element selection using UiSelector
365
 * @param selector - Android UiSelector string
366
 * @returns Promise resolving to matching element
367
 */
368
$android(selector: string): Promise<WebdriverIO.Element>;
369

370
/**
371
 * Android back button press
372
 * @returns Promise that resolves when back button is pressed
373
 */
374
back(): Promise<void>;
375

376
/**
377
 * Android home button press
378
 * @returns Promise that resolves when home button is pressed
379
 */
380
home(): Promise<void>;
381

382
/**
383
 * Android menu button press
384
 * @returns Promise that resolves when menu button is pressed
385
 */
386
menu(): Promise<void>;
387
```
388

389
**Usage Examples:**
390

391
```typescript
392
// iOS predicate strings
393
const iOSButton = await browser.$ios('name == "Submit" AND visible == 1');
394
const iOSInput = await browser.$ios('type == "XCUIElementTypeTextField"');
395

396
// Android UiSelector
397
const androidButton = await browser.$android('new UiSelector().text("Submit")');
398
const androidInput = await browser.$android('new UiSelector().className("android.widget.EditText")');
399

400
// Android hardware buttons
401
await browser.back();  // Press back button
402
await browser.home();  // Press home button  
403
await browser.menu(); // Press menu button
404
```
405

406
### Mobile Wait Strategies
407

408
Mobile-specific waiting and synchronization patterns.
409

410
```typescript { .api }
411
/**
412
 * Wait for element to be stable (not moving/animating)
413
 * @param options - Wait options including timeout
414
 * @returns Promise that resolves when element is stable
415
 */
416
element.waitForStable(options?: object): Promise<boolean>;
417

418
/**
419
 * Wait for app to reach a specific state
420
 * @param state - Expected app state
421
 * @param timeout - Maximum wait time
422
 * @returns Promise that resolves when state is reached
423
 */
424
waitForAppState(state: string, timeout?: number): Promise<void>;
425
```
426

427
**Usage Examples:**
428

429
```typescript
430
// Wait for element to stop animating
431
const animatedElement = await browser.$accessibility('animated-view');
432
await animatedElement.waitForStable({ timeout: 5000 });
433

434
// Wait for app state changes
435
await browser.waitForAppState('RUNNING_IN_FOREGROUND', 10000);
436

437
// Mobile-specific wait patterns
438
await browser.waitUntil(async () => {
439
  const contexts = await browser.getContexts();
440
  return contexts.includes('WEBVIEW_chrome');
441
}, {
442
  timeout: 15000,
443
  timeoutMsg: 'WebView context never became available'
444
});
445
```