Skip to content


Subversion checkout URL

You can clone with
Download ZIP
Calabash for iOS
Ruby Clojure HTML Other
Latest commit 50bbb55 @jmoody jmoody Merge pull request #926 from calabash/feature/fix-missing-links-to-A0…

Launcher: remove dead link in warning emitted by #attach

master develop versioning license contributing
Build Status Build Status GitHub version License Contributing

Calabash iOS

Calabash is an automated testing technology for Android and iOS native and hybrid applications.

Calabash is a free-to-use open source project that is developed and maintained by Xamarin.

While Calabash is completely free, Xamarin provides a number of commercial services centered around Calabash and quality assurance for mobile, namely Xamarin Test Cloud consisting of hosted test-execution environments which let you execute Calabash tests on a large number of Android and iOS devices. For more information about the Xamarin Test Cloud visit


Xamarin Studio users should visit for setup instructions and requirements.

We recommend that you use the most recent released version of Xcode, MacOS, and Ruby.

  • 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 that you use a managed ruby (e.g. rbenv, rvm) or manually manage your gem environment with this script.

For more information about ruby on MacOS, see these Wiki pages:

Getting Started

If you want to see Calabash iOS in action, head over to the Calabash iOS Smoke Test App and follow the instructions in the README. We use this app to document, demonstrate, and test Calabash iOS. You can use this app to explore Calabash and as an example for how to configure your Xcode project and Calabash workflow.

Step 1: Link calabash.framework

To start using Calabash in your project, you need to link an Objective-C framework (calabash.framework) to your application.

Tutorial Description
Debug Config Use linker flags in the Debug build config to load the calabash.framework
Calabash Config Create a new Calabash Build Configuration
-cal Target Add a new app target to Xcode.

If you want to get started quickly, follow the Debug Config instructions. The Tutorial: How to add Calabash to Xcode wiki page discusses the merits of each approach and has instructions for using CocoaPods.

Step 2: Run Cucumber against an iOS Simulator

The Calabash iOS Example README has simple instructions for how to link the calabash.framwork, generate a features directory, run cucumber, and and open a Calabash console.

# In the directory where your .xcodeproj and Gemfile are
$ bundle exec calabash-ios gen

Build and run in Xcode, targeting an iOS Simulator. Calabash will try to detect the .app you just built.

$ bundle exec cucumber

If Calabash cannot find the .app you just built, it will raise an error. If this happens, you will to tell Calabash where it can find your .app.

By default, Xcode builds to a DerivedData directory:


Try to locate the .app and set the APP variable:

$ export APP="~/Library/Developer/Xcode/DerivedData/<UDID>/Build/Products/Debug-iphonesimulator/<NAME>.app"
$ bundle exec cucumber

We recommend using scripts and/or changing the location where Xcode stages build products.

  • Tutorial: Build scripts WIP
  • Tutorial: Xcode Location Settings WIP

Where to go from here?

Topic Description
Getting Started A more in-depth tutorial using the LPSimpleExample.
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



Copyright (c) LessPainful APS. All rights reserved.
The use and distribution terms for this software are covered by the
Eclipse Public License 1.0 (
which can be found in the file epl-v10.html at the root of this distribution.
By using this software in any fashion, you are agreeing to be bound by
the terms of this license. You must not remove this notice, or any other,
from this software.
Something went wrong with that request. Please try again.