Creating an AndroidDriver — Session Lifecycle in Java

AndroidDriver is the entry point to all Android automation. It extends AppiumDriver with Android-specific methods — app management, clipboard control, gesture shortcuts, and deep integration with the UiAutomator2 engine.

Creating the driver

import io.appium.java_client.android.AndroidDriver;
import io.appium.java_client.android.options.UiAutomator2Options;
 
import java.net.URL;
 
URL serverUrl = new URL("http://127.0.0.1:4723");
UiAutomator2Options options = new UiAutomator2Options()
    .setDeviceName("emulator-5554")
    .setApp("/path/to/app.apk")
    .setAutoGrantPermissions(true);
 
AndroidDriver driver = new AndroidDriver(serverUrl, options);

The constructor blocks until the session is established or throws SessionNotCreatedException. Common causes of session failure: wrong device serial, Appium server not running, UiAutomator2 driver not installed.

AndroidDriver vs AppiumDriver

Declare the variable as AndroidDriver rather than AppiumDriver if you need Android-specific APIs:

// AppiumDriver — cross-platform, no Android extras
AppiumDriver driver = new AndroidDriver(url, options);
driver.pressKey(new KeyEvent(AndroidKey.BACK)); // compile error
 
// AndroidDriver — full Android API available
AndroidDriver driver = new AndroidDriver(url, options);
driver.pressKey(new KeyEvent(AndroidKey.BACK)); // works

In the DriverManager pattern, storing as AppiumDriver and casting when needed is acceptable:

AndroidDriver androidDriver = (AndroidDriver) DriverManager.getDriver();
androidDriver.openNotifications();

App lifecycle management

// Check if app is installed
boolean installed = driver.isAppInstalled("com.example.myapp");
 
// Install from file
driver.installApp("/path/to/new-version.apk");
 
// Launch without reinstalling
driver.activateApp("com.example.myapp");
 
// Move to background (simulates pressing Home)
driver.runAppInBackground(Duration.ofSeconds(3));
 
// Terminate the app
driver.terminateApp("com.example.myapp");
 
// Reset app state (clear data, restart)
driver.removeApp("com.example.myapp");
driver.installApp("/path/to/app.apk");
driver.activateApp("com.example.myapp");

Device hardware simulation

// Press Back
driver.pressKey(new KeyEvent(AndroidKey.BACK));
 
// Press Home
driver.pressKey(new KeyEvent(AndroidKey.HOME));
 
// Press Recent Apps
driver.pressKey(new KeyEvent(AndroidKey.APP_SWITCH));
 
// Set volume
driver.pressKey(new KeyEvent(AndroidKey.VOLUME_UP));

AndroidKey covers the full set of Android virtual keys — use it for hardware button simulation without writing ADB shell commands.

Clipboard and text input

// Set clipboard content (useful for testing paste flows)
driver.setClipboardText("paste this text");
 
// Read clipboard
String content = driver.getClipboardText();

For typing into a focused input field, sendKeys is the standard approach. For special characters or non-English text, use driver.setClipboardText() then long-press paste:

element.clear();
driver.setClipboardText("テスト入力");
element.click(); // focus
// Long-press to show paste option
new Actions(driver)
    .clickAndHold(element)
    .pause(Duration.ofSeconds(2))
    .release()
    .perform();
// Tap Paste in the popup
driver.findElement(AppiumBy.androidUIAutomator(
    "new UiSelector().text(\"Paste\")"
)).click();

Network and device state

// Check connectivity
ConnectionState state = driver.getConnection();
 
// Toggle WiFi
driver.toggleWifi();
 
// Toggle airplane mode
driver.toggleAirplaneMode();

Network simulation is useful for offline mode tests. Pair toggleAirplaneMode() with a runAppInBackground() to simulate a network drop mid-session.

Screenshot and recording

// Screenshot
File screenshot = driver.getScreenshotAs(OutputType.FILE);
Files.copy(screenshot, new File("target/screenshots/failure.png"));
 
// Screen recording (Android 4.4+)
driver.startRecordingScreen();
// ... run test steps ...
String base64Video = driver.stopRecordingScreen();
byte[] videoBytes = Base64.getDecoder().decode(base64Video);
Files.write(Paths.get("target/recordings/test.mp4"), videoBytes);

Screen recording is resource-intensive. Use it conditionally in @AfterMethod when the test has failed, not on every test run.

Getting device context

String deviceTime = driver.getDeviceTime();
String currentActivity = driver.currentActivity();
String currentPackage = driver.getCurrentPackage();
 
System.out.println("Activity: " + currentActivity);
// Output: Activity: com.example.myapp.LoginActivity

currentActivity() is indispensable for debugging "element not found" errors — it tells you which screen Appium is actually seeing when the locator fails.