calabash-cucumber 0.10.0.pre1 → 0.10.0.pre2

data/lib/calabash-cucumber/map.rb

@@ -2,20 +2,22 @@ require 'json'
 
 module Calabash
   module Cucumber
-    module Map #=> Connection
 
-      # returns an array of views matched by the +query+ or the result of
-      # performing the Objective-C sequence defined by the +method_name+ and
-      # +method_args+ on all the views matched by the +query+
+    # @!visibility private
+    module Map
+
+      # returns an array of views matched by the `query` or the result of
+      # performing the Objective-C sequence defined by the `method_name` and
+      # `method_args` on all the views matched by the `query`
       #
       # the query language is documented here: https://github.com/calabash/calabash-ios/wiki
       #
       # returns a JSON representation of each view that is matched
       #
-      # when the +method_name+ is a calabash operation, returns an array that
-      # contains the result of calling the objc selector +description+ on each
-      # matched view.  these are examples of calabash operations: +:flash+,
-      # +:scrollToRowWithMark+, +:changeDatePickerDate+.
+      # when the `method_name` is a calabash operation, returns an array that
+      # contains the result of calling the objc selector `description` on each
+      # matched view.  these are examples of calabash operations: `:flash`,
+      # `:scrollToRowWithMark`, `:changeDatePickerDate`.
       def map(query, method_name, *method_args)
         #todo calabash operations should return 'views touched' in JSON format
         raw_map(query, method_name, *method_args)['results']
@@ -24,26 +26,26 @@ module Calabash
       # returns a JSON object the represents the result of performing an http
       # query against the calabash server.
       #
-      # gem users should _not_ call this method directly; call +map+ instead.
+      # gem users should _not_ call this method directly; call `map` instead.
       #
-      # raises an error and takes a screenshot if the value of the +outcome+ key
+      # raises an error and takes a screenshot if the value of the `outcome` key
       # is _not_ 'SUCCESS'
       #
       # the JSON object contains the following keys:
       #
-      #     +outcome+ => indicates the success or failure of the query
+      #     `outcome` => indicates the success or failure of the query
       #
-      #     +status_bar_orientation+ => the orientation of the status bar
+      #     `status_bar_orientation` => the orientation of the status bar
       #
-      #     +results+ => views matched by the +query+ or the result of
+      #     `results` => views matched by the `query` or the result of
       #                  performing the Objective-C selector sequence defined by
-      #                  the +method_name+ with arguments defined in
-      #                  +method_args+ on all views matched by the +query+
+      #                  the `method_name` with arguments defined in
+      #                  `method_args` on all views matched by the `query`
       #
       # the query language is documented here: https://github.com/calabash/calabash-ios/wiki
       #
-      # here are some examples that clarify how the +method_name+ and +method_args+
-      # influence the value of the +results+ key
+      # here are some examples that clarify how the `method_name` and `method_args`
+      # influence the value of the `results` key
       #
       # simple examples:
       #
@@ -76,20 +78,20 @@ module Calabash
         res
       end
 
-      # asserts the result of a calabash +map+ call and raises an error with
-      # +msg+ if no valid results are found.
+      # asserts the result of a calabash `map` call and raises an error with
+      # `msg` if no valid results are found.
       #
       # casual gem users should never need to call this method; this is a
       # convenience method for gem maintainers.
       #
-      # raises an error if +map_results+:
+      # raises an error if `map_results`:
       #
       #              is an empty list #=> []
       #    contains a '<VOID>' string #=> [ "<VOID>" ]
       #       contains '*****' string #=> [ "*****"  ]
       #         contains a single nil #=> [ nil ]
       #
-      # when evaluating whether a +map+ call is successful it is important to
+      # when evaluating whether a `map` call is successful it is important to
       # note that sometimes a <tt>[ nil ]</tt> or <tt>[nil, <val>, nil]</tt> is
       # a valid result.
       #
@@ -110,7 +112,7 @@ module Calabash
       #
       # here a <tt>[ nil ]</tt> should be considered invalid because the
       # the operation could not be performed because there is not row that
-      # matches +mark+
+      # matches `mark`
       def assert_map_results(map_results, msg)
         compact = map_results.compact
         if compact.empty? or compact.member? '<VOID>' or compact.member? '*****'

data/lib/calabash-cucumber/operations.rb

@@ -5,7 +5,7 @@ require 'calabash-cucumber/keychain_helpers'
 require 'calabash-cucumber/wait_helpers'
 require 'calabash-cucumber/launcher'
 require 'net/http'
-require 'test/unit'
+require 'test/unit/assertions'
 require 'json'
 require 'set'
 require 'calabash-cucumber/version'
@@ -13,17 +13,13 @@ require 'calabash-cucumber/date_picker'
 require 'calabash-cucumber/ipad_1x_2x'
 require 'calabash-cucumber/utils/logging'
 
-if not Object.const_defined?(:CALABASH_COUNT)
-  #compatability with IRB
-  CALABASH_COUNT = {:step_index => 0, :step_line => "irb"}
-end
-
-
 module Calabash
   module Cucumber
+
+    # A module for wrapping the public APIs of this gem.
     module Operations
 
-      include Minitest::Assertions
+      include Test::Unit::Assertions
       include Calabash::Cucumber::Logging
       include Calabash::Cucumber::Core
       include Calabash::Cucumber::TestsHelpers
@@ -33,158 +29,6 @@ module Calabash
       include Calabash::Cucumber::DatePicker
       include Calabash::Cucumber::IPad
 
-      def page(clz,*args)
-        clz.new(self,*args)
-      end
-
-      def await_page(clz,*args)
-        clz.new(self,*args).await
-      end
-
-      def home_direction
-        status_bar_orientation.to_sym
-      end
-
-      def assert_home_direction(expected)
-        unless expected.to_sym == home_direction
-          screenshot_and_raise "Expected home button to have direction #{expected} but had #{home_direction}"
-        end
-      end
-
-      def label(uiquery)
-        query(uiquery, :accessibilityLabel)
-      end
-
-      def identifier(uiquery)
-        query(uiquery, :accessibilityIdentifier)
-      end
-
-      def simple_touch(label, *args)
-        touch("view marked:'#{label}'", *args)
-      end
-
-      def tap(hash_or_string, *args)
-        if hash_or_string.is_a?(String)
-          tap_mark(hash_or_string, *args)
-        elsif hash_or_string.respond_to?(:[])
-          wait_tap(hash_or_string[:query], hash_or_string)
-        else
-          raise(ArgumentError, "first parameter to tap must be a string or a hash. Was: #{hash_or_string.class}, #{hash_or_string}")
-        end
-      end
-
-      def tap_mark(label, *args)
-        simple_touch(label, *args)
-      end
-
-      def html(q)
-        query(q).map { |e| e['html'] }
-      end
-
-      # sets the text value of the views matched by +uiquery+ to +txt+
-      #
-      # @deprecated since 0.9.145
-      #
-      # we have stopped testing this method.  you have been warned.
-      #
-      # * to enter text using the native keyboard use 'keyboard_enter_text'
-      # * to delete text use 'keyboard_enter_text('Delete')"
-      # * to clear a text field or text view:
-      #   - RECOMMENDED: use queries and touches to replicate what the user would do
-      #     - for text fields, implement a clear text button and touch it
-      #     - for text views, use touches to reveal text editing popup
-      #       see https://github.com/calabash/calabash-ios/issues/151
-      #   - use 'clear_text'
-      #  https://github.com/calabash/calabash-ios/wiki/03.5-Calabash-iOS-Ruby-API
-      #
-      # raises an error if the +uiquery+ finds no matching queries or finds
-      # a view that does not respond to the objc selector 'setText'
-      def set_text(uiquery, txt)
-        msgs = ["'set_text' is deprecated and its behavior is now unpredictable",
-                "* to enter text using the native keyboard use 'keyboard_enter_text'",
-                "* to delete text use 'keyboard_enter_text('Delete')",
-                '* to clear a text field or text view:',
-                '  - RECOMMENDED: use queries and touches to replicate what the user would do',
-                '    * for text fields, implement a clear text button and touch it',
-                '    * for text views, use touches to reveal text editing popup',
-                '    see https://github.com/calabash/calabash-ios/issues/151',
-                "  - use 'clear_text'",
-                'https://github.com/calabash/calabash-ios/wiki/03.5-Calabash-iOS-Ruby-API']
-        msg = msgs.join("\n")
-        _deprecated('0.9.145', msg, :warn)
-
-        text_fields_modified = map(uiquery, :setText, txt)
-
-        msg = "query '#{uiquery}' returned no matching views that respond to 'setText'"
-        assert_map_results(text_fields_modified, msg)
-        text_fields_modified
-      end
-
-      # sets the text value of the views matched by +uiquery+ to <tt>''</tt>
-      # (the empty string)
-      #
-      # using this sparingly and with caution
-      #
-      #
-      # it is recommended that you instead do some combination of the following
-      #
-      # * use queries and touches to replicate with the user would
-      #   - for text fields, implement a clear text button and touch it
-      #   - for text views, use touches to reveal text editing popup
-      #   see https://github.com/calabash/calabash-ios/issues/151
-      #
-      #  https://github.com/calabash/calabash-ios/wiki/03.5-Calabash-iOS-Ruby-API
-      #
-      # raises an error if the +uiquery+ finds no matching queries or finds
-      # a _single_ view that does not respond to the objc selector 'setText'
-      #
-      # IMPORTANT
-      # calling:
-      #
-      #     > clear_text("view")
-      #
-      # will clear the text on _all_ visible views that respond to 'setText'
-      def clear_text(uiquery)
-        views_modified = map(uiquery, :setText, '')
-        msg = "query '#{uiquery}' returned no matching views that respond to 'setText'"
-        assert_map_results(views_modified, msg)
-        views_modified
-      end
-
-
-      def set_user_pref(key, val)
-        res = http({:method => :post, :path => 'userprefs'},
-                   {:key=> key, :value => val})
-        res = JSON.parse(res)
-        if res['outcome'] != 'SUCCESS'
-          screenshot_and_raise "set_user_pref #{key} = #{val} failed because: #{res['reason']}\n#{res['details']}"
-        end
-
-        res['results']
-      end
-
-      def user_pref(key)
-        res = http({:method => :get, :raw => true, :path => 'userprefs'},
-                   {:key=> key})
-        res = JSON.parse(res)
-        if res['outcome'] != 'SUCCESS'
-          screenshot_and_raise "get user_pref #{key} failed because: #{res['reason']}\n#{res['details']}"
-        end
-
-        res['results'].first
-      end
-
-      #def screencast_begin
-      #   http({:method=>:post, :path=>'screencast'}, {:action => :start})
-      #end
-      #
-      #def screencast_end(file_name)
-      #  res = http({:method=>:post, :path=>'screencast'}, {:action => :stop})
-      #  File.open(file_name,'wb') do |f|
-      #      f.write res
-      #  end
-      #  file_name
-      #end
     end
   end
 end

data/lib/calabash-cucumber/playback_helpers.rb

@@ -3,12 +3,25 @@ require 'calabash-cucumber/device'
 
 module Calabash
   module Cucumber
+
+    # This module provides methods for interaction with UIAutomation's
+    # record-and-playback features.
+    #
+    # @note
+    #  In iOS 7, the record-and-playback feature was dropped from UIAutomation.
+    #  As such, using the record-and-playback API is not recommended.
+    #
+    # @note
+    #  We expect that this module will be deprecated once iOS 6 testing is no
+    #  longer supported.
     module PlaybackHelpers
 
       include Calabash::Cucumber::Logging
 
+      # @!visibility private
       DATA_PATH = File.expand_path(File.dirname(__FILE__))
 
+      # @!visibility private
       def recording_name_for(recording_name, os, device)
         #noinspection RubyControlFlowConversionInspection
         if !recording_name.end_with? '.base64'
@@ -18,6 +31,7 @@ module Calabash
         end
       end
 
+      # @!visibility private
       def load_recording(recording, rec_dir)
         directories = playback_file_directories(rec_dir)
         directories.each { |dir|
@@ -29,6 +43,7 @@ module Calabash
         nil
       end
 
+      # @!visibility private
       def playback_file_directories (rec_dir)
         # rec_dir is either ENV['PLAYBACK_DIR'] or ./features/playback
         [File.expand_path(rec_dir),
@@ -38,6 +53,7 @@ module Calabash
          "#{DATA_PATH}/resources/"].uniq
       end
 
+      # @!visibility private
       def load_playback_data(recording_name, options={})
         device = options['DEVICE'] || ENV['DEVICE'] || 'iphone'
 
@@ -79,6 +95,7 @@ EOF
         data
       end
 
+      # @!visibility private
       def find_compatible_recording (recording_name, os, rec_dir, device, candidates)
         recording = recording_name_for(recording_name, os, device)
         data = load_recording(recording, rec_dir)
@@ -99,6 +116,9 @@ EOF
         data
       end
 
+      # Plays back a recording.
+      # @param [String] recording the filename of the recording
+      # @param [Hash] options can control the behavior of the recording
       def playback(recording, options={})
         data = load_playback_data(recording)
 
@@ -119,6 +139,9 @@ EOF
         res['results']
       end
 
+      # Plays back a recording but interpolates it first.
+      # @param [String] recording the filename of the recording
+      # @param [Hash] options can control the behavior of the recording
       def interpolate(recording, options={})
         data = load_playback_data(recording)
 
@@ -138,10 +161,13 @@ EOF
         res['results']
       end
 
+      # Begins a recording.
       def record_begin
         http({:method => :post, :path => 'record'}, {:action => :start})
       end
 
+      # Ends a recording and saves it.
+      # @param [String] file_name where to save the recording.
       def record_end(file_name)
         res = http({:method => :post, :path => 'record'}, {:action => :stop})
         File.open('_recording.plist', 'wb') do |f|

data/lib/calabash-cucumber/query_helpers.rb

@@ -1,11 +1,23 @@
 module Calabash
   module Cucumber
+
+    # A module of methods that can help you construct queries.
     module QueryHelpers
 
+      # call this method to properly escape single quotes in Calabash queries
+      # Calabash iOS has some annoying rules for text containing single quotes.
+      # This helper frees you from manual escaping.
+      # @example
+      #   quoted = escape_quotes("Karl's child")
+      #   # => "Karl\\'s child"
+      # @param {String} str string to escape
+      # @return {String} escaped version of `str`
       def escape_quotes(str)
         str.gsub("'", "\\\\'")
       end
 
+      # converts a query result or off-set hash to a point hash
+      # @!visibility private
       def point_from(query_result, options={})
         offset_x = 0
         offset_y = 0

data/lib/calabash-cucumber/rotation_helpers.rb

@@ -2,23 +2,57 @@ require 'calabash-cucumber/utils/logging'
 
 module Calabash
   module Cucumber
-    module RotationHelpers  #=> Connection, StatusBarHelpers
+
+    # Provides methods for rotating a device in a direction or to a particular
+    # orientation.
+    module RotationHelpers
 
       include Calabash::Cucumber::Logging
 
+      # @!visibility private
       def rotation_candidates
         %w(rotate_left_home_down rotate_left_home_left rotate_left_home_right rotate_left_home_up
            rotate_right_home_down rotate_right_home_left rotate_right_home_right rotate_right_home_up)
       end
 
-      # orientations refer to home button position
-      #  down ==> bottom
-      #    up ==> top
-      #  left ==> landscape with left home button AKA: _right_ landscape*
-      # right ==> landscape with right home button AKA: _left_ landscape*
+      # Rotates the home button position to the position indicated by `dir`.
+      #
+      # @example portrait
+      #  rotate_home_button_to :down
+      #
+      # @example upside down
+      #  rotate_home_button_to :up
+      #
+      # @example landscape with left home button AKA: _right_ landscape
+      #  rotate_home_button_to :left
+      #
+      # @example landscape with right home button AKA: _left_ landscape
+      #  rotate_home_button_to :right
+      #
+      # @note Refer to Apple's documentation for clarification about left vs.
+      #  right landscape orientations.
+      #
+      # @note For legacy support the `dir` argument can be a String or Symbol.
+      #  Please update your code to pass a Symbol.
+      #
+      # @note For legacy support `:top` and `top` are synonyms for `:up`.
+      #  Please update your code to pass `:up`.
+      #
+      # @note For legacy support `:bottom` and `bottom` are synonyms for `:down`.
+      #  Please update your code to pass `:down`.
+      #
+      # @note This method generates verbose messages when full console logging
+      #  is enabled.  See {Calabash::Cucumber::Logging#full_console_logging?}.
       #
-      # * see apple documentation for clarification about where the home button
-      #   is in left and right landscape orientations
+      # @param [Symbol] dir The position of the home button after the rotation.
+      #  Can be one of `{:down | :left | :right | :up }`.
+      #
+      # @return [Symbol] The orientation of the button when all rotations have
+      #  been completed.  If there is problem rotating, this method will return
+      #  `:down` regardless of the actual home button position.
+      #
+      # @todo When running under UIAutomation, we should use that API to rotate
+      #  instead of relying on playbacks.
       def rotate_home_button_to(dir)
         dir_sym = dir.to_sym
         if dir_sym.eql?(:top)
@@ -75,6 +109,28 @@ module Calabash
         :down
       end
 
+      # Rotates the device in the direction indicated by `dir`.
+      #
+      # @example rotate left
+      #  rotate :left
+      #
+      # @example rotate right
+      #  rotate :right
+      #
+      # @example rotate down
+      #  rotate :down
+      #
+      # @example rotate up
+      #  rotate :up
+      #
+      # @note For legacy support the `dir` argument can be a String or Symbol.
+      #  Please update your code to pass a Symbol.
+      #
+      # @param [Symbol] dir The position of the home button after the rotation.
+      #  Can be one of `{:down | :left | :right | :up }`.
+      #
+      # @todo When running under UIAutomation, we should use that API to rotate
+      #  instead of relying on playbacks.
       def rotate(dir)
         dir = dir.to_sym
         current_orientation = status_bar_orientation().to_sym