Updating your Calabash iOS version

Calabash iOS

Calabash iOS has a client-server architecture. The Calabash iOS gem is the client side which communicates via HTTP with the server that is embedded in your app via the Objective-C calabash.framework.

The Calabash iOS gem and the calabash.framework versions must be compatible.

In general, when you update the Calabash iOS gem, you should update the calabash.framework as well.

Most problems can be traced back to incompatible gem and framework versions.

You can read more about Calabash iOS's architecture here: An Overview of Calabash iOS Architecture.

What version of the gem am I using?

$ calabash-ios version
0.16.3

What version of the server is embedded in my app?

Use curl.

Launch your app in the simulator and ask the server for the version.

$ curl http://localhost:37265/version

This is also the best way to determine if your app has properly linked the calabash.framework. If curl outputs "Failed to connect", you will know that your app has not properly linked the calabash.framework.

Query the executable.

You can query the executable for the version of the calabash.framework that it has linked.

$ xcrun strings path/to/MyApp-cal.app/MyApp-cal | grep -E 'CALABASH VERSION'
0.16.3

What is the version of the calabash.framework?

The following methods will tell you what version you have downloaded. It will not tell you what version of the framework is linked in your application. Use the steps above (curl or xcrun strings) to see what version is embedded in your app.

Use the version command line tool.

$ calabash.framework/Resources/version
0.16.3

Visually inspect the calabash.framework.

Note: tree is not installed by default on MacOS. It can be installed with homebrew or MacPorts.

$ tree calabash.framework
calabash.framework
├── Headers -> Versions/Current/Headers
├── Resources -> Versions/Current/Resources
├── Versions
│ ├── 0.16.3 -> A

Is the gem compatible with the embedded server?

Start your app manually in the simulator or from Xcode and then launch a console.

$ calabash-ios console
> server_version['version']
0.16.3
> Calabash::Cucumber::MIN_SERVER_VERSION
0.16.2

The server_version['version'] must be greater than or equal ( >= ) to the MIN_SERVER_VERSION.

Calabash will perform a runtime check to see if the server version is compatible with the gem version. Keep an eye out for warnings like this:

WARN: server version is not compatible with gem version
please update your server and gem
       gem version: '0.16.3'
min server version: '0.16.2'
    server version: '0.16.0'

If the server version is not compatible with the gem version, follow the directions below to update your application.

Updating Calabash iOS

There are 3 steps to updating Calabash iOS

1. Update the Calabash iOS gem,
2. Download the latest calabash.framework.
3. Clean your Xcode project, remove stale apps, and rebuild.

1. Updating the Calabash iOS gem

The name of the gem is 'calabash-cucumber', but we refer to it as Calabash iOS.

Use bundler

Best Practice: Use Gemfile and bundler

# Update your Gemfile to the version of calabash-ios you want.
1. gem 'calabash-cucumber', '>= 0.16.3', '< 2.0'

# Get the latest gem versions.
2. $ bundle update

Without bundler

Not using bundler and Gemfile? You should be.

$ gem update --system
$ gem uninstall -Vax --force --no-abort-on-dependent calabash-cucumber
$ gem install calabash-cucumber

Still installing gems with sudo?

If you are installing gems with sudo, you should stop. See Best Practice: Never install gems with sudo for alternatives and the dangers of sudo gem install.

2. Download the calabash.framework.

In the directory that contains the existing calabash.framework run the following:

# Check your version.
$ calabash-ios version
0.12.3

# Download the framework.
$ calabash-ios download

----------Info----------
Shall I delete it and download the latest matching version?
Please answer yes (y) or no (n)
y

# Check the framework version is correct.
$ calabash.framework/Resources/version
0.12.3

3. Clean, rebuild, and check.

1. Do a deep clean of your Xcode project.

• Xcode Project > Clean Build Folder... + Alt key or
• Shift + Option + Command + K

2. Remove your -cal.app from the simulator.

• UPDATE This step can be skipped as of Calabash 0.16.3.
• Reset the simulator with $ calabash-ios sim reset.
• Remove the calabash targets manually through the simulator UI.

3. Remove your -cal.app from physical devices.

This must be done manually or with third-party tools.

4. Rebuild and run your calabash target on a simulator.

Use the methods described above to verify the new version of the calabash server is embedded in your app.