Visual Studio App Center Test is the next generation of Xamarin Test Cloud! Read the blog post.

Using the Calabash Installer Script

Easily setting up a Calabash Environment on OS X

PDF for offline use
Related Links:

Let us know how you feel about this

Translation Quality


0/250

last updated: 2016-09

This guide describes how to install and use the Calabash Sandbox on OS X to get started with creating and using Calabash scripts.

Overview

The Calabash Sandbox is the best way for a novice to get started with Calabash. This is a Bash script that will establish a pre-configured Ruby environment with everything necessarily to creating and running tests.

The Calabash installer script will setup the Calabash Sandbox and the current gems for Calabash iOS, Calabash Android, and Xamarin Test Cloud. This will ensure maximum compatibility between a local test environment and the Xamarin Test Cloud environment.

The Calabash Sandbox ignores the default Ruby configuration on a computer and stores its files in the directory $HOME/.calabash/sandbox. The Sandbox shell has its own PATH, GEM_PATH, and GEM_HOME environment variables, which are updated to reference the Sandbox directory. When the Calabash Sandbox exits, these environment variables are restored to their previous values.

The Calabash Installer will not check to see if the Calabash gems which are currently installed are the most current or up to date gems. The guide Determining the Calabash Version describes how to check what versions of the Calabash gems are installed. How to update the gems is described later on in this guide.

Requirements

The Calabash Installer script is only available for OS X Yosemite and OS X El Capitan.

The use of Ruby environment managers such as rbenv or RVM in the Calabash Sandbox is not supported.

Usage

To install the Calabash Sandbox, run the following script in a Terminal session:

curl -sSL https://raw.githubusercontent.com/calabash/install/master/install-osx.sh | bash

Do not use sudo to install the Calabash Sandbox.

When installation completes, you should see something like the following:

Preparing Ruby 2.1.6-p336...
######################################################################## 100.0%
Installing gems, this may take a little while...
######################################################################## 100.0%
Preparing sandbox...
######################################################################## 100.0%
Done! Installed:
calabash-ios:       0.19.2
calabash-android:   0.7.3
xamarin-test-cloud: 2.0.0
Execute 'calabash-sandbox update' to check for gem updates.
Execute 'calabash-sandbox' to get started!

At this point, you can execute calabash-sandbox in a Terminal session to initiate a sandbox environment. To leave the sandbox environment and return the Terminal session to its previous state, type exit.

Installing Gems

Any gems that are installed with the Calabash Sandbox is running will be kept in the Sandbox's GEM_HOME directory, isolated from the default Ruby environment used by OSX and not available outside of the Sandbox.

Updating the Calabash Gems

It may be necessary, from time to time, to manually updated the gems that are used by the Calabash Sandbox. To update the gems, use the update command for the sandbox:

$ calabash-sandbox update
Updating gems...
Fetching gem metadata from https://rubygems.org/..........
Fetching version metadata from https://rubygems.org/..
Fetching dependency metadata from https://rubygems.org/.
Resolving dependencies...
Using CFPropertyList 2.3.3
Using awesome_print 1.7.0
Using builder 3.2.2
Using bundler 1.13.1
Using gherkin 4.0.0
Using cucumber-wire 0.0.1
Using diff-lcs 1.2.5
Using multi_json 1.12.1
Using multi_test 0.1.2
Using escape 0.0.4
Using httpclient 2.8.2.4
Using json 1.8.3
Installing retriable 2.0.2
Using thor 0.19.1
Using rubyzip 1.2.0
Using clipboard 1.1.1
Using edn 1.1.1
Using geocoder 1.4.0
Using command_runner_ng 0.1.0
Using i18n 0.7.0
Installing mime-types 2.99.3
Using cucumber-core 1.5.0
Using luffa 2.0.0
Using run_loop 2.2.0
Using xamarin-test-cloud 2.0.0
Using cucumber 2.4.0
Using slowhandcuke 0.0.3
Installing calabash-android 0.8.2
Using calabash-cucumber 0.20.0
Bundle updated!

Done! Now the sandbox contains:
calabash-ios:       0.20.0
calabash-android:   0.8.2
xamarin-test-cloud: 2.0.0

Restoring the Sandbox

It is possible to reset the Sandbox environment to the original state by running the following commands in the Terminal:

rm -r ${HOME}/.calabash/sandbox
curl -sSL https://raw.githubusercontent.com/calabash/install/master/install-osx.sh | bash

Troubleshooting

This section will identify some common problems when using the Calabash Sandbox and how to address them.

I get the error message /usr/local/bin is not writeable

The script attempts to install the sandbox executable to /usr/local/bin so that it can be easily invoked from the command line. However, if you don't have write permissions in that dir, the install script will not be able to move the script there. You can still run it locally by executing:

./calabash-sandbox

from the same directory as you ran the install script.

If you'd like to install it globally, either have an administrator move the calabash-sandbox executable to somewhere in your PATH or modify your .bash_profile, .profile, .zsh etc. to find calabash-sandbox in your PATH. It is not recommended to run the install script under sudo.

I installed the Calabash Sandbox using sudo and now can't restart it

You are strongly discouraged from installing the Calabash Sandbox using sudo. If you have problems starting the Calabash Sandbox after installing it with sudo then you should uninstall the Sandbox by executing:

sudo rm -r ${HOME}/.calabash/sandbox

This will uninstall the the Calabash Sandbox. Install it again, without using sudo.

Summary

This guide discussed how to install and use the Calabash Sandbox to get started with creating and running Calabash test scripts.

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.