Appium mobile test automation

Appium mobile test automation for Google Android and Apple ios Last updated: 10 July 2017 Pepgo Limited, 71-75 Shelton Street, Covent Garden, London, WC2H 9JQ, United Kingdom

Contents About this document... 3 Appium... 3 Architecture... 3 Enable developer options on an Android device:... 4 Install Android Studio and SDK (in Microsoft Windows)... 5 Install Appium:... 5 Run Appium (example)... 5 Create an Android Virtual Device... 7 Installing an app on a Virtual Device... 8 Finding element properties... 9 Using UI Automator Viewer... 9 Using Appium Inspector... 10 Remote debugging Android hybrid applications with Google Chrome... 10 A full Appium Java example... 10 What the PasswdSafe example does... 11 Using the PasswdSafe example... 11 The pom.xml file... 12 The AppiumTest.java file... 13 The AndroidSetup.java file... 14 The LandingPage.java file... 14 The BasePage.java file... 15

About this document This document explains the test automation tool Appium for mobile devices. Appium is powered by Selenium WebDriver, and the same Appium program code can be used for automating both Google Android and Apple ios platforms. This document contains Java samples developed on the Microsoft Windows operating system for Google Android as target platform. The samples in this document use an Android native app, but they can easily be adapted to Android hybrid applications, or Android mobile web applications. The examples can also easily be adapted for development on the Apple macos operating system, targeting the Apple ios mobile platform for mobile devices such as the Apple iphone. Appium Appium is an open source test automation tool for mobile applications. It allows you to test all the three types of mobile applications: native, hybrid and mobile web. It also allows you to run the automated tests on actual devices, emulators and simulators. Today when almost every mobile app is available for at least two platforms (ios and Android), you need a tool, which allows testing cross platforms. Having two different frameworks for the same app would increase the cost of testing and time to maintain it as well. The basic philosophy of Appium is that you should be able to reuse code between ios and Android, and that s why the API s are the same across ios and Android. Another important thing to highlight is that unlike Calabash, Appium doesn t modify your app or need you to even recompile the app, or have access to its source code. Appium lets you choose the language you want to write your test in. It doesn t dictate the language or framework to be used. Architecture When you download Appium, you are basically downloading the server. The server is written in Node.js and implements Selenium WebDriver. It allows you to use Selenium WebDriver clients to drive your tests. Your mobile app acts precisely like a web app, where the DOM is represented by the View hierarchy. So this server basically exposes a REST API, which performs the following actions: 1. Receives connection from client 2. Listen command 3. Execute command 4. Respond back the command execution status

In terms of an architecture diagram, this is how Appium can be explained: Enable developer options on an Android device: This article contains helpful background information: http://www.greenbot.com/article/2457986/how-to-enable-developer-options-on-your-androidphone-or-tablet.html 1. On stock Android go to: Settings > About phone > Build number. 2. Once you ve found the build number section of the settings, tap on the section 7 times. After two taps, a small pop up notification should appear saying "you are now X steps away from being a developer" with a number that counts down with every additional tap. After the 7 th tap, the developer options will be unlocked and available. They can usually be found in the main settings menu. 3. Switch on "Stay awake". 4. Switch on "USB debugging". To check if the (real) device can be used, type from command prompt: "adb devices" (after you have correctly installed the Android SDK, as described in the next paragraph). In Microsoft Windows, the output should look like this: C:\>adb devices List of devices attached 00c600c600c600c6 device If the device is not recognised, then check if the USB driver is correctly installed in Microsoft Windows: http://developer.android.com/studio/run/oem-usb.html

Install Android Studio and SDK (in Microsoft Windows) Android Studio contains the Android SDK. It is recommended to install Android Studio, although you can also just install the Android SDK (the links to the SDK are provided at the bottom of the page under Get just the command line tools ). 1. Go to https://developer.android.com/studio/index.html 2. Download Android Studio 3. Confirm the license agreement 4. Launch the downloaded *.exe file 5. Follow the setup wizard to install Android Studio and the SDK Install Appium: Appium can be downloaded from http://appium.io/downloads.html Run Appium (example) The following example uses the open source Password Safe app ( https://www.pwsafe.org/ ). The app is available for free from the Google play app store. The source code, including the *.apk file for this app are available from http://sourceforge.net/projects/passwdsafe/ (just click on the Download link). The Android app file ( *.apk ) must be set in the Application Path of the Appium Android Settings. However, please note that some versions of Appium have problems with paths that contain spaces, so avoid that if possible. Newer versions of Appium will find the Package and (starting) activity automatically, but if not, then theses can also be found from command line with the command: aapt dump badging PasswdSafe.apk Note that aapt is part of the Android SDK build-tools folder (in the relevant Android SDK version subfolder). So if the command is not recognised, then you might have to add the folder to your Microsoft Windows path environment variable.

Under Device Name, you will have to set the (real or virtual) device name that you know from running the adb devices command. In the General Settings, it is recommended to tick the Pre-Launch Application option:

Once the Appium server is started, you will see some logs in the Appium screen, or alternately check this local URL for the status of the Appium server: http://localhost:4723/wd/hub/status Create an Android Virtual Device Many developers prefer working with real devices, as the Google virtual devices are notoriously slow and often painful to create and use. However, it is still often required to create and use virtual devices, particularly to cover the wide range of Android devices both with respect to device hardware and screen sizes, as well as Android versions. You first need to open the Android Virtual Device Manager. From a command prompt, you can do this with the command android avd. Then you need to create an Android Virtual Device. The ideal settings for the device depend on the host machine. Here are a few performance tips for Microsoft Windows:

1. If you run on a host machine with an Intel processor that supports Intel s virtualisation (VT-x) technology, then use Intel Atom (x86) as CPU/ABI. Please note that you therefore need to install HAXM ("Intel Hardware Accelerated Execution Manager") through the Android SDK Manager. 2. A lower screen resolution is generally faster, for example use WVGA800. 3. If you tick the Snapshot option, then you will be able to save a snapshot of the machine and therefore be much faster on the next start/execution. You can start virtual devices right from the Android Virtual Device Manager by selecting the device and clicking the Start button. As you already know, you can check the name(s) of the running virtual and real devices from command line: adb devices Installing an app on a Virtual Device Once your Virtual Device is ready, you can install an app on the Virtual Device. The first step is to run the Virtual Device, on which you want to install the app. You can start a Virtual Device from the AVD Manager by clicking the Start button, or from the command line: emulator -avd <AVD_Name> This launches the Virtual Device and the command is running in the command prompt window. Launch another command prompt window and run the following command (the parameter e is for specifically addressing the Emulator, for addressing a real device on a USB connection, the corresponding parameter is d ). adb e install <path_to_apk_file>

Finding element properties Using UI Automator Viewer uiautomatorviewer is an application that comes packaged with the Android SDK and is present under the tools folder of the Android SDK. It is a tool that lets you inspect the User Interface (UI) of an application in order to explore the layout hierarchy, and view the properties associated with the controls. While writing your tests, this tool is essential, as it exposes the Id and other attributes of an element, which are required for writing scripts. Clicking on the devices icon (second from the left, next to the open folder icon) takes a dump of a UI XML snapshot of the screen shown on the device. The left side of the tool shows how the device looks like. The right side is divided in two parts: 1. The upper half shows the UI XML snapshot and the nodes structure. 2. The lower half shows the details of the selected node with all the attributes. You can explore the properties of UI elements by clicking on them. Usually, the most helpful property for scripting is the resource-id, but it is not always available. When it is not available, it is often best to use the class name in combination with another property (such as text) to generate an Xpath expression that uniquely identifies the UI element.

Using Appium Inspector An alternative tool to the uiautomatorviewer is the Appium Inspector that is available from the Appium toolbar of the Appium server: Remote debugging Android hybrid applications with Google Chrome When working with Android hybrid applications (as opposed to Android native apps), then the Google Chrome web browser offers better and faster locator features than the uiautomatorviewer. However, it requires a real device connected through a USB cable to the machine with the Google Chrome web browser. A full Appium Java example The Android app PasswdSafe is a port of the popular free and open-source password manager program Password Safe to Android. Password Safe allows you to safely and easily create a secured and encrypted user name/password list. With Password Safe all you have to do is to create and remember a single "Master Password" of your choice in order to unlock and access your entire user name/password list. PasswdSafe supports viewing and editing of Password Safe data files. You can therefore exchange your data files between your (Microsoft Windows) PC and your Android device. The PasswdSafe app can be installed on your Android device from Google play. The app and the source code can also be downloaded from http://sourceforge.net/projects/passwdsafe/.

What the PasswdSafe example does The PasswdSafe example project will first create an empty password file and then delete the newly create file. Here are some screenshots from an Android phone device: Using the PasswdSafe example You need to download the ZIP-file with the source code from http://sourceforge.net/projects/passwdsafe/ and place the PasswdSafe.apk file in the apps folder of your Java project:

The other 5 required files are: File name pom.xml AppiumTest.java AndroidSetup.java BasePage.java LandingPage.java Contains Contains information about the project and configuration details used by Apache Maven to build the project. Contains the test(s). This example project only contains one single test case (with the JUnit annotation @Test ). Most real world projects would contain multiple test cases. Contains the initialisation information for the Selenium (Appium) web driver. A library that contains generally useful universal helper methods. Not all of them are used in this example project. Contains methods for the landing page of the application. It extends the selection of the general purpose methods defined in BasePage.java. This project contains one method for creating files, and one method for deleting files. In most real world applications, there will be multiple pages, each with specific methods for a particular page. The pom.xml file This example projects targets Java version 8 (1.8) in its Apache Maven pom.xml file. You might have to adapt the pom.xml file to fit your environment and change the version numbers of the dependencies: <?xml version="1.0" encoding="utf-8"?> <project xmlns="http://maven.apache.org/pom/4.0.0" xmlns:xsi="http://www.w3.org/2001/xmlschema-instance" xsi:schemalocation="http://maven.apache.org/pom/4.0.0 http://maven.apache.org/xsd/maven- 4.0.0.xsd"> <modelversion>4.0.0</modelversion> <groupid>com.pepgo</groupid>

<artifactid>appiumpasswdsafe</artifactid> <version>1.0-snapshot</version> <packaging>jar</packaging> <properties> <project.build.sourceencoding>utf-8</project.build.sourceencoding> <maven.compiler.source>1.8</maven.compiler.source> <maven.compiler.target>1.8</maven.compiler.target> </properties> <dependencies> <dependency> <groupid>org.seleniumhq.selenium</groupid> <artifactid>selenium-java</artifactid> <version>3.4.0</version> </dependency> <dependency> <groupid>junit</groupid> <artifactid>junit</artifactid> <version>4.12</version> <scope>test</scope> </dependency> <dependency> <groupid>io.appium</groupid> <artifactid>java-client</artifactid> <version>4.1.2</version> <scope>test</scope> </dependency> </dependencies> </project> The AppiumTest.java file @BeforeClass prepares the Selenium WebDriver, while @AfterClass disposes the driver. In between the two, all @Test will be executed, although this example only contains one single test. package com.pepgo.appiumpasswdsafe.scenarios; import org.junit.beforeclass; import org.junit.afterclass; import org.junit.test; import org.openqa.selenium.by; import com.pepgo.appiumpasswdsafe.pages.landingpage; public class AppiumTest extends AndroidSetup { @BeforeClass public static void setup() throws Exception { prepareandroidforappium(); @AfterClass public static void teardown() throws Exception { driver.quit(); @Test public void createanddeletepasswdsafefile_test() throws Exception { // Close start pop-up window driver.findelement(by.id("android:id/button1")).click(); // Create new PasswdSafe file

new LandingPage(driver).createPasswdSafeFile("MyFileName", "MyPassword"); // Delete new PasswdSafe file new LandingPage(driver).deletePasswdSafeFile("MyFileName", "MyPassword"); The AndroidSetup.java file This setup executes the tests on a (virtual or real) device called 00c600c600c600c6. You will have to adapt this to fit your environment. You must also adapt the application path to the apps folder where you have saved the PasswdSafe.apk file. package com.pepgo.appiumpasswdsafe.scenarios; import io.appium.java_client.android.androiddriver; import org.openqa.selenium.remote.desiredcapabilities; import java.io.file; import java.net.malformedurlexception; import java.net.url; public class AndroidSetup { protected static AndroidDriver driver; protected static void prepareandroidforappium() throws MalformedURLException { File appdir = new File("C:\\Temp\\apps"); File app = new File(appDir, "PasswdSafe.apk"); DesiredCapabilities capabilities = new DesiredCapabilities(); capabilities.setcapability("device","android"); capabilities.setcapability("devicename","00c600c600c600c6"); capabilities.setcapability("platformname","android"); //other caps capabilities.setcapability("app", app.getabsolutepath()); driver = new AndroidDriver(new URL("http://localhost:4723/wd/hub"), capabilities); The LandingPage.java file This Java class contains the methods that are available for the main page of the app. The class extends the general purpose helper functions of the BasePage.java class. package com.pepgo.appiumpasswdsafe.pages; import io.appium.java_client.android.androiddriver; import org.openqa.selenium.by; import static org.junit.assert.*; public class LandingPage extends BasePage { public LandingPage(AndroidDriver driver) { super(driver); public LandingPage createpasswdsafefile(string strfilename, String strpassword) { By menufilenew = By.id(app_package_name + "menu_file_new"); By edittextfilename = By.id(app_package_name + "file_name"); By edittextpassword = By.id(app_package_name + "password"); By edittextpasswordconfirm = By.id(app_package_name + "password_confirm");

// Create new file driver.findelement(menufilenew).click(); // Enter file name driver.findelement(edittextfilename).sendkeys(strfilename); // Enter password driver.findelement(edittextpassword).click(); entertextinpasswordfield(strpassword); // Enter password confirmation driver.findelement(edittextpasswordconfirm).click(); entertextinpasswordfield(strpassword); // Click OK driver.findelement(by.id("android:id/button1")).click(); // Click widget button driver.findelement(by.classname("android.widget.imagebutton")).click(); // Click on text "Close" driver.findelement(by.xpath("//android.widget.textview[@text='close']")).click(); try { Thread.sleep(3000); catch (InterruptedException e) { Thread.currentThread().interrupt(); // Assert that the PasswdSafe file exists asserttrue(driver.findelements(by.xpath("//android.widget.textview[@text='" +strfilename+ ".psafe3']")).size() > 0); return new LandingPage(driver); public LandingPage deletepasswdsafefile(string strfilename, String strpassword) { By entertextpassword = By.id(app_package_name + "passwd_edit"); By checkboxconfirm = By.id(app_package_name + "confirm"); // Click on text for file name driver.findelement(by.xpath("//android.widget.textview[@text='" + strfilename + ".psafe3']")).click(); // Enter password driver.findelement(entertextpassword).click(); entertextinpasswordfield(strpassword); // Click widget button driver.findelement(by.classname("android.widget.imagebutton")).click(); // Click on text "File Operations " driver.findelement(by.xpath("//android.widget.textview[@text='file Operations ']")).click(); // Click on text "Delete File" driver.findelement(by.xpath("//android.widget.textview[@text='delete File']")).click(); // Click on checkbox "Confirm" driver.findelement(checkboxconfirm).click(); // Click OK driver.findelement(by.id("android:id/button1")).click(); // Assert that the PasswdSafe file no longer exists assertequals(driver.findelements(by.xpath("//android.widget.textview[@text='" +strfilename+ ".psafe3']")).size(), 0); return new LandingPage(driver); The BasePage.java file This Java class contains useful general purpose helper functions. package com.pepgo.appiumpasswdsafe.pages; import org.openqa.selenium.by; import org.openqa.selenium.javascriptexecutor; import io.appium.java_client.android.androiddriver; import org.openqa.selenium.webelement; import org.openqa.selenium.remote.remotewebelement; import org.openqa.selenium.support.ui.expectedconditions; import org.openqa.selenium.support.ui.webdriverwait;

import java.util.hashmap; public class BasePage { protected static AndroidDriver driver; String app_package_name = "com.jefftharris.passwdsafe:id/"; public BasePage(AndroidDriver driver) { this.driver = driver; protected void waitforvisibilityof(by locator) { WebDriverWait wait = new WebDriverWait(driver, 30); wait.until(expectedconditions.visibilityofelementlocated(locator)); protected void waitforclickabilityof(by locator) { WebDriverWait wait = new WebDriverWait(driver, 30); wait.until(expectedconditions.elementtobeclickable(locator)); public void scrollpageup() { JavascriptExecutor js = (JavascriptExecutor) driver; HashMap<String, Double> swipeobject = new HashMap<String, Double>(); swipeobject.put("startx", 0.50); swipeobject.put("starty", 0.95); swipeobject.put("endx", 0.50); swipeobject.put("endy", 0.01); swipeobject.put("duration", 3.0); js.executescript("mobile: swipe", swipeobject); public void swipelefttoright() { JavascriptExecutor js = (JavascriptExecutor) driver; HashMap<String, Double> swipeobject = new HashMap<String, Double>(); swipeobject.put("startx", 0.01); swipeobject.put("starty", 0.5); swipeobject.put("endx", 0.9); swipeobject.put("endy", 0.6); swipeobject.put("duration", 3.0); js.executescript("mobile: swipe", swipeobject); public void swiperighttoleft() { JavascriptExecutor js = (JavascriptExecutor) driver; HashMap<String, Double> swipeobject = new HashMap<String, Double>(); swipeobject.put("startx", 0.9); swipeobject.put("starty", 0.5); swipeobject.put("endx", 0.01); swipeobject.put("endy", 0.5); swipeobject.put("duration", 3.0); js.executescript("mobile: swipe", swipeobject); public void swipefirstcarouselfromrighttoleft() { JavascriptExecutor js = (JavascriptExecutor) driver; HashMap<String, Double> swipeobject = new HashMap<String, Double>(); swipeobject.put("startx", 0.9); swipeobject.put("starty", 0.2); swipeobject.put("endx", 0.01); swipeobject.put("endy", 0.2); swipeobject.put("duration", 3.0); js.executescript("mobile: swipe", swipeobject); public void performtapaction(webelement elementtotap) { JavascriptExecutor js = (JavascriptExecutor) driver; HashMap<String, Double> tapobject = new HashMap<String, Double>(); tapobject.put("x", (double) 360); // in pixels from left tapobject.put("y", (double) 170); // in pixels from top tapobject.put("element", Double.valueOf(((RemoteWebElement) elementtotap).getid())); js.executescript("mobile: tap", tapobject); // Accepts only numbers (key codes 7-16) and lower and upper case letters (key codes 29-54) // Key code 66 is <Enter> public void entertextinpasswordfield(string strtexttoenter) { int intcounter, intkey; for (intcounter = 0; intcounter < strtexttoenter.length(); intcounter++) { intkey = (int) strtexttoenter.charat(intcounter); if (intkey > 47 && intkey < 58) { intkey = intkey - 41; driver.presskeycode(intkey); else if (intkey > 64 && intkey < 91) { intkey = intkey - 36; driver.presskeycode(intkey, 1);

else if (intkey > 96 && intkey < 123) { intkey = intkey - 68; driver.presskeycode(intkey); driver.presskeycode(66);