This Tutorial Explains How to Download, Install & Configure UIAutomator and how to use UIAutomatorViewer to inspect Element on Android Applications:
Google has provided its own Android test automation tools, and UIAutomatorviewer is one of them. If you have an idea about Selenium, then it will be easy for you to understand UIAutomator.
This tutorial will give you a detailed explanation of UIAutomator along with its installation, configuration, components, commands, sample test program, and some of the commonly asked FAQs.
Let’s Explore!!
Table of Contents:
What Is UIAutomatorViewer?
UIAutomatorViewer comes as a part of the Android SDK manager and it is a UI inspector GUI (graphical user interface) tool that helps us to inspect UI elements of an Android application.
Inspecting of an application is important as we need locators like resource IDs, class, and text of an Android application component to automate the application.
An XML screenshot of the current screen will be taken by the UIAutomatorViewer. By clicking on any element on the screen, we can get to know about the class that is used to represent, the element on the screen along with all the properties listed on the right-hand side of the tool.
The object hierarchy is the order of objects in which they are defined. For example, a class is a child of another class. It is placed at the top right portion of the tool.
Using UIAutomator you can write automation test cases for Android applications. These tests will be performed on the UI layer of the application. You can simulate each and every action that a tester does manually, for example, verifying login.
Installation
You can install this tool in two ways.
#1) Android Studio
If you work frequently with Android application testing/development, then you can install Android Studio.
It has all the Build, platform, and SDK tools. So by installing Android Studio, you will get all the tools with it. It is suggested that you go for Android Studio only if you have a good laptop/PC. Because it takes considerable RAM on your PC and needs 4-5GB of data to download and install all the requirements. But you will get everything with just one click.
#2) Command-line Tools Only
If you only need testing-related tools, then you can download only the Android SDK manager.
In this tutorial, we follow the second method as the first method is pretty much straightforward.
Open this URL and scroll down to the header Command line tools only, then click on the suitable download file link based on your machine OS. See the below screenshot for reference.
To run a program, we need to have Android SDK tools, Platform-tools, Platforms and Build tools.
- Open tools and click the platform-tools link & download the files.
- Create a folder named AndroidSDK and extract the downloaded tools and platform tools here.
- Inside tools, you will find an android.bat folder, click or run the bat file and the Android SDK Manager window will be displayed. Select the required platform version, for example, Android 25 related, and click install. You need to select platforms and build tools for the required version of the Android API.
- Accept the terms and conditions. Download and install platforms & build tools. Make sure that all the required files are under the AndroidSDK folder.
Along with Android SDK, we need a few more things to start as mentioned below.
Ant Tool:
The Apache tool will be used to compile and build written code. Using the Ant tool, we can generate a JAR file which is a Java Archive file. Using the jar file, automation suite/test cases will be executed.
=> Install Apache ant here
Eclipse IDE and Java:
We hope you must have Eclipse IDE and editor to build our code and Java installed on your PC. If not, please install the latest version of Eclipse from here
We need a language to write our automation test cases and we use Java to automate our tests.
=> Install Java here
Configuration
The next thing we need to do is add an environment variable for the SDK manager. You can use this tool without adding the environment variable as well but the problem is that you cannot use it everywhere in the system.
You will be able to access it only within the folder you installed it. So we better add environment variables for SDK to access it anywhere. Now create environment variables for Ant, Android SDK, and for Java. Add all of them to the path variable.
To do that, navigate to System -> Advanced System settings -> Advanced tab -> Environment variables -> Click New in the System variables section. This navigation may differ from system to system.
Example system variable for paths:
ANDROID_HOME : F:\Workspace\SDK
ANT_HOME : C:\apache-ant-1.10.5
JAVA_HOME: C:\Program Files\Java\jdk1.8.0_111
Now add all these system variables to the path as shown in the below example.
%ANDROID_HOME%;%ANT_HOME%;%JAVA_HOME%
Hit the Apply button and then the OK button.
Now we have all the setup ready.
Before starting our code, we first need to make sure that the Android device is ready to run tests on it. For that, we need to enable the Developer options if not enabled yet.
Enabling the Developer options in Android:
- Open phone settings and navigate to “System” and then to “About Phone” section.
- There you will find “Build number”.
- Tap on Build number Five times.
- The developer option will be enabled and you can see it in the “System”.
- Open Developer options and enable “USB debugging” and “Verify apps over USB”.
How To Inspect UI Elements On Android
Open command prompt anywhere and enter command uiautomatorviewer. Note that there are no spaces in the command and it is just a single word. If you have configured the SDK properly, then you will get a UIAutomator window opened. Otherwise please check if the installation and configuration are done properly.
Let’s see the usage of each circled element one by one.
#1) At the topmost ribbon, click on the second icon from left to right i.e the screenshot icon. In the image shown, it is marked as the one which is circled with red.
#2) You can save the current screenshot as well as the UI dump file for future purposes. Saved files can be opened using the folder icon at the top.
#3) This section contains all the information related to UI hierarchy. You can search using the search box provided. Expand/collapse the hierarchy. Traverse between the objects using the up and down arrows.
#4) “Node details” is the place where we get information about a UI element.
It shows all the necessary information about the element like its accessibility, visibility, and different locators like class name, text, resource id, content-description, etc. Using which we need to access the element in automation.
After that, the screen will look as shown below.
Click on the Google search box on the device and again take a screenshot using the UIAutomatorViewer.
On PC click on the displayed UI components and observe. The tool detects the component you select and it shows the component details. The selected UI component will be highlighted with a red-colored box on the left side of the screen.
Sample Test Program
Creating a Test project and class in Eclipse:
Open Eclipse IDE on your PC and click on File -> New -> Java Project. A project creation window will be opened, enter the project name for example “UiAutomator_Demo”. Leave all the default settings as it is and click the finish button two times. Now your project has been created.
The created project will be displayed on the left side of the IDE. Right-click on the project name where you need to select New -> Class and on the window opened to enter the class name, for example, DemoTest, and hit the finish button.
Adding Jars To The Project
We should add all the libraries that we use while automating tests.
#1) Right-click on the project name in Eclipse and then select “Properties”.
#2) A new window with properties will be shown, select “Java build path”.
#3) Click the Libraries menu and click on the “Add external jars” button.
#4) The File Manager window will be opened. Navigate to the folder where you have SDK installed. Select android.jar and uiautomator.jar and then hit the apply button and close the additional window.
In this test, we will perform a small operation in the Google search to see if the results are displayed as per our search query.
Below are the steps involved to perform the steps:
- Click on the Google search box.
- Enter a search query, for example, Software Testing Help
- Press the enter button and check if the results contain the Software Testing Help website link
So these are the steps that we perform manually.
Let’s automate the same.
package com.android.uiautomation;
import com.android.uiautomator.core.UiDevice;
import com.android.uiautomator.core.UiObject;
import com.android.uiautomator.core.UiSelector;
import com.android.uiautomator.core.UiObjectNotFoundException;
import com.android.uiautomator.testrunner.UiAutomatorTestCase;
public class DemoTest extends UiAutomatorTestCase{
public void testApps() throws UiObjectNotFoundException, InterruptedException {
getUiDevice().pressHome();
//Step1
UiObject searchBox = new UiObject(new UiSelector().resourceId
("com.google.android.googlequicksearchbox:id/search_edit_frame"));
searchBox.clickAndWaitForNewWindow();
//step2
UiObject searchBar = new UiObject(new UiSelector().resourceId
("com.google.android.googlequicksearchbox:id/search_box"));
searchBar.setText("SoftwareTestingHelp");
//step3
UiDevice device = getUiDevice();
device.pressEnter();
Thread.sleep(3000);
//step4
UiObject results = new UiObject(new UiSelector().textContains("Software Testing Help"));
//step5
if(results.exists()){
System.out.println("Passed: Result has been shown for software testing help");
}
else{
System.out.println("Failed: Result were not shown for software testing help");
}
getUiDevice().pressHome();
}
}
Let’s explore the above code snippet.
We have imported all the required modules to our program.
Step 1: Storing the resource id of the Google search box in a UiObject and performing the click Operation.
Step 2: Entering the text in the search box and hitting enter
Step 3: Verify if the search results contain the Software Testing Help website. Print the “Passed” message to the console if the desired text exists, else print the “Failed” message.
List Of Commands
#1) Create a Test project
Android create uitest-project –t <android target version> -p <path where your test source code is present> -n <name of the project>
This command creates a build.xml file that will be further used for Jar generation.
-t parameter takes the Android version as a parameter. You need to specify which version of Android you are targeting to test. Example: android-25 i.e. we are targeting the Android 7 version.
-p parameter is where you need to mention your path for the project. Example: D:\Workspace\UiAutomator_Demo
-n is the name of the project Example: UiAutomator_Demo
#2) Build your source code
As mentioned earlier, we would use Apache ant as a build tool to compile our source code and to generate an executable JAR file.
Ant build
If there is no error at the compilation time, a message will be shown on the console “Build is successful”.
Then you can find the executable jar file in the bin folder of your project with the name specified at the time of executing the first command. If there are any issues in your code, then the errors will be shown on the console and the JAR file will not be generated.
#3) Pushing generated JAR file to the device
Adb push <jar file> /data/local/tmp/
Example: adb push D:\Workspace\UiAutomator_Demo\bin\ UiAutomator_Demo.jar /data/local/tmp/
As the UiAutomator tests run based on the JAR file pushed to the device, we need to first push our jar file to the device. For this, we will use adb push command.
This command takes two parameters – one is the file that is to be pushed to the Android device and the other is the destination path.
The second argument for this command is the destination path where our file should be pushed. In our case it should be /data/local/tmp/
#4) Run the Test
Now, we have everything ready. The only thing pending is to execute our test.
Adb shell uiautomator runtest <jar name> –c <class qualified name of the test class>
Example: adb shell uiautomator runtest UiAutomator_Demo.jar –c com.android.uiautomation.DemoTest
If you do not know how to get the class qualified name, then follow the below process:
In your Eclipse, click on the dropdown of your project and drill down to the class where your test code is present. Here the class is DemoTest. Right-click on the class name. A window will be opened, click on the “copy qualified name”.
As soon as you hit this command in the command prompt, the test will start executing and you can now see the test being performed on the device.
FAQs
Q #1) Is path setting for SDK mandatory?
Answer: No, but it is advisable to set the path, because if you do not set the path of SDK in environment variables, then you can only access files in the location where it is installed.
So, to access your SDK anywhere you need to set the path. Not only for SDK, but it is also advisable to follow the same for Java and ant.
Q #2) Why UIAutomatorViewer is showing an error while taking a screenshot?
Answer:
There are 3 possible reasons for it:
#1) Adb has not recognized your device and you need to update the device driver software. You can search online for them and install them, for example if you are working with an LG device, then you can search for LG adb drivers.
#2) Your device is not in an idle state: For the screen which is not static, like the video is playing or any animation is being displayed uiautomatorviewer cannot take a screenshot in these cases. So ensure that your device screen is not displaying any videos/animation at the time of taking a screenshot.
#3) Android version mismatch: Make sure that your SDK api version is higher or equal to the device’s Android version api level. If not you can update the SDK by clicking android.bat file or through the SDK manager.
Q #3) Is there any official documentation for the UIAutomatorViewer?
Answer: Yes, Google has provided documentation for UIAutomatorViewer. Not though fully covered on all topics, but can get an idea about this tool.
Q #4) Why adb devices command does not show any devices?
Answer: Check if the developer options are enabled on your device. To enable the Developers option on Android devices, follow the below process. Go to the device settings and About the phone. Tap on 5 times on the build number. A toast message “You’re a developer now” will be shown and the Developer settings option will be added.
Q #5) Why is Adb still not recognizing my device?
Answer: There might be a driver issue. You need to update the driver which helps to detect the device.
Follow the below steps to update the driver.
#1) Open your System and open device manager; you can get this setting upon right-clicking the Start button.
#2) Open Device Manager, there you can find your device name on Android devices/ portable devices.
#3) Right-click on the device name and select Update drivers.
#4) Click on Browse my computer for driver software option and click on let me pick from a list of device drivers on my computer.
#5) Select any one of the suitable drivers to install and hit the next button. If the device driver is successfully installed, a message will be shown below.
#6) As these are hardware changes applied to your system, you may need to restart the system if prompted to do so.
#7) If you feel that the device is not recognized, then you can first change the mode connection. These modes are displayed on the device when you connect your device to the system.
Example: Transfer files, Transfer photos, MIDI1.
Q #6) Can I see each and every UI component detail of an Android application?
Answer: You can see almost all the UI components’ detail in the UIAutomatorViewer. If any UI/Layout uses other than the defaults provided by android, then those can’t be viewed in the UIAutomatorViewer tool.
You can ask your developer to put any identifier in the UI element to automate the feature. For example, putting a resource id, content description, etc.
Q #7) Does the Appium tool use UIAutomator tool in it?
Answer: Yes.
Q #8) Does this tool support any other devices like Windows/ iOS than Android?
Answer: No, this is developed by Google and supports only Android devices.
Q #9) What is UIautomator Android?
Answer: UIAutomator is a tool/framework that helps to automate Android application test cases.
Q #10) How do you Setup UIAutomator?
Answer: Please refer Installation section of this tutorial for a detailed explanation.
Q #11) What is UIAutomator in Appium?
Answer: UiAutomator is a testing framework/tool provided by Android for automating Android application testing, Appium internally uses it internally.
Q #12) How do you inspect an element in UIAutomator?
Answer: Once you are done with the setup, open a command prompt, and enter the command UIAutomatorViewer. A window will be displayed on your PC. Connect the mobile to a PC and click on the Device screenshot (uiautomator dump) second icon at the top.
After that device, the current screen will be displayed on the inspector window. Click on any one of the elements to get info about that element. For a detailed explanation refer Inspect required UI element section.
Conclusion
To summarize,
- UIAutomatorViewer is a graphical user interface tool to inspect the UI layer of any application.
- You need to know the structure of the UI of an application under test so that it will be easier to automate the user interaction in the UI layer of the application
- UIAutomator uses an XML snapshot and screenshot. You can know the layout hierarchy.
- For automating the UI tests of android applications, you need to first identify some locators to perform an interaction with the app Example: Class name, resource id, text.
- Adb is a part of SDK which is called Android Debug Bridge.
- You can open the UIAutomatorViewer by entering the command uiautomatorviewer in the command line.
- As this tool is free of cost, it can be used by anyone and it is reliable.
Happy Reading!!