Tutorial: How to add Calabash to Xcode
Calabash iOS is a client/server architecture. The client is the calabash-cucumber gem. The server is an Objective-C framework that is linked to your app. When your app is launched, the HTTP server starts automatically.
We have written three tutorials that demonstrate how to integrate Calabash into your Xcode project.
| Tutorial | Description |
|---|---|
| [[Debug Config | Tutorial:-Link-Calabash-in-Debug-config]] |
| [[Calabash Config | Tutorial:-Calabash-config]] |
| [[-cal Target | Tutorial:--Creating-a-cal-Target]] |
The Calabash in Debug Configuration is the easiest to understand, set up, and maintain. It is not as flexible as the other two options, but if you are just starting with Calabash you probably don't need and won't miss the flexibility.
The Calabash Configuration is easy to set up and maintain. It has the advantage of logically separating your Debug and Release builds from those builds that include the Calabash server. Creating preprocessor macros to include or exclude code blocks at compile time is easy with a Calabash configuration. This might be important to you plan to make use of Calabash's backdoor features.
The -cal target setup is more difficult to set up and maintain. This setup creates a physical and logical separation of your production app and the app that is linked with Calabash. You might want to choose this setup if you organization has strict rules about maintaining a pristine production app. This is setup is very flexible and offers some advantages that the other setups do not.
Don't worry about making the best choice for your app - you can also switch to a different setup. If you are just starting out or want to evaluate Calabash, use the Calabash in Debug Configuration.
If you are not already using CocoaPods in your project, we do not recommend that use CocoaPods to integrate Calabash into your project. We have nothing against CocoaPods, but it is, itself, a dependency that must be managed. As you can see from the tutorials, it is fast and easy to integrate Calabash into your Xcode project. CocoaPods adds a layer of complexity that is not warranted in this case in our opinion.
If you are already using CocoaPods in your project, you might find it easier to set up and maintain your Calabash integrate manually rather than relying on the Pod. We don't maintain the podspec and it is often slow to be updated. From our own experience and from user feedback we know that integrating Calabash with Xcode using CocoaPods can be painful - especially if you are trying maintain a separate -cal target.
Angel G. Olloqui has written a nice blog post: Acceptance Testing with Calabash and CocoaPods with solid instructions.
CocoaPods discussions are often contentious. As mentioned above, we have nothing against CocoaPods. Its goals are, in a word, admirable.
In our experience, one of the biggest hurdles to adopting and using Calabash is integrating the calabash.framework into your Xcode project. The calabash-cucumber gem ships with a command line tool: calabash setup. Unfortunately, this tool has been broken since Xcode 6. As you can imagine, any tool that tries to edit an Xcode project file is difficult to maintain. The setup tools creates the -cal target mentioned below. We've included the original setup instructions on this wiki page. However, we encourage you to take a look at the tutorials below rather than run the setup tool.