appium_lib_core 5.0.0 → 6.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 88e1099c62a49f922529ee84563d0b475c160a981451da59210819e61956f985
-  data.tar.gz: bb653d62d35c461e8e0c9dcec726064992e735418b20c85b4aa6aae16d9b0a88
+  metadata.gz: c45a558b448d89b1b356b221257279ff8c148680a1dc09f7414877e6e59a6257
+  data.tar.gz: d09d57109c80759c9b92942b7f8e1424c2614f34e4fcdbe9f6d4d0e48ee41816
 SHA512:
-  metadata.gz: 1a18f9f6ea13b72f0aff09ea748c102fdfe202be60ac59f7fcaceee34485746a75fd83d8e438c2fd0447b64ce3c17655418ccdf599fba618afd75db7bab72e73
-  data.tar.gz: 6cac7cbba8c64d8f97fa34af6adc1b33f432549950551826cfc0e1d0340e0add900b85bf0c09cbbfa9fae551aec873d68b08b9f301d9ace40e9716d453c3ca4b
+  metadata.gz: 6f50481e6656b18e7dfe5dc631137ab1ab041c9c6087fcf27b1fd24e91814e83ce051f22db1a3e4b41f5d2a4b8320e2ac7c323638e9e9b76d2508d66a7992cdf
+  data.tar.gz: 0b04644ee8c7704080935777b01886cca17acce8dab8c7953b769c9dd9ca33efc588e3da5e08bba6a91f0ac17bde973c607f3b886c4724eb84be3c44aece2690

data/CHANGELOG.md

@@ -10,6 +10,146 @@ Read `release_notes.md` for commit level details.
 
 ### Deprecations
 
+## [6.3.0] - 2023-03-14
+
+### Enhancements
+- Support custom listener
+    - e.g. A listener named `CustomListener` which inherits `::Selenium::WebDriver::Support::AbstractEventListener` can set as `appium_lib: { listener: CustomListener.new}` capability
+
+## [6.2.1] - 2023-03-09
+
+### Enhancements
+- Add `uia_device_orientation_landscaperight` and `uia_device_orientation_portrait_upsidedown` symbols in the `drivede.rotation=`
+- Add `drivede.orientation=` as a syntax sugar of `drivede.rotation=`
+
+
+## [6.2.0] - 2023-01-26
+
+### Enhancements
+
+- Append `selenium-webdriver` `4.8` support
+- Add `::Appium::Location` since `::Selenium::WebDriver::Location` no longer exists
+
+### Deprecations
+
+- `::Selenium::WebDriver::Location` is deprecated in favor of `::Appium::Location` in Appium Ruby binding
+
+
+## [6.1.0] - 2023-01-18
+
+### Bug fixes
+- `Element#immediate_value` sends `text` as the request body
+
+## [6.0.0] - 2022-12-25
+- Remove iOS/UiAutomation classes
+    - The version may work for iOS 8. XCUITest driver will be the default behavior for iOS.
+
+## [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
+- Allow selenium webdriver version 4.7 [#423](https://github.com/appium/ruby_lib_core/pull/423)
+
+## [5.6.0] - 2022-11-08
+
+### Enhancements
+- Append `selenium-webdriver` `4.6` support
+
+## [5.5.2] - 2022-10-11
+
+### Bug fixes
+- Fix wrong deprecation message
+
+## [5.5.1] - 2022-10-10
+
+### Bug fixes
+- Keep converting String to Symbol for `capabilities`, `caps` and `appium_lib` for the backward compatibility
+- Wrong `automationName` and `platformName` detection in this library before starting a session
+
+### Deprecations
+- Converting `capabilities`, `caps` and `appium_lib` from String to Symbol
+    - They are expected to be Symbol. Nothing affects existing users who already give the above keys as Symbol for `Appium::Core.for`.
+
+## [5.5.0] - 2022-10-09
+
+### Bug fixes
+- Removed forcefully converting keys of capabilities into symbol, which caused unexpected capabilities format issue [ruby_lib/945](https://github.com/appium/ruby_lib/issues/945)
+
+## [5.4.0] - 2022-10-01
+
+### Enhancements
+- Append `selnium-webdriver` `4.5` support
+
+## [5.3.0] - 2022-08-10
+
+### Enhancements
+
+- Allow selenium webdriver version 4.4 [#404](https://github.com/appium/ruby_lib_core/pull/404)
+
+## [5.2.2] - 2022-06-26
+
+### Enhancements
+- Relax the selenium webdriver version restriction of `4.2.0`
+
+### Bug fixes
+- Remove undefined module in selenium webdriver version `4.3.0`
+
+## [5.2.1] - 2022-06-24
+
+### Bug fixes
+- Restrict the selenium webdriver version to `4.2.0`
+
+## [5.2.0] - 2022-06-19
+
+### Enhancements
+
+- Update base Selenium Ruby client to `4.2+`
+  - Please call `key_action` or set `[::Selenium::WebDriver::Interactions.key('keyboard')]` as the deviecs parameter to build `driver.send_keys().perform` W3C action.
+    - `driver.key_action.send_keys('xxx').perform` instead of `driver.action.send_keys('xxx').perform`, or `driver.action(devices: [::Selenium::WebDriver::Interactions.key('keyboard')]).send_keys('xxx').perform`.
+    - [This PR change](https://github.com/appium/ruby_lib_core/pull/381/files) will help to update your some actions.
+
+## [5.1.2] - 2022-06-02
+
+### Enhancements
+
+- Limit selenium webdriver version less than `4.2`
+
+## [5.1.1] - 2022-04-18
+
+### Enhancements
+
+- Remove unneccessry files from gem package to reduce the size.
+
+## [5.1.0] - 2021-12-25
+
+### Enhancements
+- Make default pointerType `touch` for the pointer in W3C actions instead of `mouse` for Appium
+    - This change should not affect W3C actions
+
+## [5.0.3] - 2021-12-13
+
+### Enhancements
+- Can add more arguments in `install_app`
+    - e.g. Add `timeoutMs` for XCUITest driver as `@driver.install_app("/path/to/test.ipa", timeoutMs: 20000)`
+
+### Bug fixes
+- (internal) Allow to access to `bridge` attribute in `driver` instance for appium_flutter_finder
+
+## [5.0.2] - 2021-12-01
+
+### Bug fixes
+- (internal) Fix firstMatch format in a new session creation
+
+## [5.0.1] - 2021-11-23
+
+### Enhancements
+- Relaxed version restriction of selenium-webdriver
+
 ## [5.0.0] - 2021-11-05
 
 ### Enhancements

data/README.md

@@ -10,12 +10,14 @@ This library wraps [selenium-webdriver](https://github.com/SeleniumHQ/selenium/w
 
 # Documentation
 
-- http://www.rubydoc.info/github/appium/ruby_lib_core
+- https://www.rubydoc.info/gems/appium_lib_core
     - You can find working API examples in test code, [test/functional](test/functional)
+- Appium 2.0
+    - https://appium.github.io/appium/docs/en/2.0/ (Not completed yet)
 
 # Migration from v4 to v5
 
-Please read `[5.0.0]` section in CHANGELOG.md
+Please read [`[5.0.0]`](CHANGELOG.md#500---2021-11-05) section in [CHANGELOG](CHANGELOG.md)
 
 # Related library
 - https://github.com/appium/ruby_lib
@@ -30,20 +32,29 @@ $ bundle install
 $ bundle exec parallel_test test/unit/
 ```
 
+or
+
+```bash
+$ bundle install
+$ bundle exec rake test:unit
+```
+
 ### Functional Tests
 Run functional tests which require the Appium server and real device, Simulator/Emulator.
 
-- Start Appium server
+- Start Appium server (Appium 2.0 base)
 ```bash
-$ npm install -g appium opencv4nodejs
-$ appium --relaxed-security # To run all tests in local
+$ npm install -g appium@next
+$ appium driver install xcuitest
+$ appium driver install uiautomator2 # etc
+$ appium --base-path=/wd/hub --relaxed-security # To run all tests in local
 ```
 
 - Conduct tests
 ```bash
 $ bundle install
 $ rake test:func:android # Andorid, uiautomator2
-$ AUTOMATION_NAME_DROID=espresso rake test:func:android # Andorid, uiautomator2
+$ APPIUM_DRIVER=espresso rake test:func:android # Andorid, uiautomator2
 $ rake test:func:ios     # iOS
 ```
 
@@ -99,12 +110,12 @@ $ IGNORE_VERSION_SKIP=true CI=true bundle exec rake test:func:android
     require 'appium_lib_core'
 
     opts = {
-      capabilities: { # or { caps: {....} }
-        platformName: :ios,
+      capabilities: { # Append capabilities
+        platformName: 'ios',
         platformVersion: '11.0',
         deviceName: 'iPhone Simulator',
-        automationName: 'XCUITest',
-        app: '/path/to/MyiOS.app'
+        # app: '/path/to/MyiOS.app',  # Without 'app' capability, an appium session starts with the home screen
+        automationName: 'XCUITest'
       },
       appium_lib: {
         wait: 30
@@ -125,13 +136,47 @@ $ IGNORE_VERSION_SKIP=true CI=true bundle exec rake test:func:android
     $ ruby test.rb
     ```
 
+[Appium::Core.for](https://www.rubydoc.info/github/appium/ruby_lib_core/Appium/Core/Driver#for-class_method) documentation has more example to build a new driver instance.
+
 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.
 Capabilities affect only ruby_lib is [Appium/Core/Options](https://www.rubydoc.info/github/appium/ruby_lib_core/Appium/Core/Options).
 
+
+### Gives custom listener
+
+An example to define a customer listener with [Selenium::WebDriver::Support::AbstractEventListener](https://www.selenium.dev/selenium/docs/api/rb/Selenium/WebDriver/Support/AbstractEventListener.html)
+
+```ruby
+class CustomListener < ::Selenium::WebDriver::Support::AbstractEventListener
+  // something
+end
+capabilities: {
+  platformName: :ios,
+  platformVersion: '11.0',
+  deviceName: 'iPhone Simulator',
+  automationName: 'XCUITest',
+  app: '/path/to/MyiOS.app'
+},
+appium_lib: {
+  listener: CustomListener.new
+}
+@core = Appium::Core.for capabilities: capabilities, appium_lib: appium_lib
+@core.start_driver
+```
+
 # Development
 - Demo app
     - https://android.googlesource.com/platform/development/+/master/samples/ApiDemos

data/appium_lib_core.gemspec

@@ -4,7 +4,7 @@ $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require 'appium_lib_core/version'
 
 Gem::Specification.new do |spec|
-  spec.required_ruby_version = '>= 2.6'
+  spec.required_ruby_version = Gem::Requirement.new('>= 2.7')
 
   spec.name          = 'appium_lib_core'
   spec.version       = Appium::Core::VERSION
@@ -16,21 +16,21 @@ Gem::Specification.new do |spec|
   spec.homepage      = 'https://github.com/appium/ruby_lib_core/'
   spec.license       = 'Apache-2.0'
   spec.files         = `git ls-files -z`.split("\x0").reject do |f|
-    f.match(%r{^(doc|test|spec|features)/})
+    f.match(%r{(^(doc|docs|test|spec|features|ci-jobs|.github|script)/|release_notes.md|.gitignore|azure-pipelines.yml|.rubocop.yml)})
   end
   spec.bindir        = 'exe'
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ['lib']
 
-  spec.add_runtime_dependency 'selenium-webdriver', '~> 4.0.0'
+  spec.add_runtime_dependency 'selenium-webdriver', '~> 4.2', '< 4.9'
   spec.add_runtime_dependency 'faye-websocket', '~> 0.11.0'
 
   spec.add_development_dependency 'rake', '~> 13.0'
   spec.add_development_dependency 'yard', '~> 0.9.11'
   spec.add_development_dependency 'minitest', '~> 5.0'
   spec.add_development_dependency 'minitest-reporters', '~> 1.1'
-  spec.add_development_dependency 'webmock', '~> 3.14.0'
-  spec.add_development_dependency 'rubocop', '1.22.3'
+  spec.add_development_dependency 'webmock', '~> 3.18.1'
+  spec.add_development_dependency 'rubocop', '1.47.0'
   spec.add_development_dependency 'appium_thor', '~> 1.0'
   spec.add_development_dependency 'parallel_tests'
   spec.add_development_dependency 'simplecov'

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

@@ -43,18 +43,44 @@ 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.
         #
-        # @param [::Selenium::WebDriver::Remote::Capabilities, Hash] capabilities A capability
-        # @return [::Selenium::WebDriver::Remote::Capabilities]
+        # @param [::Appium::Core::Base::Capabilities, Hash] capabilities A capability
+        # @return [::Appium::Core::Base::Capabilities]
         #
         # @example
         #
@@ -77,8 +103,8 @@ module Appium
         def create_session(capabilities)
           @available_commands = ::Appium::Core::Commands::COMMANDS.dup
 
-          caps = add_appium_prefix(capabilities)
-          response = execute(:new_session, {}, { capabilities: { alwaysMatch: caps, firstMatch: [] } })
+          always_match = add_appium_prefix(capabilities)
+          response = execute(:new_session, {}, { capabilities: { alwaysMatch: always_match, firstMatch: [{}] } })
 
           @session_id = response['sessionId']
           raise ::Selenium::WebDriver::Error::WebDriverError, 'no sessionId in returned payload' unless @session_id
@@ -89,10 +115,10 @@ module Appium
         # Append +appium:+ prefix for Appium following W3C spec
         # https://www.w3.org/TR/webdriver/#dfn-validate-capabilities
         #
-        # @param [::Selenium::WebDriver::Remote::Capabilities, Hash] capabilities A capability
-        # @return [::Selenium::WebDriver::Remote::Capabilities]
+        # @param [::Appium::Core::Base::Capabilities, Hash] capabilities A capability
+        # @return [::Appium::Core::Base::Capabilities]
         def add_appium_prefix(capabilities)
-          w3c_capabilities = ::Selenium::WebDriver::Remote::Capabilities.new
+          w3c_capabilities = ::Appium::Core::Base::Capabilities.new
 
           capabilities = capabilities.send(:capabilities) unless capabilities.is_a?(Hash)
 
@@ -111,12 +137,12 @@ module Appium
 
         private
 
-        def camel_case(str)
-          str.gsub(/_([a-z])/) { Regexp.last_match(1).upcase }
+        def camel_case(str_or_sym)
+          str_or_sym.to_s.gsub(/_([a-z])/) { Regexp.last_match(1).upcase }
         end
 
         def extension_prefix?(capability_name)
-          snake_cased_capability_names = ::Selenium::WebDriver::Remote::Capabilities::KNOWN.map(&:to_s)
+          snake_cased_capability_names = ::Appium::Core::Base::Capabilities::KNOWN.map(&:to_s)
           camel_cased_capability_names = snake_cased_capability_names.map { |v| camel_case(v) }
 
           # Check 'EXTENSION_CAPABILITY_PATTERN'
@@ -126,7 +152,7 @@ module Appium
         end
 
         def json_create(value)
-          ::Selenium::WebDriver::Remote::Capabilities.json_create(value)
+          ::Appium::Core::Base::Capabilities.json_create(value)
         end
 
         public
@@ -153,26 +179,26 @@ module Appium
           execute :status
         end
 
-        # Perform touch actions for W3C module.
+        # Perform 'touch' actions for W3C module.
         # Generate +touch+ pointer action here and users can use this via +driver.action+
         # - https://seleniumhq.github.io/selenium/docs/api/rb/Selenium/WebDriver/W3CActionBuilder.html
         # - https://seleniumhq.github.io/selenium/docs/api/rb/Selenium/WebDriver/PointerActions.html
         # - https://seleniumhq.github.io/selenium/docs/api/rb/Selenium/WebDriver/KeyActions.html
         #
-        # 'mouse' action is by default in the Ruby client. Appium server force the +mouse+ action to +touch+ once in
-        # the server side. So we don't consider the case.
+        # The pointer type is 'touch' by default in the Appium Ruby client.
         #
         # @example
         #
         #     element = @driver.find_element(:id, "some id")
         #     @driver.action.click(element).perform # The 'click' is a part of 'PointerActions'
         #
-        def action(async = false)
-          # Used for default duration of each touch actions
-          # Override from 250 milliseconds to 50 milliseconds
-          action_builder = super
-          action_builder.default_move_duration = 0.05
-          action_builder
+        def action(_deprecated_async = nil, async: false, devices: nil)
+          ::Selenium::WebDriver::ActionBuilder.new(
+            self,
+            devices: devices || [::Selenium::WebDriver::Interactions.pointer(:touch, name: 'touch')],
+            async: async,
+            duration: 50 # milliseconds
+          )
         end
 
         # Port from MJSONWP
@@ -182,23 +208,7 @@ module Appium
 
         # Port from MJSONWP
         def session_capabilities
-          ::Selenium::WebDriver::Remote::Capabilities.json_create execute(:get_capabilities)
-        end
-
-        # Port from MJSONWP
-        def send_keys_to_active_element(key)
-          text = ::Selenium::WebDriver::Keys.encode(key).join
-          execute :send_keys_to_active_element, {}, { value: text.chars }
-        end
-
-        # For Appium
-        # override
-        def page_source
-          # For W3C
-          # execute_script('var source = document.documentElement.outerHTML;' \
-          # 'if (!source) { source = new XMLSerializer().serializeToString(document); }' \
-          # 'return source;')
-          execute :get_page_source
+          ::Appium::Core::Base::Capabilities.json_create execute(:get_capabilities)
         end
 
         # For Appium
@@ -214,7 +224,8 @@ module Appium
         # override
         def element_attribute(element, name)
           # For W3C in Selenium Client
-          # execute_atom :getAttribute, element, name
+          # execute_atom :getAttribute, element, name.
+          # 'dom_attribute' in the WebDriver Selenium.
           execute :get_element_attribute, id: element.id, name: name
         end
 
@@ -291,7 +302,7 @@ module Appium
         # called in 'extend DriverExtensions::HasLocation'
         def location
           obj = execute(:get_location) || {}
-          ::Selenium::WebDriver::Location.new obj['latitude'], obj['longitude'], obj['altitude']
+          ::Appium::Location.new obj['latitude'], obj['longitude'], obj['altitude']
         end
 
         # For Appium
@@ -356,6 +367,9 @@ module Appium
             element_id = element_id_from(arg)
             return ::Appium::Core::Element.new(self, element_id) if element_id
 
+            shadow_root_id = shadow_root_id_from(arg)
+            return ::Selenium::WebDriver::Remote::ShadowRoot.new self, shadow_root_id if shadow_root_id
+
             arg.each { |k, v| arg[k] = unwrap_script_result(v) }
           else
             arg

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

@@ -15,22 +15,14 @@
 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::Capabilities] Return instance of Appium::Core::Base::Capabilities
-        #                         inherited ::Selenium::WebDriver::Remote::Capabilities
-        def self.create_capabilities(opts_caps = {})
-          # TODO: Move to 'Options' way instead of 'Capabilities'.
-          # Selenium 5 will have Options instead of 'Capabilities'.
-          # https://github.com/SeleniumHQ/selenium/blob/trunk/rb/lib/selenium/webdriver/common/options.rb
-          # Then, Ruby client also shoud move to the Options way.
-          # Appium's capabilities could change by depending on Appium versions. So it does not have
-          # standard options like chrome and firefox etc. So, the implementation should differ from
-          # other browsers. But here should inherit `Options` to follow Selenium.
-          ::Selenium::WebDriver::Remote::Capabilities.new(opts_caps)
-        end
+      class Capabilities < ::Selenium::WebDriver::Remote::Capabilities
+        # TODO: Move to 'Options' way instead of 'Capabilities'.
+        # Selenium 5 will have Options instead of 'Capabilities'.
+        # https://github.com/SeleniumHQ/selenium/blob/trunk/rb/lib/selenium/webdriver/common/options.rb
+        # Then, Ruby client also shoud move to the Options way.
+        # Appium's capabilities could change by depending on Appium versions. So it does not have
+        # standard options like chrome and firefox etc. So, the implementation should differ from
+        # other browsers. But here should inherit `Options` to follow Selenium.
       end
     end
   end