appium_lib_core 5.7.0 → 5.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fdc105db151bc415072c5c693ec951a14ea681762f686be52941b89d48eb879c
-  data.tar.gz: 74ae58624c62216572e321b22386b530f3271ffeeba15b9e25764b9ffda5328d
+  metadata.gz: 06c7b0bb078ece1a833874436e4611cb407cc762d73dd2fbcb27e69ace076e14
+  data.tar.gz: ab4e2733c06ed9866368e983c4e2a28510a4125eff5614e404c3e83f1eaceae9
 SHA512:
-  metadata.gz: 0a52ad3c06dc494049be9c72cf7e74fea74ad005b4c45bc87ae308e3b27e180f0488c0a9e967e16992031d5282f637bba35b5aa80235ece79d1307e9e05ca120
-  data.tar.gz: 160ec09d1c7f1205ade5e17fab276a3e68f10250b7c3ff84a5984b9fd875a7d74238fc5cc7bb2c6c960ccf581993b642718fba6b7f8731df2e74e1d676c0f2ae
+  metadata.gz: fd894aaad52613559c842c0a42ff6d6bbfc9b871ea5f3bf02a302f7ae53e9b7cb6397bea363f9108ac9bbe601f1f1cacb5fa38ee4371eebaf875d2e64b756cf4
+  data.tar.gz: '097f706be4f0403e6397bdb941f1f63ced8c6cfae8a7f68af401ffcd0fa2e75d81051b37d1f421c9d60051c85f125c6662edb8461f8fcbc7afcaa6a89ba69142'

data/CHANGELOG.md

@@ -10,6 +10,12 @@ Read `release_notes.md` for commit level details.
 
 ### Deprecations
 
+## [5.8.0] - 2022-12-11
+
+### Enhancements
+- Add `::Appium::Core::Driver#attach_to` to generate a driver instance which has the given session id.
+    - The primary usage is for debugging to attach to an existing session.
+
 ## [5.7.0] - 2022-12-02
 
 ### Enhancements

data/README.md

@@ -104,7 +104,7 @@ $ IGNORE_VERSION_SKIP=true CI=true bundle exec rake test:func:android
 
     opts = {
       capabilities: { # Append capabilities
-        platformName: :ios,
+        platformName: 'ios',
         platformVersion: '11.0',
         deviceName: 'iPhone Simulator',
         automationName: 'XCUITest',
@@ -133,6 +133,15 @@ $ IGNORE_VERSION_SKIP=true CI=true bundle exec rake test:func:android
 
 More examples are in [test/functional](test/functional)
 
+As of version 5.8.0, the client can attach to an existing session. The main purpose is for debugging.
+
+```ruby
+# @driver is the driver instance of an existing session
+attached_driver = ::Appium::Core::Driver.attach_to @driver.session_id, url: 'http://127.0.0.1:4723/wd/hub', automation_name: 'XCUITest', platform_name: 'ios'
+assert attached_driver.session_id == @driver.session_id
+attached_driver.page_source
+```
+
 ### Capabilities
 
 Read [Appium/Core/Driver](https://www.rubydoc.info/github/appium/ruby_lib_core/Appium/Core/Driver) to catch up with available capabilities.

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

@@ -43,13 +43,39 @@ module Appium
 
         def browser
           @browser ||= begin
-            name = @capabilities.browser_name
+            name = @capabilities&.browser_name
             name ? name.tr(' ', '_').downcase.to_sym : 'unknown'
           rescue KeyError
             APPIUM_NATIVE_BROWSER_NAME
           end
         end
 
+        # Appium only.
+        # Attach to an existing session.
+        #
+        # @param [String] The session id to attach to.
+        # @param [String] platform_name The platform name to keep in the dummy capabilities
+        # @param [String] platform_name The automation name to keep in the dummy capabilities
+        # @return [::Appium::Core::Base::Capabilities]
+        #
+        # @example
+        #
+        #   new_driver = ::Appium::Core::Driver.attach_to(
+        #     driver.session_id,
+        #     url: 'http://127.0.0.1:4723/wd/hub', automation_name: 'UiAutomator2', platform_name: 'Android'
+        #   )
+        #
+        def attach_to(session_id, platform_name, automation_name)
+          @available_commands = ::Appium::Core::Commands::COMMANDS.dup
+          @session_id = session_id
+
+          # generate a dummy capabilities instance which only has the given platformName and automationName
+          @capabilities = ::Appium::Core::Base::Capabilities.new(
+            'platformName' => platform_name,
+            'automationName' => automation_name
+          )
+        end
+
         # Override
         # Creates session handling.
         #

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

@@ -51,10 +51,6 @@ module Appium
           @wait_timeout = opts.delete(:wait_timeout)
           @wait_interval = opts.delete(:wait_interval)
 
-          # For logging.
-          # TODO: Remove when appium core no longer uses this in this bridge.
-          @automation_name = opts.delete(:automation_name)
-
           super
         end
 
@@ -63,13 +59,26 @@ module Appium
         # @return [::Appium::Core::Base::Bridge]
         #
         def create_bridge(**opts)
+          # for a new session request
           capabilities = opts.delete(:capabilities)
           bridge_opts = { http_client: opts.delete(:http_client), url: opts.delete(:url) }
+
+          # for attaching to an existing session
+          session_id = opts.delete(:existing_session_id)
+          automation_name = opts.delete(:automation_name)
+          platform_name = opts.delete(:platform_name)
+
           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)
+          if session_id.nil?
+            bridge.create_session(capabilities)
+          else
+            # attach to the existing session id
+            bridge.attach_to(session_id, platform_name, automation_name)
+          end
+
           bridge
         end
 
@@ -566,12 +575,6 @@ module Appium
         #   @driver.launch_app
         #
         def launch_app
-          # TODO: Define only in Windows module when ruby_lib_core removes this method
-          if @automation_name != :windows
-            ::Appium::Logger.warn(
-              '[DEPRECATION] launch_app is deprecated. Please use activate_app instead.'
-            )
-          end
           @bridge.launch_app
         end
 
@@ -583,12 +586,6 @@ module Appium
         #   @driver.close_app
         #
         def close_app
-          # TODO: Define only in Windows module when ruby_lib_core removes this method
-          if @automation_name != :windows
-            ::Appium::Logger.warn(
-              '[DEPRECATION] close_app is deprecated. Please use terminate_app instead.'
-            )
-          end
           @bridge.close_app
         end
 

data/lib/appium_lib_core/common/device/app_management.rb

@@ -18,10 +18,16 @@ module Appium
       module Device
         module AppManagement
           def launch_app
+            ::Appium::Logger.warn(
+              '[DEPRECATION] launch_app is deprecated. Please use activate_app instead.'
+            )
             execute :launch_app
           end
 
           def close_app
+            ::Appium::Logger.warn(
+              '[DEPRECATION] close_app is deprecated. Please use terminate_app instead.'
+            )
             execute :close_app
           end
 

data/lib/appium_lib_core/driver.rb

@@ -275,7 +275,40 @@ module Appium
       #     @core.start_driver # start driver with 'url'. Connect to 'http://custom-host:8080/wd/hub.com'
       #
       def self.for(opts = {})
-        new(opts)
+        new.setup_for_new_session(opts)
+      end
+
+      # Attach to an existing session. The main usage of this method is to attach to
+      # an existing session for debugging. The generated driver instance has the capabilities which
+      # has the given automationName and platformName only since the W3C WebDriver spec does not provide
+      # an endpoint to get running session's capabilities.
+      #
+      #
+      # @param [String] The session id to attach to.
+      # @param [String] url The WebDriver URL to attach to with the session_id.
+      # @param [String] automation_name The platform name to keep in the dummy capabilities
+      # @param [String] platform_name The automation name to keep in the dummy capabilities
+      # @return [Selenium::WebDriver] A new driver instance with the given session id.
+      #
+      # @example
+      #
+      #   new_driver = ::Appium::Core::Driver.attach_to(
+      #     driver.session_id,  # The 'driver' has an existing session id
+      #     url: 'http://127.0.0.1:4723/wd/hub', automation_name: 'UiAutomator2', platform_name: 'Android'
+      #   )
+      #   new_driver.page_source # for example
+      #
+      def self.attach_to(
+        session_id, url: nil, automation_name: nil, platform_name: nil,
+        http_client_ops: { http_client: nil, open_timeout: 999_999, read_timeout: 999_999 }
+      )
+        new.attach_to(
+          session_id,
+          automation_name: automation_name,
+          platform_name: platform_name,
+          url: url,
+          http_client_ops: http_client_ops
+        )
       end
 
       private
@@ -286,12 +319,18 @@ module Appium
         @delegate_target
       end
 
-      public
-
       # @private
-      def initialize(opts = {})
+      def initialize
         @delegate_target = self # for testing purpose
         @automation_name = nil # initialise before 'set_automation_name'
+      end
+
+      public
+
+      # @private
+      # Set up for a neww session
+      def setup_for_new_session(opts = {})
+        @custom_url = opts.delete :url # to set the custom url as :url
 
         # TODO: Remove when we implement Options
         # The symbolize_keys is to keep compatiility for the legacy code, which allows capabilities to give 'string' as the key.
@@ -299,7 +338,6 @@ module Appium
         # FIXME: First, please try to remove `nested: true` to `nested: false`.
         opts = Appium.symbolize_keys(opts, nested: true)
 
-        @custom_url = opts.delete :url
         @caps = get_caps(opts)
 
         set_appium_lib_specific_values(get_appium_lib_opts(opts))
@@ -308,8 +346,7 @@ module Appium
         set_automation_name
 
         extend_for(device: @device, automation_name: @automation_name)
-
-        self # rubocop:disable Lint/Void
+        self
       end
 
       # Creates a new global driver and quits the old one if it exists.
@@ -320,7 +357,7 @@ module Appium
       # @option http_client_ops [Hash] :http_client Custom HTTP Client
       # @option http_client_ops [Hash] :open_timeout Custom open timeout for http client.
       # @option http_client_ops [Hash] :read_timeout Custom read timeout for http client.
-      # @return [Selenium::WebDriver] the new global driver
+      # @return [Selenium::WebDriver] A new driver instance
       #
       # @example
       #
@@ -377,8 +414,7 @@ module Appium
                                                      capabilities: @caps, # ::Appium::Core::Base::Capabilities
                                                      url: @custom_url,
                                                      wait_timeout: @wait_timeout,
-                                                     wait_interval: @wait_interval,
-                                                     automation_name: @automation_name)
+                                                     wait_interval: @wait_interval)
 
           if @direct_connect
             d_c = DirectConnections.new(@driver.capabilities)
@@ -396,6 +432,8 @@ module Appium
           @http_client.additional_headers.delete Appium::Core::Base::Http::RequestHeaders::KEYS[:idempotency]
         end
 
+        # TODO: this method can be removed after releasing Appium 2.0, and after a while
+        # since Appium 2.0 reuqires 'automationName'. This method won't help anymore then.
         # If "automationName" is set only server side, this method set "automationName" attribute into @automation_name.
         # Since @automation_name is set only client side before start_driver is called.
         set_automation_name_if_nil
@@ -405,7 +443,47 @@ module Appium
         @driver
       end
 
-      private
+      # @privvate
+      # Attach to an existing session
+      def attach_to(session_id, url: nil, automation_name: nil, platform_name: nil,
+                    http_client_ops: { http_client: nil, open_timeout: 999_999, read_timeout: 999_999 })
+
+        raise ::Appium::Core::Error::ArgumentError, 'The :url must not be nil' if url.nil?
+        raise ::Appium::Core::Error::ArgumentError, 'The :automation_name must not be nil' if automation_name.nil?
+        raise ::Appium::Core::Error::ArgumentError, 'The :platform_name must not be nil' if platform_name.nil?
+
+        @custom_url = url
+
+        # use lowercase internally
+        @automation_name = convert_downcase(automation_name)
+        @device = convert_downcase(platform_name)
+
+        extend_for(device: @device, automation_name: @automation_name)
+
+        @http_client = get_http_client http_client: http_client_ops.delete(:http_client),
+                                       open_timeout: http_client_ops.delete(:open_timeout),
+                                       read_timeout: http_client_ops.delete(:read_timeout)
+
+        # Note that 'enable_idempotency_header' works only a new session reqeust. The attach_to method skips
+        # the new session request, this it does not needed.
+
+        begin
+          # included https://github.com/SeleniumHQ/selenium/blob/43f8b3f66e7e01124eff6a5805269ee441f65707/rb/lib/selenium/webdriver/remote/driver.rb#L29
+          @driver = ::Appium::Core::Base::Driver.new(http_client: @http_client,
+                                                     url: @custom_url,
+                                                     listener: @listener,
+                                                     existing_session_id: session_id,
+                                                     automation_name: automation_name,
+                                                     platform_name: platform_name)
+
+          # export session
+          write_session_id(@driver.session_id, @export_session_path) if @export_session
+        rescue Errno::ECONNREFUSED
+          raise "ERROR: Unable to connect to Appium. Is the server running on #{@custom_url}?"
+        end
+
+        @driver
+      end
 
       def get_http_client(http_client: nil, open_timeout: nil, read_timeout: nil)
         client = http_client || Appium::Core::Base::Http::Default.new
@@ -431,8 +509,6 @@ module Appium
         {}
       end
 
-      public
-
       # Quits the driver
       # @return [void]
       #
@@ -626,7 +702,7 @@ module Appium
         @device = @caps[:platformName] || @caps['platformName']
         return @device unless @device
 
-        @device = @device.is_a?(Symbol) ? @device.downcase : @device.downcase.strip.intern
+        @device = convert_downcase @device
       end
 
       # @private
@@ -634,9 +710,12 @@ module Appium
         # TODO: check if the Appium.symbolize_keys(opts, nested: false) enoug with this
         candidate = @caps[:automationName] || @caps['automationName']
         @automation_name = candidate if candidate
-        @automation_name = if @automation_name
-                             @automation_name.is_a?(Symbol) ? @automation_name.downcase : @automation_name.downcase.strip.intern
-                           end
+        @automation_name = convert_downcase @automation_name if @automation_name
+      end
+
+      # @private
+      def convert_downcase(value)
+        value.is_a?(Symbol) ? value.downcase : value.downcase.strip.intern
       end
 
       # @private
@@ -650,6 +729,10 @@ module Appium
 
       # @private
       def write_session_id(session_id, export_path = '/tmp/appium_lib_session')
+        ::Appium::Logger.warn(
+          '[DEPRECATION] export_session option will be removed. ' \
+          'Please save the session id by yourself with #session_id method like @driver.session_id.'
+        )
         export_path = export_path.tr('/', '\\') if ::Appium::Core::Base.platform.windows?
         File.write(export_path, session_id)
       rescue IOError => e

data/lib/appium_lib_core/version.rb

@@ -14,7 +14,7 @@
 
 module Appium
   module Core
-    VERSION = '5.7.0' unless defined? ::Appium::Core::VERSION
-    DATE    = '2022-12-02' unless defined? ::Appium::Core::DATE
+    VERSION = '5.8.0' unless defined? ::Appium::Core::VERSION
+    DATE    = '2022-12-11' unless defined? ::Appium::Core::DATE
   end
 end

data/lib/appium_lib_core/windows/device/app_management.rb

@@ -0,0 +1,38 @@
+# 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
+    module Windows
+      module Device
+        module AppManagement
+          # override
+          def self.add_methods
+            ::Appium::Core::Device.add_endpoint_method(:launch_app) do
+              def launch_app
+                execute :launch_app
+              end
+            end
+
+            ::Appium::Core::Device.add_endpoint_method(:close_app) do
+              def close_app
+                execute :close_app
+              end
+            end
+          end
+        end # module AppManagement
+      end # module Device
+    end # module Windows
+  end # module Core
+end # module Appium

data/lib/appium_lib_core/windows/device.rb

@@ -13,6 +13,7 @@
 # limitations under the License.
 
 require_relative 'device/screen'
+require_relative 'device/app_management'
 
 module Appium
   module Core
@@ -78,6 +79,7 @@ module Appium
         class << self
           def extended(_mod)
             Screen.add_methods
+            AppManagement.add_methods
           end
         end # class << self
       end # module Device

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: appium_lib_core
 version: !ruby/object:Gem::Version
-  version: 5.7.0
+  version: 5.8.0
 platform: ruby
 authors:
 - Kazuaki MATSUO
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-12-03 00:00:00.000000000 Z
+date: 2022-12-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: selenium-webdriver
@@ -267,6 +267,7 @@ files:
 - lib/appium_lib_core/windows.rb
 - lib/appium_lib_core/windows/bridge.rb
 - lib/appium_lib_core/windows/device.rb
+- lib/appium_lib_core/windows/device/app_management.rb
 - lib/appium_lib_core/windows/device/screen.rb
 homepage: https://github.com/appium/ruby_lib_core/
 licenses: