Calabash Plug In for Frank

FRANK SUPPORT WILL BE DROPPED IN 0.19.0

The content on this page is out of date.

As of 0.10.0, Calabash can be used a plug-in for Frank. This is an alpha-level feature, which is our way of saying, "We haven't worked out all the kinks yet."

Feedback is welcomed and encouraged! We need your feedback to make this plug-in better.

• https://groups.google.com/forum/?fromgroups=#!forum/calabash-ios
• https://groups.google.com/forum/?fromgroups=#!forum/frank-discuss

Please do not cross-post. We monitor both Google groups.

Getting Started

To install the Frank-Calabash plugin, make sure you're using Frank 1.2.3 or above and Calabash iOS version 0.10.0 or above.

Installing

In your Frank project run the command:

# copies libFrankCalabash.a to Frank/plugins/calabash/
$ frank-calabash install
$ frank build

Uninstalling

To uninstall, run:

$ frank-calabash uninstall
$ frank build

Getting started

To use Calabash with Frank, you must modify your test scripts and hooks to let Calabash launch your app using instruments. Using Frank's sim_launcher doesn't work as Calabash relies on Apple's "public" UIAutomation launched with instruments.

Update your features/support/env.rb to include:

require 'frank-calabash'
require 'calabash-cucumber/operations'

You can then include the Frank::Calabash module which provides two important methods:

• launch allows launching using instruments [1]
• calabash_client an object that provides access to the Calabash API [2]

• [1] http://calabashapi.xamarin.com/ios/Calabash/Cucumber/Launcher.html#relaunch-instance_method
• [2] http://calabashapi.xamarin.com/ios/Calabash/Cucumber/Core.html

Using the Calabash API

$ frank-calabash console
> launch(:uia_strategy => :preferences) # other strategies are available too 

# Uses Calabash Selector engine for Frank methods
> frankly_map("* {text BEGINSWITH 'foo'}", :touch) # for example, Calabash supports NSPredicate queries

# Access the Calabash API via the client object
> calabash = calabash_client()
> calabash.touch("* marked:'Second'")
> calabash.swipe(:left)
> client.query("webView css:'a'") # Hybrid/UIWebView support
> client.touch("webView css:'a'") # Touch a link in a web view
> client.send_app_to_background(4) # Calls UIAutomations deactivateAppForDuration

For an informal demo: http://screencast.com/t/hBtcdwzelfO

On-Device Testing

Frank does not support building a Frankified app for on-device testing. We have been able to run Frank-Calabash on devices using the steps below. These steps may or may not work for you.

We used the LPSimpleExample as our test project.

https://github.com/calabash/calabash-ios-example

First, make sure you've run:

$ frank setup
$ frank-calabash install
$ frank build

and you have verified that frank-calabash is working against the simulator.

Then you must build and and package your application.

build-frank-calabash.sh

#!/bin/sh

FRANK_LIB="/Users/krukow/code/calabash-ios-example/Frank"
FRANK_CAL_LIB="/Users/krukow/code/calabash-ios-example/Frank/plugins/calabash"

xcrun xcodebuild \
    -xcconfig Frank/frank.xcconfig \
    -arch armv7s \
    -configuration Debug \
    -sdk iphoneos \
    ONLY_ACTIVE_ARCH=NO \
    DEPLOYMENT_LOCATION=YES \
    DSTROOT="/Users/krukow/code/calabash-ios-example/Frank/frankified_build" \
    FRANK_LIBRARY_SEARCH_PATHS="\"${FRANK_LIB}\" \"${FRANK_CAL_LIB}\"" \
    clean build

# optionally resign the application
xcrun -sdk iphoneos PackageApplication \
    -v /Users/krukow/code/calabash-ios-example/Frank/frankified_build/LPSimpleExample.app \
    -o "${PWD}/frank.ipa"

To launch the app on the device, use the frank console.

$ frank-calabash console
> launch(app:'com.lesspainful.example.LPSimpleExample', device_target:'device')

LPSimpleExample

Intro...

To try the Frank-Calabash plugin support do the following.

1. Make sure frank version 1.2.3 or above is installed. (gem install frank-cucumber)

2. Make sure Calabash version 0.10.0 or above is installed (gem install calabash-cucumber).

3. Run frank setup: frank setup (if using rbenv remember to run rbenv rehash after installing frank).

   I found more than one target in this project. Which is the main app target that you wish to Frankify?

   1: LPSimpleExample
   2: LPSimpleExample-cal
   > 1

4. Run frank-calabash install to install the Calabash plugin to frank:

   frank-calabash install
   Creating directory Frank/plugins/calabash
   Copied files Frank/plugins/calabash/calabash.xcconfig.erb, Frank/plugins/calabash/libFrankCalabash.a

   Installed Frank-Calabash plugin.
   Please rebuild using frank build.

5. Run frank build to build the project for simulator. Verify the successful build of: "./Frank/frankified_build/Frankified.app".

Now it's time to tryout the Frank-Calabash console:

$ frank-calabash console
[1] pry(#<Frank::Console>)> launch
=> nil
[2] pry(#<Frank::Console>)> c = calabash_client
=> #<Frank::Calabash::Client:0x007fb3290f4c48>
[3] pry(#<Frank::Console>)> c.query("button")
=> [{"class"=>"UIRoundedRectButton",
  "id"=>nil,
  "rect"=>
   {"center_x"=>136,
    "y"=>287,
    "width"=>72,
    "x"=>100,
    "center_y"=>305.5,
    "height"=>37},
  "frame"=>{"y"=>287, "width"=>72, "x"=>100, "height"=>37},
  "label"=>"BAL:42",
  "description"=>
   "<UIRoundedRectButton: 0x17650a80; frame = (100 287; 72 37); opaque = NO; autoresize = RM+BM; layer = <CALayer: 0x17650c10>>"},
 {"class"=>"UIRoundedRectButton",
  "id"=>nil,
  "rect"=>
   {"center_x"=>145.5,
    "y"=>215,
    "width"=>73,
    "x"=>109,
    "center_y"=>233.5,
    "height"=>37},
  "frame"=>{"y"=>215, "width"=>73, "x"=>109, "height"=>37},
  "label"=>"login",
  "description"=>
   "<UIRoundedRectButton: 0x17648e50; frame = (109 215; 73 37); opaque = NO; autoresize = RM+BM; layer = <CALayer: 0x176491c0>>"}]
[6] pry(#<Frank::Console>)> c.touch("view marked:'Second'")
=> [{"class"=>"UITabBarButton",
  "id"=>nil,
  "rect"=>
   {"center_x"=>120, "y"=>520, "width"=>76, "x"=>82, "center_y"=>544, "height"=>48},
  "frame"=>{"y"=>1, "width"=>76, "x"=>82, "height"=>48},
  "label"=>"Second",
  "description"=>
   "<UITabBarButton: 0x17573150; frame = (82 1; 76 48); opaque = NO; layer = <CALayer: 0x17573680>>"}]
[7] pry(#<Frank::Console>)> launch(app:'com.lesspainful.example.LPSimpleExample', device_target:'device')
[7] pry(#<Frank::Console>)>