Have you ever developed an Android application and publish it to Google Play? What will you do if you get a user review like -

When you publish an app to Google play, it must be well tested to avoid the potential bugs. There's a ton of test scenarios that should be executed before publishing an app. To save the testing effort, you need a testing tool. One of the best testing tool for Android app is Selendroid.

What is the Selendroid?

Selendroid is a test automation framework for multi type of mobile application: native and hybrid android app and mobile web.


You can write the tests using the Selenium 2 client APIs. Because Selendroid still reuses of the existing Selenium infrastructure for the web
Selendroid is a powerful testing tool. It can be used on emulators and real devices

Why do we need Selendroid?

Selendroid is a great testing tool. But you may still doubt its usefulness.
This section will introduce the important feautures of the Selendroid to answer the question why you need Selendroid.
  • You can test the application under test using Selendroid without any modification of the app. You just need the binary file (APK) installed on the computer. In order to install the binary file on the device, the test app and mobile app must be signed with same sign key
  • Selendroid test app can interact with multiple devices or simulators simultaneously. It's a great advantage of Selendroid. So you can test your app with various android devices to check compatibility.
  • Selendroid can simulate human-user actions on an app, such as touch, swipe, drag and drop on devices
  • You can change the hardware devices (Plug and unplug) during the testing without restarting or stopping the test. Selendroid recognizes the new devices automatically
  • Corresponding to the Android API version up, Selendroid also supports the new Android API (From API 10 to API 19)
  • Selendroid also has some built in inspector tool to help you identify the UI element of application under test. For example the ID of button, text field, text view…

Selendroid architecture

Selendroid is based on the Android instrumentation framework. Selendroid tests are written base on the Selenium Web driver client API, so it support full integration with current Selenium frameworks.
The folllowing figure describe the architecture of Selendroid

Selendroid contains 4 major components:
  • Web Driver Client – The Java client library based on Selenium. This library should be installed on the computer (which is used to develop the test cases)
  • Selendroid-Server – The server which runs be in the app under test on Android device or simulator. This is the main components of Selendroid architecture
  • Android Driver-App - A built in Android driver, Web View app to test the mobile web.
  • Selendroid-Standalone – This component is used to install the Selendroid server and the application under test (AUT)

Getting started with Selendroid

You already known the importance of the Selendroid. Now let's get our hands dirty with Selendroid.
There're 3 steps should be done before first test with Selendroid

Setting up Selendroid environment

Selendroid can work on Window, Linux and Mac OS. In this tutorial, I will setup Selendroid in Linux OS.
Before using Selendroid, you need install following package first

How to launch Selendroid

Step 1) Getting an application under test
You can use existing Selendroid test app to check that how Selendroid works (Link to sample application under test)
Once download is complete, copy this APK and the above Selendroid Standalone jar file to a folder with name "Guru99"
Step 2) Launch the Selendroid
Open the terminal on Windows & navigate to the folder Guru99 created in step 1.
Run the following command
The output will display as following


After running this command, Selendroid-standalone http server starts! The default port number of this server is 4444. All hardware device as well as Android Virtual Device will be scanned and recognized automatically. Selendroid will identify the Android target version and device screen size.
To check the Android target version as well as the device information, you can launch following URL on browser:

Selendroid basic command

This section introduce you some basic Selendroid-Standalone command line. You may use them to setup the Selendroid testing environment
  1. Setting port of Selendroid

    The default port of Selendroid is 4444. But you can change to other port by adding parameter to the command to launch Selendroid
    Parameter: -port [port number]
    For example:
    In above command, 5555 is the new port.
    So the URL to check the Android target version is changed to: http://localhost:5555/wd/hub/status
  1. Specify the location of the application under test (Binary APK file). Selendroid often required the absolute path for this file
    Parameter: -app [file path]
    For example:

    In above command, the Selendroid automatically find the binary file base on the "C:\Guru99App.apk" to get the information of the application under test.
    Check the URL http://localhost:4444/wd/hub/status, you will see this information

  2. Change the port the Selendroid uses to communicate with instrumentation server. Selendroid uses the port 8080 as the default
    Parameter: -selendroidServerPort [port number]
    Example
    The port now is changed to 9000
  3. Change the timeout to start emulators. The unit is milliseconds.
    Parameter: -timeoutEmulatorStart
    By default Selendroid will wait 300,000 milliseconds until the emulator starts. You can change to new timeout (200,000 ms) by command
    After this time our expired, if the emulator cannot start, the Selendroid will throw the exception error (Error occurred while looking for devices/emulators.) then stop running
  4. When you start the Selendroid command on terminal, you will see a log printed out on the screen. You can change the type of log you see by adding following parameter
    Parameter: -logLevel [type of log]
    The log level values are: ERROR, WARNING, INFO, DEBUG and VERBOSE. Default: ERROR.
    For example, set Selendroid to print the WARNING log only, you can use this command
    The Selendroid only print the WARNING log

Start your first test with Selendroid

This section is a step by step guide to create your first test script using Selendroid
Suppose we have an Android application under test name Guru99App. The application include a text field and a button name "Show Text".
DOWNLOAD THE APK HERE
We need execute following test case using Selendroid
Test Cases 
Condition 
Expected output: 
  1. Launch the application
  2. Enter a text "Guru99 Test" to the text field
  3. Press "Show Text" button
The binary of the application under test is available
Device is connected to PC 
The text "Text Show here" is change to the text
which user enter in text field

Step 1) Create a Java project in Eclipse
Step 2) Add selenium and Selendroid jar file in eclipse environments
Right click Guru99Test Project -> Build Path -> Add External Archives

Navigate to the folder which stored the jar files
There're 3 jar files should be added
  • selendroid-client-0.10.0.jar : Selendroid java client library
  • selendroid-standalone-0.11.0-with-dependencies :Selendroid standalone server library
  • selenium-java-2.40.0.jar : Selenium Web Driver library
Select all -> Choose Open to add jar file to the project

Step 3) after adding the above library, those libraries will be added to the Reference Libraries of the test project. Tester can use the APIs of those library to develop the test program
Create package "com.guru.test"and add java file "Guru99Test.java" like below
Right Click Guru99Test -> New -> Package
Type com.guru.test to the Name field on New Java Package dialog à Finish
The Eclipse will create a list folders and sub folders like this in the source code structure

Step 4) Install TestNG for Eclipse

In Eclipse, Help -> Install New Software, in the Install Dialog, click Add and enter the following
Press OK -> Next to install the TestNG
Step 5) Copy the Guru99App.apk to the folder of Test App

Step 6) Get the ID of application under test.
Suppose we have an APK file name Guru99App.apk. Follow the step which is described in previous section, execute the command on terminal
Open following link in browser
The information of device is displayed, copy the appId value "com.guru99app:1.0"
Step 7) Open the file Guru99Test.java (in sample code) and change as following
To create a new test session with Selendroid, you have to provide the app id in the format: com.guru99app:1.0. This app Id can is identified in step 6. If you don't set the app Id matching the Android device, the test session will throw error and will not start.
After initializing the found device, Selendroid creates a customized selendroid-server and installs the Selendroid server on it
Selendroid also installs the application under test and starts the selendroid-server on device
After initzalizing the test session succesfully, the test command is started executing on device. (Such as enter text, press button…). If the test app ends the test session, the emulator will stop automatically
Step 8) Start the new test session
Launch the Selendroid server using following command on terminal like step 6
After the Selendroid Server started, open the sample test project Guru99test on Eclipse, set a breakpoint at line 77 on file Guru99Test.java by double click to the line 77 -> A dot will display like below
Start a test session by right Click to Guru99Test project -> Debug As -> TestNg Test.
A test session will start like below
Step 9) Get the Id of GUI element of application under test
After test session start successfully, open browser, navigate to the URL http://localhost:4444/inspector
You will see the Application Under Test is launched like below
Use mouse hover to each UI element of AUT (Button, TextField, Text Label), the ID of each element will hightlight on the right pane
After this step, you can get the ID of each above UI element
  • Button Show Text ID : "btnShow"
  • Text Field ID: "edtText"
  • Label Text ID: "txtView"
Those IDs will be used in next step
Step 10) Enter the test program like below
A test program using Selendroid includes 3 sections
Setup Test:
Following is the code for setup test, it will set up the condition for a test session.In case of an error, the Selendroid will throw the exception and the test app will stop.
The code include the commments to explain each the statement.
?
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
package com.guru.test;
         
 import io.selendroid.SelendroidCapabilities;
        import io.selendroid.SelendroidConfiguration;
        import io.selendroid.SelendroidDriver;
        import io.selendroid.SelendroidLauncher;
        import io.selendroid.device.DeviceTargetPlatform;
         
        import org.openqa.selenium.By;
        import org.openqa.selenium.WebDriver;
        import org.openqa.selenium.WebElement;
        import org.testng.Assert;
        import org.testng.annotations.AfterSuite;
        import org.testng.annotations.BeforeSuite;
        import org.testng.annotations.Test;
         
 /**
         * @author Guru99 Test App using Selendroid
             * Application under test: Guru99App
         *
         */
        public
                class Guru99Test {
                 
                     //Declare web driver variable
            private WebDriver driver;
                        
    
            /**
             * Setup the environment before testing
             * @throws Exception
                 */
            @BeforeSuite
            public
                    void setUp() throws Exception {
                             
        //Start selendroid-standalone during test
                SelendroidConfiguration config = new SelendroidConfiguration();
                     
              // Add the selendroid-test-app to the standalone server
                config.addSupportedApp("Guru99App.apk");
                     
                  
                //start the standalone server
                SelendroidLauncher selendroidServer = new SelendroidLauncher(config);
                    selendroidServer.launchSelendroid();
                 
               // Create the selendroid capabilities
                SelendroidCapabilities capa = new SelendroidCapabilities();
                     
         
               // Specify to use selendroid's test app
                capa.setAut("com.guru99app:1.0");
                    
               // Specify to use the Android device API 19
                capa.setPlatformVersion(DeviceTargetPlatform.ANDROID19);
                     
                // Don't request simulator, use real device
                capa.setEmulator(false);
                     
          
                //capa.wait(10000000);
                 
                // Create instance of Selendroid Driver
                driver = new SelendroidDriver(capa);
                            
            }
        
Execute Test
Below is the code to execute a test. The code includes the commments
Here are the test steps again
  1. Enter the text "Hello Guru""
  2. Click Show Text Button
  3. Wait a while
  4. Verify that the app display the text as user enter to text field (Ex. Display the text "Hello Guru")
?
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
 /**
             * Start execute the test case
             * 01. Enter the text "Selendroid" to the textfield
             * 02. Press OK button
             * @throws Exception
                 */
            @Test
            public
                    void selendroidTest() throws Exception {
                                     
                // Print the log
                System.out.print("Start executing test");
                             
                // Find the input text field on screen
        // The id of this text field was get from step 9
                WebElement inputField = driver.findElement(By.id("edtText"));
                             
                // Verify that the text field enabled so user can enter text
                Assert.assertEquals("true", inputField.getAttribute("enabled"));
                             
                // Enter a text to text field
                inputField.sendKeys("Hello Guru");        
             
         // click Show Text button
        // The id of this button was get from step 9
                WebElement button = driver.findElement(By.id("btnShow"));
                            button.click();
                 
                // Delay time to take effect
                Thread.sleep(5000);
                 
                //Find the label "Text Show Here" on screen
        // The id of this label was get from step 9
                WebElement txtView = driver.findElement(By.id("txtView"));
                             
                //Get the text display on screen
                String expected = txtView.getText();
                 
        // Verify that the text which user enter on text field is same as text display on screen
                Assert.assertEquals(expected, inputField.getText());        
         
     }

Finish Test
Following code will complete the test by stopping the Selendroid driver.
?
1
2
3
4
5
6
7
8
9
 /**
             * Stop the Selendroid driver
             *
             */
            @AfterSuite
            public
                    void tearDown() {
                            driver.quit();
                }
You can see the detail in sample code included in this article.

Step 10) Connect Android device to the PC via USB cable. Points to observe -
  • Please make sure the device has no screen lock configured.
  • Devices must be plugged in via USB to the computer that the selendroid-standalone component is running on.
  • The device should install at least Android Target Version API 10
Step 11) Run the Test App: Right click Guru99test -> Run as -> TestNG test

Step 10) The Script start executed as following
Step 12) After test finishes execution, TestNG auto generates the test report as following
Good Job, you are done the test now.
Summary

Summary

  • Selendroid is a very powerful tool for testing Android native app, hybrid app as well as the web app.
  • It can be used on real devices as well as the simulator.
  • It also allows you to run tests in parallel by running test on multi devices.
  • The entire Selendroid suite is comprised of four components:
    • Web Driver client,
    • Selendroid-Server,
    • Android Driver App
    • Selendroid-stand alone
  • To use Selendroid you need Java JDK, Android SDK and Eclipse installed.

Setup and execute Test on Emulator

  • Change capa.setEmulator(false); to capa.setEmulator(true);
  • Use selendroid-standalone-0.15.0-with-dependencies.jar file instead of selendroid-standalone-0.11.0-with-dependencies.jar
  • Assure that the .apk file is deployed on emulator.