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()
    	//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"));

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

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


    	//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");

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"));

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");

//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


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.

6 thoughts on “Testing native Mobile Apps with TestComplete and Appium – An Alternative

  1. After looking into a number of the blog articles on your web page,
    I seriously appreciate your technique of blogging.
    I book-marked it to my bookmark website list and will be checking back in the near
    future. Please check out my web site too and tell
    me your opinion.

  2. What’s up it’s me, I am also visiting this web site on a regular basis, this site is actually pleasant and the visitors are really sharing
    pleasant thoughts.

  3. > info: Welcome to Appium v1.3.7 (REV 72fbfaa116d3d9f6a862600ee99cf02f6d0e2182)
    > info: Appium REST http interface listener started on
    > info: [debug] Non-default server args: {“address”:”″,”logNoColors”:true,”platformName”:”Android”,”platformVersion”:”18″,”automationName”:”Appium”}
    > info: Console LogLevel: debug
    > info: –> POST /wd/hub/session {“desiredCapabilities”:{“appPackage”:”com.android.calculator2″,”appActivity”:”com.android.calculator2.Calculator”,”platformName”:”Android”,”version”:”4.3.0″,”deviceName”:”TA64301YDK”}}
    > info: Client User-Agent string: Apache-HttpClient/4.4.1 (Java/1.8.0_45)
    > info: [debug] The following desired capabilities were provided, but not recognized by appium. They will be passed on to any other services running on this server. : version
    > info: [debug] Didn’t get app but did get Android package, will attempt to launch it on the device
    > info: [debug] Creating new appium session 08ffb614-2052-4edb-9b70-24c06545dd64
    > info: Starting android appium
    > info: [debug] Getting Java version
    > info: Java version is: 1.8.0_45
    > error: Unhandled error: Error: ENOENT, no such file or directory ‘C:\Users\pratik\android-sdks\build-tools’
    > at Object.fs.readdirSync (fs.js:654:18)
    > at exports.getDirectories (C:\Program Files (x86)\Appium\node_modules\appium\node_modules\appium-adb\lib\helpers.js:100:18)
    > at ADB.checkSdkBinaryPresent (C:\Program Files (x86)\Appium\node_modules\appium\node_modules\appium-adb\lib\adb.js:97:25)
    > at ADB.checkAdbPresent (C:\Program Files (x86)\Appium\node_modules\appium\node_modules\appium-adb\lib\adb.js:134:8)
    > at Function.ADB.createADB (C:\Program Files (x86)\Appium\node_modules\appium\node_modules\appium-adb\lib\adb.js:73:7)
    > at androidCommon.initAdb (C:\Program Files (x86)\Appium\node_modules\appium\lib\devices\android\android-common.js:1059:9)
    > at C:\Program Files (x86)\Appium\node_modules\appium\node_modules\async\lib\async.js:610:21
    > at C:\Program Files (x86)\Appium\node_modules\appium\node_modules\async\lib\async.js:249:17
    > info: [debug] Checking whether adb is present
    > at C:\Program Files (x86)\Appium\node_modules\appium\node_modules\async\lib\async.js:160:25 context: [POST /wd/hub/session {“desiredCapabilities”:{“appPackage”:”com.android.calculator2″,”appActivity”:”com.android.calculator2.Calculator”,”platformName”:”Android”,”version”:”4.3.0″,”deviceName”:”TA64301YDK”}}]
    > info: info: –> POST /wd/hub/session {“desiredCapabilities”:{“appPackage”:”com.android.calculator2″,”appActivity”:”com.android.calculator2.Calculator”,”platformName”:”Android”,”version”:”4.3.0″,”deviceName”:”TA64301YDK”}}
    > error: Failed to start an Appium session, err was: Error: Requested a new session but one was in progress
    > info: Client User-Agent string: Apache-HttpClient/4.4.1 (Java/1.8.0_45)
    > info: [debug] Error: Requested a new session but one was in progress
    > at Appium.start (C:\Program Files (x86)\Appium\node_modules\appium\lib\appium.js:139:15)
    > at exports.createSession (C:\Program Files (x86)\Appium\node_modules\appium\lib\server\controller.js:182:16)
    > at Layer.handle [as handle_request] (C:\Program Files (x86)\Appium\node_modules\appium\node_modules\express\lib\router\layer.js:82:5)
    > at next (C:\Program Files (x86)\Appium\node_modules\appium\node_modules\express\lib\router\route.js:110:13)
    > at Route.dispatch (C:\Program Files (x86)\Appium\node_modules\appium\node_modules\express\lib\router\route.js:91:3)
    > at Layer.handle [as handle_request] (C:\Program Files (x86)\Appium\node_modules\appium\node_modules\express\lib\router\layer.js:82:5)
    > at C:\Program Files (x86)\Appium\node_modules\appium\node_modules\express\lib\router\index.js:267:22
    > at Function.proto.process_params (C:\Program Files (x86)\Appium\node_modules\appium\node_modules\express\lib\router\index.js:321:12)
    > at next (C:\Program Files (x86)\Appium\node_modules\appium\node_modules\express\lib\router\index.js:261:10)
    > at next (C:\Program Files (x86)\Appium\node_modules\appium\node_modules\express\lib\router\route.js:100:14)
    > info: [debug] Responding to client with error: {“status”:33,”value”:{“message”:”A new session could not be created. (Original error: Requested a new session but one was in progress)”,”origValue”:”Requested a new session but one was in progress”},”sessionId”:”08ffb614-2052-4edb-9b70-24c06545dd64″}
    > info: <– POST /wd/hub/session 500 12.959 ms – 250

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s