0
# Mobile Testing
1

2
Comprehensive mobile testing support through Appium integration with device-specific actions, app management, and mobile-optimized interactions.
3

4
## Capabilities
5

6
### Device Actions
7

8
Control physical device functions and hardware features.
9

10
```javascript { .api }
11
/**
12
 * Shake the device
13
 * @param cb - Callback receiving (err)
14
 */
15
shakeDevice(cb?: callback): void;
16
shake(cb?: callback): void; // Alias
17

18
/**
19
 * Lock device for specified duration
20
 * @param seconds - Lock duration in seconds
21
 * @param cb - Callback receiving (err)
22
 */
23
lockDevice(seconds?: number, cb?: callback): void;
24
lock(seconds?: number, cb?: callback): void; // Alias
25

26
/**
27
 * Unlock the device
28
 * @param cb - Callback receiving (err)
29
 */
30
unlockDevice(cb?: callback): void;
31
unlock(cb?: callback): void; // Alias
32

33
/**
34
 * Check if device is locked
35
 * @param cb - Callback receiving (err, isLocked)
36
 */
37
isLocked(cb?: callback): boolean;
38

39
/**
40
 * Rotate device orientation
41
 * @param x - X-axis rotation
42
 * @param y - Y-axis rotation
43
 * @param z - Z-axis rotation
44
 * @param cb - Callback receiving (err)
45
 */
46
rotateDevice(x: number, y: number, z: number, cb?: callback): void;
47
rotate(x: number, y: number, z: number, cb?: callback): void; // Alias
48
```
49

50
**Usage Examples:**
51

52
```javascript
53
// Shake device to trigger refresh
54
browser.shakeDevice(function(err) {
55
  console.log('Device shaken');
56
});
57

58
// Lock device and verify
59
browser.lockDevice(5, function(err) {
60
  browser.isLocked(function(err, locked) {
61
    console.log('Device is locked:', locked);
62
    
63
    setTimeout(() => {
64
      browser.unlockDevice();
65
    }, 2000);
66
  });
67
});
68

69
// Rotate device for landscape testing
70
browser.rotateDevice(0, 0, 90, function(err) {
71
  console.log('Device rotated to landscape');
72
});
73

74
// Promise chain device control
75
browser
76
  .lockDevice(3)
77
  .sleep(1000)
78
  .unlockDevice()
79
  .isLocked()
80
  .then(locked => console.log('Still locked:', locked));
81
```
82

83
### Screen Orientation
84

85
Manage device screen orientation for responsive testing.
86

87
```javascript { .api }
88
/**
89
 * Get current screen orientation
90
 * @param cb - Callback receiving (err, orientation)
91
 */
92
getOrientation(cb?: callback): string;
93

94
/**
95
 * Set screen orientation
96
 * @param orientation - 'PORTRAIT', 'LANDSCAPE', 'UIA_DEVICE_ORIENTATION_PORTRAIT', etc.
97
 * @param cb - Callback receiving (err)
98
 */
99
setOrientation(orientation: string, cb?: callback): void;
100
```
101

102
**Usage Examples:**
103

104
```javascript
105
// Get current orientation
106
browser.getOrientation(function(err, orientation) {
107
  console.log('Current orientation:', orientation);
108
});
109

110
// Set to landscape mode
111
browser.setOrientation('LANDSCAPE', function(err) {
112
  console.log('Switched to landscape');
113
  
114
  // Test responsive layout
115
  browser.elementByCss('.responsive-menu', function(err, menu) {
116
    menu.isDisplayed(function(err, visible) {
117
      console.log('Landscape menu visible:', visible);
118
    });
119
  });
120
});
121

122
// Portrait mode testing
123
browser.setOrientation('PORTRAIT', function(err) {
124
  browser.takeScreenshot('portrait-view.png');
125
});
126
```
127

128
### App Management
129

130
Install, launch, and manage mobile applications.
131

132
```javascript { .api }
133
/**
134
 * Get current activity (Android)
135
 * @param cb - Callback receiving (err, activity)
136
 */
137
getCurrentDeviceActivity(cb?: callback): string;
138
getCurrentActivity(cb?: callback): string; // Alias
139

140
/**
141
 * Get current package name (Android)
142
 * @param cb - Callback receiving (err, package)
143
 */
144
getCurrentPackage(cb?: callback): string;
145

146
/**
147
 * Install app on device
148
 * @param appPath - Path to app file
149
 * @param cb - Callback receiving (err)
150
 */
151
installAppOnDevice(appPath: string, cb?: callback): void;
152
installApp(appPath: string, cb?: callback): void; // Alias
153

154
/**
155
 * Activate app by bundle ID
156
 * @param bundleId - App bundle identifier
157
 * @param cb - Callback receiving (err)
158
 */
159
activateApp(bundleId: string, cb?: callback): void;
160

161
/**
162
 * Remove app from device
163
 * @param bundleId - App bundle identifier
164
 * @param cb - Callback receiving (err)
165
 */
166
removeAppFromDevice(bundleId: string, cb?: callback): void;
167
removeApp(bundleId: string, cb?: callback): void; // Alias
168

169
/**
170
 * Check if app is installed
171
 * @param bundleId - App bundle identifier
172
 * @param cb - Callback receiving (err, isInstalled)
173
 */
174
isAppInstalledOnDevice(bundleId: string, cb?: callback): boolean;
175
isAppInstalled(bundleId: string, cb?: callback): boolean; // Alias
176

177
/**
178
 * Launch current app
179
 * @param cb - Callback receiving (err)
180
 */
181
launchApp(cb?: callback): void;
182

183
/**
184
 * Close current app
185
 * @param cb - Callback receiving (err)
186
 */
187
closeApp(cb?: callback): void;
188

189
/**
190
 * Reset app to clean state
191
 * @param cb - Callback receiving (err)
192
 */
193
resetApp(cb?: callback): void;
194

195
/**
196
 * Put app in background
197
 * @param seconds - Duration to background (0 = indefinitely)
198
 * @param cb - Callback receiving (err)
199
 */
200
backgroundApp(seconds: number, cb?: callback): void;
201
```
202

203
**Usage Examples:**
204

205
```javascript
206
// Check current app state
207
browser.getCurrentActivity(function(err, activity) {
208
  console.log('Current activity:', activity);
209
});
210

211
browser.getCurrentPackage(function(err, package) {
212
  console.log('Current package:', package);
213
});
214

215
// Install and launch app
216
browser.installApp('/path/to/app.apk', function(err) {
217
  if (err) throw err;
218
  console.log('App installed');
219
  
220
  browser.launchApp(function(err) {
221
    console.log('App launched');
222
  });
223
});
224

225
// Check if app is installed
226
browser.isAppInstalled('com.example.myapp', function(err, installed) {
227
  if (!installed) {
228
    console.log('App not installed, installing...');
229
    browser.installApp('/path/to/myapp.apk');
230
  } else {
231
    browser.activateApp('com.example.myapp');
232
  }
233
});
234

235
// App lifecycle testing
236
browser
237
  .launchApp()
238
  .sleep(2000)
239
  .backgroundApp(5)  // Background for 5 seconds
240
  .sleep(6000)
241
  .activateApp('com.example.myapp')  // Bring back to foreground
242
  .getCurrentActivity()
243
  .then(activity => console.log('Resumed activity:', activity));
244
```
245

246
### Keyboard Management
247

248
Handle virtual keyboard interactions on mobile devices.
249

250
```javascript { .api }
251
/**
252
 * Check if keyboard is shown
253
 * @param cb - Callback receiving (err, isShown)
254
 */
255
isKeyboardShown(cb?: callback): boolean;
256

257
/**
258
 * Hide device keyboard
259
 * @param strategy - Hide strategy ('tap', 'press', 'swipe', etc.)
260
 * @param key - Key to press (for 'press' strategy)
261
 * @param cb - Callback receiving (err)
262
 */
263
hideDeviceKeyboard(strategy?: string, key?: string, cb?: callback): void;
264
hideKeyboard(strategy?: string, key?: string, cb?: callback): void; // Alias
265
```
266

267
**Usage Examples:**
268

269
```javascript
270
// Check keyboard state and hide if shown
271
browser.isKeyboardShown(function(err, shown) {
272
  console.log('Keyboard visible:', shown);
273
  
274
  if (shown) {
275
    browser.hideKeyboard('tap', function(err) {
276
      console.log('Keyboard hidden');
277
    });
278
  }
279
});
280

281
// Different keyboard hiding strategies
282
browser.hideKeyboard('press', 'Done'); // Press Done button
283
browser.hideKeyboard('swipe');         // Swipe to hide
284
browser.hideKeyboard('tap');           // Tap outside
285
```
286

287
### Hardware Key Events
288

289
Send hardware key events to mobile devices.
290

291
```javascript { .api }
292
/**
293
 * Send device key event
294
 * @param keycode - Android keycode
295
 * @param metastate - Key meta state (optional)
296
 * @param cb - Callback receiving (err)
297
 */
298
deviceKeyEvent(keycode: number, metastate?: number, cb?: callback): void;
299
pressDeviceKey(keycode: number, metastate?: number, cb?: callback): void; // Alias
300

301
/**
302
 * Press keycode
303
 * @param keycode - Android keycode
304
 * @param metastate - Key meta state (optional)
305
 * @param cb - Callback receiving (err)
306
 */
307
pressKeycode(keycode: number, metastate?: number, cb?: callback): void;
308

309
/**
310
 * Long press keycode
311
 * @param keycode - Android keycode
312
 * @param metastate - Key meta state (optional)
313
 * @param cb - Callback receiving (err)
314
 */
315
longPressKeycode(keycode: number, metastate?: number, cb?: callback): void;
316
```
317

318
**Usage Examples:**
319

320
```javascript
321
// Common Android keycodes
322
const KEYCODE_HOME = 3;
323
const KEYCODE_BACK = 4;
324
const KEYCODE_MENU = 82;
325
const KEYCODE_POWER = 26;
326
const KEYCODE_VOLUME_UP = 24;
327
const KEYCODE_VOLUME_DOWN = 25;
328

329
// Press hardware buttons
330
browser.pressKeycode(KEYCODE_BACK, function(err) {
331
  console.log('Back button pressed');
332
});
333

334
browser.pressKeycode(KEYCODE_HOME, function(err) {
335
  console.log('Home button pressed');
336
});
337

338
// Long press power button
339
browser.longPressKeycode(KEYCODE_POWER, function(err) {
340
  console.log('Power button long pressed');
341
});
342

343
// Volume control
344
browser.pressKeycode(KEYCODE_VOLUME_UP);
345
browser.pressKeycode(KEYCODE_VOLUME_DOWN);
346
```
347

348
### Network and Connectivity
349

350
Control device network settings and connectivity features.
351

352
```javascript { .api }
353
/**
354
 * Toggle airplane mode
355
 * @param cb - Callback receiving (err)
356
 */
357
toggleAirplaneModeOnDevice(cb?: callback): void;
358
toggleAirplaneMode(cb?: callback): void; // Alias
359
toggleFlightMode(cb?: callback): void;   // Alias
360

361
/**
362
 * Toggle WiFi
363
 * @param cb - Callback receiving (err)
364
 */
365
toggleWiFiOnDevice(cb?: callback): void;
366
toggleWiFi(cb?: callback): void; // Alias
367

368
/**
369
 * Toggle location services
370
 * @param cb - Callback receiving (err)
371
 */
372
toggleLocationServicesOnDevice(cb?: callback): void;
373
toggleLocationServices(cb?: callback): void; // Alias
374

375
/**
376
 * Toggle mobile data
377
 * @param cb - Callback receiving (err)
378
 */
379
toggleDataOnDevice(cb?: callback): void;
380
toggleData(cb?: callback): void; // Alias
381

382
/**
383
 * Set network connection type
384
 * @param type - Connection type bitmask
385
 * @param cb - Callback receiving (err)
386
 */
387
setNetworkConnection(type: number, cb?: callback): void;
388

389
/**
390
 * Get network connection type
391
 * @param cb - Callback receiving (err, connectionType)
392
 */
393
getNetworkConnection(cb?: callback): number;
394
```
395

396
**Usage Examples:**
397

398
```javascript
399
// Network connection types
400
const CONNECTION_NONE = 0;
401
const CONNECTION_AIRPLANE_MODE = 1;
402
const CONNECTION_WIFI_ONLY = 2;
403
const CONNECTION_DATA_ONLY = 4;
404
const CONNECTION_ALL_NETWORK_ON = 6;
405

406
// Test offline scenarios
407
browser.setNetworkConnection(CONNECTION_NONE, function(err) {
408
  console.log('Network disabled');
409
  
410
  // Test app behavior offline
411
  browser.elementById('sync-button', function(err, button) {
412
    button.click();
413
    // Verify offline message appears
414
  });
415
  
416
  // Re-enable network
417
  browser.setNetworkConnection(CONNECTION_ALL_NETWORK_ON);
418
});
419

420
// Toggle connectivity features
421
browser.toggleAirplaneMode(function(err) {
422
  console.log('Airplane mode toggled');
423
});
424

425
browser.toggleWiFi(function(err) {
426
  console.log('WiFi toggled');
427
});
428

429
// Check current connection
430
browser.getNetworkConnection(function(err, connectionType) {
431
  console.log('Connection type:', connectionType);
432
  
433
  if (connectionType === CONNECTION_WIFI_ONLY) {
434
    console.log('Device connected via WiFi only');
435
  }
436
});
437
```
438

439
### Context Switching
440

441
Switch between native and web contexts in hybrid apps.
442

443
```javascript { .api }
444
/**
445
 * Get current context
446
 * @param cb - Callback receiving (err, context)
447
 */
448
currentContext(cb?: callback): string;
449

450
/**
451
 * Switch to context
452
 * @param contextRef - Context name
453
 * @param cb - Callback receiving (err)
454
 */
455
context(contextRef: string, cb?: callback): void;
456

457
/**
458
 * Get all available contexts
459
 * @param cb - Callback receiving (err, contexts)
460
 */
461
contexts(cb?: callback): string[];
462
```
463

464
**Usage Examples:**
465

466
```javascript
467
// List available contexts
468
browser.contexts(function(err, contexts) {
469
  console.log('Available contexts:', contexts);
470
  // Example: ['NATIVE_APP', 'WEBVIEW_1', 'WEBVIEW_2']
471
});
472

473
// Switch to web context for hybrid app testing
474
browser.context('WEBVIEW_1', function(err) {
475
  console.log('Switched to web context');
476
  
477
  // Now can use web element selectors
478
  browser.elementByCss('.web-button', function(err, button) {
479
    button.click();
480
  });
481
});
482

483
// Switch back to native context
484
browser.context('NATIVE_APP', function(err) {
485
  console.log('Switched to native context');
486
  
487
  // Use native selectors
488
  browser.elementByAccessibilityId('native-button', function(err, button) {
489
    button.click();
490
  });
491
});
492

493
// Context switching workflow
494
browser
495
  .contexts()
496
  .then(contexts => {
497
    console.log('Contexts:', contexts);
498
    if (contexts.includes('WEBVIEW_1')) {
499
      return browser.context('WEBVIEW_1');
500
    }
501
  })
502
  .elementByCss('.login-form')
503
  .then(form => {
504
    // Interact with web elements
505
    return browser.context('NATIVE_APP');
506
  })
507
  .elementByAccessibilityId('native-menu')
508
  .click();
509
```