Testing on Physical Devices

Joshua Moody edited this page Oct 8, 2015 · 6 revisions

Calabash iOS supports running tests on physical devices.

We recommend that you always use a Gemfile and bundler.

These instructions assume you are following this advice. If not, omit any bundle exec from the commands you find below.

1. Pre-flight check

  1. You must be using Mac with at least Yosemite installed.
  2. The most recent released version of Xcode is always recommended. The minimum practical version of Xcode 6.4, but we support back to Xcode 6.0. If you report a problem, we'll always ask you to upgrade.
  3. If you have recently:
  • installed Xcode,
  • installed a new version of Xcode,
  • changed the location of Xcode on your hard drive (including renaming Xcode.app),
  • installed an iOS Simulator

you must restart your computer. That is the official word from Apple in their release notes.

2. Configuring your device

  1. Make sure your computer and device are on the same WiFi network. You can improve your network stability by creating a WiFi network on your Mac.
  2. Your device must be connected by USB.
  3. Your device must enabled for development. The fastest check is visually inspect the output of xcrun instruments -s devices. If you devices appears there, it is enabled for development. If it does not appear, then you should carefully follow steps 3, 4, and 5 in this Hot Topic.
  4. You must enable UIAutomation on your device using the switch in Settings.app > Developer > Enable UIAutomation.

3. Install the app

Unlike Calabash Android, Calabash iOS cannot install apps on physical devices. It is a sad state of affairs, but that is the world we live in. If you control the source code, the easiest way to get an app onto your device is to build and run from Xcode. If you only have an ipa, then you have two options:

  1. Drag and drop the ipa onto the device in the Xcode Device Manager window (Command + Shift + 2).
  2. Use a third-party command-line tool like ideviceinstaller (available with homebrew).

The problem most users have is that the .ipa must be signed correctly to run on your device. Resigning is a complicated issue. This repo and the briar gem might help you. Websites that resign your app may work, but often they resign with an ad hoc distribution profiles which prohibit interaction with Xcode's instruments for security reasons.

If you are interested in fully automating your Calabash iOS on-device testing, we recommend looking at the Makefile and scripts in these repositories:

4. Collecting information

Calabash needs 3 pieces of information to launch and interact with an app installed on a physical device.

  1. The device UDID.
  2. The IP address of the device.
  3. The bundle identifier of the app (CFBundleIdentifier).

The device UDID you can obtain from Xcode on the Device Manager window (Command + Shift + 2) or via the command line with:

$ xcrun instruments -s devices


$ bundle exec calabash-ios console
> RunLoop::Instruments.new.physical_devices

The IP address can be found on the device under Settings.app > WiFi > [Network] and touching the information disclosure button (the blue 'i').

You can improve your Calabash experience by naming your devices and taking advantage of the fact that Calabash is Bonjour server.

Bundle identifier

You may already know your bundle identifier; it will be something like com.example.MyApp or by convention com.example.MyApp-cal. The fastest way to find the bundle identifier is install the app your device and then open Xcode's Device Manager window, select your device, and view the installed apps.

If you have an ipa, you can use Calabash to find your app's bundle identifier:

$ bundle exec calabash-ios console
> RunLoop::Ipa.new('/path/to/your/app.ipa').bundle_identifier

You can also open the ipa's Info.plist in Xcode and find the bundle identifier.

$ mkdir tmp
$ cp app.ipa tmp/
$ cd tmp
$ unzip app.ipa
$ find Payload -name "Info.plist" -exec open {} \;

5. Verify your Calabash iOS version

Launch the app manually on your device. You should check to see if the Calabash server is running.

$ curl http://<ip>:37265/version

You should also make sure that the version of the Calabash iOS gem you are using is compatible with the server version.

If your version of the server is not compatible with your gem version, follow the instructions on the Updating your Calabash version.

6. Launch

IMPORTANT Many people have been using setting the NO_LAUNCH environment variable. This variable is deprecated in Xcode 7 and only usable when testing on iOS 6 devices.

$ export BUNDLE_ID=com.example.MyApp-cal
$ export DEVICE_ENDPOINT=http://<ip>:37265
$ bundle exec calabash-ios console
> start_test_server_in_background

Your app should launch. If it does not, try running with DEBUG=1

> exit
$ DEBUG=1 bundle exec calabash-ios console
> start_test_server_in_background

Use the information you see in DEBUG mode to find the source of the problem.

7. Run Cucumber

Once you have verified that you can launch.

$ export BUNDLE_ID=com.example.MyApp-cal
$ export DEVICE_ENDPOINT=http://<ip>:37265
$ bundle exec cucumber

If you what to improve your on-device cucumber experience, take a look at the config/cucumber.yml files in these repositories:

Clone this wiki locally
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.