#java-client

This is the Java language binding for writing Appium Tests, conforms to Mobile JSON Wire Protocol

API docs

###Features and other interesting information###

Tech stack

How to install the project

WIKI

##Changelog## 5.0.0 (under construction yet)

5.0.0-BETA3 [BUG FIX]

• [BUG FIX]:Issue report: #567. Fix: #568

5.0.0-BETA2

• [BUG FIX]:Issue report: #549. Fix: #551
• New capabilities were added #533:
  • IOSMobileCapabilityType#USE_NEW_WDA
  • IOSMobileCapabilityType#WDA_LAUNCH_TIMEOUT
  • IOSMobileCapabilityType#WDA_CONNECTION_TIMEOUT

The capability IOSMobileCapabilityType#REAL_DEVICE_LOGGER was removed. #533

• [BUG FIX]/[ENHANCEMENT]. Issue report: #552. FIX #556

  • Additional methods were added to the io.appium.java_client.HasSessionDetails
    • String getPlatformName()
    • String getAutomationName()
    • boolean isBrowser()
  • io.appium.java_client.HasSessionDetails is used by the io.appium.java_client.internal.JsonToMobileElementConverter to define which instance of the org.openqa.selenium.WebElement subclass should be created.

• [ENHANCEMENT]: The additional event firing feature. PR: #559. The WIKI chapter about the event firing was updated.

5.0.0-BETA1

• [MAJOR ENHANCEMENT]: Migration to Java 8. Epic: #399

  • API with default implementation. PR #470
  • Tools that provide Page Object engines were redesigned. The migration to repeatable annotations. Details you can read there: #497. Documentation was synced as well.
  • The new functional interface io.appium.java_client.functions.AppiumFunction was designed. It extends java.util.function.Function and com.google.common.base.Function. It was designed in order to provide compatibility with the org.openqa.selenium.support.ui.Wait #543
  • The new functional interface io.appium.java_client.functions.ExpectedCondition was designed. It extends io.appium.java_client.functions.AppiumFunction and org.openqa.selenium.support.ui.ExpectedCondition. #543
  • The new functional interface io.appium.java_client.functions.ActionSupplier was designed. It extends java.util.function.Supplier. #543

• [MAJOR ENHANCEMENT]: Migration from Maven to Gradle. Feature request is #214. Fixes: #442, #465.

• [MAJOR ENHANCEMENT] [MAJOR REFACTORING]. Non-abstract AppiumDriver:

  • Now the io.appium.java_client.AppiumDriver can use an instance of any io.appium.java_client.MobileBy subclass for the searching. It should work as expected when current session supports the given selector. It will throw org.openqa.selenium.WebDriverException otherwise. #462

  • The new interface io.appium.java_client.FindsByFluentSelector was added. #462

  • API was redesigned:

    these interfaces were marked deprecated and they are going to be removed #513#514:

    • io.appium.java_client.DeviceActionShortcuts
    • io.appium.java_client.android.AndroidDeviceActionShortcuts
    • io.appium.java_client.ios.IOSDeviceActionShortcuts

    instead following inerfaces were designed:

    • io.appium.java_client.HasDeviceTime
    • io.appium.java_client.HidesKeyboard
    • io.appium.java_client.HidesKeyboardWithKeyName
    • io.appium.java_client.PressesKeyCode
    • io.appium.java_client.ios.ShakesDevice
    • io.appium.java_client.HasSessionDetails That was done because Windows automation tools have some features that were considered as Android-specific and iOS-specific.

    The list of classes and methods which were marked deprecated and they are going to be removed

    • AppiumDriver#swipe(int, int, int, int, int)
    • AppiumDriver#pinch(WebElement)
    • AppiumDriver#pinch(int, int)
    • AppiumDriver#zoom(WebElement)
    • AppiumDriver#zoom(int, int)
    • AppiumDriver#tap(int, WebElement, int)
    • AppiumDriver#tap(int, int, int, int)
    • AppiumDriver#swipe(int, int, int, int, int)
    • MobileElement#swipe(SwipeElementDirection, int)
    • MobileElement#swipe(SwipeElementDirection, int, int, int)
    • MobileElement#zoom()
    • MobileElement#pinch()
    • MobileElement#tap(int, int)
    • io.appium.java_client.SwipeElementDirection and io.appium.java_client.TouchebleElement also were marked deprecated.

    redesign of TouchAction and MultiTouchAction

    • constructors were redesigned. There is no strict binding of AppiumDriver and TouchAction /MultiTouchAction. They can consume any instance of a class that implements PerformsTouchActions.
    • io.appium.java_client.ios.IOSTouchAction was added. It extends io.appium.java_client.TouchAction.
    • the new interface io.appium.java_client.PerformsActions was added. It unifies TouchAction and MultiTouchAction now. #543

    JsonToMobileElementConverter re-design #532:

    • unused MobileElementToJsonConverter was removed
    • JsonToMobileElementConverter is not rhe abstract class now. It generates instances of MobileElement subclasses according to current session parameters
    • JsonToAndroidElementConverter is deprecated now
    • JsonToIOSElementConverter is depreacated now
    • JsonToYouiEngineElementConverter is deprecated now.
    • constructors of 'AppiumDriver' were re-designed.
    • constructors of 'AndroidDriver' were re-designed.
    • constructors of 'IOSDriver' were re-designed.

• [MAJOR ENHANCEMENT] Windows automation. Epic #471

  • The new interface io.appium.java_client.FindsByWindowsAutomation was added. #462. With @jonstoneman 's authorship.
  • The new selector strategy io.appium.java_client.MobileBy.ByWindowsAutomation was added. #462. With @jonstoneman 's authorship.
  • io.appium.java_client.windows.WindowsDriver was designed. #538
  • io.appium.java_client.windows.WindowsElement was designed. #538
  • io.appium.java_client.windows.WindowsKeyCode was added. #538
  • Page object tools were updated #538
    • the io.appium.java_client.pagefactory.WindowsFindBy annotation was added.
    • io.appium.java_client.pagefactory.AppiumFieldDecorator and supporting tools were actualized.

• [MAJOR ENHANCEMENT] iOS XCUIT mode automation:

  • io.appium.java_client.remote.AutomationName#IOS_XCUI_TEST was added
  • The new interface io.appium.java_client.FindsByIosNSPredicate was added. #462. With @rafael-chavez 's authorship. It is implemented by io.appium.java_client.ios.IOSDriver and io.appium.java_client.ios.IOSElement.
  • The new selector strategy io.appium.java_client.MobileBy.ByIosNsPredicate was added. #462. With @rafael-chavez 's authorship.
  • Page object tools were updated #545, #546
    • the io.appium.java_client.pagefactory.iOSXCUITFindBy annotation was added.
    • io.appium.java_client.pagefactory.AppiumFieldDecorator and supporting tools were actualized.

• [ENHANCEMENT] Added the ability to set UiAutomator Congfigurator values. #410. #477.

• [ENHANCEMENT]. Additional methods which perform device rotation were implemented. #489. #439. But it works for iOS in XCUIT mode and for Android in UIAutomator2 mode only. The feature request: #7131

• [ENHANCEMENT]. TouchID Implementation (iOS Sim Only). Details: #509

• [ENHANCEMENT]. The ability to use port, ip and log file as server arguments was provided. Feature request: #521. Fixes: #522, #524.

• [ENHANCEMENT]. The new interface io.appium.java_client.android.HasDeviceDetails was added. It is implemented by io.appium.java_client.android.AndroidDriver by default. #518

• [ENHANCEMENT]. New touch actions were added. io.appium.java_client.ios.IOSTouchAction#doubleTap(WebElement, int, int) and io.appium.java_client.ios.IOSTouchAction#doubleTap(WebElement). #523, #444

• [ENHANCEMENT]. All constructors declared by io.appium.java_client.AppiumDriver are public now.

• [BUG FIX]: There was the issue when "@WithTimeout" was changing general timeout of the waiting for elements. Bug report: #467. Fixes: #468, #469, #480. Read: supported-settings

• Added the server flag io.appium.java_client.service.local.flags.AndroidServerFlag#REBOOT. #476

• Added io.appium.java_client.remote.AndroidMobileCapabilityType.APP_WAIT_DURATION capability. #461

• the new automation type io.appium.java_client.remote.MobilePlatform#ANDROID_UIAUTOMATOR2 was add.

• the new automation type io.appium.java_client.remote.MobilePlatform#YOUI_ENGINE was add.

• Additional capabilities were addede:

  • IOSMobileCapabilityType#CUSTOM_SSL_CERT
  • IOSMobileCapabilityType#TAP_WITH_SHORT_PRESS_DURATION
  • IOSMobileCapabilityType#SCALE_FACTOR
  • IOSMobileCapabilityType#WDA_LOCAL_PORT
  • IOSMobileCapabilityType#SHOW_XCODE_LOG
  • IOSMobileCapabilityType#REAL_DEVICE_LOGGER
  • IOSMobileCapabilityType#IOS_INSTALL_PAUSE
  • IOSMobileCapabilityType#XCODE_CONFIG_FILE
  • IOSMobileCapabilityType#KEYCHAIN_PASSWORD
  • IOSMobileCapabilityType#USE_PREBUILT_WDA
  • IOSMobileCapabilityType#PREVENT_WDAATTACHMENTS
  • IOSMobileCapabilityType#WEB_DRIVER_AGENT_URL
  • IOSMobileCapabilityType#KEYCHAIN_PATH
  • MobileCapabilityType#CLEAR_SYSTEM_FILES

• [UPDATE] to Selenium 3.0.1.

• [UPDATE] to Spring Framework 4.3.5.RELEASE.

• [UPDATE] to AspectJ weaver 1.8.10.

4.1.2

• Following capabilities were added:
  • io.appium.java_client.remote.AndroidMobileCapabilityType.ANDROID_INSTALL_TIMEOUT
  • io.appium.java_client.remote.AndroidMobileCapabilityType.NATIVE_WEB_SCREENSHOT
  • io.appium.java_client.remote.AndroidMobileCapabilityType.ANDROID_SCREENSHOT_PATH. The pull request: #452
• org.openqa.selenium.Alert was reimplemented for iOS. Details: #459
• The deprecated io.appium.java_client.generic.searchcontext was removed.
• The dependency on com.google.code.gson was updated to 2.7. Also it was adde to exclusions for org.seleniumhq.selenium selenium-java.
• The new AutomationName was added. IOS_XCUI_TEST. It is needed for the further development.
• The new MobilePlatform was added. WINDOWS. It is needed for the further development.

4.1.1

BUG FIX: Issue #450. Fix: #451. Thanks to @tutunang for the report.

4.1.0

• all code marked @Deprecated was removed.
• getSessionDetails() was added. Thanks to @saikrishna321 for the contribution.
• FIX #362, #220, #323. Details read there: #413
• FIX #392. Thanks to @truebit for the bug report.
• The dependency on cglib was replaced by the dependency on cglib-nodep. FIX #418
• The casting to the weaker interface HasIdentity instead of class RemoteWebElement was added. It is the internal refactoring of the TouchAction. #432. Thanks to @asolntsev for the contribution.
• The setValue method was moved to MobileElement. It works against text input elements on Android.
• The dependency on org.springframework spring-context v4.3.2.RELEASE was added
• The dependency on org.aspectj aspectjweaver v1.8.9 was added
• ENHANCEMENT: The alternative event firing engine. The feature request: #242. Implementation: #437. Also new WIKI chapter was added.
• ENHANCEMENT: Convenient access to specific commands for each supported mobile OS. Details: #445
• dependencies and plugins were updated
• ENHANCEMENT: YouiEngineDriver was added. Details: appium server #6215, #429, #448. It is just the draft of the new solution that is going to be extended further. Please stay tuned. There are many interesting things are coming up. Thanks to You I Engine team for the contribution.

4.0.0

• all code marked @Deprecated was removed. Java client won't support old servers (v<1.5.0) anymore.
• the ability to start an activity using Android intent actions, intent categories, flags and arguments was added to AndroidDriver. Thanks to @saikrishna321 for the contribution.
• scrollTo() and scrollToExact() became deprecated. They are going to be removed in the next release.
• The interface io.appium.java_client.ios.GetsNamedTextField and the declared method T getNamedTextField(String name) are deprecated as well. They are going to be removed in the next release.
• Methods findElements(String by, String using) and findElement(String by, String using) of org.openga.selenium.remote.RemoteWebdriver are public now. Thanks to @SrinivasanTarget.
• the io.appium.java_client.NetworkConnectionSetting class was marked deprecated
• the enum io.appium.java_client.android.Connection was added. All supported network bitmasks are defined there.
• Android. Old methods which get/set connection were marked @Deprecated
• Android. New methods which consume/return io.appium.java_client.android.Connection were added.
• the commandRepository field is public now. The modification of the MobileCommand
• Constructors like AppiumDriver(HttpCommandExecutor executor, Capabilities capabilities) were added to io.appium.java_client.android.AndroidDriver and io.appium.java_client.ios.IOSDriver
• The refactoring of io.appium.java_client.internal.JsonToMobileElementConverter. Now it accepts org.openqa.selenium.remote.RemoteWebDriver as the constructor parameter. It is possible to re-use io.appium.java_client.android.internal.JsonToAndroidElementConverter or io.appium.java_client.ios.internal.JsonToIOSElementConverter by RemoteWebDriver when it is needed.
• Constructors of the abstract io.appium.java_client.AppiumDriver were redesigned. Now they require a subclass of io.appium.java_client.internal.JsonToMobileElementConverter. Constructors of io.appium.java_client.android.AndroidDriver and io.appium.java_client.ios.IOSDriver are same still.
• The pushFile(String remotePath, File file) was added to AndroidDriver
• FIX of TouchAction. Instances of the TouchAction class are reusable now
• FIX of the swiping issue (iOS, server version >= 1.5.0). Now the swiping is implemented differently by AndroidDriver and IOSDriver. Thanks to @truebit and @nuggit32 for the catching.
• the project was integrated with maven-checkstyle-plugin. Thanks to @SrinivasanTarget for the work
• source code was improved according to code style checking rules.
• the integration with org.owasp dependency-check-maven was added. Thanks to @saikrishna321 for the work.
• the integration with org.jacoco jacoco-maven-plugin was added. Thanks to @SrinivasanTarget for the contribution.

3.4.1

• Update to Selenium v2.53.0
• all dependencies were updated to latest versions
• the dependency on org.apache.commons commons-lang3 v3.4 was added
• the fix of Widget method invocation.#340. A class visibility was taken into account. Thanks to aznime for the catching. Server flags were added:
  • GeneralServerFlag.ASYNC_TRACE
  • IOSServerFlag.WEBKIT_DEBUG_PROXY_PORT
• Source code was formatted using eclipse-java-google-style.xml. This is not the complete solution. The code style checking is going to be added further. Thanks to SrinivasanTarget for the work!

3.4.0

• Update to Selenium v2.52.0
• getAppStrings() methods are deprecated now. They are going to be removed. getAppStringMap() methods were added and now return a map with app strings (keys and values) instead of a string. Thanks to @rgonalo for the contribution.
• Add getAppStringMap(String language, String stringFile) method to allow searching app strings in the specified file
• FIXED of the bug which causes deadlocks of AppiumDriver LocalService in multithreading. Thanks to saikrishna321 for the bug report.
• FIXED Zoom methods, thanks to @kkhaidukov
• FIXED The issue of compatibility of AppiumServiceBuilder with Appium node server v >= 1.5.x. Take a look at #305
• getDeviceTime() was added. Thanks to @SrinivasanTarget for the contribution.
• FIXED longPressKeyCode() methods. Now they use the convenient JSONWP command.Thanks to @kirillbilchenko for the proposed fix.
• FIXED javadoc.
• Page object tools were updated. Details read here: #311, #313, #317. By.name locator strategy is deprecated for Android and iOS. It is still valid for the Selendroid mode. Thanks to @SrinivasanTarget for the helping.
• The method lockScreen(seconds) is deprecated and it is going to be removed in the next release. Since Appium node server v1.5.x it is recommended to use AndroidDriver.lockDevice()...AndroidDriver.unlockDevice() or IOSDriver.lockDevice(int seconds) instead. Thanks to @namannigam for the catching. Read #315
• maven-release-plugin was added to POM.XML configuration
• #320 fix. The Widget.getSelfReference() was added. This method allows to extract a real widget-object from inside a proxy at some extraordinary situations. Read: PR. Thanks to SergeyErmakovMercDev for the reporting.
• all capabilities were added according to this description. There are three classes: io.appium.java_client.remote.MobileCapabilityType (just modified), io.appium.java_client.remote.AndroidMobileCapabilityType (android-specific capabilities), io.appium.java_client.remote.IOSMobileCapabilityType (iOS-specific capabilities). Details are here: #326
• some server flags were marked deprecated because they are deprecated since server node v1.5.x. These flags are going to be removed at the java client release. Details are here: #326
• The ability to start Appium node programmatically using desired capabilities. This feature is compatible with Appium node server v >= 1.5.x. Details are here: #326

3.3.0

• updated the dependency on Selenium to version 2.48.2
• bug fix and enhancements of io.appium.java_client.service.local.AppiumDriverLocalService
  • FIXED bug which was found and reproduced with Eclipse for Mac OS X. Please read about details here: #252 Thanks to saikrishna321 for the bug report
  • FIXED bug which was found out by Jonahss. Thanks for the reporting. Details: #272 and #273
  • For starting an appium server using localService, added additional environment variable to specify the location of Node.js binary: NODE_BINARY_PATH
  • The ability to set additional output streams was provided
• The additional startActivity() method was added to AndroidDriver. It allows to start activities without the stopping of a target app Thanks to deadmoto for the contribution
• The additional extension of the Page Object design pattern was designed. Please read about details here: #267
• New public constructors to AndroidDriver/IOSDriver that allow passing a custom HttpClient.Factory Details: #276 thanks to baechul

3.2.0

• updated the dependency on Selenium to version 2.47.1
• the new dependency on commons-validator v1.4.1
• the ability to start programmatically/silently an Appium node server is provided now. Details please read at #240. Historical reference: The similar solution has been designed by @Hassan-Radi. The mentioned framework and the current solution use different approaches.
• Throwing declarations were added to some searching methods. The "getMouse" method of RemoteWebDriver was marked Deprecated
• Add replaceValue method for elements.
• Replace sendKeyEvent() method in android with pressKeyCode(int key) and added: pressKeyCode(int key, Integer metastate), longPressKeyCode(int key), longPressKeyCode(int key, Integer metastate)

3.1.1

• Page-object findBy strategies are now aware of which driver (iOS or Android) you are using. For more details see the Pull Request: #213
• If somebody desires to use their own Webdriver implementation then it has to implement HasCapabilities.
• Added a new annotation: WithTimeout. This annotation allows one to specify a specific timeout for finding an element which overrides the drivers default timeout. For more info see: #210
• Corrected an uninformative Exception message.

3.0.0

• AppiumDriver class is now a Generic. This allows us to return elements of class MobileElement (and its subclasses) instead of always returning WebElements and requiring users to cast to MobileElement. See #182
• Full set of Android KeyEvents added.
• Selenium client version updated to 2.46
• PageObject enhancements
• Junit dependency removed

2.2.0

• Added new TouchAction methods for LongPress, on an element, at x,y coordinates, or at an offset from within an element
• SwipeElementDirection changed. Read the documentation, it's now smarter about how/where to swipe
• Added APPIUM_VERSION MobileCapabilityType
• sendKeyEvent() moved from AppiumDriver to AndroidDriver
• linkText and partialLinkText locators added
• setValue() moved from MobileElement to iOSElement
• Fixed Selendroid PageAnnotations

2.1.0

• Moved hasAppString() from AndroidDriver to AppiumDriver
• Fixes to PageFactory
• Added @AndroidFindAll and @iOSFindAll
• Added toggleLocationServices() to AndroidDriver
• Added touchAction methods to MobileElement, so now you can do element.pinch(), element.zoom(), etc.
• Added the ability to choose a direction to swipe over an element. Use the SwipeElementDirection enums: UP, DOWN, LEFT, RIGHT

2.0.0

• AppiumDriver is now an abstract class, use IOSDriver and AndroidDriver which both extend it. You no longer need to include the PLATFORM_NAME desired capability since it's automatic for each class. Thanks to @TikhomirovSergey for all their work
• ScrollTo() and ScrollToExact() methods reimplemented
• Zoom() and Pinch() are now a little smarter and less likely to fail if you element is near the edge of the screen. Congratulate @BJap on their first PR!

1.7.0

• Removed scrollTo() and scrollToExact() methods because they relied on complexFind(). They will be added back in the next version!
• Removed complexFind()
• Added startActivity() method
• Added isLocked() method
• Added getSettings() and ignoreUnimportantViews() methods

1.6.2

• Added MobilePlatform interface (Android, IOS, FirefoxOS)
• Added MobileBrowserType interface (Safari, Browser, Chromium, Chrome)
• Added MobileCapabilityType.APP_WAIT_ACTIVITY
• Fixed small Integer cast issue (in Eclipse it won't compile)
• Set -source and -target of the Java Compiler to 1.7 (for maven compiler plugin)
• Fixed bug in Page Factory

1.6.1

• Fixed the logic for checking connection status on NetworkConnectionSetting objects

1.6.0

• Added @findBy annotations. Explanation here: #68 Thanks to TikhomirovSergey
• Appium Driver now implements LocationContext interface, so setLocation() works for setting GPS coordinates

1.5.0

• Added MobileCapabilityType enums for desired capabilities
• findElement and findElements return MobileElement objects (still need to be casted, but no longer instantiated)
• new appium v1.2 hideKeyboard() strategies added
• getNetworkConnection() and setNetworkConnection() commands added

1.4.0

• Added openNotifications() method, to open the notifications shade on Android
• Added pullFolder() method, to pull an entire folder as a zip archive from a device/simulator
• Upgraded Selenium dependency to 2.42.2

1.3.0

• MultiGesture with a single TouchAction fixed for Android
• Now depends upon Selenium java client 2.42.1
• Cleanup of Errorcode handling, due to merging a change into Selenium

1.2.1

• fix dependency issue

1.2.0

• complexFind() now returns MobileElement objects
• added scrollTo() and scrollToExact() methods for use with complexFind()

1.1.0

• AppiumDriver now implements Rotatable. rotate() and getOrientation() methods added
• when no appium server is running, the proper error is thrown, instead of a NullPointerException

1.0.2

• recompiled to include some missing methods such as shake() and complexFind()

Run a test using

gradle clean -Dtest.single=IOSAlertTest test