calabash 1.9.9.pre3 → 2.0.0.prelegacy

data/lib/calabash/cli/build.rb

@@ -2,10 +2,24 @@ module Calabash
   module CLI
     # @!visibility private
     module Build
+      # @!visibility private
       def parse_build_arguments!
         fail('Should only build test-server for Android') unless @platform.nil? || @platform == :android
 
         application = @arguments.shift
+        test_server_path = nil
+
+        arg = @arguments.shift
+
+        if arg != nil
+          if arg == '-o'
+            test_server_path = @arguments.shift
+
+            if test_server_path == nil
+              raise 'Expected an output path for the test-server'
+            end
+          end
+        end
 
         if application.nil?
           fail('Must supply application as first parameter to build', :build)
@@ -18,7 +32,7 @@ module Calabash
           case extension
             when '.apk'
               set_platform!(:android)
-              Calabash::Android::Build::Builder.new(application_path).build
+              Calabash::Android::Build::Builder.new(application_path).build(test_server_path)
             when '.ipa', '.app'
               set_platform!(:ios)
               fail('Should only build test-server for Android')

data/lib/calabash/cli/console.rb

@@ -3,6 +3,7 @@ module Calabash
   module CLI
     # @!visibility private
     module Console
+      # @!visibility private
       def parse_console_arguments!
         application = @arguments.shift
 
@@ -22,12 +23,14 @@ module Calabash
             when '.apk'
               set_platform!(:android)
 
-              # Create the test server if it does not exist
-              test_server = Android::Build::TestServer.new(application_path)
+              unless Environment::TEST_SERVER_PATH
+                # Create the test server if it does not exist
+                test_server = Android::Build::TestServer.new(application_path)
 
-              unless test_server.exists?
-                Logger.info('Test server does not exist. Creating test server.')
-                Calabash::Android::Build::Builder.new(application_path).build
+                unless test_server.exists?
+                  Logger.info('Test server does not exist. Creating test server.')
+                  Calabash::Android::Build::Builder.new(application_path).build
+                end
               end
 
               enter_console(application_path)
@@ -45,6 +48,7 @@ module Calabash
         end
       end
 
+      # @!visibility private
       def enter_console(application_path)
         irbrc_path = Environment::IRBRC
 

data/lib/calabash/cli/generate.rb

@@ -5,6 +5,7 @@ module Calabash
   module CLI
     # @!visibility private
     module Generate
+      # @!visibility private
       def parse_generate_arguments!
         if File.exist?('features')
           puts "A features directory already exists. Please remove this to continue."
@@ -22,6 +23,7 @@ module Calabash
         cucumber_config = File.read(file(File.join('config', 'cucumber.yml')))
 
         env = File.read(file(File.join('features', 'support', 'env.rb')))
+        dry_run = File.read(file(File.join('features', 'support', 'dry_run.rb')))
         sample_feature = File.read(file(File.join('features', 'sample.feature')))
         calabash_steps = File.read(file(File.join('features', 'step_definitions', 'calabash_steps.rb')))
 
@@ -46,6 +48,7 @@ module Calabash
         File.open(File.join('features', 'step_definitions', 'calabash_steps.rb'), 'w') {|file| file.write(calabash_steps) }
         File.open(File.join('features', 'support', 'hooks.rb'), 'w') {|file| file.write(hooks) }
         File.open(File.join('features', 'support', 'env.rb'), 'w') {|file| file.write(env) }
+        File.open(File.join('features', 'support', 'dry_run.rb'), 'w') {|file| file.write(dry_run) }
 
         gemfile = File.readlines(file(File.join('Gemfile')))
 
@@ -68,10 +71,12 @@ module Calabash
         end
       end
 
+      # @!visibility private
       def file(file)
         File.join(Calabash::Environment::SKELETON_DIR_PATH, file)
       end
 
+      # @!visibility private
       def msg(title, &block)
         puts "\n" + "-"*10 + title + "-"*10
         block.call

data/lib/calabash/cli/helpers.rb

@@ -3,6 +3,7 @@ module Calabash
   module CLI
     # @!visibility private
     module Helpers
+      # @!visibility private
       HELP = {
           help: 'help',
           generate: 'generate',
@@ -14,6 +15,7 @@ module Calabash
           build: 'build <apk>'
       }
 
+      # @!visibility private
       def key_for_command(command)
         HELP.each do |key, value|
           if value.split(' ').first == command
@@ -24,6 +26,7 @@ module Calabash
         nil
       end
 
+      # @!visibility private
       def print_usage_for(key, output=STDOUT)
         if key.nil? || HELP[key].nil?
           output.write <<EOF
@@ -37,6 +40,7 @@ EOF
         end
       end
 
+      # @!visibility private
       def print_usage(output=STDOUT)
           output.write <<EOF
   Usage: calabash [options] <command-name> [command specific options]
@@ -64,7 +68,7 @@ EOF
       #{HELP[:resign]}
         resigns the app with the currently configured keystore.
 
-      #{HELP[:build]}
+      #{HELP[:build]} [-o <output_file>]
         builds the test server that will be used when testing the app.
 
     iOS specific commands
@@ -101,11 +105,13 @@ EOF
 EOF
       end
 
+      # @!visibility private
       def help
         file_name = File.join(File.dirname(__FILE__), '..', 'doc', 'calabash_help.txt')
         system("less \"#{file_name}\"")
       end
 
+      # @!visibility private
       def fail(reason, command=nil)
         STDERR.write("#{reason}\n")
 

data/lib/calabash/cli/resign.rb

@@ -3,6 +3,7 @@ module Calabash
   module CLI
     # @!visibility private
     module Resign
+      # @!visibility private
       def parse_resign_arguments!
         fail('Can only resign Android applications') unless @platform.nil? || @platform == :android
 

data/lib/calabash/cli/run.rb

@@ -3,6 +3,7 @@ module Calabash
   module CLI
     # @!visibility private
     module Run
+      # @!visibility private
       def parse_run_arguments!
         first_argument = @arguments.first # Do not remove the entry from the arguments yet - it might be a cucumber arg
 
@@ -30,12 +31,14 @@ module Calabash
             when '.apk'
               set_platform!(:android)
 
-              # Create the test server if it does not exist
-              test_server = Android::Build::TestServer.new(application_path)
+              unless Environment::TEST_SERVER_PATH
+                # Create the test server if it does not exist
+                test_server = Android::Build::TestServer.new(application_path)
 
-              unless test_server.exists?
-                Logger.info('Test server does not exist. Creating test server.')
-                Calabash::Android::Build::Builder.new(application_path).build
+                unless test_server.exists?
+                  Logger.info('Test server does not exist. Creating test server.')
+                  Calabash::Android::Build::Builder.new(application_path).build
+                end
               end
 
               run(application_path, @arguments)
@@ -54,6 +57,7 @@ module Calabash
         end
       end
 
+      # @!visibility private
       def run(application_path, cucumber_arguments)
         cucumber_environment = {}
         cucumber_environment['CAL_DEBUG'] = Environment::DEBUG ? '1' : '0'
@@ -88,7 +92,7 @@ module Calabash
           end
         end
 
-        arguments = ['-S', 'cucumber', '-p', @platform.to_s, *cucumber_arguments]
+        arguments = ['-S', 'cucumber', *cucumber_arguments]
 
         Logger.debug("Starting Ruby with arguments: #{arguments.join(', ')} and environment #{cucumber_environment.to_s}")
 

data/lib/calabash/cli/setup_keystore.rb

@@ -6,6 +6,7 @@ module Calabash
   module CLI
     # @!visibility private
     module SetupKeystore
+      # @!visibility private
       def parse_setup_keystore_arguments!
         set_platform!(:android)
 
@@ -25,6 +26,7 @@ module Calabash
         puts "Saved your settings to '#{Android::Build::JavaKeystore::CALABASH_KEYSTORE_SETTINGS_FILENAME}'. You can edit the settings manually or run this setup script again"
       end
 
+      # @!visibility private
       def prompt(message, secure = false)
         puts message
 

data/lib/calabash/color.rb

@@ -1,30 +1,37 @@
 module Calabash
   # @!visibility private
   module Color
+    # @!visibility private
     def self.colorize(string, color)
       "\e[#{color}m#{string}\e[0m"
     end
 
+    # @!visibility private
     def self.red(string)
       colorize(string, 31)
     end
 
+    # @!visibility private
     def self.green(string)
       colorize(string, 32)
     end
 
+    # @!visibility private
     def self.yellow(string)
       colorize(string, 33)
     end
 
+    # @!visibility private
     def self.blue(string)
       colorize(string, 34)
     end
 
+    # @!visibility private
     def self.magenta(string)
       colorize(string, 35)
     end
 
+    # @!visibility private
     def self.cyan(string)
       colorize(string, 36)
     end

data/lib/calabash/console_helpers.rb

@@ -4,7 +4,6 @@ module Calabash
 
   # Methods you can use in the Calabash console to help you
   # interact with your app.
-  # @!visibility private
   module ConsoleHelpers
 
     # Outputs all visible elements as a tree.
@@ -30,13 +29,15 @@ module Calabash
       true
     end
 
-    # Clear the console.
+    # Clear the console history. Note that this also clears the contents
+    # given to Calabash::ConsoleHelpers#copy.
     def clear
       ConsoleHelpers.clear
       true
     end
 
     # Puts a message of the day.
+    # @!visibility private
     def message_of_the_day
       messages = [
             "Let's get this done!",
@@ -141,6 +142,7 @@ module Calabash
       readline_history.last(length)
     end
 
+    # @!visibility private
     FILTER_REGEX = Regexp.union(/\s*copy(\(|\z)/, /\s*tree(\(|\z)/,
                                 /\s*flash(\(|\z)/, /\s*classes(\(|\z)/,
                                 /\s*ids(\(|\z)/, /\s*start_app(\(|\z)/,

data/lib/calabash/defaults.rb

@@ -1,4 +1,5 @@
 module Calabash
+  # Runtime defaults.
   module Defaults
     # Get the default device. The device represents a physical device,
     # an emulator, or a simulator. Calabash will communicate with this

data/lib/calabash/device.rb

@@ -1,4 +1,6 @@
 module Calabash
+  # A model of the device under test.  Can be a physical Android or iOS device,
+  # an Android emulator, or an iOS simulator.
   class Device
     include Utility
 
@@ -138,9 +140,6 @@ module Calabash
       gesture_options[:at] ||= {}
       gesture_options[:at][:x] ||= 50
       gesture_options[:at][:y] ||= 50
-      gesture_options[:offset] ||= {}
-      gesture_options[:offset][:x] ||= 0
-      gesture_options[:offset][:y] ||= 0
       gesture_options[:timeout] ||= Calabash::Gestures::DEFAULT_GESTURE_WAIT_TIMEOUT
 
       _tap(query, gesture_options)
@@ -156,9 +155,6 @@ module Calabash
       gesture_options[:at] ||= {}
       gesture_options[:at][:x] ||= 50
       gesture_options[:at][:y] ||= 50
-      gesture_options[:offset] ||= {}
-      gesture_options[:offset][:x] ||= 0
-      gesture_options[:offset][:y] ||= 0
       gesture_options[:timeout] ||= Calabash::Gestures::DEFAULT_GESTURE_WAIT_TIMEOUT
 
       _double_tap(query, gesture_options)
@@ -174,9 +170,6 @@ module Calabash
       gesture_options[:at] ||= {}
       gesture_options[:at][:x] ||= 50
       gesture_options[:at][:y] ||= 50
-      gesture_options[:offset] ||= {}
-      gesture_options[:offset][:x] ||= 0
-      gesture_options[:offset][:y] ||= 0
       gesture_options[:timeout] ||= Calabash::Gestures::DEFAULT_GESTURE_WAIT_TIMEOUT
       gesture_options[:duration] ||= 1
 
@@ -237,6 +230,7 @@ module Calabash
       end
 
       gesture_options = options.dup
+      gesture_options[:duration] ||= 0.5
       gesture_options[:timeout] ||= Calabash::Gestures::DEFAULT_GESTURE_WAIT_TIMEOUT
 
       _pinch(direction, query, gesture_options)
@@ -259,6 +253,11 @@ module Calabash
       abstract_method!
     end
 
+    # @!visibility private
+    def keyboard_visible?
+      abstract_method!
+    end
+
     private
 
     # @!visibility private

data/lib/calabash/environment.rb

@@ -11,6 +11,7 @@ module Calabash
       ENV[name]
     end
 
+    # @!visibility private
     # Utility method to set the value of an environment variable.
     #
     # @param [String] name of the environment variable
@@ -30,6 +31,10 @@ module Calabash
     # Is Calabash running in debug mode. True if $CAL_DEBUG is '1'
     DEBUG = variable('CAL_DEBUG') == '1'
 
+    # @!visibility private
+    # Experimental! Print every method that is called in Calabash
+    DEBUG_CALLED_METHODS = variable('CAL_DEBUG_CALLED_METHODS') == '1'
+
     # The path of the default app under test. This value is used if no app is
     # given from the command line. e.g. $ calabash run.
     #

data/lib/calabash/gestures.rb

@@ -1,16 +1,20 @@
 module Calabash
-  # Methods for performing gestures.  Gestures are taps, flicks,
-  # and pans.
+  # Methods for performing gestures.  Gestures are taps, flicks, and pans.
   #
   # Many gestures take an optional :duration. On iOS, the duration must be
   # between 0.5 and 60 (seconds).  This is a limitation of the UIAutomation API.
+  #
+  # @note All gestures have _undefined return values._  This is intentional.
+  #  Please do not rely on return values of gestures in your tests.  For
+  #  convenience when working in the console, some gestures return sensible
+  #  values.  However, these values are subject to change.
   module Gestures
 
     # How long do we wait for a view to appear by default when performing a
     # gesture.
     DEFAULT_GESTURE_WAIT_TIMEOUT = 3
 
-    # Performs a `tap` on the (first) view that matches `query`.
+    # Performs a **tap** on the first view that matches `query`.
     #
     # Taps the center of the view by default.
     #
@@ -19,33 +23,25 @@ module Calabash
     #
     #      ┬    ┌─────────────────────────────────────┐
     #      |    │2                                   3│
-    #      |    │                 4                   │
+    #      |    │                                     │
     #      |    │                                     │
     #   200 px  │                 1                   │
     #      |    │                                     │
-    #      |    │             7     5                 │   6
     #      |    │                                     │
+    #      |    │                 4                   │
     #      ┴    └─────────────────────────────────────┘
     #
     #   1. tap("* marked:'email'")
     #   2. tap("* marked:'email'", at:  {x: 0, y: 0})
     #   3. tap("* marked:'email'", at:  {x: 100, y: 0})
-    #   4. tap("* marked:'email'", offset: {y: -40})
-    #   5. tap("* marked:'email'", offset: {x: 20, y: 40})
-    #   6. tap("* marked:'email'", at: {x: 100, y: 75}, offset: {x: 80})
-    #   7. tap("* marked:'email'", at: {x: 50, y: 100},
-    #                              offset: {x: -80, y: -40})
+    #   4. tap("* marked:'email'", at:  {x: 50, y: 100})
     #
-    # @param [String] query A query describing the view to tap.
+    # @param [String, Hash, Calabash::Query] query A query describing the view
+    #   to tap.
     # @param [Hash] options Options for modifying the details of the touch.
     # @option options [Hash] :at ({x: 50, y: 50}) The point at which the
     #   gesture originates from.  It is a percentage-based translation using
-    #   top-left `(0,0)` as the reference point. This translation is always
-    #   applied before any `:offset`.
-    # @option options [Hash] :offset ({x: 0, y: 0}) Offset to touch point.
-    #   Offset supports an `:x` and `:y` key and causes the touch to be
-    #   offset with `(x,y)`.  This offset is always applied _after_ any
-    #   translation performed by `:at`.
+    #   top-left `(0,0)` as the reference point.
     # @raise [ViewNotFoundError] If the `query` returns no results.
     # @raise [ArgumentError] If `query` is invalid.
     def tap(query, options={})
@@ -54,8 +50,17 @@ module Calabash
       Device.default.tap(Query.new(query), options)
     end
 
-    # Performs a `double_tap` on the (first) view that matches `query`.
-    # @see tap
+    # Performs a **double_tap** on the first view that matches `query`.
+    #
+    # @see #tap
+    #
+    # @param [String, Hash, Calabash::Query] query A query describing the view
+    #  to tap.
+    # @param [Hash] options Options for modifying the details of the touch.
+    # @option options [Hash] :at ({x: 50, y: 50}) The point at which the
+    #   gesture originates from.  It is a percentage-based translation using
+    #   top-left `(0,0)` as the reference point.
+    #
     # @raise [ViewNotFoundError] If the `query` returns no results.
     # @raise [ArgumentError] If `query` is invalid.
     def double_tap(query, options={})
@@ -64,12 +69,14 @@ module Calabash
       Device.default.double_tap(Query.new(query), options)
     end
 
-    # Performs a `long_press` on the (first) view that matches `query`.
+    # Performs a **long_press** on the first view that matches `query`.
+    #
     # On iOS this is often referred to as _touch-and-hold_.  On Android this
     # is known variously as _press_, _long-push_, _press-and-hold_, or _hold_.
     #
-    # @see tap
+    # @see #tap
     #
+    # @param [String] query A query describing the view to tap.
     # @param [Hash] options Options for modifying the details of the touch.
     # @option options [Number] :duration (1.0) The amount of time in seconds to
     #  press.  On iOS, the duration must be between 0.5 and 60.
@@ -82,11 +89,14 @@ module Calabash
       Device.default.long_press(Query.new(query), options)
     end
 
-    # Performs a `pan` on the (first) view that matches `query`.
+    # Performs a **pan** on the first view that matches `query`.
+    #
     # A pan is a straight line swipe that pauses at the final point
     # before releasing the gesture. This is the general purpose pan method. For
     # standardized pans see `pan_left`, `pan_right`, `pan_up`, and `pan_down`.
     #
+    # Also known as **scroll** and **swipe**.
+    #
     # @example
     #  Consider a pan on a scrollable view.  When the finger is is released,
     #  the velocity of the view is zero.
@@ -112,7 +122,8 @@ module Calabash
     # @see Calabash::IOS::Scroll#scroll_to_item
     # @see Calabash::IOS::Scroll#scroll_to_item_with_mark
     #
-    # @param [String] query A query describing the view to pan inside.
+    # @param [String, Hash, Calabash::Query] query A query describing the view
+    #  to pan inside.
     # @param [Hash] from `({:x, :y})` The point at which the gesture
     #   originates from.
     # @param [Hash] to `({:x, :y})` The point at which the gesture
@@ -132,9 +143,11 @@ module Calabash
       Device.default.pan(Query.new(query), from, to, options)
     end
 
-    # Performs a `pan` from the center of the first view that matches
+    # Performs a **pan** from the center of the first view that matches
     # `query_from` to the center of the first view that matches `query_to`.
     #
+    # Also known as **drag and drop**.
+    #
     # @example
     #  Panning between two elements.
     #  `pan_between("* id:'first'", "* id:'second'")`
@@ -171,56 +184,64 @@ module Calabash
       Device.default.pan_between(Query.new(query_from), Query.new(query_to), options)
     end
 
-    # Performs a `pan` heading `left` on the (first) view that matches `query`.
-    # @see pan
+    # Performs a **pan** heading _left_ on the first view that matches `query`.
+    #
+    # @see #pan
     def pan_left(query, options={})
       pan(query, {x: 90, y: 50}, {x: 10, y: 50}, options)
     end
 
-    # Performs a `pan` heading `right` on the (first) view that matches
-    # `query`.
-    # @see pan
+    # Performs a **pan** heading _right_ on the first view that matches `query`.
+    #
+    # @see #pan
     def pan_right(query, options={})
       pan(query, {x: 10, y: 50}, {x: 90, y: 50}, options)
     end
 
-    # Performs a `pan` heading `up` on the (first) view that matches `query`.
-    # @see pan
+    # Performs a **pan** heading _up_ on the first view that matches `query`.
+    #
+    # @see #pan
     def pan_up(query, options={})
       pan(query, {x: 50, y: 90}, {x: 50, y: 10}, options)
     end
 
-    # Performs a `pan` heading `down` on the (first) view that matches `query`.
-    # @see pan
+    # Performs a **pan** heading _down_ on the first view that matches `query`.
+    #
+    # @see #pan
     def pan_down(query, options={})
       pan(query, {x: 50, y: 10}, {x: 50, y: 90}, options)
     end
 
-    # Performs a `pan` heading `left` on the screen.
-    # @see pan_left
+    # Performs a **pan** heading _left_ on the screen.
+    #
+    # @see #pan
     def pan_screen_left(options={})
       pan_left('*', options)
     end
 
-    # Performs a `pan` heading `right` on the screen.
-    # @see pan_right
+    # Performs a **pan** heading _right_ on the screen.
+    #
+    # @see #pan
     def pan_screen_right(options={})
       pan_right('*', options)
     end
 
-    # Performs a `pan` heading `up` on the screen.
-    # @see pan_up
+    # Performs a **pan** heading _up_ on the screen.
+    #
+    # @see #pan
     def pan_screen_up(options={})
       _pan_screen_up(options)
     end
 
-    # Performs a `pan` heading `down` on the screen.
-    # @see pan_down
+    # Performs a **pan** heading _down_ on the screen.
+    #
+    # @see #pan
     def pan_screen_down(options={})
       _pan_screen_down(options)
     end
 
-    # Performs a `flick` on the (first) view that matches `query`.
+    # Performs a **flick** on the first view that matches `query`.
+    #
     # A flick is a straight line swipe that **lifts the finger while
     # the gesture is still in motion**. This will often cause scrollable
     # views to continue moving for some time after the gesture is released.
@@ -257,91 +278,163 @@ module Calabash
       Device.default.flick(Query.new(query), from, to, options)
     end
 
-    # Performs a `flick` heading `left` on the (first) view that matches `query`.
-    # @see flick
+    # Performs a **flick** heading _left_ on the first view that matches `query`.
+    # @see #flick
     def flick_left(query, options={})
       flick(query, {x: 90, y: 50}, {x: 10, y: 50}, options)
     end
 
-    # Performs a `flick` heading `right` on the (first) view that matches
+    # Performs a **flick** heading _right_ on the first view that matches
     # `query`.
-    # @see flick
+    # @see #flick
     def flick_right(query, options={})
       flick(query, {x: 10, y: 50}, {x: 90, y: 50}, options)
     end
 
-    # Performs a `flick` heading `up` on the (first) view that matches `query`.
-    # @see flick
+    # Performs a **flick** heading _up_ on the first view that matches `query`.
+    # @see #flick
     def flick_up(query, options={})
       flick(query, {x: 50, y: 90}, {x: 50, y: 10}, options)
     end
 
-    # Performs a `flick` heading `down` on the (first) view that matches `query`.
-    # @see flick
+    # Performs a **flick** heading _down_ on the first view that matches `query`.
+    # @see #flick
     def flick_down(query, options={})
       flick(query, {x: 50, y: 10}, {x: 50, y: 90}, options)
     end
 
-    # Performs a `flick` heading `left` on the screen.
-    # @see flick_left
+    # Performs a **flick** heading _left_ on the screen.
+    # @see #flick
     def flick_screen_left(options={})
       flick_left('*', options)
     end
 
-    # Performs a `flick` heading `right` on the screen.
-    # @see flick_right
+    # Performs a **flick** heading _right_ on the screen.
+    # @see #flick
     def flick_screen_right(options={})
       flick_right('*', options)
     end
 
-    # Performs a `flick` heading `up` on the screen.
-    # @see flick_up
+    # Performs a **flick** heading _up_ on the screen.
+    # @see #flick
     def flick_screen_up(options={})
       _flick_screen_up(options)
     end
 
-    # Performs a `flick` heading `down` on the screen.
-    # @see flick_down
+    # Performs a **flick** heading _down_ on the screen.
+    # @see #flick
     def flick_screen_down(options={})
       _flick_screen_down(options)
     end
 
-    # Performs a `pinch` outwards.
+    # Performs a **pinch** outwards on the first view match by `query`.
+    #
+    # @param [String, Hash, Calabash::Query] query A query describing the view
+    #   to pinch.
+    # @param [Hash] options Options for controlling the pinch.
+    # @option options [Numeric] :duration The duration of the pinch. On iOS,
+    #   the duration must be between 0.5 and 60.
+    #
+    # @raise [ViewNotFoundError] If the `query` returns no results.
+    # @raise [ArgumentError] If `query` is invalid.
+    # @raise [ArgumentError] iOS: if the `:duration` is not between 0.5 and 60.
     def pinch_out(query, options={})
       Device.default.pinch(:out, query, options)
     end
 
-    # Performs a `pinch` inwards.
+    # Performs a **pinch** inwards on the first view match by `query`.
+    #
+    # @param [String, Hash, Calabash::Query] query A query describing the view
+    #   to pinch.
+    # @param [Hash] options Options for controlling the pinch.
+    # @option options [Numeric] :duration The duration of the pinch. On iOS,
+    #   the duration must be between 0.5 and 60.
+    #
+    # @raise [ViewNotFoundError] If the `query` returns no results.
+    # @raise [ArgumentError] If `query` is invalid.
+    # @raise [ArgumentError] iOS: if the `:duration` is not between 0.5 and 60.
     def pinch_in(query, options={})
       Device.default.pinch(:in, query, options)
     end
 
-    # Performs a `pinch` outwards on the screen.
+    # Performs a **pinch** outwards on the screen.
+    #
+    # @param [Hash] options Options for controlling the pinch.
+    # @option options [Numeric] :duration The duration of the pinch. On iOS,
+    #   the duration must be between 0.5 and 60.
+    #
+    # @raise [ViewNotFoundError] If the `query` returns no results.
+    # @raise [ArgumentError] If `query` is invalid.
+    # @raise [ArgumentError] iOS: if the `:duration` is not between 0.5 and 60.
     def pinch_screen_out(options={})
       _pinch_screen(:out, options)
     end
 
-    # Performs a `pinch` inwards on the screen.
+    # Performs a **pinch** inwards on the screen.
+    #
+    # @param [Hash] options Options for controlling the pinch.
+    # @option options [Numeric] :duration The duration of the pinch. On iOS,
+    #   the duration must be between 0.5 and 60.
+    #
+    # @raise [ViewNotFoundError] If the `query` returns no results.
+    # @raise [ArgumentError] If `query` is invalid.
+    # @raise [ArgumentError] iOS: if the `:duration` is not between 0.5 and 60.
     def pinch_screen_in(options={})
       _pinch_screen(:in, options)
     end
 
-    # Performs a `pinch` to zoom out.
+    # Performs a **pinch** to zoom out.
+    #
+    # @param [String, Hash, Calabash::Query] query A query describing the view
+    #   to pinch.
+    # @param [Hash] options Options for controlling the pinch.
+    # @option options [Numeric] :duration The duration of the pinch. On iOS,
+    #   the duration must be between 0.5 and 60.
+    #
+    # @raise [ViewNotFoundError] If the `query` returns no results.
+    # @raise [ArgumentError] If `query` is invalid.
+    # @raise [ArgumentError] iOS: if the `:duration` is not between 0.5 and 60.
     def pinch_to_zoom_out(query, options={})
       _pinch_to_zoom(:out, query, options)
     end
 
-    # Performs a `pinch` to zoom in.
+    # Performs a **pinch** to zoom in.
+    #
+    # @param [String, Hash, Calabash::Query] query A query describing the view
+    #   to pinch.
+    # @param [Hash] options Options for controlling the pinch.
+    # @option options [Numeric] :duration The duration of the pinch. On iOS,
+    #   the duration must be between 0.5 and 60.
+    #
+    # @raise [ViewNotFoundError] If the `query` returns no results.
+    # @raise [ArgumentError] If `query` is invalid.
+    # @raise [ArgumentError] iOS: if the `:duration` is not between 0.5 and 60.
     def pinch_to_zoom_in(query, options={})
       _pinch_to_zoom(:in, query, options)
     end
 
-    # Performs a `pinch` to zoom in on the screen.
+    # Performs a **pinch** on the screen to zoom in.
+    #
+    # @param [Hash] options Options for controlling the pinch.
+    # @option options [Numeric] :duration The duration of the pinch. On iOS,
+    #   the duration must be between 0.5 and 60.
+    #
+    # @raise [ViewNotFoundError] If the `query` returns no results.
+    # @raise [ArgumentError] If `query` is invalid.
+    # @raise [ArgumentError] iOS: if the `:duration` is not between 0.5 and 60.
     def pinch_screen_to_zoom_in(options={})
       _pinch_screen_to_zoom(:in, options)
     end
 
-    # Performs a `pinch` to zoom in on the screen.
+    # Performs a **pinch** on the screen to zoom out.
+    #
+    # @param [Hash] options Options for controlling the pinch.
+    # @option options [Numeric] :duration The duration of the pinch. On iOS,
+    #   the duration must be between 0.5 and 60.
+    #
+    # @raise [ViewNotFoundError] If the `query` returns no results.
+    # @raise [ArgumentError] If `query` is invalid.
+    # @raise [ArgumentError] iOS: if the `:duration` is not between 0.5 and 60.
     def pinch_screen_to_zoom_out(options={})
       _pinch_screen_to_zoom(:out, options)
     end