appium_lib 9.5.0 → 9.6.0

data/lib/appium_lib/common/command.rb

@@ -52,11 +52,19 @@ module Appium
         end_coverage:               [:post, 'session/:session_id/appium/app/end_test_coverage'.freeze],
         set_network_connection:     [:post, 'session/:session_id/network_connection'.freeze],
         get_performance_data:       [:post, 'session/:session_id/appium/getPerformanceData'.freeze],
+        get_ime_available_engines:  [:get,  'session/:session_id/ime/available_engines'.freeze],
+        get_ime_active_engine:      [:get,  'session/:session_id/ime/active_engine'.freeze],
+        get_ime_activated:          [:get,  'session/:session_id/ime/activated'.freeze],
+        ime_deactivate:             [:post, 'session/:session_id/ime/deactivate'.freeze],
+        ime_activate:               [:post, 'session/:session_id/ime/activate'.freeze],
 
         # iOS
         touch_id:                   [:post, 'session/:session_id/appium/simulator/touch_id'.freeze],
         toggle_touch_id_enrollment: [:post, 'session/:session_id/appium/simulator/toggle_touch_id_enrollment'.freeze]
-      }.merge(COMMAND_NO_ARG).merge(::Selenium::WebDriver::Remote::OSS::Bridge::COMMANDS).freeze
+      }.merge(COMMAND_NO_ARG).freeze
+
+      COMMANDS_EXTEND_OSS = COMMAND.merge(::Selenium::WebDriver::Remote::OSS::Bridge::COMMANDS).freeze
+      COMMANDS_EXTEND_W3C = COMMAND.merge(::Selenium::WebDriver::Remote::W3C::Bridge::COMMANDS).freeze
     end
   end
 end

data/lib/appium_lib/common/helper.rb

@@ -77,9 +77,9 @@ module Appium
       end
 
       # http://nokogiri.org/Nokogiri/XML/SAX/Document.html
-      def start_element(name, attrs = [])
+      def start_element(name, attrs = [], driver = $driver)
         # Count only visible elements. Android is always visible
-        element_visible = $driver.device_is_android? ? true : Hash[attrs]['visible'] == 'true'
+        element_visible = driver.device_is_android? ? true : Hash[attrs]['visible'] == 'true'
         @result[name] += 1 if element_visible
       end
 
@@ -115,8 +115,8 @@ module Appium
     # ```ruby
     # px_to_window_rel x: 50, y: 150
     # ```
-    def px_to_window_rel(opts = {})
-      w = $driver.window_size
+    def px_to_window_rel(opts = {}, driver = $driver)
+      w = driver.window_size
       x = opts.fetch :x, 0
       y = opts.fetch :y, 0
 
@@ -214,6 +214,7 @@ module Appium
       end
     end
 
+    # @private
     def _no_such_element
       error_message = 'An element could not be located on the page using the given search parameters.'
       raise Selenium::WebDriver::Error::NoSuchElementError, error_message

data/lib/appium_lib/common/patch.rb

@@ -27,7 +27,7 @@ module Appium
       # ```
       #
       # @return [OpenStruct] the relative x, y in a struct. ex: { x: 0.50, y: 0.20 }
-      def location_rel
+      def location_rel(driver = $driver)
         # TODO: Remove with 'refine Appium ruby binding'
         #     https://github.com/appium/ruby_lib/issues/602
         if ::Appium.selenium_webdriver_version_more?('3.4.0')
@@ -50,7 +50,7 @@ module Appium
         center_x = location_x + (size_width / 2.0)
         center_y = location_y + (size_height / 2.0)
 
-        w = $driver.window_size
+        w = driver.window_size
         OpenStruct.new(x: "#{center_x} / #{w.width.to_f}",
                        y: "#{center_y} / #{w.height.to_f}")
       end
@@ -129,8 +129,13 @@ def patch_webdriver_bridge
         # for example invalid JSON will not be a Hash
         Appium::Logger.ap_info command_hash
       end
-      delay = $driver.global_webdriver_http_sleep
-      sleep delay if !delay.nil? && delay > 0
+
+      if !$driver.nil? && $driver.global_webdriver_http_sleep
+        warn '[DEPRECATION] global_webdriver_http_sleep will be removed. Please arrange with timeout.'
+
+        delay = $driver.global_webdriver_http_sleep
+        sleep delay if delay > 0
+      end
       # Appium::Logger.info "verb: #{verb}, path #{path}, command_hash #{command_hash.to_json}"
       http.call(verb, path, command_hash)
     end # def
@@ -168,7 +173,18 @@ end
 def patch_remote_driver_commands
   Selenium::WebDriver::Remote::OSS::Bridge.class_eval do
     def commands(command)
-      ::Appium::Driver::Commands::COMMAND[command]
+      ::Appium::Driver::Commands::COMMANDS_EXTEND_OSS[command]
+    end
+  end
+
+  Selenium::WebDriver::Remote::W3C::Bridge.class_eval do
+    def commands(command)
+      case command
+      when :status, :is_element_displayed
+        ::Appium::Driver::Commands::COMMANDS_EXTEND_OSS[command]
+      else
+        ::Appium::Driver::Commands::COMMANDS_EXTEND_W3C[command]
+      end
     end
   end
 end

data/lib/appium_lib/common/version.rb

@@ -1,5 +1,5 @@
 module Appium
   # Version and Date are defined on the 'Appium' module, not 'Appium::Common'
-  VERSION = '9.5.0'.freeze unless defined? ::Appium::VERSION
-  DATE    = '2017-08-05'.freeze unless defined? ::Appium::DATE
+  VERSION = '9.6.0'.freeze unless defined? ::Appium::VERSION
+  DATE    = '2017-08-19'.freeze unless defined? ::Appium::DATE
 end

data/lib/appium_lib/common/wait.rb

@@ -48,6 +48,7 @@ module Appium
     end
 
     # process opts before calling _generic_wait
+    # @private
     def _process_wait_opts(opts)
       opts = { timeout: opts } if opts.is_a?(Numeric)
       raise 'opts must be a hash' unless opts.is_a? Hash

data/lib/appium_lib/device/device.rb

@@ -254,14 +254,7 @@ module Appium
 
         add_endpoint_method(:background_app) do
           def background_app(duration = 0)
-            # https://github.com/appium/ruby_lib/issues/500, https://github.com/appium/appium/issues/7741
-            # `execute :background_app, {}, seconds: { timeout: duration_milli_sec }` works over Appium 1.6.4
-            if $driver.automation_name_is_xcuitest?
-              duration_milli_sec = duration.nil? ? nil : duration * 1000
-              execute :background_app, {}, seconds: { timeout: duration_milli_sec }
-            else
-              execute :background_app, {}, seconds: duration
-            end
+            execute :background_app, {}, seconds: duration
           end
         end
 
@@ -295,16 +288,9 @@ module Appium
           def hide_keyboard(close_key = nil, strategy = nil)
             option = {}
 
-            if $driver.device_is_android? # Android can only tapOutside.
-              option[:key] = close_key if close_key
-              option[:strategy] = strategy || :tapOutside # default to pressKey
-            elsif $driver.automation_name_is_xcuitest?
-              option[:key] = close_key if close_key
-              option[:strategy] = strategy if strategy
-            else
-              option[:key] = close_key || 'Done'        # default to Done key.
-              option[:strategy] = strategy || :pressKey # default to pressKey
-            end
+            option[:key] = close_key || 'Done'        # default to Done key.
+            option[:strategy] = strategy || :pressKey # default to pressKey
+
             execute :hide_keyboard, {}, option
           end
         end
@@ -440,6 +426,10 @@ module Appium
         Selenium::WebDriver::Remote::OSS::Bridge.class_eval do
           block_given? ? class_eval(&Proc.new) : define_method(method) { execute method }
         end
+
+        Selenium::WebDriver::Remote::W3C::Bridge.class_eval do
+          block_given? ? class_eval(&Proc.new) : define_method(method) { execute method }
+        end
       end
 
       # @!method find_element_with_appium
@@ -520,7 +510,7 @@ module Appium
         #   ```
         add_endpoint_method(:ime_activate) do
           def ime_activate(ime_name)
-            execute :imeActivateEngine, {}, engine: ime_name
+            execute :ime_activate, {}, engine: ime_name
           end
         end
 
@@ -533,7 +523,7 @@ module Appium
         #   ```
         add_endpoint_method(:ime_available_engines) do
           def ime_available_engines
-            execute :imeGetAvailableEngines
+            execute :get_ime_available_engines
           end
         end
 
@@ -546,7 +536,7 @@ module Appium
         #   ```
         add_endpoint_method(:ime_active_engine) do
           def ime_active_engine
-            execute :imeGetActiveEngine
+            execute :get_ime_active_engine
           end
         end
 
@@ -559,7 +549,7 @@ module Appium
         #   ```
         add_endpoint_method(:ime_activated) do
           def ime_activated
-            execute :imeIsActivated
+            execute :get_ime_activated
           end
         end
 
@@ -573,7 +563,7 @@ module Appium
         #   ```
         add_endpoint_method(:ime_deactivate) do
           def ime_deactivate
-            execute :imeDeactivate, {}
+            execute :ime_deactivate, {}
           end
         end
       end

data/lib/appium_lib/device/multi_touch.rb

@@ -14,31 +14,56 @@ module Appium
   # multi_touch_action.add action_1
   # multi_touch_action.add action_2
   # multi_touch_action.perform
+  # ```
+  #
+  # ```
+  # # with an arbitrary driver
+  # driver =  Appium::Driver.new(opts, false).start_driver
+  # multi_touch_action = MultiTouch.new(driver)
+  # multi_touch_action.add action_1
+  # multi_touch_action.add action_2
+  # multi_touch_action.perform
+  # ```
+
   class MultiTouch
     class << self
       # Convenience method for pinching the screen.
       # Places two fingers at the edges of the screen and brings them together.
       # @param percentage (int) The percent size by which to shrink the screen when pinched.
       # @param auto_perform (boolean) Whether to perform the action immediately (default true)
+      # @param driver (Driver) Set a driver to conduct the action. DEfault is global driver($driver)
       #
       # ```ruby
-      # action = pinch 75 #=> Pinch the screen from the top right and bottom left corners
+      # pinch 75 #=> Pinch the screen from the top right and bottom left corners
+      # ```
+      #
+      # Without auto_perform
+      #
+      # ```ruby
+      # action = pinch 75, false #=> Pinch the screen from the top right and bottom left corners
       # action.perform    #=> to 25% of its size.
       # ```
-      def pinch(percentage = 25, auto_perform = true)
+      #
+      # With driver
+      #
+      # ```ruby
+      # driver =  Appium::Driver.new(opts, false).start_driver
+      # pinch 75, true, driver #=> Pinch the screen from the top right and bottom left corners
+      # ```
+      def pinch(percentage = 25, auto_perform = true, driver = $driver)
         raise ArgumentError("Can't pinch to greater than screen size.") if percentage > 100
 
         rate = Float(percentage) / 100
+        pinch = MultiTouch.new(driver)
 
-        if $driver.automation_name_is_xcuitest?
-          top, bottom = pinch_for_xcuitest(rate)
-        elsif $driver.device_is_android?
+        if pinch.driver.automation_name_is_xcuitest?
+          top, bottom = pinch_for_xcuitest(rate, pinch.driver)
+        elsif pinch.driver.device_is_android?
           top, bottom = pinch_android(rate)
         else
           top, bottom = pinch_ios(rate)
         end
 
-        pinch = MultiTouch.new
         pinch.add top
         pinch.add bottom
         return pinch unless auto_perform
@@ -49,25 +74,39 @@ module Appium
       # Places two fingers at the edges of the screen and brings them together.
       # @param percentage (int) The percent size by which to shrink the screen when pinched.
       # @param auto_perform (boolean) Whether to perform the action immediately (default true)
+      # @param driver (Driver) Set a driver to conduct the action. DEfault is global driver($driver)
       #
       # ```ruby
       # action = zoom 200 #=> Zoom in the screen from the center until it doubles in size.
-      # action.perform
       # ```
-      def zoom(percentage = 200, auto_perform = true)
+      #
+      # Without auto_perform
+      #
+      # ```ruby
+      # action = zoom 200, false #=> Zoom in the screen from the center until it doubles in size.
+      # action.perform    #=> to 25% of its size.
+      # ```
+      #
+      # With driver
+      #
+      # ```ruby
+      # driver =  Appium::Driver.new(opts, false).start_driver
+      # pinch 200, true, driver #=> Zoom in the screen from the center until it doubles in size.
+      # ```
+      def zoom(percentage = 200, auto_perform = true, driver = $driver)
         raise ArgumentError("Can't zoom to smaller then screen size.") if percentage < 100
 
         rate = 100 / Float(percentage)
+        zoom = MultiTouch.new(driver)
 
-        if $driver.automation_name_is_xcuitest?
-          top, bottom = zoom_for_xcuitest(rate)
-        elsif $driver.device_is_android?
+        if zoom.driver.automation_name_is_xcuitest?
+          top, bottom = zoom_for_xcuitest(rate, zoom.driver)
+        elsif zoom.driver.device_is_android?
           top, bottom = zoom_android(rate)
         else
           top, bottom = zoom_ios(rate)
         end
 
-        zoom = MultiTouch.new
         zoom.add top
         zoom.add bottom
         return zoom unless auto_perform
@@ -76,10 +115,10 @@ module Appium
 
       private
 
-      def pinch_for_xcuitest(rate)
+      def pinch_for_xcuitest(rate, driver)
         height = 100
 
-        ele = $driver.find_element :class, 'XCUIElementTypeApplication'
+        ele = driver.find_element :class, 'XCUIElementTypeApplication'
         top = TouchAction.new
         top.swipe({ start_x: 0.5, start_y: 0.0,
                     offset_x: 0.0, offset_y: (1 - rate) * height }, ele)
@@ -119,10 +158,10 @@ module Appium
         [top, bottom]
       end
 
-      def zoom_for_xcuitest(rate)
+      def zoom_for_xcuitest(rate, driver)
         height = 100
 
-        ele = $driver.find_element :class, 'XCUIElementTypeApplication'
+        ele = driver.find_element :class, 'XCUIElementTypeApplication'
         top = TouchAction.new
         top.swipe({ start_x: 0.5, start_y: (1 - rate) * height,
                     offset_x: 0.0, offset_y: - (1 - rate) * height }, ele)
@@ -163,11 +202,12 @@ module Appium
       end
     end # self
 
-    attr_reader :actions
+    attr_reader :actions, :driver
 
-    # Create a new multi-action
-    def initialize
+    # Create a new multi-action with Driver
+    def initialize(driver = $driver)
       @actions = []
+      @driver = driver
     end
 
     # Add a touch_action to be performed
@@ -178,7 +218,7 @@ module Appium
 
     # Ask Appium to perform the actions
     def perform
-      $driver.multi_touch @actions
+      @driver.multi_touch @actions
       @actions.clear
     end
   end # class MultiTouch

data/lib/appium_lib/device/touch_actions.rb

@@ -1,6 +1,6 @@
 module Appium
   # Perform a series of gestures, one after another.  Gestures are chained
-  # together and only performed when `perform()` is called.
+  # together and only performed when `perform()` is called. Default is conducted by global driver.
   #
   # Each method returns the object itself, so calls can be chained.
   #
@@ -17,7 +17,15 @@ module Appium
   # # called `swipe(...).perform` in this method.
   # swipe(start_x: 75, start_y: 500, offset_x: 75, offset_y: 20, duration: 500)
   # ```
-
+  #
+  # If you'd like to perform the chain with an arbitrary driver:
+  # ```ruby
+  # driver =  Appium::Driver.new(opts, false).start_driver
+  # action = TouchAction.new.press(x: 45, y: 100).wait(5).release
+  # action.perform(@driver)
+  # action = TouchAction.new.swipe(....)
+  # action.perform(@driver)
+  # ```
   class TouchAction
     ACTIONS         = [:move_to, :long_press, :double_tap, :two_finger_tap, :press, :release, :tap, :wait, :perform].freeze
     COMPLEX_ACTIONS = [:swipe].freeze
@@ -176,21 +184,22 @@ module Appium
     end
 
     # Ask the driver to perform all actions in this action chain.
-    def perform
-      $driver.touch_actions @actions
+    def perform(driver = $driver)
+      driver.touch_actions @actions
       @actions.clear
       self
     end
 
     # Does nothing, currently.
-    def cancel
+    def cancel(driver = $driver)
       @actions << { action: cancel }
-      $driver.touch_actions @actions
+      driver.touch_actions @actions
       self
     end
 
-    def swipe_coordinates(end_x: nil, end_y: nil, offset_x: nil, offset_y: nil)
-      if $driver.device_is_android?
+    # Visible for testing
+    def swipe_coordinates(end_x: nil, end_y: nil, offset_x: nil, offset_y: nil, driver: $driver)
+      if driver.device_is_android?
         puts 'end_x and end_y are used for Android. Not offset_x and offset_y.' if end_x.nil? || end_y.nil?
         end_x ||= 0
         end_y ||= 0

data/lib/appium_lib/driver.rb

@@ -24,7 +24,17 @@ require_relative 'ios/element/generic'
 require_relative 'ios/element/textfield'
 require_relative 'ios/element/text'
 require_relative 'ios/mobile_methods'
-require_relative 'ios/xcuitest_gestures'
+
+# ios - xcuitest
+require_relative 'ios/xcuitest/element'
+require_relative 'ios/xcuitest/gestures'
+require_relative 'ios/xcuitest/mobile_methods'
+require_relative 'ios/xcuitest/device'
+require_relative 'ios/xcuitest/helper'
+require_relative 'ios/xcuitest/element/text'
+require_relative 'ios/xcuitest/element/textfield'
+require_relative 'ios/xcuitest/element/generic'
+require_relative 'ios/xcuitest/element/button'
 
 # android
 require_relative 'android/helper'
@@ -37,6 +47,11 @@ require_relative 'android/element/textfield'
 require_relative 'android/element/text'
 require_relative 'android/mobile_methods'
 
+require_relative 'android/device'
+
+# android - uiautomator2
+require_relative 'android/uiautomator2/helper.rb'
+
 # device methods
 require_relative 'device/device'
 require_relative 'device/touch_actions'
@@ -168,8 +183,8 @@ module Appium
   # if modules is a module instead of an array, then the constants of
   # that module are promoted on.
   # otherwise, the array of modules will be used as the promotion target.
-  def self.promote_singleton_appium_methods(modules)
-    raise 'Driver is nil' if $driver.nil?
+  def self.promote_singleton_appium_methods(modules, driver = $driver)
+    raise 'Global $driver is nil' if driver.nil?
 
     target_modules = []
 
@@ -185,15 +200,15 @@ module Appium
     target_modules.each do |const|
       # noinspection RubyResolve
       # rubocop:disable Style/MultilineIfModifier
-      $driver.public_methods(false).each do |m|
+      driver.public_methods(false).each do |m|
         const.send(:define_singleton_method, m) do |*args, &block|
           begin
             super(*args, &block) # promote.rb
           rescue NoMethodError, ArgumentError
-            $driver.send m, *args, &block if $driver.respond_to?(m)
+            driver.send m, *args, &block if driver.respond_to?(m)
           end
           # override unless there's an existing method with matching arity
-        end unless const.respond_to?(m) && const.method(m).arity == $driver.method(m).arity
+        end unless const.respond_to?(m) && const.method(m).arity == driver.method(m).arity
       end
       # rubocop:enable Style/MultilineIfModifier
     end
@@ -221,13 +236,13 @@ module Appium
   # # promote on minispec
   # Appium.promote_appium_methods Minitest::Spec
   # ```
-  def self.promote_appium_methods(class_array)
-    raise 'Driver is nil' if $driver.nil?
+  def self.promote_appium_methods(class_array, driver = $driver)
+    raise 'Driver is nil' if driver.nil?
     # Wrap single class into an array
     class_array = [class_array] unless class_array.class == Array
     # Promote Appium driver methods to class instance methods.
     class_array.each do |klass|
-      $driver.public_methods(false).each do |m|
+      driver.public_methods(false).each do |m|
         klass.class_eval do
           define_method m do |*args, &block|
             begin
@@ -239,7 +254,7 @@ module Appium
               # so rescue argument error
               # and call the name method on $driver
             rescue NoMethodError, ArgumentError
-              $driver.send m, *args, &block if $driver.respond_to?(m)
+              driver.send m, *args, &block if driver.respond_to?(m)
             end
           end
         end
@@ -320,7 +335,8 @@ module Appium
     # @return [Integer]
     attr_reader :appium_wait_interval
 
-    # Creates a new driver
+    # Creates a new driver. The driver is defined as global scope by default.
+    # We can avoid defining global driver.
     #
     # @example
     #
@@ -330,7 +346,7 @@ module Appium
     #
     #     # platformName takes a string or a symbol.
     #
-    #     # Start iOS driver
+    #     # Start iOS driver with global scope
     #     opts = {
     #              caps: {
     #                platformName: :ios,
@@ -342,7 +358,7 @@ module Appium
     #            }
     #     Appium::Driver.new(opts).start_driver
     #
-    #     # Start Android driver
+    #     # Start Android driver with global scope
     #     opts = {
     #              caps: {
     #                platformName: :android,
@@ -354,13 +370,30 @@ module Appium
     #              }
     #            }
     #     Appium::Driver.new(opts).start_driver
+    #
+    #     # Start iOS driver without global scope
+    #     opts = {
+    #              caps: {
+    #                platformName: :ios,
+    #                app: '/path/to/MyiOS.app'
+    #              },
+    #              appium_lib: {
+    #                wait_timeout: 30
+    #              }
+    #            }
+    #     Appium::Driver.new(opts, false).start_driver
     #     ```
     #
     # @param opts [Object] A hash containing various options.
+    # @param global_driver [Bool] A bool require global driver before initialize.
     # @return [Driver]
-    def initialize(opts = {})
-      # quit last driver
-      $driver.driver_quit if $driver
+    def initialize(opts = {}, global_driver = true)
+      if global_driver
+        warn '[DEPRECATION] Appium::Driver.new(opts) will not generate global driver by default.' \
+                 'If you would like to generate the global driver dy default, ' \
+                 'please initialise driver with Appium::Driver.new(opts, true)'
+        $driver.driver_quit if $driver
+      end
       raise 'opts must be a hash' unless opts.is_a? Hash
 
       opts              = Appium.symbolize_keys opts
@@ -391,11 +424,19 @@ module Appium
 
       if device_is_android?
         extend Appium::Android
+        extend Appium::Android::Device
+        if automation_name_is_uiautomator2?
+          extend Appium::Android::Uiautomator2::Helper
+        end
       else
         extend Appium::Ios
-        if automation_name_is_xcuitest? # Override touch actions
+        if automation_name_is_xcuitest?
+          # Override touch actions and patch_webdriver_element
           extend Appium::Ios::Xcuitest
+          extend Appium::Ios::Xcuitest::Helper
           extend Appium::Ios::Xcuitest::Gesture
+          extend Appium::Ios::Xcuitest::Device
+          extend Appium::Ios::Xcuitest::Element
         end
       end
 
@@ -417,7 +458,7 @@ module Appium
       end
 
       # Save global reference to last created Appium driver for top level methods.
-      $driver = self
+      $driver = self if global_driver
 
       self # return newly created driver
     end
@@ -485,6 +526,12 @@ module Appium
       !@automation_name.nil? && @automation_name == :uiautomator2
     end
 
+    # Return true if automationName is 'Espresso'
+    # @return [Boolean]
+    def automation_name_is_espresso?
+      !@automation_name.nil? && @automation_name == :espresso
+    end
+
     # Return true if the target Appium server is over REQUIRED_VERSION_XCUITEST.
     # If the Appium server is under REQUIRED_VERSION_XCUITEST, then error is raised.
     # @return [Boolean]
@@ -617,6 +664,9 @@ module Appium
       nil
     end
 
+    # Alias for driver_quit
+    alias_method :quit_driver, :driver_quit
+
     # Creates a new global driver and quits the old one if it exists.
     # You can customise http_client as the following
     #
@@ -677,11 +727,21 @@ module Appium
       check_server_version_xcuitest
       set_automation_name_if_nil
 
-      @driver.manage.timeouts.implicit_wait = @default_wait
+      set_implicit_wait(@default_wait)
 
       @driver
     end
 
+    # To ignore error for Espresso Driver
+    def set_implicit_wait(wait)
+      @driver.manage.timeouts.implicit_wait = wait
+    rescue Selenium::WebDriver::Error::UnknownError => e
+      unless e.message.include?('The operation requested is not yet implemented by Espresso driver')
+        raise ::Appium::Error::ServerError
+      end
+      {}
+    end
+
     # Set implicit wait to zero.
     def no_wait
       @driver.manage.timeouts.implicit_wait = 0