Welcome to 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 http://xamarin.com/test-cloud.
- Getting Help
- Reporting Problems
- Public API
- Xamarin Studio + Ruby Client
- Xamarin Studio + UITest
Setup and Requirements
Xamarin Studio users should visit http://developer.xamarin.com/testcloud/ for setup instructions and requirements.
We recommend that you the most recent released version of Xcode, MacOS, and Ruby.
- MacOS 10.9 or 10.10
- Xcode 5.1.1 - Xcode 6.3
- ruby 1.9.3 - 2.2.+
We recommend that you use a managed ruby like rbenv or rvm. If you prefer to stick with the pre-installed ruby on MacOS, please avoid installing gems with
sudo. Simply put, using
sudoe is dangerous. Follow these excellent instructions for a ruby setup that avoids
The best practice is to always use a Gemfile and bundler.
The traditional setup creates a separate Xcode target application that mirrors your original application except that it link to the Calabash server library. We call this new target the -cal target.
Why a separate target?
The Calabash server contains symbols and methods that will cause any application that links to it to be rejected from the AppStore. A separate target with a different bundle identifier will ensure that you never accidently submit an application that has the Calabash server linked.
If the separate -cal target does not suit your needs, there are many other ways to setup your project. The community has collected these alternative methods for integrating Calabash into your Xcode project.
- Using Xcode Configuration instead of a separate target Jian Fang and David Siegel
- Load Calabash dylibs in Debug configuration at runtime
- CocoaPods Angel G. Olloqui
If you are not already using CocoaPods, we don't recommend adopt CocoaPods just to link the Calabash library.
Setup: Fast Track
The fast-track instructions are EXPERIMENTAL, but in our experience they work for most iOS projects.
If it doesn't work in your project, see the "Manual setup with Xcode" section below.
Starting in Xcode 6, we've had trouble maintaining the setup tools. If you have a problem see calabash-ios setup fails on fresh Xcode 6 project.
For automatic setup:
In a terminal, go to your iOS project
cd path-to-my-ios-project(i.e. directory containing .xcodeproj file)
Install calabash-cucumber gem (this make take some time because of dependencies)
gem install calabash-cucumber
Setup your project for Calabash-iOS.
calabash-ios setupAnswer the questions and read the output :)
Generate a skeleton features folder for your tests
In Xcode, build your project using the -cal scheme
Run the generated test!
If all goes well, you are now ready to write your first test. Start by editing the file
Proceed by reading details about installation below, or moving on to the Getting started guide.
Setup: Manually Create a -cal target
To use Calabash for iOS in your app, you must do two things: link with our framework:
calabash.framework, and install a ruby gem as described below. You also need to link with Apple's CFNetwork framework if you are not already using this.
For functional testing with Calabash iOS, you should create a whole separate target by duplicating your production target in Xcode (explained below).
Ruby and calabash-cucumber gem.
calabash-cucumbergem. (You may need to do
sudo gem install calabash-cucumber)
$ gem install calabash-cucumber Successfully installed calabash-cucumber-0.9.47 1 gem installed Installing ri documentation for calabash-cucumber-0.9.47... Installing RDoc documentation for calabash-cucumber-0.9.47...
Setting up Xcode project
Step 1/3 is to duplicate your primary/production target.
- Select your project in Xcode and select your production target for your app.
- Right click (or two-finger tap) your target and select "Duplicate target"
- Select "Duplicate only" (not transition to iPad)
- Rename your new target from ".. copy" to "..-cal"
- From the menu select Edit Scheme and select manage schemes.
- Rename the new scheme from ".. copy" to "..-cal"
- Optionally, set the Product name to ..-cal in Build settings for the new target.
Step 2/3: Link with framework.
- Download the latest version of calabash.framework with calabash-ios gem command:
- Use Finder to open the folder that contains
calabash.frameworkfrom Finder into your project's
Frameworksfolder in Xcode.
Make sure that
Copy items into destination group's folder (if needed)is checked and
- only your "-cal " target is checked in
Add to targets.
- Make sure that
- You must also link you -cal target with
CFNetwork.framework(unless your production target is already linking with
CFNetwork). To do this click on your -cal target in XCode. Click on Build Phases, expand Link Binary with Libraries, click
Step 3/3: cal-Target Build Settings
- Click on your project and select your new "-cal" target.
- Select "Build Settings".
- Ensure that "All" and not "Basic" settings are selected in "build settings".
- Find "Other Linker Flags" (you can type "other link" in the search field).
- Ensure that "Other linker flags" contains:
-force_load "$(SRCROOT)/calabash.framework/calabash" -lstdc++
Note: Now that you have created a separate target, new files that you add to your project are not automatically added to your -LP target. Make sure that any new files you add to your production target are also added to your -LP target.
This screenshot is a reference for you build settings.
calabash.framework is loaded.
Make sure you select your "..-cal" scheme and then run you app on 4.x/5 simulator.
Verify that you see console output like
2012-01-19 LPSimpleExample[4318:11603] Creating the server: <HTTPServer: 0x7958d70> 2012-01-19 LPSimpleExample[4318:11603] HTTPServer: Started HTTP server on port 37265 2012-01-19 LPSimpleExample[4318:13903] Bonjour Service Published: domain(local.) type(_http._tcp.) name(Calabash Server)
Calabash iOS is moving towards what we will designate a 1.0.0 release. What we mean by '1.0.0', is that we consider Calabash a stable and reliable product with a decent feature set sufficient for testing most iOS applications. The label '1.0.0' will mean a much stronger adherence to backwards compatibility, quality and stability. Particularly, from version 1.0.0, Calabash will be adhering to the notion of Semantic Versioning: http://semver.org/, and we will use also continuous integration and automated testing on Calabash (iOS and Android) itself.
But 1.0.0 won't be the next line of releases. There will be a number of other lines first (0.10.x, 0.11.x, ...) which will incorporate significant changes.
In the 0.10.x line, Calabash will optionally be supplied as a 'plugin' to the Frank project. The idea being to unify the communities more, although full unification will not be possible currently (as Calabash focuses on supporting on-device testing which is not currently a specific design-goal of Frank).
The Calabash framework uses private Apple APIs to synthesize touch events. This means that you should double check that
calabash.framework is not included in the .ipa file you submit to App Store. This is usually done by creating a separate build configuration or target for the version of your app running calabash tests.
An experimental check can be done by the calabash-ios tool
calabash-ios check PATH_TO_IPA_OR_APP
This is not guaranteed to work; it is your responsibility to ensure that the framework is properly installed.
How does automated setup work?
If you're interested in what's going on you can read the installation details here.
Verify that you have installed calabash-cucumber correctly by running
calabash-ios from the command line:
$ calabash-ios Usage: calabash-ios <command-name> [parameters] <command-name> can be one of help prints more detailed help information. gen generate a features folder structure. setup (EXPERIMENTAL) [opt path]? setup your XCode project for calabash-ios ...
When you run
calabash-ios setup and answer any questions it might ask the following happens:
Note that calabash-ios will backup your project file:
$ calabash-ios setup Checking if Xcode is running... ----------Info---------- Making backup of project file: ~/sample/sample.xcodeproj/project.pbxproj ...
The project file is copied to
project.pbxproj.bak. In case something goes wrong you can move this file back to
project.pbxproj (in your .xcodeproj) folder.
Setup will modify your xcode project file to use
calabash-ios. You should now have a new Scheme named [target]-cal in Xcode:
calabash-ios setup does the following:
- creates a new -cal target as a copy of your primary target
- add the calabash.framework to your Frameworks folder
- add $(SRCROOT) to framework search path (for that target)
- link with calabash.framework (for that target)
- link with Apple's CFNetwork.framework (for that target)
- set the special
-lstdc++linker flags (for that target)
Copyright (c) LessPainful APS. All rights reserved. The use and distribution terms for this software are covered by the Eclipse Public License 1.0 (http://opensource.org/licenses/eclipse-1.0.php) 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.