frank-cucumber 0.9.4 → 0.9.5.pre1

data/lib/frank-cucumber/frank_helper.rb

@@ -7,73 +7,128 @@ require 'frank-cucumber/bonjour'
 
 module Frank module Cucumber
 
+  # FrankHelper provides a core set of helper functions for use when interacting with Frank.
+  #
+  # == Most helpful methods
+  # * {#touch}
+  # * {#wait_for_element_to_exist}
+  # * {#wait_for_element_to_exist_and_then_touch_it}
+  # * {#wait_for_nothing_to_be_animating}
+  # * {#app_exec}
+  #
+  # == Configuring the Frank driver
+  # There are some class-level facilities which configure how all Frank interactions work. For example you can specify which selector engine to use 
+  # with {FrankHelper.selector_engine}. You can specify the base url which the native app's Frank server is listening on with {FrankHelper.server_base_url}.
+  #
+  # Two common use cases are covered more conveniently with {FrankHelper.use_shelley_from_now_on} and {FrankHelper.test_on_physical_device_via_bonjour}.
 module FrankHelper 
   include WaitHelper
   include KeyboardHelper
   include HostScripting
 
+  # @!attribute [rw] selector_engine
   class << self
-    # TODO: adding an ivar to the module itself is a big ugyl hack. We need a FrankDriver class, or similar
-    attr_accessor :selector_engine, :server_base_url
+    # @return [String] the selector engine we tell Frank to use when interpreting view selectors. 
+    attr_accessor :selector_engine
+    # @return [String] the base url which the Frank server is running on. All Frank commands will be sent to that server.
+    attr_accessor :server_base_url
 
+    # After calling this method all subsequent commands will ask Frank to use the Shelley selector engine to interpret view selectors.
     def use_shelley_from_now_on
       @selector_engine = 'shelley_compat'
     end
 
+    # Use Bonjour to search for a running Frank server. The server found will be the recipient for all subsequent Frank commands.
+    # @raise a generic exception if no Frank server could be found via Bonjour
     def test_on_physical_device_via_bonjour
       @server_base_url = Bonjour.new.lookup_frank_base_uri
       raise 'could not detect running Frank server' unless @server_base_url
     end
   end
 
+  #@api private
+  #@return [:String] convient shorthand for {Frank::Cucumber::FrankHelper.selector_engine}, defaulting to 'uiquery'
   def selector_engine
     Frank::Cucumber::FrankHelper.selector_engine || 'uiquery' # default to UIQuery for backwards compatibility
   end
 
+  #@api private
+  #@return [:String] convient shorthand for {Frank::Cucumber::FrankHelper.server_base_url}
   def base_server_url
     Frank::Cucumber::FrankHelper.server_base_url
   end
   
-
-
-  def touch( uiquery )
-    touch_successes = frankly_map( uiquery, 'touch' )
-    raise "could not find anything matching [#{uiquery}] to touch" if touch_successes.empty?
+  # Ask Frank to touch all views matching the specified selector. There may be views in the view heirarchy which match the selector but
+  # which Frank cannot or will not touch - for example views which are outside the current viewport. You can discover which of the matching
+  # views were actually touched by inspecting the Array which is returned.
+  #
+  # @param [String] selector a view selector.
+  # @return [Array<Boolean>] an array indicating for each view which matched the selector whether it was touched or not.
+  # @raise an expection if no views matched the selector
+  # @raise an expection if no views which matched the selector could be touched
+  def touch( selector )
+    touch_successes = frankly_map( selector, 'touch' )
+    raise "could not find anything matching [#{selector}] to touch" if touch_successes.empty?
     raise "some views could not be touched (probably because they are not within the current viewport)" if touch_successes.include?(false)
   end
-
-  def element_exists( query )
-    matches = frankly_map( query, 'accessibilityLabel' )
+  
+  # Indicate whether there are any views in the current view heirarchy which match the specified selector.
+  # @param [String] selector a view selector.
+  # @return [Boolean]
+  # @see #check_element_exists
+  def element_exists( selector )
+    matches = frankly_map( selector, 'accessibilityLabel' )
     # TODO: raise warning if matches.count > 1
     !matches.empty?
   end
 
-  def check_element_exists( query )
-    #puts "checking #{query} exists..."
-    element_exists( query ).should be_true
+  # Assert whether there are any views in the current view heirarchy which match the specified selector.
+  # @param [String] selector a view selector.
+  # @raise an rspec exception if the assertion fails
+  # @see #element_exists, #check_element_does_not_exist
+  def check_element_exists( selector )
+    element_exists( selector ).should be_true
   end
 
-  def check_element_does_not_exist( query )
-    #puts "checking #{query} does not exist..."
-    element_exists( query ).should be_false
+  # Assert whether there are no views in the current view heirarchy which match the specified selector.
+  # @param [String] selector a view selector.
+  # @raise an rspec exception if the assertion fails
+  # @see #element_exists, #check_element_exists
+  def check_element_does_not_exist( selector )
+    element_exists( selector ).should be_false
   end
 
+  # Indicate whether there are any views in the current view heirarchy which contain the specified accessibility label.
+  # @param [String] expected_mark the expected accessibility label
+  # @return [Boolean]
+  # @see #check_view_with_mark_exists
   def view_with_mark_exists(expected_mark)
     element_exists( "view marked:'#{expected_mark}'" )
   end
 
+  # Assert whether there are any views in the current view heirarchy which contain the specified accessibility label.
+  # @param [String] expected_mark the expected accessibility label
+  # @raise an rspec exception if the assertion fails
+  # @see #view_with_mark_exists
   def check_view_with_mark_exists(expected_mark)
     check_element_exists( "view marked:'#{expected_mark}'" )
   end
 
+  # Assert whether there are no views in the current view heirarchy which contain the specified accessibility label.
+  # @param [String] expected_mark the expected accessibility label
+  # @raise an rspec exception if the assertion fails
+  # @see #view_with_mark_exists, #check_view_with_mark_exists
   def check_view_with_mark_does_not_exist(expected_mark)
     check_element_does_not_exist( "view marked:'#{expected_mark}'" )
   end
 
 
-  # Waits for any of the selectors provided to match a view. Returns true
-  # as soon as we find a matching view, otherwise keeps testing until timeout.
-  # The first selector which matches is passed to a block if it was provided. 
+  # Waits for any of the specified selectors to match a view. 
+  #
+  # Checks each selector in turn within a {http://sauceio.com/index.php/2011/04/how-to-lose-races-and-win-at-selenium/ spin assert} loop and yields the first one which is found to exist in the view heirarchy. 
+  # Raises an exception if no views could be found to match any of the provided selectors within {WaitHelper::TIMEOUT} seconds.
+  #
+  # @see WaitHelper#wait_until
   def wait_for_element_to_exist(*selectors,&block)
     wait_until(:message => "Waited for element matching any of #{selectors.join(', ')} to exist") do
       at_least_one_exists = false
@@ -87,18 +142,37 @@ module FrankHelper
     end
   end
 
+  # Waits for the specified selector to not match any views.
+  #
+  # Uses {WaitHelper#wait_until} to check for any matching views within a {http://sauceio.com/index.php/2011/04/how-to-lose-races-and-win-at-selenium/ spin assert} loop. 
+  # Returns as soon as no views match the specified selector.
+  # Raises an exception if there continued to be at least one view which matched the selector by the time {WaitHelper::TIMEOUT} seconds passed.
+  #
+  # @see check_element_does_not_exist
+  # @see wait_for_element_to_not_exist
   def wait_for_element_to_not_exist(selector)
     wait_until(:message => "Waited for element #{selector} to not exist") do
       !element_exists(selector)
     end
   end
 
+  # Waits for a view to exist and then send a touch command to that view. 
+  #
+  # @param selectors takes one or more selectors to use to search for a view. The first selector which is found to matches a view is the selector
+  # which is then used to send a touch command.
+  #
+  # Raises an exception if no views could be found to match any of the provided selectors within {WaitHelper::TIMEOUT} seconds.
   def wait_for_element_to_exist_and_then_touch_it(*selectors)
     wait_for_element_to_exist(*selectors) do |sel| 
       touch(sel)
     end
   end
 
+  # Waits for there to be no views which report an isAnimated property of true.
+  #
+  # @param timeout [Number] number of seconds to wait for nothing to be animating before timeout out. Defaults to {WaitHelper::TIMEOUT}
+  #
+  # Raises an exception if there were still views animating after {timeout} seconds.
   def wait_for_nothing_to_be_animating( timeout = false )
     wait_until :timeout => timeout do
       !element_exists('view isAnimating')
@@ -106,15 +180,30 @@ module FrankHelper
   end
 
 
-  # a better name would be element_exists_and_is_not_hidden
-  def element_is_not_hidden(query)
-     matches = frankly_map( query, 'isHidden' )
+  # Checks that the specified selector matches at least one view, and that at least one of the matched 
+  # views has an isHidden property set to false
+  #
+  # a better name for this method would be element_exists_and_is_not_hidden
+  def element_is_not_hidden(selector)
+     matches = frankly_map( selector, 'isHidden' )
      matches.delete(true)
      !matches.empty?
   end
 
-  def app_exec(method_name, *method_args)
-    operation_map = Gateway.build_operation_map(method_name.to_s, method_args)
+
+  # Ask Frank to invoke the specified method on the app delegate of the iOS application under automation.
+  # @param method_sig [String] the method signature
+  # @param method_args the method arguments
+  #
+  # @example 
+  #   # the same as calling 
+  #   # [[[UIApplication sharedApplication] appDelegate] setServiceBaseUrl:@"http://example.com/my_api" withPort:8080]
+  #   # from your native app
+  #   app_exec( "setServiceBaseUrl:withPort:", "http://example.com/my_api", 8080 )
+  #
+  #
+  def app_exec(method_sig, *method_args)
+    operation_map = Gateway.build_operation_map(method_sig.to_s, method_args)
     
     res = frank_server.send_post( 
       'app_exec', 
@@ -124,24 +213,33 @@ module FrankHelper
     return Gateway.evaluate_frankly_response( res, "app_exec #{method_name}" )
   end
 
-  def frankly_map( query, method_name, *method_args )
+  # Ask Frank to execute an arbitrary Objective-C method on each view which matches the specified selector. 
+  #
+  # @return [Array] an array with an element for each view matched by the selector, each element in the array gives the return value from invoking the specified method on that view.
+  def frankly_map( selector, method_name, *method_args )
     operation_map = Gateway.build_operation_map(method_name.to_s, method_args)
 
     res = frank_server.send_post( 
       'map',
-      :query => query, 
+      :query => selector, 
       :operation => operation_map, 
       :selector_engine => selector_engine
     )
 
-    return Gateway.evaluate_frankly_response( res, "frankly_map #{query} #{method_name}" )
+    return Gateway.evaluate_frankly_response( res, "frankly_map #{selector} #{method_name}" )
   end
 
+  # print a JSON-formatted dump of the current view heirarchy to stdout
   def frankly_dump
     res = frank_server.send_get( 'dump' )
     puts JSON.pretty_generate(JSON.parse(res)) rescue puts res #dumping a super-deep DOM causes errors
   end
 
+  # grab a screenshot of the application under automation and save it to the specified file.
+  #
+  # @param filename [String] where to save the screenshot image file
+  # @param subframe describes which section of the screen to grab. If unspecified then the entire screen will be captured. #TODO document what format this parameter takes.
+  # @param allwindows [Boolean] If true then all UIWindows in the current UIScreen will be included in the screenshot. If false then only the main window will be captured.
   def frankly_screenshot(filename, subframe=nil, allwindows=true)
     path = 'screenshot'
     path += '/allwindows' if allwindows
@@ -154,14 +252,20 @@ module FrankHelper
     end
   end
 
+  # @return [Boolean] true if the device running the application currently in a portrait orientation
+  # @note wil return false if the device is in a flat or unknown orientation. Sometimes the iOS simulator will report this state when first launched.
   def frankly_oriented_portrait?
     'portrait' == frankly_current_orientation
   end
 
+  # @return [Boolean] true if the device running the application currently in a landscape orientation
+  # @note wil return false if the device is in a flat or unknown orientation. Sometimes the iOS simulator will report this state when first launched.
   def frankly_oriented_landscape?
     'landscape' == frankly_current_orientation
   end
 
+  # @return [String] the orientation of the device running the application under automation.
+  # @note this is a low-level API. In most cases you should use {frankly_oriented_portrait} or {frankly_oriented_landscape} instead.
   def frankly_current_orientation
     res = frank_server.send_get( 'orientation' )
     orientation = JSON.parse( res )['orientation']
@@ -169,11 +273,19 @@ module FrankHelper
     orientation
   end
 
+  # @return [Boolean] Does the device running the application have accessibility enabled.
+  # If accessibility is not enabled then a lot of Frank functionality will not work.
   def frankly_is_accessibility_enabled
     res = frank_server.send_get( 'accessibility_check' )
     JSON.parse( res )['accessibility_enabled'] == 'true'
   end
 
+  # wait for the application under automation to be ready to receive automation commands.
+  #
+  # Has some basic heuristics to cope with cases where the Frank server is intermittently available when first launching.
+  #
+  # @raise [Timeout::TimeoutError] if nothing is ready within 20 seconds
+  # @raise generic error if the device hosting the application does not appear to have accessibility enabled.
   def wait_for_frank_to_come_up
     num_consec_successes = 0
     num_consec_failures = 0
@@ -211,10 +323,13 @@ module FrankHelper
     end
   end
   
+  # Check whether Frank is able to communicate with the application under automation
   def frankly_ping
     frank_server.ping
   end
 
+  #@api private
+  #@return [Frank::Cucumber::Gateway] a gateway for sending Frank commands to the application under automation
   def frank_server
     @_frank_server ||= Frank::Cucumber::Gateway.new( base_server_url )
   end

data/lib/frank-cucumber/version.rb

@@ -1,5 +1,5 @@
 module Frank
   module Cucumber
-    VERSION = "0.9.4"
+    VERSION = "0.9.5.pre1"
   end
 end

data/lib/frank-cucumber/wait_helper.rb

@@ -3,38 +3,37 @@ require 'timeout'
 module Frank
 module Cucumber
 
-# What's going on here?!
+# This module contains a single method called wait_until which implements the {http://sauceio.com/index.php/2011/04/how-to-lose-races-and-win-at-selenium/ Spin Assert} pattern.
 #
-# This module contains a single method called wait_until. When we mix this module into another class or module (such as 
-# FrankHelper) then that wait_until method will be available inside that class or module. Because we call module_function
-# at the end of the module this method is also available as a static method on the module. That means you can also call 
-# Frank::Cucumber::WaitHelper.wait_until from anywhere in your code.
+# When we mix this module into another class or module (such as {FrankHelper}) then that wait_until method will be available inside 
+# that class or module. Because we call module_function at the end of the module this method is also available as a static method on the module. 
+# That means you can also call {Frank::Cucumber::WaitHelper.wait_until} from anywhere in your code.
 #
-#
-# wait_until will repeatedly execute the passed in block until either it returns true or a timeout expires. Between 
-# executions there is a pause of POLL_SLEEP seconds.
-#
-# wait_until takes two options, a timeout and a message. 
-# The timeout defaults to the WaitHelper::TIMEOUT constant. That constant is based off of a WAIT_TIMEOUT 
-# environment variable, otherwise it defaults to 240 seconds.
-# If a message is passed in as an option then that message is used when reporting a timeout.
-#
-#
-# Example usage: 
-#
-# wait_until( :timeout => 20, :message => 'timed out waiting for splines to reticulate' ) do
-#   num_splines_reticulated = reticulate_splines(1,2,3)
-#   num_splines_reticulated > 0
-# end
-# 
-# Here we will keep calling the reticulate_splines method until either it returns a result
-# greater than 0 or 20 seconds elapses. In the timeout case an exception will be raised 
-# saying "timed out waiting for splines to reticulate"
-
 module WaitHelper
+  # Default option for how long (in seconds) to keep checking before timing out the entire wait
   TIMEOUT = ENV['WAIT_TIMEOUT'].to_i || 240
-  POLL_SLEEP = 0.1 #seconds
+  # How long to pause (in seconds) inbetween each spin through the assertion block
+  POLL_SLEEP = 0.1
 
+  # Repeatedly evaluate the passed in block until either it returns true or a timeout expires. Between 
+  # evaluations there is a pause of {POLL_SLEEP} seconds.
+  #
+  # wait_until takes the following options:
+  #  :timeout - How long in seconds to keep spinning before timing out of the entire operation. Defaults to TIMEOUT
+  #  :message - What to raise in the event of a timeout. Defaults to an empty StandardError
+  # 
+  # @yield the assertion to wait for
+  # @yieldreturn whether the assertion was met
+  #
+  #
+  # Here's an example where we will keep calling the reticulate_splines method until either it returns a result
+  # greater than 0 or 20 seconds elapses. In the timeout case an exception will be raised 
+  # saying "timed out waiting for splines to reticulate":
+  #
+  #   wait_until( :timeout => 20, :message => 'timed out waiting for splines to reticulate' ) do
+  #     num_splines_reticulated = reticulate_splines(1,2,3)
+  #     num_splines_reticulated > 0
+  #   end
   def wait_until(opts = {})
     timeout = opts[:timeout] || TIMEOUT
     message = opts[:message]

metadata

@@ -1,8 +1,8 @@
 --- !ruby/object:Gem::Specification
 name: frank-cucumber
 version: !ruby/object:Gem::Version
-  version: 0.9.4
-  prerelease: 
+  version: 0.9.5.pre1
+  prerelease: 6
 platform: ruby
 authors:
 - Pete Hodgson
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-06-25 00:00:00.000000000 Z
+date: 2012-07-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: cucumber
@@ -156,6 +156,22 @@ dependencies:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Use cucumber to test native iOS apps via Frank
 email:
 - gems@thepete.net
@@ -167,6 +183,7 @@ extra_rdoc_files: []
 files:
 - .gitignore
 - Gemfile
+- Gemfile.lock
 - Rakefile
 - bin/frank
 - bin/frank-skeleton
@@ -196,10 +213,14 @@ files:
 - test/keyboard_helper_test.rb
 - test/launcher_test.rb
 - test/test_helper.rb
+- frank-skeleton/frank_static_resources.bundle/_solarized_colors.scss
+- frank-skeleton/frank_static_resources.bundle/coffee-script.js
 - frank-skeleton/frank_static_resources.bundle/images/ajax-loader.gif
 - frank-skeleton/frank_static_resources.bundle/images/file.gif
 - frank-skeleton/frank_static_resources.bundle/images/folder-closed.gif
 - frank-skeleton/frank_static_resources.bundle/images/folder.gif
+- frank-skeleton/frank_static_resources.bundle/images/loader.gif
+- frank-skeleton/frank_static_resources.bundle/images/loader.png
 - frank-skeleton/frank_static_resources.bundle/images/minus.gif
 - frank-skeleton/frank_static_resources.bundle/images/plus.gif
 - frank-skeleton/frank_static_resources.bundle/images/treeview-black-line.gif
@@ -214,15 +235,23 @@ files:
 - frank-skeleton/frank_static_resources.bundle/images/treeview-red.gif
 - frank-skeleton/frank_static_resources.bundle/index.haml
 - frank-skeleton/frank_static_resources.bundle/index.html
-- frank-skeleton/frank_static_resources.bundle/jquery-ui.css
 - frank-skeleton/frank_static_resources.bundle/jquery-ui.min.js
 - frank-skeleton/frank_static_resources.bundle/jquery.min.js
 - frank-skeleton/frank_static_resources.bundle/jquery.treeview.css
 - frank-skeleton/frank_static_resources.bundle/jquery.treeview.js
 - frank-skeleton/frank_static_resources.bundle/json2.js
+- frank-skeleton/frank_static_resources.bundle/pictos/index.html
+- frank-skeleton/frank_static_resources.bundle/pictos/pictos-web.eot
+- frank-skeleton/frank_static_resources.bundle/pictos/pictos-web.svg
+- frank-skeleton/frank_static_resources.bundle/pictos/pictos-web.ttf
+- frank-skeleton/frank_static_resources.bundle/pictos/pictos-web.woff
+- frank-skeleton/frank_static_resources.bundle/pictos/pictos.css
+- frank-skeleton/frank_static_resources.bundle/pictos/pictos_base64.css
 - frank-skeleton/frank_static_resources.bundle/raphael-min.js
+- frank-skeleton/frank_static_resources.bundle/reset.css
 - frank-skeleton/frank_static_resources.bundle/symbiote.css
 - frank-skeleton/frank_static_resources.bundle/symbiote.js
+- frank-skeleton/frank_static_resources.bundle/symbiote_ui.coffee
 - frank-skeleton/frank_static_resources.bundle/underscore.js
 - frank-skeleton/frank_static_resources.bundle/ViewAttributeMapping.plist
 homepage: http://rubygems.org/gems/frank-cucumber
@@ -240,9 +269,9 @@ required_ruby_version: !ruby/object:Gem::Requirement
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
-  - - ! '>='
+  - - ! '>'
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 1.3.1
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.24
@@ -253,3 +282,4 @@ test_files:
 - test/keyboard_helper_test.rb
 - test/launcher_test.rb
 - test/test_helper.rb
+has_rdoc: