Currently as a QA Engineer , I have been spending most of the time at work writing automation scripts for Android apps rather than manual testing. I have already written automation scripts for three android mobile apps for my company.

I never really thought that this would be easy . Google has provided a tool named ‘UI Automator’ for executing Automation scripts for Android in a pretty simple manner. It comes under UI Testing. UI testing ensures that the app returns the correct UI output in response to a user actions on a device, say keyboard input or pressing toolbars, menus, dialogs, images, and other UI controls. It reduces a lot of manual testing job and saves a lot of time.


Android SDK provides with uiautomator , a java library to automate and run the tests. Along with this , it also provides a GUI tool called uiautomatorviewer to inspect the layout hierarchy and view the properties of the individual UI components on your test device.

‘uiautomatorviewer’ Overview –

[1] ‘uiautomatorviewer’ tool can be used to take a snapshot of the foreground UI screen on any Android device which is connected to your machine.

[2] Make sure ‘USB Debugging’ is ‘ON’ when using uiautomatorviewer. For that : Go to ‘Settings’ on your device -> ‘Developer Options’ -> check ‘USB debugging’ option.



[3] Keep your Android SDK updated to latest version. Open Eclipse -> Go to ‘Window’ in toolbar -> ‘Android SDK Manager’. It will display the updates there. Install all packages and keep it up-to-date.


[4] To take screen shot of foreground UI screen :

  • Connect your device to your development machine.
  • Open command prompt.
  • ‘uiautomatorviewer’ is a batch file which exists inside ‘tools’ folder of ‘sdk’. So you can go to your ‘tools folder inside ‘sdk’ in command prompt and type ‘uiautomatorviewer’ there :


or directly click on that batch file from your tools folder and use.

  • One empty window will open :



[5] Hover on the second ‘green’ button on the top. It shows ‘Device Screenshot’. Click    on it and you will get UI screen of what ever is open on your device :



Accessing  elements  through  uiautomatorviewer

[1] Say , we open ‘Clock’ app in any Android device. So that screenshot would appear like :



[2] Hover on the screenshot to view elements hierarchy. As you keep hovering over        the elements on the screenshot -> you will observe that the ‘Node Detail’ (at right bottom) and the hierarchy (right top) keeps changing.

[3] Say , now I want to access the current date on clock app. So for that , I hover on the date :


[4] For reference , I have marked some element properties with red as shown in above screenshot. So from that , we get to know that :

Today’s date has :

  • resource id  :
  • text : Wed , April 23
  • content-desc : Wednesday , April 23
  • index : 0
  • class : android.widget.TextView
  • package :
  • enabled : true
  • other properties : false


We will create a demo script which shows how to access time on clock.


Frequently  used  Classes  in  UI Automator

Some most common frequently used classes in UI Automator are :

[1] UiDevice :

Provides access to device state , serving purpose like  :

i) ‘Home’ button press :


ii) Click on something using (x,y) coordinates : x , int y);

iii) ‘Back’ button press :


Full details can be found here for this class here.

[2] UiSelector :

Used to mention search criteria for an element , refining elements based on text , content-desc , class etc. If more than one matching element is found : it returns the first matching element in the hierarchy. If no matching element is found : ‘UiAutomatorObjectNotFoundException’ is thrown. ‘childSelector()’ method ca be used here for nested UiSelector instances.

Some examples to access elements through :

i) text :

new UiObject(new UiSelector().text("abcd");

ii) resource-id:

new UiObject(new UiSelector().resourceId("com.example.abcd");

iii) Nested : Find the first ListView in the currently displayed UI, then search within that ListView to find a UI element with the text property Apps :

UiObject appItem = new UiObject(new UiSelector().className("android.widget.ListView").
instance(1) .childSelector(new UiSelector().text("Apps")));

Full details can be found here for this class here.

[3] UiObject :

Represents a UI element. UiSelector is used to create a UiObject instance showing how to search for element.

Instances can be created as :

UiObject yes_button = new UiObject(new UiSelector().text("YES");
//searching for button on screen
if (yes_button.exists()) {;


UiObject instances can be reused in code.

Full details can be found here for this class here.

[4] UiScrollable :

Can be used for horizontal/vertical scroll on screen. Can be useful when you need to swipe on screen to bring any specific element into view.

Example : how to simulate scrolling down the Settings menu and clicking on an ‘About phone’ option:

UiScrollable settings = new UiScrollable(new UiSelector() .

UiObject about = settingsItem.getChildByText(new UiSelector() .
className("android.widget.LinearLayout"), "About phone");;


Full details can be found here for this class here.


Executing  Basic  Script –

FIRST  STEP : Creating  a  new  project

[1] Create a new java project in Eclipse :

  • Go to ‘File’ -> ‘New’ -> ‘Java Project’




[2] Add project name and click ‘Next’ –



[3] Click ‘Finish’ –



[4] Expand your project. Right click on src folder -> ‘New’ -> ‘Class’ –



[5] Enter ‘Name’ for class. Also mention ‘Package’ and then click ‘Finish’ –



[6] You will see something like –


SECOND  STEP : Adding  required  jar  files

[1] We need to add uiautomator and android jar files along with JUnit library. For that :

  • Right click on your project -> open ‘Properties’.
  • Go to ‘Java Build Path’ from left menu.
  • Open ‘Libraries’ section –



[2] Click on ‘Add External JARs’ . Navigate to your platforms folder inside sdk say like ‘../android-sdk/platforms’ . Select your highest platform here say platform-19 : you will find uiautomator.jar and android.jar. Just select both and add them –


[3] Now click -> ‘Add Library’ -> select JUnit –


[4] Click ‘Next’ -> then ‘Finish’. Then ‘Ok’. You will see that the jar files and JUnit are added to your project –




THIRD  STEP : Writing  script

Now we will be writing basic script say to view current date and time on clock app –

package com.smriti.firsttest;


public class FirstTestCases extends UiAutomatorTestCase {

  public void testDemo() throws UiObjectNotFoundException,
      InterruptedException {

    // Simulate a short press on the HOME button.

    // simulate click on All Apps screen.
    // All Apps button’s content-description property has the value “Apps”
    UiObject allAppsButton = new UiObject(
        new UiSelector().description("Apps"));

    // Simulate a click to bring up the All Apps screen.

    // Simulate click on 'Apps' section
    UiObject appsTab = new UiObject(new UiSelector().text("Apps"));

    // Simulate a click to enter the Apps tab.;

    // Simulate a user swiping until they come to the Clock app icon
    UiScrollable appViews = new UiScrollable(
        new UiSelector().scrollable(true));

    // Set the swiping mode to horizontal - default is vertical

    // Create a UiSelector to find the Clock app and simulate
    // a user click to launch the app.
    UiObject clock_app = appViews.getChildByText(new UiSelector()
        .className(android.widget.TextView.class.getName()), "Clock");

    // Validate that the package name is the expected one
    UiObject clock_validation = new UiObject(
        new UiSelector().packageName(""));
    assertTrue("Unable to detect Clock App", clock_validation.exists());
    System.out.println("Clock App launched");

    // adding 5sec delay after app is launched

    // get current time
    UiObject time = new UiObject(
        new UiSelector().resourceId(""));
    String current_time = time.getContentDescription();
    System.out.println("Current Time : " + current_time);

    // get current date
    UiObject date = new UiObject(
        new UiSelector().resourceId(""));
    String todays_date = date.getText();
    System.out.println("Today's Date : " + todays_date);



FOURTH  STEP : Building  and  Deploying  test

Once you have written your test script , you need to build and deploy your JAR. We can mention all the steps in one batch file and just execute that.

  • Open a text file and write the following steps :
    Echo build output jar file
    call android.bat create uitest-project -n FirstTest -t 13 -p
    Echo set home variable
    set ANDROID_HOME=D:\Android Development\android-sdk
    Echo navigating to project directory where build.xml file is located
    cd D:\Android_Workspace1\FirstTest
    Echo build test JAR
    call ant build
    Echo navigating to platform-tools directory
    cd D:\Android Development\android-sdk\platform-tools
    Echo deploying generated test JAR file to device
    adb push D:\Android_Workspace1\FirstTest\bin\FirstTest.jar /data/local/tmp/
    Echo running script
    adb shell uiautomator runtest FirstTest.jar -c com.smriti.firsttest.FirstTestCases
    Echo Test Complete


  • Save text file as “.bat” extension inside your sdk tools folder.
  • Open cmd now and navigate to your tools folder : run_batch_file
  • Write your batch file name and press ‘Enter’.
  • Script will start and finally output will appear :output

This is how anyone can run a sample script.

It didn’t seem so easy at first but now I am comfortable writing automation scripts for Android and I keep sending automated emails to my team members whenever I run my script on any app builds 🙂

Share if you like : Share on Facebook
Tweet about this on Twitter
Share on LinkedIn

30 comments on “Android Mobile Apps Automation using UI Automator

  • the best UI Automator tutorial on earth !!
    it took me 1 week to study this !
    u rock !!
    keep on posting test automation stuff 😀
    can you plz post how to use appium in android 🙂

    • You can try either by resource id like –
      new UiObject(new UiSelector().resourceId(""));

      or by index as well say –
      new UiObject(new UiSelector().className("android.widget.ImageButton").index(0));

      Note – “resourceId” is supported only from API 18.

  • Hi…

    I am trying to use java script scroll command to scroll the page while automating android mobile native application to scroll the window dowm .But I am Getting error message :
    org.openqa.selenium.WebDriverException: Not yet implemented. Please help us:

    Can you please tell me how to scroll down in Android mobile native application using Appium and Selenium Webdriver command.

    • Can try this out –
      JavascriptExecutor js = (JavascriptExecutor)driver;
      HashMap flickObject = new HashMap();
      flickObject.put("endX", 0);
      flickObject.put("endY", 0);
      flickObject.put("touchCount", 1);
      js.executeScript("mobile: flick", flickObject);

  • Hi Smriti,
    Can you please tell me how to access particular image inside Gallery. Is it there any way to access without coordinates.


  • I want to click on USB computer connection in settings->Storage->click on 3 vertical dots using UI automator.

    I am able to enter in to storage app and unable to click on 3 vertical dots.
    Please let me know if you any idea…Thanks in Advance

      • Hi, Can you please tell me how to take test the messaging app in android mobile. i need to verify all the keys(a,b,c,etc) from keyboard.i tried with uiautomator and appium but not able to take properties of all the keywords.

        • You should try keycodes here.

          So say to tap on alphabet “h” from keyboard, I shall use it like –

          as it’s given as
          Key code constant: ‘H’ key.
          Constant Value: 36 (0x00000024)

  • Thanks for this article! Can you please clarify the below issue:
    I am trying to access a child view using UIAutomator with the below code.

    UiObject appItem = new UiObject(new UiSelector().className(“android.widget.ListView”).index(3).childSelector(new UiSelector().description(“main”)));;

    When run my code, it is not clicking on desired item in my webapp. Getting the below error message:

    Exception in thread “main” java.lang.RuntimeException: Stub!

    Thanks in advance!

  • Smriti,
    Am getting error like this
    [javac] D:\Testing_Work\MonkeyTalkProject\AndroidSource\UiAutomatorClock\src\com\test\clock\ error: cannot find symbol
    [javac] new UiSelector().resourceId(“”));
    [javac] ^
    [javac] symbol: method resourceId(String)
    [javac] location: class UiSelector
    [javac] D:\Testing_Work\MonkeyTalkProject\AndroidSource\UiAutomatorClock\src\com\test\clock\ error: cannot find symbol
    [javac] new UiSelector().resourceId(“”));
    [javac] ^
    [javac] symbol: method resourceId(String)
    [javac] location: class UiSelector

    • Can you post your code here.
      Possible causes of “error: cannot find symbol” should be either of the following –
      – trying to use a variable without declaring it.
      – a class or method name is misspelled.
      – parameters used do not match a method’s signature.
      – packaged class is not referenced correctly.

  • Thanks a lot smriti..I am using android LG phone..UI looks very different
    I was trying to click on some app(hip chat) but didnt work for me… Following is the steps to go to hip chat app on my device
    1:When i open the phone ,it shows me first screen
    2:Then i have to swipe right side(horizontally) to get the second screen
    3:In second screen i have “All apps” icon
    4:Clicking on all apps icon ,brings up all apps
    5.last step is clicking on hip chat app

    • Hey

      You can use as follows –

      UiScrollable appViews = new UiScrollable(new UiSelector().scrollable(true));

      public void testDemo() throws UiObjectNotFoundException, RemoteException {

      //swipe right to second screen

      //all apps click
      UiObject appsTab = new UiObject(new UiSelector().text("Apps"));;

      //search and click on app
      int maxSearchSwipes = 6;
      for (int i = 0; i < maxSearchSwipes; i++) { try { selector = new UiSelector().className(android.widget.TextView.class .getName()); appToLaunch = appViews.getChildByText(selector, "HipChat"); if (appToLaunch != null) { appToLaunch.clickAndWaitForNewWindow(); sleep(5000); break; } } catch (UiObjectNotFoundException e) { System.out.println("Did not find match for " + e.getLocalizedMessage()); } for (int j = 0; j < i; j++) { appViews.scrollForward(); System.out.println("Scrolling forward through apps"); } if (i == maxSearchSwipes) { System.out.println("App not found - launch failed"); System.exit(0); } }

      This would first swipe the screen to go to 'All Apps' -> then tap on it and then search your app from all apps in the phone and keep scrolling till it finds the app required and when app finally found - taps on it otherwise prints error - "App not found - launch failed".

  • Hi,
    i am unable to use the uiautomator jar in android studio. can u please help. I am new to android framework as I worked in C++


  • Thanks Smirti.
    How do i click on Imagebutton if Imagebutton doesnt have any text or description or id?I heard that we can use bounds but not sure how exactly i can use it..please provide me some example.

    • You can use (x,y) coordinates of the bounds and click on the required ImageButton.
      One example can be :

      int x = (new UiObject(new UiSelector().className("android.widget.ImageView")).getBounds().centerX();
      int y = (new UiObject(new UiSelector().className("android.widget.ImageView")).getBounds().centerY();

  • Hi smriti, please help me on below error.

    UiObject btnSignout = new UiObject(new UiSelector().description(“Sign Out”));;
    UiDevice getUiDevice = UiDevice.getInstance();

    java.lang.RuntimeException: Stub! at

  • Hi smriti,

    Excellent job. Thanks a lot for the information, It will help so many people who are new to this like me.
    Hope will get so many posts like this in future to help people like me.

    Thanks & Regards,

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.