How to run an Appium test in Java

A Java Appium smoke test proves that Maven, the Appium Java client, the server, and the selected mobile target can create one WebDriver session before a larger test suite hides setup errors. Running a tiny test first makes dependency, capability, driver, and device failures easier to separate.

The example uses JUnit and the official io.appium:java-client dependency to open the built-in Android Settings app with UiAutomator2. It uses the current Appium server root URL at http://127.0.0.1:4723 and Java option classes instead of old raw DesiredCapabilities setup.

Keep the Appium server and Android target ready before running the Java test. The sample uses com.android.settings so no project APK is required, but the same structure works for an installed app when the package, activity, locator, and assertion are changed to match that app.

1. Check that the Appium server is accepting sessions.

   $ curl --silent http://127.0.0.1:4723/status
   {"value":{"ready":true,"message":"The server is ready to accept new connections","build":{"version":"3.5.0"}}}

   Start the server first if the status endpoint does not answer. Current Appium servers use the root path by default, so the Java client should point at http://127.0.0.1:4723 unless the server was started with a legacy base path.
   Related: How to start the Appium server

2. Confirm the Android device or emulator is visible to adb.

   $ adb devices
   List of devices attached
   emulator-5554	device

   Use a specific udid capability when more than one Android target is connected.
   Related: How to run an Appium session on an Android emulator
   Related: How to run an Appium session on an Android real device

3. Add the Appium Java client and JUnit dependencies to the Maven test project.

     <properties>
       <maven.compiler.release>11</maven.compiler.release>
       <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
     </properties>
    
     <dependencies>
       <dependency>
         <groupId>io.appium</groupId>
         <artifactId>java-client</artifactId>
         <version>10.1.1</version>
         <scope>test</scope>
       </dependency>
       <dependency>
         <groupId>junit</groupId>
         <artifactId>junit</artifactId>
         <version>4.13.2</version>
         <scope>test</scope>
       </dependency>
     </dependencies>

   Add these entries inside the existing pom.xml project element. Appium Java client version 10.1.1 is published under io.appium:java-client and requires Java 11 or newer.

4. Create the Android Settings smoke test class.

   package guide;
    
   import io.appium.java_client.AppiumBy;
   import io.appium.java_client.android.*;
   import io.appium.java_client.android.options.*;
   import org.junit.*;
   import org.openqa.selenium.WebElement;
    
   import java.net.URI;
    
   public class AndroidSettingsTest {
       @Test
       public void opensBatterySettings() throws Exception {
           UiAutomator2Options options = new UiAutomator2Options()
                   .setPlatformName("Android")
                   .setAutomationName("UiAutomator2")
                   .setDeviceName("Android")
                   .setAppPackage("com.android.settings")
                   .setAppActivity(".Settings")
                   .setLanguage("en")
                   .setLocale("US");
    
           AndroidDriver driver = new AndroidDriver(
                   new URI("http://127.0.0.1:4723").toURL(),
                   options
           );
    
           try {
               System.out.println("Session: " + driver.getSessionId());
               WebElement battery = driver.findElement(
                       AppiumBy.xpath("//*[@text=\"Battery\"]")
               );
               battery.click();
               Assert.assertNotNull(driver.getPageSource());
               System.out.println("Opened Battery settings");
           } finally {
               driver.quit();
           }
       }
   }

   Set udid in the options when the host has multiple connected Android targets. Use setApp for an APK path, or replace setAppPackage and setAppActivity with the identifiers for the installed app under test.
   Related: How to install an app for an Appium session
   Related: How to configure Appium capabilities

5. Run the Java test from the Maven project root.

   $ mvn -q test -Dtest=AndroidSettingsTest
   Session: 6f9d2f7e-1f1a-4a42-a0c7-36d8f3c90511
   Opened Battery settings

   The session ID confirms that the Java client created an Appium session. The final line should appear after Android Settings opens and the Battery row is clicked.

6. Check the Appium server log for the matching session lifecycle.

   [HTTP] --> POST /session
   [AppiumDriver@7b1f] Session created with session id: 6f9d2f7e-1f1a-4a42-a0c7-36d8f3c90511
   [HTTP] --> POST /session/6f9d2f7e-1f1a-4a42-a0c7-36d8f3c90511/element
   [HTTP] --> DELETE /session/6f9d2f7e-1f1a-4a42-a0c7-36d8f3c90511

   A failed POST /session usually points to server, driver, capability, or device setup. A failure after the session is created usually points to the locator, app state, or wait timing.
   Related: How to debug Appium session logs
   Related: How to troubleshoot Appium timeout errors