Skip to content
Switch branches/tags

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time
master license
Build Status License


This project demonstrates how to integrate Calabash into an existing Xcode project and provides an introduction to UI testing with Calabash.

If you have any trouble building the app on the command line, please see the xcpretty and Code Signing sections for debugging tips.


  • MacOS 10.10 or 10.11
  • Xcode 6 or 7
  • iOS Devices >= 7.1
  • iOS Simulators >= 8.0
  • ruby >= 2.0 (latest is preferred)

We recommend a managed ruby environment like rbenv or rvm. If you are installing gems with sudo, please see our guide on why you should stop.

Bundler needs to be installed.

$ gem install bundler

Step 1: Install calabash.framework

You can find complete tutorials on the Tutorial: How to add Calabash to Xcode page of the Calabash iOS wiki. To get started quickly, we'll use the Debug Config approach.

# Install the necessary gems
$ bundle update

# Make sure you can build the app
$ make app

# Download the last calabash.framework
$ bundle exec calabash-ios download

Open Xcode and update the Linker Flags for the Debug Configuration.

alt text

These are the linker flags:

-ObjC -force_load "$(SOURCE_ROOT)/calabash.framework/calabash" -framework CFNetwork

Try to build and run on an iOS Simulator from Xcode In the Console you should see output like this:

DEBUG CalabashServer:222 | Creating the server: <LPHTTPServer: 0x7fe97a507ef0>
DEBUG CalabashServer:223 | Calabash iOS server version: CALABASH VERSION: 0.16.4

Step 2: Run cucumber

# Generate a features dir
$ bundle exec calabash-ios gen

# Tell Calabash where your app is (see Where is are the .app and ipa? below)
$ export APP=Products/app/

# Try running cucumber
$ bundle exec cucumber

Step 3: Open a console

# The console is a ruby irb
$ bundle exec calabash-ios console

# Launch the app with Calabash.
> start_test_server_in_background

# Type some text
> query("* marked:'Name'")
> touch("* marked:'Name'")
> keyboard_enter_text("Hello!")

Where to go from here?

Topic Description
Getting Started A more in-depth tutorial using this app.
Testing on Physical Devices Everything you need to know about testing on physical devices.
API Docs The Calabash iOS ruby API
iOS Smoke Test App Demonstrates advanced features, setups, and workflows
iOS WebView Test App Demonstrates how to interact with UIWebView and WKWebView
Getting Help The Calabash iOS Wiki

Where are the .app and .ipa?

This project includes a Run Phase build script that copies binaries built by Xcode to a local Products/ directory - this is the same directory that the make rules stage their build products. We encourage you to use this technique to ensure that you are always testing the most recent build of your app - whether it was built with Xcode or from the command line.



We use xcpretty to make builds faster and to reduce the amount of logging. Travis CI, for example, has a limit on the number of lines of logging that can be generated; xcodebuild breaks this limit.

The only problem with xcpretty is that it does not report build errors very well. If you encounter an issue with any of the make rules, run without xcpretty:

$ XCPRETTY=0 make ipa

Code Signing

If you have multiple code signing identities, you might need to set the CODE_SIGN_IDENTITY variable for the make scripts. If you are running with xcpretty, you might see output like this:

$ make ipa

The following build commands failed:
        PhaseScriptExecution Run\ Script\ Add\ Calabash\ dylibs\ to\

Try again without xpretty to reveal the problem:

$ XCPRETTY=0 make ipa
iPhone Developer: ambiguous (matches "iPhone Developer: Some Developer
(89543FK9SZ)" and "iPhone Developer: Some Other Developer (7QJQJFT49Q)"
Command /bin/sh failed with exit code 1


Fix this problem by telling Xcode which identity to use:

$ export CODE_SIGN_IDENTITY="iPhone Developer: Joshua Moody (7QJQJFT49Q)"
$ make ipa


An example project for Calabash iOS




No releases published


No packages published