Tutorial: Link Calabash in Debug config

vadnai edited this page Jun 29, 2016 · 5 revisions

This tutorial demonstrates how add the calabash.framework to your existing production app, but only when building the Debug configuration. Linking the calabash.framework will start the Calabash iOS server when the Debug version of your app is launched.

This is approach has the advantage that it is extremely easy to setup and maintain. There are a few things that make this approach unattractive. The Calabash iOS server requires the CFNetwork.framework. If your production app does not already link the CFNetwork.framework, this approach might not be for you. Linking the calabash.framework to the Debug mode means that the Calabash iOS server will start every time you launch the app. This might interfere with the normal behavior of your app. In practice, we haven't seen any interference, but we think it is worth mentioning.

Why load calabash.framework only in the Debug config?

The Calabash server contains symbols and methods that will cause any application that links to it to be rejected from the AppStore. By default, applications are archived for the App Store (and for distribution to beta testers) using a Release configuration. By only linking the calabash.framework in the Debug configuration will ensure that you never accidently submit an application that has the Calabash server linked.

Starting Point Completed Video
master demo/debug-config screencast.com ~3 minutes

Step 1. Link CFNetwork

If your app already links CFNetwork.framework, you can skip this step.


Step 2. Download calabash.framework

Create a Gemfile in the same directory as your .xcodeproj:

source "https://rubygems.org"

gem "calabash-cucumber", ">= 0.16", "< 2.0"

Then execute the following commands in that directory:

$ bundle
$ bundle exec calabash-ios download

caution: excluded filename not matched:  __MACOSX/*
caution: excluded filename not matched:  calabash.framework/.DS_Store

3. Link calabash.framework


The linker flags are:

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

If your app already links CFNetwork.framework, don't add "-framework CFNetwork".

4. Build and Run

Be sure that your Scheme runs the Debug configuration. You can target a simulator or physical device.


In your Xcode console you should see the following output - the exact content will differ by Calabash version:

DEBUG CalabashServer:222 | Creating the server: <LPHTTPServer: 0x7f80b3d066e0>
DEBUG CalabashServer:223 | Calabash iOS server version: CALABASH VERSION: 0.16.4
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.