Test Uiautomator

  
Framework for cross app functional UI testing
Latest Update Stable Release Release Candidate Beta Release Alpha Release
June 26, 2024 2.3.0 - - 2.4.0-alpha01

Declaring dependencies

To add a dependency on test, you must add the Google Maven repository to your project. Read Google's Maven repository for more information.

Add the dependencies for the artifacts you need in the build.gradle file for your app or module:

Groovy

dependencies {
    // Use to implement UIAutomator tests
    androidTestImplementation "androidx.test.uiautomator:uiautomator:2.4.0-alpha01"
}

Kotlin

dependencies {
    // Use to implement UIAutomator tests
    androidTestImplementation("androidx.test.uiautomator:uiautomator:2.4.0-alpha01")
}

For more information about dependencies, see Add build dependencies.

Feedback

Your feedback helps make Jetpack better. Let us know if you discover new issues or have ideas for improving this library. Please take a look at the existing issues in this library before you create a new one. You can add your vote to an existing issue by clicking the star button.

Create a new issue

See the Issue Tracker documentation for more information.

Version 2.4

Version 2.4.0-alpha01

June 26, 2024

androidx.test.uiautomator:uiautomator:2.4.0-alpha01 is released. Version 2.4.0-alpha01 contains these commits.

API Changes

  • Deprecated Configurator#getKeyInjectionDelay and setKeyInjectionDelay as the parameter is unused now that text is always injected directly rather than by key presses. (I3bcc5).

Bug Fixes

  • Updated the delay between UiObject2 motion events to account for dynamic refresh rates (i.e. Smooth Display) (I43f12).
  • Reduced flakiness from accessibility node staleness on certain UIs by periodically invalidating the accessibility cache (I3be25).
  • Fixed StaleObjectExceptions occurring when calling toString or hashCode on a stale UiObject2. (I38ea1).
  • Improved UiWatcher performance by skipping unnecessary waitForIdle calls. (I8c65e).
  • Fixed javadoc inaccuracies, especially to clarify when each Configurator parameter is used. (Ie10b1, I71631).

Version 2.3.0

Version 2.3.0

February 21, 2024

androidx.test.uiautomator:uiautomator:2.3.0 is released. Version 2.3.0 contains these commits.

Important changes since 2.2.0

  • Multi-display support: Added support for finding and operating on objects across multiple displays, and UiDevice methods to manage secondary displays (Ie6544, I912cd).
  • New selectors:
    • Added By.displayId to select objects by their display ID (I1825b).
    • Added By.hasParent and By.hasAncestor to select objects according to their parents (I93c36).
    • Added By.hint methods to select objects by their hint text (Idd345).
  • Custom conditions: Exposed a Condition interface to support custom wait conditions, and added corresponding UiDevice#wait, UiObject2#wait, and UiObject2#scrollUntil methods (27c0ea, 099d6e).
  • Bug fixes and reliability
    • Fixed an issue where the display size calculations were occasionally incorrect and might ignore portions of the screen (Ifc016). Coordinates and offsets used in tests may need to be adjusted.
    • Updated MotionEvent injection to improve accuracy (678ca3) and better emulate user gestures (454450).
    • Improved the reliability of scrolls (I7b059), rotations (c6cea0), long clicks (49572b), pinches (3c619a), and more.

Version 2.3.0-rc01

February 7, 2024

androidx.test.uiautomator:uiautomator:2.3.0-rc01 is released with no changes. Version 2.3.0-rc01 contains these commits.

Version 2.3.0-beta01

December 13, 2023

androidx.test.uiautomator:uiautomator:2.3.0-beta01 is released. Version 2.3.0-beta01 contains these commits.

API Changes

  • Renamed the UiObject2 percentage-based margin methods to setGestureMarginPercentage and setGestureMarginsPercentage for consistency (I24435)

Bug Fixes

  • Improved the error thrown when a secondary display is not found or not accessible (116b23)

Version 2.3.0-alpha05

November 1, 2023

androidx.test.uiautomator:uiautomator:2.3.0-alpha05 is released. Version 2.3.0-alpha05 contains these commits.

API Changes

  • Added UiObject2#getDrawingOrder to expose drawing order (z-index) information. (I5dfa4).
  • Added UiDevice methods to get, set, freeze, and unfreeze the rotation of secondary displays. (I912cd).

Bug Fixes

  • Added retry to UiObject2#scrollUntil when the end of scrolling could not be detected (Ibac6f).
  • Fixed issue where UiDevice would use a stale Instrumentation instance if it was recreated (I18cae).
  • Fixed possible NPE if the display ID cannot be determined when dumping nodes (Icafcb).
  • Added warning when performing clicks/scrolls on non-clickable/scrollable objects (I4a5d9).
  • Reduced the default UiObject2 scroll speed to improve reliability (I5e071).

Version 2.3.0-alpha04

July 26, 2023

androidx.test.uiautomator:uiautomator:2.3.0-alpha04 is released. Version 2.3.0-alpha04 contains these commits.

API Changes

  • Added By.hasParent and By.hasAncestor to support finding objects according to their parents (I93c36).
  • Added UiObject2#getHint to retrieve an object's hint text, and By.hint methods to select objects according to their hint text (Idd345).
  • Added By.displayId to support selecting objects according to the display they are on (I1825b).
  • Added UiDevice#getDisplayHeight(int) and UiDevice#getDisplayWidth(int) methods to find the dimensions of a display by its ID (Ie6544).
  • Re-added wait(SearchCondition, long) and wait(UiObject2Condition, long) methods for backwards compatibility (Iebfda).
  • Changed UiDevice#executeShellCommand to public but discouraged instead of hidden (Ic48a1).

Bug Fixes

  • Updated MotionEvent injection to reduce flakiness by prioritizing gesture accuracy over speed (678ca3).
  • Added tracing to resource heavy methods to identify performance bottlenecks (d17de3).
  • Added a retry mechanism when initiating a UiAutomation connection (048caf).
  • Fixed a possible NPE from null nodes in UiDevice#dumpWindowHierarchy (b725eb).
  • Fixed unexpected errors from querying or operating on private displays (985db6, 7053d4).

Version 2.3.0-alpha03

April 19, 2023

androidx.test.uiautomator:uiautomator:2.3.0-alpha03 is released. Version 2.3.0-alpha03 contains these commits.

API Changes

  • Exposed a Condition interface to allow custom wait conditions instead of relying solely on the built-ins in Until, and updated UiDevice#wait and UiObject2#wait methods to accept this interface (27c0ea).
  • Added UiObject2#scrollUntil to support scrolling until a condition is met and to reach parity with UiScrollable (099d6e).
  • Added UiDevice#setOrientationPortrait and setOrientationLandscape to facilitate rotations across device types (e13cb7).
  • Added UiObject2#setGestureMarginPercent to support setting margins relative to the object size. (Ib8c77)

Bug Fixes

  • Fixed UiScrollable methods occasionally using invalid coordinates on SDKs 18 to 22 (b53ece).
  • Fixed UiObject2#setText and clearText failing to modify text on SDKs 18 and 19 (77e41d).
  • Fixed UiWatchers not being executed in the right order (c85f92).
  • Fixed issue where device rotation might not yet be complete after a UiDevice orientation change (c6cea0).
  • Improved reliability of long clicks, drags, and pinches (49572b, 3c619a).

Version 2.3.0-alpha02

January 11, 2023

androidx.test.uiautomator:uiautomator:2.3.0-alpha02 is released. Version 2.3.0-alpha02 contains these commits.

API Changes

  • Reworked logging throughout the library to provide more information, warn about possible issues, and improve consistency.
  • Added UiDevice#pressKeyCodes to support pressing multiple keys simultaneously, e.g. pressing POWER and VOLUME_DOWN to take a screenshot (22e525).
  • Added UiDevice#setCompressedLayoutHierarchy and deprecated UiDevice#setCompressedLayoutHeirarchy to fix a typo in the method name (4e2f65).
  • Marked UiAutomatorInstrumentationTestRunner as deprecated as it handles deprecated UiAutomatorTestCases and is no longer necessary (be6c85).
  • Updated delay between UiObject2 MotionEvents to twice the display refresh rate to better emulate user gestures (454450).
  • Added support for multiline text and description matching (1625e6, b/255787130).

Bug Fixes

  • Fixed StaleObjectExceptions occasionally being thrown while querying or waiting for objects (4cbcc0).
  • Fixed the return values of UiScrollable#scrollToBeginning, scrollToEnd, flingToBeginning, and flingToEnd not denoting whether the beginning/end was reached (d33e06).
  • Fixed UiScrollable#scrollForward and scrollBackward methods ignoring the configured timeout (29e4f3).
  • Fixed the BySelector copy constructor not handling depth selectors (6c7b91).
  • Fixed the handling of invalid percent values in UiObject#pinchIn and pinchOut (01b973).
  • Fixed a rare issue where multi-window support was lost if the underlying UiAutomation connection was reset (1bb956).

Version 2.3.0-alpha01

September 7, 2022

androidx.test.uiautomator:uiautomator:2.3.0-alpha01 is released. Version 2.3.0-alpha01 contains these commits.

API Changes

  • Annotated the nullness of all public methods.
  • Switched MotionEvent injection to asynchronous with a short delay for smoother UiObject2 gestures.
  • Reduced the polling interval while waiting from 1000ms to 100ms.
  • Updated UiDevice#wakeUp and UiDevice#sleep to use KEYCODE_WAKEUP and KEYCODE_SLEEP to support devices that override the power button.
  • Added UiObject2#getDisplayId and support for finding and managing objects across multiple displays.
  • Added UiObject#click and UiObject2#clickAndWait methods for clicking on a point using its coordinates.

Bug Fixes

  • Fixed an issue where the display size calculations were occasionally incorrect and might ignore portions of the screen, especially in multi-window mode (Ifc016c).
  • Fixed the scaling of screenshots in UiDevice#takeScreenshot (Id80ad6).
  • Improved the reliability of Until.scrollFinished and UiObject2#scroll (I7b0595).
  • Fixed strict mode IncorrectContextUseViolation warnings (Iffa6a0).