Testing native Mobile Apps with TestComplete and Appium – An Alternative

[Note] This post was written well before SmartBear released TestComplete 10 with support for testing iOS and Android mobile apps. Please visit the SmartBear TestComplete product page for more details. This post is no longer valid and kept here as a reference.

My day job needs me to work on TestComplete a popular commercial testing tool from SmartBear Software. We do a lot of serious testing using TestComplete for our Desktop applications.

Recently I saw discussions on TestComplete User Forums about possibility of testing mobile apps using TestComplete.  While TestComplete supports testing on wide range of technologies and application platforms including Web and Desktop applications developed on Windows, .NET, WPF, Delphi, C++, Java and so on. However while writing this post it does not have in-built mobile testing capabilities. SmartBear is working on adding mobile testing features which are in beta phase. There are third party tool/plug-in(s) available which use Image Recognition based approach to test the applications. But there is no native support to test iOS or Android Apps.

With these thoughts in my mind, I started to explore if I could mix Appium with TestComplete which will allow testing mobile Apps without leaving the TestComplete environment? With couple hours of hacking, here are the results!

About Appium

Appium is an open source test automation framework for automating native and hybrid mobile apps.
It drives iOS and Android Apps using the WebDriver JSON wire protocol. Appium tests are built on Selenium WebDriver API.  The WebDriver API is used for driving user actions in Browsers, but now it can be used to drive the user interaction on native and hybrid mobile Apps. WebDriver API provides various language bindings which allow you to use them with your choice of programming language and platform, very cool!

How does this works?

TestComplete is a versatile tool and provides supports for more than dozen technologies and extensibility features. TestComplete provides a .NET Bridge which allows access to individual objects of .NET assemblies, their internal properties and methods. This is done by a special dotNET object that provides access to .NET assemblies, types and type members. This feature is available as part of .NET Classes Support plug-in in TestComplete.

Since Appium is driven by WebDriver API, we can connect the WebDriver .NET APIs with TestComplete using the .NET bridge and drive the mobile Apps using Appium. Following diagram provides an overview of this interaction

How to do it?

Setting up the WebDriver .NET API with TestComplete is relatively easy task. Following section describe the detailed steps for driving Appium through TestComplete for testing a sample iOS native App.

Step 1 – Download the WebDriver .NET API Binaries

Download the latest binaries from http://docs.seleniumhq.org/download/. You need to click on Download link in front of C# option in Selenium Client & WebDriver Language Bindings section.

Step 2 – Add WebDriver assemblies to TestComplete CLR Bridge

In next step make the WebDriver assemblies available to TestComplete with following steps. These assemblies will be added to the list in the project’s CLR Bridge settings group. This group contains the list of .NET assemblies whose functions will be available to your scripts through the dotNET object:

  1. Go to TestComplete Project Setting by selecting Current Project Settings from Tools Menu
  2. Select CLR Bridge option on left side of Project Properties Pane
  3. Click Browse Files button to select the WebDriver files. This will display Select Assembly dialog box
  4. On Select Assembly dialog navigate to the net40 folder in WebDriver .NET API files downloaded in Step 1 and select the WebDriver.dll and WebDriver.Support.dll files
  5. Also make sure System.dll is added to CLR Bridge. If it’s not added already, you can add this assembly by Browser GAC button. You will see screen similar to following screen shot after you add all the assemblies to the CLR Bridge
TestComplete CLR Bridge

TestComplete CLR Bridge

This will add WebDriver API to the TestComplete project and provide access to the internal classes and functions using the dotNET object. Assemblies that are added to the CLR Bridge become available in scripts as child objects of the dotNET object. Types defined in these assemblies are available as child of dotNET object. All available assemblies, types, and type members are displayed in the Code Completion window of TestComplete. For more information on dotNET object refer Calling .NET Routines via dotNET Object section in TestComplete Help documentation (also available at http://support.smartbear.com/viewarticle/28697/)

Step 3 – Setting up Appium

Before we start testing iOS or Android apps, we need to setup Appium in a local environment. If you wish to run tests for iOS, then you need to setup Appium on a Mac OSX machine. For testing Android applications you can setup environment on a Windows or Linux machine. Setting up Appium is fairly easy with new Appium App for Mac OSX.

In this example we will test a sample BMI Calculator application for iOS. This is a pretty simple App with bunch of UI elements on a single view. You can get the App source from https://github.com/upgundecha/BmiCalculator.

Let’s setup Appium on a Mac and TestComplete on a Windows machine

  1. On Mac machine download and install the Appium from http://appium.io
  2. Before we launch Appium, download the sample App from https://github.com/upgundecha/BmiCalculator/blob/master/Sample%20App/BmiCalculator.zip,
  3. Unzip BmiCalculator.zip file to get the BmiCalculator.app file
  4. Next, launch Appium on Mac. Select the App Path checkbox and choose the location of the App. Click on Launch button, Appium will launch the application in iOS Simulator as shown in below screenshot, now it’s ready for testing the App
Appium.app running on Mac

Appium.app running on Mac

Step 4 – Writing a test

TestComplete offers multiple language options to write your tests. You can write tests in JavaScript, VBScript, Delphi or C++/C# scripting languages. This example uses JavaScript.

Our test need to tell Appium about what platform is needed for executing the tests. This is done by creating an instance of DesiredCapabilities class of WebDriver API and setting up configuration information in key/value  pair.


//Set up the capabilities to run test on iOS application on local Appium server
Capabilities.setCapability(CapabilityType.BrowserName, "iOS");
Capabilities.setCapability(CapabilityType.Version, "6.1");
Capabilities.setCapability(CapabilityType.Platform, "Mac");

Create an instance of  RemoteWebDriver instance and point it to http://mymacmachine:4723/wd/hub in the test by using Uri class from .NET System namespace and desired capabilities defined earlier. Here mymacmachine could be different in your environment. You can specify Hostname or IP of the Mac machine where Appium is running.


//Set up the RemoteWebDriver
var uri = dotNET.System.Uri.zctor("http://mymacmachine:4723/wd/hub");
var driver = dotNET.OpenQA_Selenium_Remote.RemoteWebDriver.zctor_3(uri,Capabilities);

Here is complete script which tests the BMI calculator functionality (also available as a Gist @ https://gist.github.com/upgundecha/5894126)

function BmiCalculatorTest()
{
  try
  {
    	//Create an instance of DesirecCapabilities, CapabilityType and By Class using CLR Bridge & dotNET Object
    	var Capabilities = dotNET.OpenQA_Selenium_Remote.DesiredCapabilities.zctor();
    	var CapabilityType = dotNET.OpenQA_Selenium_Remote.CapabilityType;
    	var By = dotNET.OpenQA_Selenium.By;

    	//Set up the capabilities to run test on iOS application on local Appium server
    	Capabilities.setCapability(CapabilityType.BrowserName, "iOS");
    	Capabilities.setCapability(CapabilityType.Version, "6.1");
    	Capabilities.setCapability(CapabilityType.Platform, "Mac");

    	//Set up the RemoteWebDriver
    	var uri = dotNET.System.Uri.zctor("http://mymacmachine:4723/wd/hub");

    	var driver = dotNET.OpenQA_Selenium_Remote.RemoteWebDriver.zctor_3(uri,Capabilities);

    	//Get the Hight text field and enter value
    	var HeightField = driver.FindElement(By.Name("Height"));
    	HeightField.SendKeys("181");

    	//Get the Weight text field and enter value
    	var WeightField = driver.FindElement(By.Name("Weight"));
    	WeightField.SendKeys("80");

    	//Get the Calculate button and tap/click on it
    	var CalculateButton = driver.FindElement(By.Name("Calculate"));

    	CalculateButton.Click();

    	//Get the Bmi lables
    	var BmiLabel = driver.FindElement(By.Name("bmi"));
    	var BmiCategoryLabel = driver.FindElement(By.Name("category"));

    	//Check labels for expected values
    	if(aqObject.CompareProperty(BmiLabel.Text, cmpEqual, "24.42")) {
      	  Log.Checkpoint ("Calculated BMI is correct!");
    	}
    	else {
      	  Log.Error( "Calculated BMI does not match expected value");
    	}

    	if(aqObject.CompareProperty(BmiCategoryLabel.Text, cmpEqual, "Normal")) {
      	  Log.Checkpoint( "BMI Category is correct!");
    	}
    	else {
      	  Log.Error( "BMI Category does not match with expected value");
    	}
    	driver.Quit();
  }
  catch(err){
    Log.Error(err.Message);
  }
}

If you prefer TestComplete with VBScript, you can get the VBScript version @ https://gist.github.com/upgundecha/5894141

How this works?

When this test is executed, TestComplete calls the WebDriver API and connects to the Appium server using the RemoteWebDriver. Then it locates the UI elements using FindElement() method of WebDriver API. Test can locate the elements using various locator strategies provided by the By class of WebDriver API. In following example, test is locating Height text field from Bmi Calculator App using its name property. It then enters the specified text using SendKeys() method


//Get the Hight text field and enter value
var HeightField = driver.FindElement(By.Name("Height"));
HeightField.SendKeys("181");

This is pretty much similar to how TestComplete works with UI objects while testing Web or Desktop applications. After inputting the data, TestComplete verifies the expected outcome using its inbuilt verification methods. At the end of execution TestComplete generate a result log as shown in following screenshot

Test Results

Test Results

Running test with Sauce Labs

You may not always get a dedicated hardware to test these Apps. Sauce labs, the company behind Appium, provides you an ability to run Appium tests in a virtual environment without needing you to setup everything from scratch. This also saves you costs for setting up the infrastructure on your own.

So let’s setup and run this test with Sauce Labs. You need a free Sauce Labs account to begin with. Register for a free account on Sauce Labs and get the user name and access key. Sauce Labs provides all the needed hardware and software infrastructure to run your tests in the cloud.

For running tests in Sauce Labs environment, you need to upload your App to Sauce Labs temporary storage using Temporary Storage REST API. You can get the App compiled and built by developers and upload through curl command line utility (Windows users can get curl from http://curl.haxx.se/download.html)


curl -u <sauce_user_name>:<sauce_access_key> -X POST "http://saucelabs.com/rest/v1/storage/$SAUCE_USERNAME/my_ios_app.zip?overwrite=true" -H "Content-Type: application/octet-stream" --data-binary @my_ios_app.zip

We need to modify our test a bit to run on Sauce Labs. Apart from changing the Capabilities and RemoteWebDriver Uri, we need to pass Sauce Labs user name and access key. You can save these into TestComplete project variables. With following changes to earlier test, we can now run tests with Sauce Labs:


var USER_NAME = Project.Variables.SAUCE_USER_NAME
var ACCESS_KEY = Project.Variables.SAUCE_ACCESS_KEY

//Set up the capabilities to run test on iOS application on Sauce Labs
Capabilities.SetCapability(CapabilityType.BrowserName, "iOS 6.0");
Capabilities.SetCapability(CapabilityType.Platform, "Mac 10.8");
Capabilities.SetCapability("device", "iPhone Simulator");
Capabilities.SetCapability("app", "sauce-storage:my_ios_app.zip");
Capabilities.SetCapability("username",USER_NAME);
Capabilities.SetCapability("accessKey",ACCESS_KEY);

//Set up the RemoteWebDriver
var uri = dotNET.System.Uri.zctor("http://" + USER_NAME + ":" + ACCESS_KEY +  "@ondemand.saucelabs.com:80/wd/hub");
var driver = dotNET.OpenQA_Selenium_Remote.RemoteWebDriver.zctor_3(uri,Capabilities);

When you run the test you can login to your Sauce Labs account and see the progress in a Browser window. Based on desired capabilities, Appium provisions an instance of Mac in Sauce Labs cloud and drives the App.

Test Running on Sauce

Test Running on Sauce

You can also view test run in Sauce Labs dashboard with details of each step along with screenshot and video of entire run.

Sauce Dashboard

Sauce Dashboard

Summary

Appium bring exciting possibilities to TestComplete users for testing mobile applications in a platform independent way. These tests can be executed in a local environment or in the cloud or real devices in very a short time, with minimal efforts and costs. This brings more test coverage and faster feedback.


iOS Automation with Appium & Selenium

Note: This post is not up to date with latest release of Appium. An update coming soon…

Yesterday I saw a tweet on Appium release from Sauce Labs and immediately started exploring it. This post summarizes my initial experience with Appium.

Appium (http://appium.io/) is an open source tool/framework for automating iOS Native and Hybrid Apps. It uses the WebDriver JSON wire protocol to drive iOS apps.

Appium server is written in Node.js and talks to iOS using UIAutomation via Instruments. You can use the Selenium WebDriver API for writing tests which talk to Appium via JSON wire protocol for running the Selenium commands. This also gives you advantage of writing tests in your language of preference.

Installation

I found installing Appium quite easy on a local machine. You need Node.js installed before using Appium.

1. Install Node.js from http://nodejs.org/

2. Install WebDriver package for Node.js with the following command

sudo npm install wd

3. Install Appium with the following command

sudo npm install appium -g

4. Start the Appium server with the following command

appium &

Appium server will start at http://localhost:4723

Implementing test using Selenium WebDriver

I am using a sample BMI Calculator App developed with native iOS SDK for this example

Bmi Calculator App

Bmi Calculator App

Build the app using xcodebuild command (In this example the BmiCalc app)

xcodebuild -sdk iphonesimulator6.1

I am using Maven to setup a Java project for this test and here is pom.xml with the following dependencies added. For this example I have used IntelliJ IDEA. For more information on using Maven for Selenium script development refer bonus Chapter Integration with other Tools from my Selenium Testing Tools Cookbook

<?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>org.bmicalc.test</groupId>
    <artifactId>bmi-ios-test</artifactId>
    <version>1.0-SNAPSHOT</version>
    <dependencies>
    <dependency>
        <groupId>junit</groupId>
        <artifactId>junit</artifactId>
        <version>4.11</version>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>org.seleniumhq.selenium</groupId>
        <artifactId>selenium-java</artifactId>
        <version>LATEST</version>
        <scope>test</scope>
    </dependency>
    </dependencies>
</project>

And here is BmiCalcTest class

import org.junit.After;
import org.junit.Before;
import org.junit.Test;

import org.openqa.selenium.WebDriver;
import org.openqa.selenium.remote.CapabilityType;
import org.openqa.selenium.remote.DesiredCapabilities;
import org.openqa.selenium.remote.RemoteWebDriver;
import org.openqa.selenium.WebElement;
import org.openqa.selenium.By;

import java.io.File;
import java.net.URL;
import java.util.List;

import static org.junit.Assert.assertEquals;

public class BmiCalcTest {

    private WebDriver driver;

    @Before
    public void setUp() throws Exception {

        //Appium needs the path of app build
        //Set up the desired capabilities and pass the iOS SDK version and app path to Appium
        File app = new File("/Users/upgundecha/Desktop/AppExamples/BmiCalculator/build/Release-iphonesimulator/BmiCalculator.app");
        DesiredCapabilities capabilities = new DesiredCapabilities();
        capabilities.setCapability(CapabilityType.BROWSER_NAME, "iOS");
        capabilities.setCapability(CapabilityType.VERSION, "6.1");
        capabilities.setCapability(CapabilityType.PLATFORM, "Mac");
        capabilities.setCapability("app", app.getAbsolutePath());

        //Create an instance of RemoteWebDriver and connect to the Appium server.
        //Appium will launch the BmiCalc App in iPhone Simulator using the configurations specified in Desired Capabilities
        driver = new RemoteWebDriver(new URL("http://localhost:4723/wd/hub"), capabilities);
    }

    @Test
    public void testBmiCalc() throws Exception {

        //iOS controls are accessed through WebElement class
        //Locate the Height & Weight textField by their accessibility labels using By.name()
        WebElement heightTextField = driver.findElement(By.name("Height"));
        heightTextField.sendKeys("181");

        WebElement weightTextField = driver.findElement(By.name("Weight"));
        heightTextField.sendKeys("80");

        //Locate and tap on Calculate button using the click() method
        WebElement calculateButton =  driver.findElement(By.name("Calculate"));
        calculateButton.click();

        //Locate all the label elements using By.tagName()
        List<WebElement> labels = driver.findElements(By.tagName("staticText"));

        //Check the calculated Bmi and Category displayed on labels
        //Label with index 8 has value of the Bmi and index 9 has the value for category
        assertEquals("24.42",labels.get(8).getText());
        assertEquals("Normal",labels.get(9).getText());
    }

    @After
    public void tearDown() throws Exception {
        //Close the app and simulator
        driver.quit();
    }
}

I really liked using Selenium WebDriver API for writing iOS tests with Appium. I can add iOS support to my existing Selenium Framework with minimal changes. Appium presently supports locating elements using the tag name (i.e type of iOS control) and accessibility labels.

Running tests in Cloud

You can also run Appium with Sauce Labs Cloud, for more details read http://sauceio.com/index.php/2013/02/announcing-appium-on-sauce-native-hybrid-ios-testing-in-the-cloud/

Overall Appium is a great tool to start with.

References:
Getting Started – http://appium.io/getting-started.html
Appium on GitHub – http://sauceio.com/index.php/2013/02/announcing-appium-on-sauce-native-hybrid-ios-testing-in-the-cloud/
Samples – https://github.com/appium/appium/tree/master/sample-code
Wiki – https://github.com/appium/appium/wiki
Google Group – https://groups.google.com/forum/?hl=en&fromgroups=#!forum/appium-discuss