Maintaining Calabash Gems using Bundler

PDF for offline use
Related Links:

Let us know how you feel about this


last updated: 2016-09

This section will discuss an alternative way to install and maintain the Calabash gems on OS X using Bundler. Bundler is a tool that manages gems for Ruby applications – it tracks the dependencies and version numbers at the project level. It helps developers ensure that each Ruby project has the correct gems for that project. Bundler assumes that a Ruby project will exist in it's own directory.

Bundler allows developers greater control over what gems are used in each project. For this reason, the use of Bundler is strongly encouraged.

It is strongly recommended to use Ruby 2.3.1; the same version of Ruby that is used in Xamarin Test Cloud. This will minimize any issues that may arise from different versions of Ruby.

Installing Bundler

Bundler is installed as a system wide gem. It is installed just like any other gem:

gem install bundler
Fetching: bundler-1.13.1.gem (100%)
Successfully installed bundler-1.13.1
Parsing documentation for bundler-1.13.1
Installing ri documentation for bundler-1.13.1
Done installing documentation for bundler after 6 seconds
1 gem installed

You can confirm that Bundler is installed by type

$ bundler -v
Bundler version 1.13.1

Using Bundler

Bundler makes use of a special text file called a Gemfile, which contains a list of all the gems that a Calabash project will use. To create the Gemfile was created by type the following command in the directory that will hold your Calabash tests:

$ bundler init

As an example, consider the following screenshot for the TaskyPro project:

In this example, the solution directory for TaskyPro will hold the Calabash scripts. This is where bundler init was run, creating an empty Gemfile.

Installing the Calabash gems

To install and manage gems using Bundler, edit the Gemfile for your project, as shown below:

source ''
gem 'calabash-cucumber', '0.20.0'
gem 'calabash-android', '0.8.2'
gem 'xamarin-test-cloud', '2.0.0'

The first line tells Bundler where to look for the gems. The remaining lines declare the dependencies that Bundler must maintain. Each line contains the name of the gem and the version number of the gem to install. These gems are actively maintained and are frequently updated. You are strongly encouraged to install the most recent version of each gem, which can be determined from

Once the Gemfile is created, invoke Bundler, passing it the install command:

$ bundle install

Bundler will install the request gems along with all the necessary dependencies. When Bundler is finished, it will create another text file called Gemfile.lock. This file that will keep track of all the gems and dependencies that were installed, and should be checked in to source code control. This file should not be modified directly as it is maintained by Bundler.

Running gems with Bundler

In order to run gems in the context of the bundle, it is necessary to run the binary commands provided by gems using the bundle exec command.

For example, the following snippet shows the version of calabash-cucumber specific to a project:

$ bundle exec calabash-ios version

In contrast, running calabash-ios version without using bundler exec may provide the following output:

$ calabash-ios version

Updating Gems with Bundler

To update the gems managed by Bundler, edit the Gemfile to reflect the update gems and re-run bundle install.


This guide discussed how to install and maintain the Calabash gems using Bundler.

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.