appium/java-client

java-client

This is the Java language bindings for writing Appium Tests that conform to WebDriver Protocol

v10 to v11 Migration

Since v11 the client depends on selenium-api only, the minimum supported Selenium version is 4.50.0, and the minimum supported Appium server version is 3. Follow the v10 to v11 Migration Guide to streamline the migration process, it includes an OpenRewrite recipe that fixes most of the imports automatically.

v9 to v10 Migration

Follow the v9 to v10 Migration Guide to streamline the migration process.

v8 to v9 Migration

Since v9 the client only supports Java 11 and above. Follow the v8 to v9 Migration Guide to streamline the migration process.

v7 to v8 Migration

Since version 8 Appium Java Client had several major changes, which might require to update your client code. Make sure to follow the v7 to v8 Migration Guide to streamline the migration process.

Add Appium java client to your test framework

Stable

Maven

Add the following to pom.xml:

<dependency>
  <groupId>io.appium</groupId>
  <artifactId>java-client</artifactId>
  <version>${version.you.require}</version>
  <scope>test</scope>
</dependency>

Gradle

Add the following to build.gradle:

dependencies {
  testImplementation 'io.appium:java-client:${version.you.require}'
}

Beta/Snapshots

Java client project is available to use even before it is officially published to Maven Central. Refer jitpack.io

Maven

Add the following to pom.xml:

<repositories>
    <repository>
        <id>jitpack.io</id>
        <url>https://jitpack.io</url>
    </repository>
</repositories>

Add the dependency:

<dependency>
    <groupId>com.github.appium</groupId>
    <artifactId>java-client</artifactId>
    <version>latest commit ID from master branch</version>
</dependency>

Gradle

Add the JitPack repository to your build file. Add it to your root build.gradle at the end of repositories:

allprojects {
    repositories {
        // ...
        maven { url 'https://jitpack.io' }
    }
}

Add the dependency:

dependencies {
    implementation 'com.github.appium:java-client:latest commit id from master branch'
}

Compatibility Matrix

Why is it so complicated?

Selenium client does not follow Semantic Versioning, so breaking changes might be introduced even in patches, which requires the Appium team to update the Java client in response.

How to pin Selenium dependencies?

Appium Java Client declares Selenium dependencies using an open version range which is handled differently by different build tools. Sometimes users may want to pin used Selenium dependencies for various reasons. Follow the Transitive Dependencies Management article for more information about establishing a fixed Selenium version for your Java test framework.

Appium Server Compatibility

A major release of the client guarantees support only for the Appium server API of the major server version that is current at the time of the release and of the previous major version. Endpoints and commands that were removed or deprecated in the server earlier may not be supported anymore. For example, if Appium 4 is the current version, the API that existed in Appium 2 and was removed or deprecated in Appium 3 is not guaranteed to work.

Drivers Support

Appium java client has dedicated classes to support the following Appium drivers:

• UiAutomator2 and Espresso: AndroidDriver
• XCUITest: IOSDriver
• Windows (deprecated, not supported since Appium 4): WindowsDriver
• Wincore: WincoreDriver
• Safari: SafariDriver
• Gecko: GeckoDriver
• Mac2: Mac2Driver

To automate other platforms that are not listed above you could use AppiumDriver or its custom derivatives.

Appium java client implements the same WebDriver interfaces from selenium-api that the foundation Selenium RemoteWebDriver does, and it is the only part of Selenium it depends on. However, Selenium lib is mostly focused on web browser automation while Appium is universal and covers a wide range of possible platforms, e.g. mobile and desktop operating systems, IOT devices, etc. Thus, the foundation AppiumDriver class in this package extends AppiumRemoteWebDriver, which talks to the server through its own HTTP client, and it is not so strictly focused on web-browser related operations.

Code that needs the Selenium RemoteWebDriver, for example the Selenium Augmenter, or Selenium BiDi modules, can use the optional io.appium:java-client-selenium-bridge artifact. See Selenium interoperability.

Appium Server Service Wrapper

Appium java client provides a dedicated class to control Appium server execution. The class is AppiumDriverLocalService. It allows to run and verify the Appium server locally from your test framework code and provides several convenient shortcuts. The service could be used as below:

AppiumDriverLocalService service = AppiumDriverLocalService.buildDefaultService();
service.start();
try {
    // do stuff with drivers
} finally {
    service.stop();
}

You could customize the service behavior, for example, provide custom command line arguments or change paths to server executables using AppiumServiceBuilder

Note

AppiumDriverLocalService does not support server management on non-local hosts

Usage Examples

UiAutomator2

UiAutomator2Options options = new UiAutomator2Options()
    .setUdid("123456")
    .setApp("/home/myapp.apk");
AndroidDriver driver = new AndroidDriver(
    // The default URL in Appium 1 is http://127.0.0.1:4723/wd/hub
    new URI("http://127.0.0.1:4723").toURL(), options
);
try {
    WebElement el = driver.findElement(AppiumBy.xpath("//Button"));
    el.click();
    driver.getPageSource();
} finally {
    driver.quit();
}

XCUITest

XCUITestOptions options = new XCUITestOptions()
    .setUdid("123456")
    .setApp("/home/myapp.ipa");
IOSDriver driver = new IOSDriver(
    // The default URL in Appium 1 is http://127.0.0.1:4723/wd/hub
    new URI("http://127.0.0.1:4723").toURL(), options
);
try {
    WebElement el = driver.findElement(AppiumBy.accessibilityId("myId"));
    el.click();
    driver.getPageSource();
} finally {
    driver.quit();
}

Any generic driver that does not have a dedicated class

BaseOptions options = new BaseOptions()
    .setPlatformName("myplatform")
    .setAutomationName("mydriver")
    .amend("mycapability1", "capvalue1")
    .amend("mycapability2", "capvalue2");
AppiumDriver driver = new AppiumDriver(
    // The default URL in Appium 1 is http://127.0.0.1:4723/wd/hub
    new URI("http://127.0.0.1:4723").toURL(), options
);
try {
    WebElement el = driver.findElement(AppiumBy.className("myClass"));
    el.click();
    driver.getPageSource();
} finally {
    driver.quit();
}

Check the corresponding driver's READMEs to know the list of capabilities and features it supports.

You can find many more code examples by checking client's unit and integration tests.

Troubleshooting

InaccessibleObjectException is thrown in runtime if Java 16+ is used

Appium Java client uses reflective access to private members of other modules to ensure proper functionality of several features, like the Page Object model. If you get a runtime exception and InaccessibleObjectException is present in the stack trace and your Java runtime is at version 16 or higher, then consider the following Oracle's tutorial and/or checking existing issues for possible solutions. The idea there would be to explicitly allow access for particular modules using --add-exports/--add-opens command line arguments.

Another possible, but weakly advised solution, would be to downgrade Java to version 15 or lower.

Issues related to environment variables' presence or to their values

Such issues are usually the case when the Appium server is started directly from your framework code rather than run separately by a script or manually. Depending on the way the server process is started it may or may not inherit the currently active shell environment. That is why you may still receive errors about the variables' presence even though these variables are defined for your command line interpreter. Again, there is no universal solution to that, as there are many ways to spin up a new server process. Consider checking the Appium Environment Troubleshooting document for more information on how to debug and fix process environment issues.

Changelog

Visit CHANGELOG.md to see the full list of changes between versions.

Running tests

Run a test using

gradle clean -Dtest.single=IOSAlertTest test