appium_lib 9.6.1 → 9.7.0

data/lib/appium_lib/common/touch_actions.rb

@@ -0,0 +1,48 @@
+module Appium
+  # Perform a series of gestures, one after another.  Gestures are chained
+  # 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.
+  #
+  # ```ruby
+  # action = TouchAction.new.press(x: 45, y: 100).wait(5).release
+  # action.perform
+  # action = TouchAction.new.swipe(....)
+  # action.perform
+  # ```
+  #
+  # Or each methods can call without `TouchAction.new` as the following.
+  # In this case, `perform` is called automatically.
+  # ```ruby
+  # # 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 < ::Appium::Core::TouchAction
+    COMPLEX_ACTIONS = ::Appium::Core::TouchAction::COMPLEX_ACTIONS
+
+    class << self
+      COMPLEX_ACTIONS.each do |action|
+        define_method(action) do |opts|
+          auto_perform = opts.delete(:auto_perform) { |_k| true }
+          ta           = ::Appium::TouchAction.new($driver)
+          ta.send(action, opts)
+          return ta unless auto_perform
+          ta.perform
+        end
+      end
+    end
+
+    def initialize(driver = $driver)
+      super driver
+    end
+  end # class TouchAction
+end # module Appium

data/lib/appium_lib/common/wait.rb

@@ -1,49 +1,10 @@
+require_relative '../core/common/base/wait'
+
 module Appium
   module Common
-    class Wait < ::Selenium::WebDriver::Wait
+    class Wait < ::Appium::Core::Base::Wait
       def initialize(opts = {})
-        valid_keys = [:timeout, :interval, :message, :ignore, :return_if_true]
-        invalid_keys = []
-        opts.keys.each { |key| invalid_keys << key unless valid_keys.include?(key) }
-        # [:one, :two] => :one, :two
-        raise "Invalid keys #{invalid_keys.to_s[1..-2]}. Valid keys are #{valid_keys.to_s[1..-2]}" unless invalid_keys.empty?
-
-        @timeout        = opts.fetch(:timeout, DEFAULT_TIMEOUT)
-        @interval       = opts.fetch(:interval, DEFAULT_INTERVAL)
-        @message        = opts[:message]
-        @ignored        = Array(opts[:ignore] || ::Exception)
-        @return_if_true = opts[:return_if_true]
-
-        super(timeout: @timeout, interval: @interval, message: @message, ignore: @ignored)
-      end
-
-      # Wait code from the selenium Ruby gem
-      # https://github.com/SeleniumHQ/selenium/blob/cf501dda3f0ed12233de51ce8170c0e8090f0c20/rb/lib/selenium/webdriver/common/wait.rb
-      # @override
-      def until
-        end_time   = Time.now + @timeout
-        last_error = nil
-
-        until Time.now > end_time
-          begin
-            return yield unless @return_if_true
-
-            result = yield
-            return result if result
-          rescue ::Errno::ECONNREFUSED => e
-            raise e
-          rescue *@ignored => last_error # rubocop:disable Lint/HandleExceptions
-            # swallowed
-          end
-
-          sleep @interval
-        end
-
-        msg = @message ? @message.dup : "timed out after #{@timeout} seconds"
-
-        msg << " (#{last_error.message})" if last_error
-
-        raise Selenium::WebDriver::Error::TimeOutError, msg
+        super(opts)
       end
     end
 
@@ -73,8 +34,8 @@ module Appium
     def wait_true(opts = {})
       opts = _process_wait_opts(opts).merge(return_if_true: true)
 
-      opts[:timeout]  ||= @appium_wait_timeout
-      opts[:interval] ||= @appium_wait_interval
+      opts[:timeout]  ||= @core.wait_timeout
+      opts[:interval] ||= @core.wait_interval
 
       wait = ::Appium::Common::Wait.new opts
       wait.until { yield }
@@ -96,11 +57,11 @@ module Appium
     def wait(opts = {})
       opts = _process_wait_opts(opts).merge(return_if_true: false)
 
-      opts[:timeout]  ||= @appium_wait_timeout
-      opts[:interval] ||= @appium_wait_interval
+      opts[:timeout]  ||= @core.wait_timeout
+      opts[:interval] ||= @core.wait_interval
 
       wait = ::Appium::Common::Wait.new opts
       wait.until { yield }
     end
-  end # module Common
-end # module Appium
+  end
+end

data/lib/appium_lib/core/android.rb

@@ -0,0 +1,4 @@
+# loaded in common/driver.rb
+require_relative 'android/search_context'
+require_relative 'android/device'
+require_relative 'android/uiautomator1/bridge'

data/lib/appium_lib/core/android/device.rb

@@ -0,0 +1,142 @@
+module Appium
+  module Android
+    module Device
+      extend Forwardable
+
+      # @!method background_app
+      #  Backgrounds the app for a set number of seconds.
+      #  This is a blocking application
+      # @param [Integer] seconds How many seconds to background the app for.
+      #
+      #   ```ruby
+      #   background_app
+      #   background_app(5)
+      #   background_app(-1) #=> the app never come back. https://github.com/appium/appium/issues/7741
+      #   ```
+
+      # @!method hide_keyboard
+      #   Hide the onscreen keyboard
+      #   @param [String] close_key The name of the key which closes the keyboard.
+      #     Defaults to 'Done' for iOS(except for XCUITest).
+      #   @param [Symbol] strategy The symbol of the strategy which closes the keyboard.
+      #     XCUITest ignore this argument.
+      #     Default for iOS is `:pressKey`. Default for Android is `:tapOutside`.
+      #  ```ruby
+      #  hide_keyboard # Close a keyboard with the 'Done' button
+      #  hide_keyboard('Finished') # Close a keyboard with the 'Finished' button
+      #  hide_keyboard(nil, :tapOutside) # Close a keyboard with tapping out side of keyboard
+      #  ```
+
+      # @!method end_coverage
+      #   Android only;  Ends the test coverage and writes the results to the given path on device.
+      #   @param [String] path Path on the device to write too.
+      #   @param [String] intent Intent to broadcast when ending coverage.
+
+      # @!method start_activity
+      #   Start a new activity within the current app or launch a new app and start the target activity.
+      #
+      #   Android only.
+      #   @option [String] The package owning the activity [required]
+      #   @option [String] The target activity [required]
+      #   @option opts [String] The package to start before the target package [optional]
+      #   @option opts [String] The activity to start before the target activity [optional]
+      #
+      #   ```ruby
+      #   start_activity app_package: 'io.appium.android.apis',
+      #     app_activity: '.accessibility.AccessibilityNodeProviderActivity'
+      #   ```
+
+      # @!method set_network_connection
+      #   Set the device network connection mode
+      #   @param [String] path Bit mask that represent the network mode
+      #
+      #   Value (Alias)      | Data | Wifi | Airplane Mode
+      #   -------------------------------------------------
+      #   1 (Airplane Mode)  | 0    | 0    | 1
+      #   6 (All network on) | 1    | 1    | 0
+      #   4 (Data only)      | 1    | 0    | 0
+      #   2 (Wifi only)      | 0    | 1    | 0
+      #   0 (None)           | 0    | 0    | 0
+      #
+
+      # @!method get_performance_data_types
+      #   Get the information type of the system state which is supported to read such as
+      #   cpu, memory, network, battery via adb commands.
+      #   https://github.com/appium/appium-base-driver/blob/be29aec2318316d12b5c3295e924a5ba8f09b0fb/lib/mjsonwp/routes.js#L300
+      #
+      #   ```ruby
+      #   get_performance_data_types #=> ["cpuinfo", "batteryinfo", "networkinfo", "memoryinfo"]
+      #   ```
+
+      # @!method get_performance_data
+      #   Get the resource usage information of the application.
+      #   https://github.com/appium/appium-base-driver/blob/be29aec2318316d12b5c3295e924a5ba8f09b0fb/lib/mjsonwp/routes.js#L303
+      #   @param [String] package_name Package name
+      #   @param [String] data_type Data type get with `get_performance_data_types`
+      #   @param [String] data_read_timeout Command timeout. Default is 2.
+      #
+      #   ```ruby
+      #   get_performance_data package_name: package_name, data_type: data_type, data_read_timeout: 2
+      #   ```
+      class << self
+        def extended(_mod)
+          Appium::Core::Device.extend_webdriver_with_forwardable
+
+          # Android
+          Appium::Core::Device.add_endpoint_method(:start_activity) do
+            def start_activity(opts)
+              raise 'opts must be a hash' unless opts.is_a? Hash
+              app_package = opts[:app_package]
+              raise 'app_package is required' unless app_package
+              app_activity = opts[:app_activity]
+              raise 'app_activity is required' unless app_activity
+              app_wait_package  = opts.fetch(:app_wait_package, '')
+              app_wait_activity = opts.fetch(:app_wait_activity, '')
+
+              unknown_opts = opts.keys - [:app_package, :app_activity, :app_wait_package, :app_wait_activity]
+              raise "Unknown options #{unknown_opts}" unless unknown_opts.empty?
+
+              execute :start_activity, {}, appPackage: app_package,
+                                           appActivity: app_activity,
+                                           appWaitPackage: app_wait_package,
+                                           appWaitActivity: app_wait_activity
+            end
+          end
+
+          # Android, Override
+          Appium::Core::Device.add_endpoint_method(:hide_keyboard) do
+            def hide_keyboard(close_key = nil, strategy = nil)
+              option = {}
+
+              option[:key] = close_key if close_key
+              option[:strategy] = strategy || :tapOutside # default to pressKey
+
+              execute :hide_keyboard, {}, option
+            end
+          end
+
+          # TODO: TEST ME
+          Appium::Core::Device.add_endpoint_method(:end_coverage) do
+            def end_coverage(path, intent)
+              execute :end_coverage, {}, path: path, intent: intent
+            end
+          end
+
+          Appium::Core::Device.add_endpoint_method(:set_network_connection) do
+            def set_network_connection(mode)
+              execute :set_network_connection, {}, type: mode
+            end
+          end
+
+          Appium::Core::Device.add_endpoint_method(:get_performance_data) do
+            def get_performance_data(package_name:, data_type:, data_read_timeout: 1000)
+              execute :get_performance_data, {}, packageName: package_name,
+                                                 dataType: data_type,
+                                                 dataReadTimeout: data_read_timeout
+            end
+          end
+        end
+      end
+    end # module Device
+  end # module Android
+end # module Appium

data/lib/appium_lib/core/android/search_context.rb

@@ -0,0 +1,17 @@
+module Appium
+  module Core
+    module Android
+      module SearchContext
+        # @!method uiautomator_find
+        #   find_element/s can be used with a [UISelector](http://developer.android.com/tools/help/uiautomator/UiSelector.html).
+        #
+        #   ```ruby
+        #    find_elements :uiautomator, 'new UiSelector().clickable(true)'
+        #   ```
+        def self.extend
+          ::Appium::Core::Base::SearchContext.add_finders(uiautomator: '-android uiautomator')
+        end
+      end # class << self
+    end # module Ios
+  end # module Core
+end # module Appium

data/lib/appium_lib/core/android/uiautomator1/bridge.rb

@@ -0,0 +1,16 @@
+require_relative '../../android'
+
+module Appium
+  module Core
+    module Android
+      module Uiautomator1
+        module Bridge
+          def self.for(target)
+            target.extend Appium::Android::Device
+            ::Appium::Core::Android::SearchContext.extend
+          end
+        end
+      end
+    end
+  end
+end

data/lib/appium_lib/core/android/uiautomator2/bridge.rb

@@ -0,0 +1,16 @@
+require_relative '../../android_uiautomator2'
+
+module Appium
+  module Core
+    module Android
+      module Uiautomator2
+        module Bridge
+          def self.for(target)
+            target.extend Appium::Android::Device
+            ::Appium::Core::Android::SearchContext.extend
+          end
+        end
+      end
+    end
+  end
+end

data/lib/appium_lib/core/android_uiautomator2.rb

@@ -0,0 +1,4 @@
+# loaded in common/driver.rb
+require_relative 'android/search_context'
+require_relative 'android/device'
+require_relative 'android/uiautomator2/bridge'

data/lib/appium_lib/core/common.rb

@@ -0,0 +1,6 @@
+require_relative 'common/logger'
+require_relative 'common/error'
+require_relative 'common/log'
+require_relative 'common/command'
+require_relative 'common/device'
+require_relative 'common/base'

data/lib/appium_lib/core/common/base.rb

@@ -0,0 +1,8 @@
+# The following files have selenium-webdriver related stuff.
+require_relative 'base/driver'
+require_relative 'base/bridge'
+require_relative 'base/capabilities'
+require_relative 'base/http_default'
+require_relative 'base/search_context'
+require_relative 'base/command'
+require_relative 'base/wait'

data/lib/appium_lib/core/common/base/bridge.rb

@@ -0,0 +1,47 @@
+module Appium
+  module Core
+    class Base
+      class Bridge < ::Selenium::WebDriver::Remote::Bridge
+        def self.handshake(**opts)
+          desired_capabilities = opts.delete(:desired_capabilities)
+
+          if desired_capabilities.is_a?(Symbol)
+            unless Remote::Capabilities.respond_to?(desired_capabilities)
+              raise Error::WebDriverError, "invalid desired capability: #{desired_capabilities.inspect}"
+            end
+            desired_capabilities = Remote::Capabilities.__send__(desired_capabilities)
+          end
+
+          bridge = new(opts)
+          capabilities = bridge.create_session(desired_capabilities)
+
+          case bridge.dialect
+          when :oss
+            CoreBridgeOSS.new(capabilities, bridge.session_id, opts)
+          when :w3c
+            CoreBridgeW3C.new(capabilities, bridge.session_id, opts)
+          else
+            raise CoreError, 'cannot understand dialect'
+          end
+        end
+      end # class Bridge
+
+      class CoreBridgeOSS < ::Selenium::WebDriver::Remote::OSS::Bridge
+        def commands(command)
+          ::Appium::Core::Commands::COMMANDS_EXTEND_OSS[command]
+        end
+      end # class CoreBridgeOSS
+
+      class CoreBridgeW3C < ::Selenium::WebDriver::Remote::W3C::Bridge
+        def commands(command)
+          case command
+          when :status, :is_element_displayed
+            ::Appium::Core::Commands::COMMANDS_EXTEND_OSS[command]
+          else
+            ::Appium::Core::Commands::COMMANDS_EXTEND_W3C[command]
+          end
+        end
+      end # class CoreBridgeW3C
+    end # class Base
+  end # module Core
+end # module Appium

data/lib/appium_lib/core/common/base/capabilities.rb

@@ -0,0 +1,16 @@
+module Appium
+  module Core
+    class Base
+      module Capabilities
+        # @private
+        # @param [Hash] opts_caps Capabilities for Appium server. All capability keys are converted to lowerCamelCase when
+        #                         this client sends capabilities to Appium server as JSON format.
+        # @return [::Selenium::WebDriver::Remote::W3C::Capabilities] Return instance of Appium::Core::Base::Capabilities
+        #                         inherited ::Selenium::WebDriver::Remote::W3C::Capabilities
+        def self.create_capabilities(opts_caps = {})
+          ::Selenium::WebDriver::Remote::W3C::Capabilities.new(opts_caps)
+        end
+      end
+    end
+  end
+end

data/lib/appium_lib/core/common/base/command.rb

@@ -0,0 +1,10 @@
+module Appium
+  module Core
+    class Base
+      module Commands
+        OSS = ::Selenium::WebDriver::Remote::OSS::Bridge::COMMANDS.freeze
+        W3C = ::Selenium::WebDriver::Remote::W3C::Bridge::COMMANDS.freeze
+      end # module Commands
+    end # module Base
+  end # module Core
+end # module Appium

data/lib/appium_lib/core/common/base/driver.rb

@@ -0,0 +1,40 @@
+require_relative 'search_context'
+
+module Appium
+  module Core
+    class Base
+      class Driver < ::Selenium::WebDriver::Driver
+        include ::Selenium::WebDriver::DriverExtensions::UploadsFiles
+        include ::Selenium::WebDriver::DriverExtensions::TakesScreenshot
+        include ::Selenium::WebDriver::DriverExtensions::HasSessionId
+        include ::Selenium::WebDriver::DriverExtensions::Rotatable
+        include ::Selenium::WebDriver::DriverExtensions::HasRemoteStatus
+        include ::Selenium::WebDriver::DriverExtensions::HasWebStorage
+
+        include ::Appium::Core::Base::SearchContext
+
+        def initialize(opts = {})
+          listener = opts.delete(:listener)
+          @bridge = ::Appium::Core::Base::Bridge.handshake(opts)
+          if @bridge.dialect == :oss
+            extend ::Selenium::WebDriver::DriverExtensions::HasTouchScreen
+            extend ::Selenium::WebDriver::DriverExtensions::HasLocation
+            extend ::Selenium::WebDriver::DriverExtensions::HasNetworkConnection
+          end
+          super(@bridge, listener: listener)
+        end
+
+        # Get the device window's size.
+        # @return [Selenium::WebDriver::Dimension]
+        #
+        # @example
+        #   size = @driver.window_size
+        #   size.width #=> Integer
+        #   size.height #=> Integer
+        def window_size
+          manage.window.size
+        end
+      end # class Driver
+    end # class Base
+  end # module Core
+end # module Appium