Calabash Plug In for Frank

Joshua Moody edited this page Mar 21, 2016 · 3 revisions


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.

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.


In your Frank project run the command:

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


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]

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:

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.

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.


xcrun xcodebuild \
    -xcconfig Frank/frank.xcconfig \
    -arch armv7s \
    -configuration Debug \
    -sdk iphoneos \
    DSTROOT="/Users/krukow/code/calabash-ios-example/Frank/frankified_build" \
    clean build

# optionally resign the application
xcrun -sdk iphoneos PackageApplication \
    -v /Users/krukow/code/calabash-ios-example/Frank/frankified_build/ \
    -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')



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
  1. 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.
  1. Run frank build to build the project for simulator. Verify the successful build of: "./Frank/frankified_build/".

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",
  "frame"=>{"y"=>287, "width"=>72, "x"=>100, "height"=>37},
   "<UIRoundedRectButton: 0x17650a80; frame = (100 287; 72 37); opaque = NO; autoresize = RM+BM; layer = <CALayer: 0x17650c10>>"},
  "frame"=>{"y"=>215, "width"=>73, "x"=>109, "height"=>37},
   "<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",
   {"center_x"=>120, "y"=>520, "width"=>76, "x"=>82, "center_y"=>544, "height"=>48},
  "frame"=>{"y"=>1, "width"=>76, "x"=>82, "height"=>48},
   "<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>)>
Clone this wiki locally
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.