Installing Calabash on OS X

PDF for offline use
Related Articles:
Related Links:

Let us know how you feel about this

Translation Quality


0/250

last updated: 2016-10

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 strongly 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:

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. For testing iOS 10 apps, Ruby 2.3.1 is preferred.

Xamarin Test Cloud uses Ruby 2.1.6. 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.3.1p112 (2016-04-26 revision 54768) [x86_64-darwin15]

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

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.