This guide covers how to setup Calabash on OS X.

Overview

In order to create or run Calabash test scripts it is necessary to use Ruby and have the Calabash client libraries. Xamarin Test Cloud uses Ruby 2.3.1p112. For maximum compatibility with tests run locally and tests run in Test Cloud it is recommended that you use the same version while developing tests. The Calabash libraries are available via the following Ruby gems:

• calabash-cucumber gem – these are the API’s for writing tests that target iOS applications and the command line utilities for running the tests locally.
• calabash-android gem – these are the API’s for tests targeting Android applications and the command line utilities for running the tests locally.
• xamarin-test-cloud gem – this gem contains the command line utility test-cloud which is necessary to submit mobile applications and tests to Xamarin Test Cloud.

A Ruby gem is a self-contained package that is the standard format for distributing Ruby programs and libraries. Gems are typically hosted and distributed at RubyGems.org and are installed via the gem command line tool.

There are two ways to configure a working environment for creating and using Calabash scripts:

1. The Calabash Sandbox – this is a Bash script that installs Ruby and Calabash in a sandbox environment.
2. Maintain it yourself – Experienced Ruby developers and testers are encouraged to use rbenv to manage their Ruby version and Bundler to manage the Ruby gems on a per-project basis.

The Calabash Sandbox will create a sandbox environment that ensures you have the most compatible version of Ruby and current versions of the Ruby gems for the Calabash scripts.

The following guides are for those who will maintain their own Ruby environment:

• Updating Ruby using rbenv describes how to control what version of Ruby in use with the help of rbenv.
• Maintaining Calabash Gems using Bundler explains how to install and use Bundler

As well, in some situations it may be necessary to install the Xcode Command Line Tools as described in the Installing the Xcode Command Line Tools guide.

Requirements

It is assumed that developers already have Ruby installed and are comfortable using the command line and creating or editing text files with a text editor.

Calabash requires Ruby 2.0 or higher. Calabash is not supported on Ruby earlier than Ruby 2.0. Xamarin Test Cloud uses Ruby 2.3.1p112. For maximum compatibility with tests run locally and tests run in Test Cloud it is recommended that you use the same version while developing tests.

The following command line shows how to check what version of Ruby is installed:

$ ruby -v
ruby 2.1.7p400 (2015-08-18 revision 51632) [x86_64-darwin14.0]

This guide assumes that you are using Bash as your OS X shell. This guide will require some changes to work with other shells.