Appium UiAutomator2 Server

Common errors

• AdbError: adb exited with code 1

  cause Appium's attempt to interact with ADB failed, often due to an unresponsive device, incorrect ADB path configuration, or insufficient permissions.
  fix Verify that your Android device/emulator is connected and recognized by `adb devices`. Check environment variables for `ANDROID_HOME` and `PATH` to ensure `adb` is correctly configured and accessible. Restart the ADB server using `adb kill-server` followed by `adb start-server`.

• Failed to create session. An unknown server-side error occurred while processing the command. Original error: UiAutomator2 server not running.

  cause The Appium UiAutomator2 server APK or its test APK failed to install, launch, or establish a connection on the Android device, preventing Appium from communicating with the device UI.
  fix Review the Appium server logs and device logs (logcat) for specific installation or runtime errors. Ensure the Android device has sufficient storage, disable 'Play Protect' (if applicable), and try restarting the device/emulator. Verify 'USB debugging' and 'Install via USB' (if available) are enabled in Developer Options.

• An element could not be located on the page using the given search parameters. (NoSuchElementError)

  cause The UI element specified by the locator strategy (e.g., accessibility ID, XPath, resource ID) was not present, visible, or interactable on the device screen at the exact moment of interaction.
  fix Verify the locator strategy is correct and the element is actually present in the application's current state using Appium Inspector. Implement explicit waits (e.g., `driver.waitUntil`) to allow elements time to appear or become interactable before attempting to locate them.

Warnings

• breaking This package has strict Node.js engine requirements, specifically `^20.19.0 || ^22.12.0 || >=24.0.0`. Using incompatible Node.js versions can lead to installation failures or runtime instability of Appium and its drivers.
  Fix: Ensure your Node.js environment matches the specified engine requirements. Use a Node Version Manager (e.g., nvm or Volta) to switch versions if needed to `20.19.0+`, `22.12.0+`, or `24.0.0+`.
• gotcha The `appium-uiautomator2-server` is a backend component of the Appium ecosystem. It is not designed to be started or managed directly by end-user scripts or run as a standalone server. It requires a running Appium server and the `appium-uiautomator2-driver` to function correctly.
  Fix: Interact with Android devices via an Appium client library (e.g., WebdriverIO, Appium client for Node.js) connected to an Appium server, which will handle the deployment and management of this server component automatically.
• gotcha Regularly update the `appium-uiautomator2-server` package to ensure the underlying Netty server components (e.g., `io.netty:netty-codec-http`) are patched against potential network security vulnerabilities and receive performance improvements. These updates are typically bundled in minor version increments of the Appium driver.
  Fix: Ensure your Appium installation and its drivers are kept up-to-date by regularly running `npm update` in your Appium project or using `appium driver update uiautomator2` if managing drivers via the Appium CLI.

Install

• npm install appium-uiautomator2-server npm
• yarn add appium-uiautomator2-server yarn
• pnpm add appium-uiautomator2-server pnpm

Imports

• N/A
  wrong:

  import { UiAutomator2Server } from 'appium-uiautomator2-server'; // Incorrect usage for this package
  const UiAutomator2Server = require('appium-uiautomator2-server'); // Incorrect usage for this package

  correct:

  // appium-uiautomator2-server is an internal Appium component; no direct JavaScript imports are typically used by end-user scripts.

  This package primarily bundles a Java server (.apk files) which the Appium server deploys to an Android device. End-user JavaScript/TypeScript test scripts interact with the Appium client library (e.g., WebdriverIO), not directly with this server component's npm package.

Quickstart

Demonstrates a typical Appium client-side setup using WebdriverIO to interact with an Android device, which implicitly leverages the appium-uiautomator2-server component deployed on the device. This code does not directly import or use 'appium-uiautomator2-server'.

import { remote } from 'webdriverio';

const capabilities = {
  platformName: 'Android',
  'appium:automationName': 'UiAutomator2',
  'appium:deviceName': 'Android Emulator',
  'appium:platformVersion': '11',
  'appium:app': '/path/to/your/app.apk', // Replace with your app's path or package/activity
  'appium:noReset': true,
  // Other capabilities as needed, e.g., 'appium:appPackage', 'appium:appActivity'
};

async function runAppiumTest() {
  let driver;
  try {
    driver = await remote({
      hostname: process.env.APPIUM_HOST ?? 'localhost',
      port: parseInt(process.env.APPIUM_PORT ?? '4723', 10),
      path: '/wd/hub',
      capabilities,
    });

    console.log('Appium session started successfully.');

    // Example: Interact with a native element using UiAutomator2 locator
    const el = await driver.$('android=new UiSelector().text("Hello World!")');
    if (await el.isDisplayed()) {
      console.log('Found element with text "Hello World!"');
      await el.click();
    }

    // Example: Perform a scroll action
    await driver.execute('mobile: scroll', { strategy: 'accessibility id', selector: 'SomeScrollableList', direction: 'down' });

    // More interactions here...

  } catch (error) {
    console.error('Appium test failed:', error);
  } finally {
    if (driver) {
      await driver.deleteSession();
      console.log('Appium session ended.');
    }
  }
}

runAppiumTest().catch(console.error);