appium_lib_core 4.5.0 → 5.0.0.beta4

data/lib/appium_lib_core/common/base/capabilities.rb

@@ -19,10 +19,10 @@ module Appium
         # @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
+        # @return [::Selenium::WebDriver::Remote::Capabilities] Return instance of Appium::Core::Base::Capabilities
+        #                         inherited ::Selenium::WebDriver::Remote::Capabilities
         def self.create_capabilities(opts_caps = {})
-          ::Selenium::WebDriver::Remote::W3C::Capabilities.new(opts_caps)
+          ::Selenium::WebDriver::Remote::Capabilities.new(opts_caps)
         end
       end
     end

data/lib/appium_lib_core/common/base/{command.rb → device_ime.rb}

@@ -15,10 +15,35 @@
 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
+      #
+      # @api private
+      #
+      class DeviceIME
+        # @private this class is private
+        def initialize(bridge)
+          @bridge = bridge
+        end
+
+        def activate(ime_name)
+          @bridge.ime_activate(ime_name)
+        end
+
+        def available_engines
+          @bridge.ime_available_engines
+        end
+
+        def active_engine
+          @bridge.ime_active_engine
+        end
+
+        def activated?
+          @bridge.ime_activated
+        end
+
+        def deactivate
+          @bridge.ime_deactivate
+        end
+      end
+    end
+  end
+end

data/lib/appium_lib_core/common/base/driver.rb

@@ -13,11 +13,14 @@
 # limitations under the License.
 
 require 'base64'
+require_relative 'device_ime'
+require_relative 'driver_settings'
 require_relative 'search_context'
 require_relative 'screenshot'
 require_relative 'rotable'
 require_relative 'remote_status'
 require_relative 'has_location'
+require_relative 'has_network_connection'
 
 module Appium
   module Core
@@ -27,31 +30,63 @@ module Appium
         include ::Selenium::WebDriver::DriverExtensions::HasSessionId
         include ::Selenium::WebDriver::DriverExtensions::HasRemoteStatus
         include ::Selenium::WebDriver::DriverExtensions::HasWebStorage
-        include ::Selenium::WebDriver::DriverExtensions::HasNetworkConnection
-        include  ::Selenium::WebDriver::DriverExtensions::HasTouchScreen
 
         include ::Appium::Core::Base::Rotatable
         include ::Appium::Core::Base::SearchContext
         include ::Appium::Core::Base::TakesScreenshot
         include ::Appium::Core::Base::HasRemoteStatus
         include ::Appium::Core::Base::HasLocation
+        include ::Appium::Core::Base::HasNetworkConnection
+
+        private
 
         # Private API.
         # Do not use this for general use. Used by flutter driver to get bridge for creating a new element
         attr_reader :bridge
 
-        def initialize(opts = {})
-          listener = opts.delete(:listener)
-          @bridge = ::Appium::Core::Base::Bridge.handshake(**opts)
-          super(@bridge, listener: listener)
+        def initialize(bridge: nil, listener: nil, **opts)
+          super
         end
 
-        # Get the dialect value
-        # @return [:oss|:w3c]
-        def dialect
-          @bridge.dialect
+        # Implements protocol handshake which:
+        #
+        #   1. Creates session with driver.
+        #   2. Sniffs response.
+        #   3. Based on the response, understands which dialect we should use.
+        #
+        # @return [::Appium::Core::Base::Bridge]
+        #
+        def create_bridge(**opts)
+          # TODO: probably Appium does not need this.
+          opts[:url] ||= service_url(opts)
+          caps = opts.delete(:capabilities)
+          # NOTE: This is deprecated
+          cap_array = caps.is_a?(Hash) ? [caps] : Array(caps)
+
+          desired_capabilities = opts.delete(:desired_capabilities)
+          if desired_capabilities
+            if desired_capabilities.is_a?(Hash)
+              desired_capabilities = ::Selenium::WebDriver::Remote::Capabilities(desired_capabilities)
+            end
+            cap_array << desired_capabilities
+          end
+
+          options = opts.delete(:options)
+          cap_array << options if options
+
+          capabilities = generate_capabilities(cap_array)
+
+          bridge_opts = { http_client: opts.delete(:http_client), url: opts.delete(:url) }
+          raise ::Appium::Core::Error::ArgumentError, "Unable to create a driver with parameters: #{opts}" unless opts.empty?
+
+          bridge = ::Appium::Core::Base::Bridge.new(**bridge_opts)
+
+          bridge.create_session(capabilities)
+          bridge
         end
 
+        public
+
         # Update +server_url+ and HTTP clients following this arguments, protocol, host, port and path.
         # After this method, +@bridge.http+ will be a new instance following them instead of +server_url+ which is
         # set before creating session.
@@ -76,6 +111,75 @@ module Appium
                                                   path: path)
         end
 
+        AVAILABLE_METHODS = [
+          :get, :head, :post, :put, :delete,
+          :connect, :options, :trace, :patch
+        ].freeze
+        # Define a new custom method to the driver so that you can define your own method for
+        # drivers/plugins in Appium 2.0. Appium 2.0 and its custom drivers/plugins allow you
+        # to define custom commands that are not part of W3C spec.
+        #
+        # @param [Symbol] method HTTP request method as https://www.w3.org/TR/webdriver/#endpoints
+        # @param [string] url The url to URL template as https://www.w3.org/TR/webdriver/#endpoints.
+        #                     +:session_id+ is the placeholder of 'session id'.
+        #                     Other place holders can be specified with +:+ prefix like +:id+.
+        #                     Then, the +:id+ will be replaced with a given value as the seconds argument of +execute+
+        # @param [Symbol] name The name of method that is called as the driver instance method.
+        # @param [Proc] block The block to involve as the method
+        # @raise [ArgumentError] If the given +name+ is already defined or +method+ are invalid value.
+        #
+        # @example
+        #
+        #   @driver.add_command(
+        #     method: :get,
+        #     url: 'session/:session_id/path/to/custom/url',
+        #     name: :test_command
+        #   )
+        #   # Send a GET request to 'session/<session id>/path/to/custom/url'
+        #   @driver.test_command
+        #
+        #
+        #   @driver.add_command(
+        #     method: :post,
+        #     url: 'session/:session_id/path/to/custom/url',
+        #     name: :test_command
+        #   ) do
+        #     def test_command(argument)
+        #       execute(:test_command, {}, { dummy: argument })
+        #     end
+        #   end
+        #   # Send a POST request to 'session/<session id>/path/to/custom/url'
+        #   # with body "{ dummy: 1 }" as JSON object. "1" is the argument.
+        #   # ':session_id' in the given 'url' is replaced with current 'session id'.
+        #   @driver.test_command(1)
+        #
+        #   @driver.add_command(
+        #     method: :post,
+        #     url: 'session/:session_id/element/:id/custom/action',
+        #     name: :test_action_command
+        #   ) do
+        #     def test_action_command(element_id, action)
+        #       execute(:test_action_command, {id: element_id}, { dummy_action: action })
+        #     end
+        #   end
+        #   # Send a POST request to 'session/<session id>/element/<element id>/custom/action'
+        #   # with body "{ dummy_action: #{action} }" as JSON object. "action" is the seconds argument.
+        #   # ':session_id' in the given url is replaced with current 'session id'.
+        #   # ':id' in the given url is replaced with the given 'element_id'.
+        #   e = @driver.find_element :accessibility_id, 'an element'
+        #   @driver.test_action_command(e.ref, 'action')
+        #
+        def add_command(method:, url:, name:, &block)
+          unless AVAILABLE_METHODS.include? method
+            raise ::Appium::Core::Error::ArgumentError, "Available method is either #{AVAILABLE_METHODS}"
+          end
+
+          # TODO: Remove this logger before Appium 2.0 release
+          ::Appium::Logger.info '[Experimental] this method is experimental for Appium 2.0. This interface may change.'
+
+          @bridge.add_command method: method, url: url, name: name, &block
+        end
+
         ### Methods for Appium
 
         # Lock the device
@@ -158,22 +262,6 @@ module Appium
         end
         alias type send_keys
 
-        class DriverSettings
-          # @private this class is private
-          def initialize(bridge)
-            @bridge = bridge
-          end
-
-          def get
-            @bridge.get_settings
-          end
-
-          def update(settings)
-            @bridge.update_settings(settings)
-          end
-        end
-        private_constant :DriverSettings
-
         # Returns an instance of DriverSettings to call get/update.
         #
         # @example
@@ -182,7 +270,7 @@ module Appium
         #   @driver.settings.update('allowInvisibleElements': true)
         #
         def settings
-          @driver_settings ||= DriverSettings.new(@bridge) # rubocop:disable Naming/MemoizedInstanceVariableName
+          @settings ||= DriverSettings.new(@bridge)
         end
 
         # Get appium Settings for current test session.
@@ -204,8 +292,8 @@ module Appium
         #
         # @example
         #
-        #   @driver.update_settings('allowInvisibleElements': true)
-        #   @driver.settings.update('allowInvisibleElements': true)
+        #   @driver.update_settings({ 'allowInvisibleElements': true })
+        #   @driver.settings.update({ 'allowInvisibleElements': true })
         #   @driver.settings = { 'allowInvisibleElements': true }
         #
         def settings=(value)
@@ -213,34 +301,6 @@ module Appium
         end
         alias update_settings settings=
 
-        class DeviceIME
-          # @private this class is private
-          def initialize(bridge)
-            @bridge = bridge
-          end
-
-          def activate(ime_name)
-            @bridge.ime_activate(ime_name)
-          end
-
-          def available_engines
-            @bridge.ime_available_engines
-          end
-
-          def active_engine
-            @bridge.ime_active_engine
-          end
-
-          def activated?
-            @bridge.ime_activated
-          end
-
-          def deactivate
-            @bridge.ime_deactivate
-          end
-        end
-        private_constant :DeviceIME
-
         # Returns an instance of DeviceIME
         #
         # @return [Appium::Core::Base::Driver::DeviceIME]
@@ -254,7 +314,7 @@ module Appium
         #   @driver.ime.deactivate #=> Deactivate current IME engine
         #
         def ime
-          @device_ime ||= DeviceIME.new(@bridge) # rubocop:disable Naming/MemoizedInstanceVariableName
+          @ime ||= DeviceIME.new(@bridge)
         end
 
         # Android only. Make an engine that is available active.
@@ -817,7 +877,7 @@ module Appium
         #    @driver.perform_actions [f1, f2] #=> 'nil' if the action succeed
         #
         def perform_actions(data)
-          raise ArgumentError, "'#{data}' must be Array" unless data.is_a? Array
+          raise ::Appium::Core::Error::ArgumentError, "'#{data}' must be Array" unless data.is_a? Array
 
           @bridge.send_actions data.map(&:encode).compact
           data.each(&:clear_actions)
@@ -887,16 +947,15 @@ module Appium
         # Retrieve the capabilities of the specified session.
         # It's almost same as +@driver.capabilities+ but you can get more details.
         #
-        # @return [Selenium::WebDriver::Remote::Capabilities, Selenium::WebDriver::Remote::W3C::Capabilities]
+        # @return [Selenium::WebDriver::Remote::Capabilities, Selenium::WebDriver::Remote::Capabilities]
         #
         # @example
         #   @driver.session_capabilities
         #
         #   #=> uiautomator2
-        #   # <Selenium::WebDriver::Remote::W3C::Capabilities:0x007fa38dae1360
+        #   # <Selenium::WebDriver::Remote::Capabilities:0x007fa38dae1360
         #   # @capabilities=
-        #   #     {:proxy=>nil,
-        #   #      :browser_name=>nil,
+        #   #     {:browser_name=>nil,
         #   #      :browser_version=>nil,
         #   #      :platform_name=>"android",
         #   #      :page_load_strategy=>nil,
@@ -943,10 +1002,9 @@ module Appium
         #   #      "viewportRect"=>{"left"=>0, "top"=>63, "width"=>1080, "height"=>1731}}>
         #   #
         #   #=> XCUITest
-        #   # <Selenium::WebDriver::Remote::W3C::Capabilities:0x007fb15dc01370
+        #   # <Selenium::WebDriver::Remote::Capabilities:0x007fb15dc01370
         #   # @capabilities=
-        #   #     {:proxy=>nil,
-        #   #      :browser_name=>"UICatalog",
+        #   #     {:browser_name=>"UICatalog",
         #   #      :browser_version=>nil,
         #   #      :platform_name=>"ios",
         #   #      :page_load_strategy=>nil,
@@ -1027,7 +1085,7 @@ module Appium
         #
         # @param [String] img_path A path to a partial image you'd like to find
         #
-        # @return [::Selenium::WebDriver::Element]
+        # @return [::Appium::Core::Element]
         #
         # @example
         #
@@ -1097,14 +1155,14 @@ module Appium
           @bridge.execute_driver(script: script, type: type, timeout_ms: timeout_ms)
         end
 
-        # Convert vanilla element response to ::Selenium::WebDriver::Element
+        # Convert vanilla element response to ::Appium::Core::Element
         #
         # @param [Hash] id The id which can get as a response from server
-        # @return [::Selenium::WebDriver::Element]
+        # @return [::Appium::Core::Element]
         #
         # @example
         #     response = {"element-6066-11e4-a52e-4f735466cecf"=>"xxxx", "ELEMENT"=>"xxxx"}
-        #     ele = @driver.convert_to_element(response) #=> ::Selenium::WebDriver::Element
+        #     ele = @driver.convert_to_element(response) #=> ::Appium::Core::Element
         #     ele.rect #=> Can get the rect of the element
         #
         def convert_to_element(id)

data/lib/appium_lib_core/common/base/driver_settings.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+module Appium
+  module Core
+    class Base
+      #
+      # @api private
+      #
+      class DriverSettings
+        # @private this class is private
+        def initialize(bridge)
+          @bridge = bridge
+        end
+
+        # Get appium Settings for current test session.
+        #
+        # @example
+        #
+        #   @driver.settings.get
+        #
+        def get
+          @bridge.get_settings
+        end
+
+        # Update Appium Settings for current test session
+        #
+        # @param [Hash] settings Settings to update, keys are settings, values to value to set each setting to
+        #
+        # @example
+        #
+        #   @driver.settings.update({'allowInvisibleElements': true})
+        #
+        def update(settings)
+          @bridge.update_settings(settings)
+        end
+      end
+    end
+  end
+end

data/lib/appium_lib_core/common/base/has_network_connection.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+module Appium
+  module Core
+    class Base
+      #
+      # @api private
+      #
+      module HasNetworkConnection
+        def network_connection_type
+          connection_value = @bridge.network_connection
+
+          connection_type = values_to_type[connection_value]
+
+          # In case the connection type is not recognized return the
+          # connection value.
+          connection_type || connection_value
+        end
+
+        def network_connection_type=(connection_type)
+          raise ::Appium::Core::Error::ArgumentError, 'Invalid connection type' unless valid_type? connection_type
+
+          connection_value = type_to_values[connection_type]
+
+          @bridge.network_connection = connection_value
+        end
+
+        private
+
+        def type_to_values
+          { airplane_mode: 1, wifi: 2, data: 4, all: 6, none: 0 }
+        end
+
+        def values_to_type
+          type_to_values.invert
+        end
+
+        def valid_type?(type)
+          type_to_values.keys.include? type
+        end
+      end
+    end
+  end
+end