Skip to content

Commit

Permalink
Merge pull request #892 from calabash/feature/README-teardown
Browse files Browse the repository at this point in the history 
README rewrite for 0.17
  • Loading branch information
@jmoody
jmoody committed Oct 28, 2015
2 parents 28fde13 + 0c8da56 commit 5919cb8
Show file tree
Hide file tree
Showing 6 changed files with 56 additions and 439 deletions.
234 changes: 56 additions & 178 deletions README.md
View file
Expand Up @@ -2,7 +2,7 @@
|---------|---------|-----------------------------|--------------------|--------------------------------|
|[![Build Status](https://travis-ci.org/calabash/calabash-ios.svg?branch=master)](https://travis-ci.org/calabash/calabash-ios)| [![Build Status](https://travis-ci.org/calabash/calabash-ios.svg?branch=develop)](https://travis-ci.org/calabash/calabash-ios-server)| [![GitHub version](https://badge.fury.io/gh/calabash%2Fcalabash-ios.svg)](http://badge.fury.io/gh/calabash%2Fcalabash-ios) |[![License](https://img.shields.io/badge/licence-Eclipse-blue.svg)](http://opensource.org/licenses/EPL-1.0) | [![Contributing](https://img.shields.io/badge/contrib-gitflow-orange.svg)](https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow/)|

## Welcome to Calabash iOS
## Calabash iOS

[http://calaba.sh/](http://calaba.sh/)

Expand All @@ -12,216 +12,96 @@ Calabash is a free-to-use open source project that is developed and maintained b

While Calabash is completely free, Xamarin provides a number of commercial services centered around Calabash and quality assurance for mobile, namely Xamarin Test Cloud consisting of hosted test-execution environments which let you execute Calabash tests on a large number of Android and iOS devices. For more information about the Xamarin Test Cloud visit [http://xamarin.com/test-cloud](http://xamarin.com/test-cloud).

## Quick Links

* [Getting Help](https://github.com/calabash/calabash-ios/wiki#getting-help)
* [Reporting Problems](https://github.com/calabash/calabash-ios/wiki#reporting-problems)
* [Public API](http://calabashapi.xamarin.com/ios/)
* [Xamarin Studio + Ruby Client](http://developer.xamarin.com/guides/testcloud/calabash/configuring/)
* [Xamarin Studio + UITest](http://developer.xamarin.com/guides/testcloud/uitest/)
* [Contributing](CONTRIBUTING.md)
* [CHANGELOGS](https://github.com/calabash/calabash-ios/tree/master/changelog)

## Setup and Requirements
## Requirements

Xamarin Studio users should visit [http://developer.xamarin.com/testcloud/](http://developer.xamarin.com/testcloud/) for setup instructions and requirements.

We recommend that you use the most recent released version of Xcode, MacOS, and Ruby.

* MacOS 10.9 or 10.10
* MacOS 10.10 or 10.11
* Xcode 6 or 7
* iOS >= 7.1
* ruby 1.9.3 - 2.2.+

We recommend that you use a managed ruby like [rbenv](https://github.com/sstephenson/rbenv) or [rvm](https://rvm.io/). If you prefer to stick with the pre-installed ruby on MacOS, please avoid installing gems with `sudo`. Simply put, using `sudo` is dangerous. Follow these [excellent instructions](http://developer.xamarin.com/guides/testcloud/calabash/configuring/osx/installing-gems/) for a ruby setup that avoids `sudo`.

The [best practice](http://developer.xamarin.com/guides/testcloud/calabash/configuring/osx/maintaining-gems-with-bundler/) is to always use a Gemfile and bundler.

### Alternative Setups

The traditional setup creates a separate Xcode target application that mirrors your original application except that it link to the Calabash server library. We call this new target the _-cal target._

_Why a separate target?_

>The Calabash server contains symbols and methods that will cause any application that links to it to _be rejected from the AppStore_. A separate target with a different bundle identifier will ensure that you never accidently submit an application that has the Calabash server linked.
If the separate -cal target does not suit your needs, there are many other ways to setup your project. The community has collected these alternative methods for integrating Calabash into your Xcode project.

* [Using Xcode Configuration instead of a separate target](http://fangmobile.com/2014/05/08/do-you-love-calabash-ios-but-hate-that-cal-second-target/) Jian Fang and David Siegel
* [Load Calabash dylibs in Debug configuration at runtime](https://github.com/calabash/ios-smoke-test-app/pull/17)
* [CocoaPods](http://angelolloqui.com/blog/25-Acceptance-testing-with-Calabash-and-CocoaPods) Angel G. Olloqui

If you are not already using CocoaPods, we don't recommend adopt CocoaPods just to link the Calabash library.

## Setup: Fast Track

The fast-track instructions are EXPERIMENTAL, but in our experience they work for most iOS projects.

If it doesn't work in your project, see the "Manual setup with Xcode" section below.

Starting in Xcode 6, we've had trouble maintaining the setup tools. If you have a problem see [calabash-ios setup fails on fresh Xcode 6 project](https://github.com/calabash/calabash-ios/issues/533).

For automatic setup:

1. In a terminal, go to your iOS project
- `cd path-to-my-ios-project` (i.e. directory containing .xcodeproj file)

2. Install calabash-cucumber gem (this make take some time because of dependencies)
- `gem install calabash-cucumber`

3. Setup your project for Calabash-iOS.
- `calabash-ios setup` Answer the questions and read the output :)

4. Generate a skeleton features folder for your tests
- `calabash-ios gen`

5. In Xcode, build your project using the <project-name>-cal scheme
- ![-cal scheme](documentation/images/scheme.png "-cal scheme")

6. Run the generated test!
- `cucumber`

If all goes well, you are now ready to write your first test. Start by editing the file `features/my_first.feature`.

Proceed by reading details about installation below, or moving on to the
[Getting started guide](https://github.com/calabash/calabash-ios/wiki/00-Calabash-iOS-documentation).

## Setup: Manually Create a -cal target

### Background
* iOS Devices >= 7.1
* iOS Simulators >= 8.0
* ruby >= 2.0 (latest is preferred)

To use Calabash for iOS in your app, you must do two things: link with our framework: `calabash.framework`, and install a ruby gem as described below. You also need to link with Apple's CFNetwork framework if you are not already using this.
We recommend that you use a managed ruby (_e.g._ [rbenv](https://github.com/sstephenson/rbenv), [rvm](https://rvm.io/)) or manually manage your gem environment with [this script](http://developer.xamarin.com/guides/testcloud/calabash/configuring/osx/installing-gems/).

For functional testing with Calabash iOS, you should create a whole separate target by duplicating your production target in Xcode (explained below).
For more information about ruby on MacOS, see these Wiki pages:

### Ruby and calabash-cucumber gem.
* [Ruby on MacOS](https://github.com/calabash/calabash-ios/wiki/Ruby-on-MacOS)
* [Best Practice: Never install gems with sudo](https://github.com/calabash/calabash-ios/wiki/Best-Practice%3A--Never-install-gems-with-sudo)

* Install the `calabash-cucumber` gem. (You may need to do `sudo gem install calabash-cucumber`)
## Getting Started

$ gem install calabash-cucumber
Successfully installed calabash-cucumber-0.9.47
1 gem installed
Installing ri documentation for calabash-cucumber-0.9.47...
Installing RDoc documentation for calabash-cucumber-0.9.47...
If you want to see Calabash iOS in action, head over to the [Calabash iOS Smoke Test App](https://github.com/calabash/ios-smoke-test-app) and follow the instructions in the README. We use this app to document, demonstrate, and test Calabash iOS. You can use this app to explore Calabash and as an example for how to configure your Xcode project and Calabash workflow.

### Step 1: Link calabash.framework

### Setting up Xcode project
To start using Calabash in your project, you need to link an Objective-C framework (calabash.framework) to your application.

Instructions:
|Tutorial|Description|
|:--------:|-----------|
|[Debug Config](https://github.com/calabash/calabash-ios/wiki/Tutorial%3A-Link-Calabash-in-Debug-config) | Use linker flags in the Debug build config to load the calabash.framework |
|[Calabash Config](https://github.com/calabash/calabash-ios/wiki/Tutorial%3A-Calabash-config) | Create a new Calabash Build Configuration |
|[-cal Target](https://github.com/calabash/calabash-ios/wiki/Tutorial%3A--Creating-a-cal-Target) | Add a new app target to Xcode.|

* Step 1/3 is to duplicate your primary/production target.
- Select your project in Xcode and select your production target for your app.
- Right click (or two-finger tap) your target and select "Duplicate target"
- Select "Duplicate only" (not transition to iPad)
- Rename your new target from ".. copy" to "..-cal"
- From the menu select Edit Scheme and select manage schemes.
- Rename the new scheme from ".. copy" to "..-cal"
- Optionally, set the Product name to ..-cal in Build settings for the new target.
If you want to get started quickly, follow the [Debug Config](https://github.com/calabash/calabash-ios/wiki/Tutorial%3A-Link-Calabash-in-Debug-config) instructions. The [Tutorial: How to add Calabash to Xcode](https://github.com/calabash/calabash-ios/wiki/Tutorial%3A-How-to-add-Calabash-to-Xcode) wiki page discusses the merits of each approach and has instructions for using CocoaPods.

* Step 2/3: Link with framework.
- Download the latest version of calabash.framework with calabash-ios gem command:
- `calabash-ios download`
- Use Finder to open the folder that contains `calabash.framework`.
- Drag `calabash.framework` from Finder into your project's `Frameworks` folder in Xcode.
* **Make sure that**
1. `Copy items into destination group's folder (if needed)` *is checked* and
2. _only_ your "-cal " target is checked in `Add to targets`.
### Step 2: Run Cucumber against an iOS Simulator

![Linking with calabash.framework](documentation/images/Frameworks.png "Linking with frameworks")
- You must also link you -cal target with `CFNetwork.framework` (unless your production target
is already linking with `CFNetwork`). To do this click on your -cal target in XCode. Click on
Build Phases, expand Link Binary with Libraries, click `+` to add `CFNetwork.framework`.


* Step 3/3: cal-Target Build Settings
- Click on your project and select your new "-cal" target.
- Select "Build Settings".
- Ensure that "All" and not "Basic" settings are selected in "build settings".
- Find "Other Linker Flags" (you can type "other link" in the search field).
- Ensure that "Other linker flags" contains: `-force_load "$(SRCROOT)/calabash.framework/calabash" -lstdc++`

*Note*: Now that you have created a separate target, new files that you add to your project are not automatically added to your -LP target. Make sure that any new files you add to your production target are also added to your -LP target.


This screenshot is a reference for you build settings.

![Build settings](documentation/images/linker_flags.png "Build settings")


### Test that `calabash.framework` is loaded.

Make sure you select your "..-cal" scheme and then run you app on 4.x/5 simulator.

Verify that you see console output like

2012-01-19 LPSimpleExample[4318:11603] Creating the server: <HTTPServer: 0x7958d70>
2012-01-19 LPSimpleExample[4318:11603] HTTPServer: Started HTTP server on port 37265
2012-01-19 LPSimpleExample[4318:13903] Bonjour Service Published: domain(local.) type(_http._tcp.) name(Calabash Server)


## Calabash 2.0

Calabash 2.0 is a merge of the iOS and Android APIs. Read the [Announcement: Calabash 2.0](https://github.com/calabash/calabash/issues/55) for details and to make comments.

## Frank

Calabash can be used as a Frank plug-in for [Frank project](https://github.com/TestingWithFrank/Frank). The idea being to unify the communities more, although full unification will not be possible currently (as Calabash focuses on supporting on-device testing which is not currently a specific design-goal of Frank). For instructions on how it integrate Calabash into your Frank project see the [README_FRANK.md](README_FRANK.md) document.

## Important notice

The Calabash framework uses private Apple APIs to synthesize touch events. This means that you should double check that `calabash.framework` is not included in the .ipa file you submit to App Store. This is usually done by creating a separate build configuration or target for the version of your app running calabash tests.

An experimental check can be done by the calabash-ios tool
The [Calabash iOS Example](https://github.com/calabash/calabash-ios-example) README has simple instructions for how to link the calabash.framwork, generate a features directory, run cucumber, and and open a Calabash console.

```
calabash-ios check PATH_TO_IPA_OR_APP
# In the directory where your .xcodeproj and Gemfile are
$ bundle exec calabash-ios gen
```

This is not guaranteed to work; it is your responsibility to ensure that the framework is properly installed.
Build and run in Xcode, targeting an iOS Simulator. Calabash will try to detect the .app you just built.

## How does automated setup work?
```
$ bundle exec cucumber
```

If you're interested in what's going on you can read the installation details here.
If Calabash cannot find the .app you just built, it will raise an error. If this happens, you will to tell Calabash where it can find your .app.

Verify that you have installed calabash-cucumber correctly by running `calabash-ios` from the command line:
By default, Xcode builds to a DerivedData directory:

```
$ calabash-ios
Usage: calabash-ios <command-name> [parameters]
<command-name> can be one of
help
prints more detailed help information.
gen
generate a features folder structure.
setup (EXPERIMENTAL) [opt path]?
setup your XCode project for calabash-ios
...
~/Library/Developer/Xcode/DerivedData/<UDID>/Build/Products/Debug-iphonesimulator/<NAME>.app
```

When you run `calabash-ios setup` and answer any questions it might ask the following happens:
Try to locate the .app and set the `APP` variable:

Note that calabash-ios will backup your project file:
```
$ export APP="~/Library/Developer/Xcode/DerivedData/<UDID>/Build/Products/Debug-iphonesimulator/<NAME>.app"
$ bundle exec cucumber
```

$ calabash-ios setup
Checking if Xcode is running...
----------Info----------
Making backup of project file: ~/sample/sample.xcodeproj/project.pbxproj
...
We recommend using scripts and/or changing the location where Xcode stages build products.

The project file is copied to `project.pbxproj.bak`. In case something goes wrong you can move this file back to `project.pbxproj` (in your .xcodeproj) folder.
* Tutorial: Build scripts **WIP**
* Tutorial: Xcode Location Settings **WIP**

Setup will modify your xcode project file to use `calabash-ios`. You should now have a new Scheme named [target]-cal in Xcode:
### Where to go from here?

![-cal scheme](documentation/images/scheme.png "-cal scheme")
| Topic | Description |
|-------|-------------|
| [Getting Started](https://github.com/calabash/calabash-ios/wiki/Getting-Started) | A more in-depth tutorial using the LPSimpleExample. |
| [Testing on Physical Devices](https://github.com/calabash/calabash-ios/wiki/Testing-on-Physical-Devices) | Everything you need to know about testing on physical devices. |
| [API Docs](http://calabashapi.xamarin.com/ios) | The Calabash iOS ruby API |
| [iOS Smoke Test App](https://github.com/calabash/ios-smoke-test-app) | Demonstrates advanced features, setups, and workflows|
| [iOS WebView Test App](https://github.com/calabash/ios-webview-test-app) | Demonstrates how to interact with UIWebView and WKWebView|
| [Getting Help](https://github.com/calabash/calabash-ios/wiki) | The Calabash iOS Wiki |

`calabash-ios setup` does the following:
## Links

- creates a new -cal target as a copy of your primary target
- add the calabash.framework to your Frameworks folder
- add $(SRCROOT) to framework search path (for that target)
- link with calabash.framework (for that target)
- link with Apple's CFNetwork.framework (for that target)
- set the special `-force_load` and `-lstdc++` linker flags (for that target)
* [Getting Help](https://github.com/calabash/calabash-ios/wiki#getting-help)
* [Reporting Problems](https://github.com/calabash/calabash-ios/wiki#reporting-problems)
* [Public API](http://calabashapi.xamarin.com/ios/)
* [Xamarin Studio + Ruby Client](http://developer.xamarin.com/guides/testcloud/calabash/configuring/)
* [Xamarin Studio + UITest](http://developer.xamarin.com/guides/testcloud/uitest/)
* [Contributing](CONTRIBUTING.md)
* [CHANGELOGS](https://github.com/calabash/calabash-ios/tree/master/changelog)

## License

Expand All @@ -234,5 +114,3 @@ By using this software in any fashion, you are agreeing to be bound by
the terms of this license. You must not remove this notice, or any other,
from this software.
```


14 changes: 0 additions & 14 deletions documentation/README.md
View file

This file was deleted.

Binary file removed documentation/images/Frameworks.png
View file
Binary file not shown.
Binary file removed documentation/images/linker_flags.png
View file
Binary file not shown.
Binary file removed documentation/images/scheme.png
View file
Binary file not shown.

0 comments on commit 5919cb8

Please sign in to comment.