Xamarin Test Cloud is now part of Visual Studio App Center! Get Started.

Linking the Calabash Framework

PDF for offline use
Related Links:

Let us know how you feel about this

Translation Quality


last updated: 2016-10

Now that we have the Calabash gems installed, the application we want to test must have the Calabash framework linked in. The Calabash framework provides a small, embedded HTTP server that allows the tests to communicate and control the application while it is running on the device. However, the Calabash framework must not be included in Release builds of the IPA. This section will discuss how to link the Calabash framework in Debug builds.

Linking in the Calabash framework involves the following steps:

  1. Download and Link the calabash.framework – This is the embedded HTTP server that allows the test scripts to interact with the app.
  2. Link CFNetwork – This is necessary for the the Calabash framework to automate the application under test.
  3. Build and Run the app – Once the IPA is built with the calabash.framework, run the application and confirm that the Calabash server is running.

Download the calabash.framework

  1. In the same directory as SimpleCreditCardValidator.xcodeproj, start an Terminal session and start up the Calabash sandbox.

    $ calabash-sandbox
    This terminal is now ready to use with Calabash.
    To exit, type 'exit'.
  2. Download the Calabash framework by running calabash-ios download in the same directory as the XCode project file:

    [tom@calabash-sandbox]$ calabash-ios download
    caution: excluded filename not matched:  __MACOSX/*
    caution: excluded filename not matched:  calabash.framework/.DS_Store
    [tom@calabash-sandbox]$ ls
    DerivedData                         SimpleCreditCardValidator           SimpleCreditCardValidator.xcodeproj calabash.framework

Notice that there is a new entry in the directory, calabash.framework. The next step is to link this library into the IPA.

Link the calabash.framework

The next step is to link the Calabash framework and the CFNetwork library into a Debug build of the app. Open up the project file, SimpleCreditCardValidator.xcodeproj in XCode.

  1. Select the SimpleCreditCardValidator target:

  2. Next, search for the Other Linker Flags settings, and expand it to reveal Debug and Release:

  3. Double click on the Debug settings, and past in the following string:

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

    This screenshot is an example of the linker flags for the Debug configuration with the Calabash and CFNetwork libraries linked in:

    If the app already links in CFNetwork framework, it is not necessary to provide the -framework CFNetwork flags.

The next thing is to confirm that the Calabash server is running when the application starts up.

Confirming the Embedded Calabash Server is Running

There are two ways to confirm that the Calabash framework is properly linked into an app and running:

  1. Viewing the log messages in the XCode output window.
  2. Using curl at the command line.

View Log Messages in the Output Window

The first way is to start the application in XCode. The Calabash server will log messages to the Output window as it starts up:

Using curl to Verify the Calabash Server

The second way to confirm that the Calabash server is running is to use curl to interrogate the app. From the Terminal, run curl as shown in the next snippet:

$ curl http://localhost:37265/version

If testing with an iOS device connected to the Mac, then substitute localhost for the IP address of the device.

If the Calabash server is running, it will return information about the version of Calabash in JSON. A sample of this response, formatted to make it easier to read, is shown below:

    "device_family": "iPhone",
    "outcome": "SUCCESS",
    "server_port": 37265,
    "simulator_device": "iPhone",
    "simulator": "CoreSimulator 303.8 - Device: iPhone 7 - Runtime: iOS 10.0 (14A345) - DeviceType: iPhone 7",
    "app_name": "",
    "app_version": "1",
    "screen_dimensions": {
      "native_scale": 2,
      "sample": 1,
      "height": 1334,
      "width": 750,
      "scale": 2
    "git": {
      "revision": "3427493",
      "remote_origin": "git@github.com:calabash/calabash-ios-server.git",
      "branch": "master"
    "device_name": "bushmaster",
    "4inch": false,
    "app_id": "com.xamarin.testcloud.quickstart.SimpleCreditCardValidator",
    "form_factor": "iphone 6",
    "system": "x86_64",
    "version": "0.20.0",
    "iOS_version": "10.0",
    "short_version_string": "1.0",
    "ios_version": "10.0",
    "iphone_app_emulated_on_ipad": false,
    "model_identifier": "iPhone9,1",
    "app_base_sdk": "iphonesimulator10.0"

The version number of the Calabash framework is contained in key-value pair "version":"0.20.0". This is a good time to confirm that your application is linking in a modern version of the Calabash HTTP server.

Xamarin Workbook

If it's not already installed, install the Xamarin Workbooks app first. The workbook file should download automatically, but if it doesn't, just click to start the workbook download manually.