Visual Studio App Center Test is the next generation of Xamarin Test Cloud! Read the blog post.

Running Calabash Tests on Local Devices

PDF for offline use
Related Articles:

Let us know how you feel about this

Translation Quality


This guide will discuss how to run Calabash tests on local devices attached to your computer.


This guide will cover how to run automated tests created with Calabash to physical devices. It will discuss how to configure the devices.


It is not possible to run tests on iOS devices using Windows. The devices must be connected to a Mac running OS X.

Compiling the Application

Before automated tests can be run, it is necessary to compile the application and install it on the device.

For iOS applications, ensure that you create an ad-hoc IPA using the DEBUG configuration. The guide IPA Support for Ad Hoc And Enterprise Deployment contains more details on this topic.

For Android applications, an APK must be deployed to the device. Xamarin Test Cloud Agent cannot interact with APK’s that are built using the Shared mono runtime. The Shared mono runtime is enabled by default in DEBUG builds and it is disabled by default in RELEASE builds. If you wish to use a DEBUG build of your APK, ensure that you turn off the Shared mono runtime:

Once you have compiled and installed the application on the device, you may need to configure the device so that the automated tests may run. This is described in the next section.

Device Configuration

Once the application has been compiled, it may be necessary to configure the device so that the application may be installed and then run.

Configuring Android Devices

The guides Set Up Device for Development and Debug on Device describe the steps necessary to configure an Android device for local development.

Configuring iOS Devices

Configuring an iOS device to run the local tests requires a few more steps. The guide Device Provisioning describes the first steps necessary to set up an iOS device for local development.

Once that is done, it may be necessary to enable UIAutomation on the device.

Enable UIAutomation

Starting in iOS 8, it is necessary to enable UIAutomation on the device. Go to the devices Settings, and select Developer:

Once in the Developer settings, turn Enable UI Automation:

Running Calabash Tests on Local Devices

In this section we will cover how to run Calabash tests on an Android or iOS device connected to the computer. Regardless of the platform involved, you must first install the application on the device. Calabash does not install an updated version of the application on a device.


To run Calabash tests on a local test:

$ calabash-android run <APK>

This will cause calabash-android to install the APK on the device and then start running the tests. If you have more than one device connected to the computer, you can specify which device to run the tests on with the following command line:

$ ADB_DEVICE_ARG=<DEVICE ID> calabash-android run <APK>

You can obtain a list of the devices and emulators using the Android Debug Bridge, as shown in the following snippet:

$ adb devices
List of devices attached
0756edf000620ace    device


Running Calabash tests on an iOS device requires two pieces of information:

  • Build Identifier of the installed application – You can find this in Project Options > Build > iOS Application as the Bundle Identifier:

The Calabash tests are run using the cucumber command, from the directory that contains your features folder. You will need to provide the bundle identifier and the device identifier to Calabash by setting the environment variables BUNDLE_ID and DEVICE_TARGET respectively. One way to do so is shown in the following command line:

$ BUNDLE_ID=com.xamarin.calabash.example.creditcardvalidation DEVICE_TARGET=f8c67472f88efb1985c2f5e73698d6bb36988f5d cucumber

When you hit enter, Calabash will start up the device on the application and begin running the test scripts.


This guide discussed how to run automated test on physical devices connected to your local workstation.

Xamarin Workbook

If it's not already installed, install the Xamarin Workbooks app first. The workbook file should download automatically, but if it doesn't, just click to start the workbook download manually.