appium_lib_core 4.1.0 → 7.1.0

data/README.md

@@ -10,7 +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]`](CHANGELOG.md#500---2021-11-05) section in [CHANGELOG](CHANGELOG.md)
 
 # Related library
 - https://github.com/appium/ruby_lib
@@ -18,27 +25,36 @@ This library wraps [selenium-webdriver](https://github.com/SeleniumHQ/selenium/w
 # How to start
 ## Run tests
 ### Unit Tests
-Run unit tests which check each method and commands, URL, using the webmock.
+Run unit tests which check each method and command, URL, using the webmock.
 
 ```bash
 $ 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 --location=global appium
+$ 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
 ```
 
@@ -78,7 +94,7 @@ $ PARALLEL=1 bundle exec parallel_test test/functional/ios -n 2
 
 - Runs on CI environment (on Azure)
     - Non `IGNORE_VERSION_SKIP` or `IGNORE_VERSION_SKIP=true` runs all tests ignoring `skip` them by Appium versions
-    - `IGNORE_VERSION_SKIP=false` skips the following tests if the Appium version is lower than the requirement  
+    - `IGNORE_VERSION_SKIP=false` skips the following tests if the Appium version is lower than the requirement
 
 ```
 $ IGNORE_VERSION_SKIP=true CI=true bundle exec rake test:func:android
@@ -92,14 +108,14 @@ $ IGNORE_VERSION_SKIP=true CI=true bundle exec rake test:func:android
     ```ruby
     require 'rubygems'
     require 'appium_lib_core'
-    
+
     opts = {
-      desired_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
@@ -107,7 +123,7 @@ $ IGNORE_VERSION_SKIP=true CI=true bundle exec rake test:func:android
     }
     @core = Appium::Core.for(opts) # create a core driver with `opts`
     @driver = @core.start_driver
-    
+
     # Launch iPhone Simulator and `MyiOS.app`
     @driver.find_element(:accessibility_id, 'some accessibility') # find an element
     ```
@@ -115,18 +131,52 @@ $ IGNORE_VERSION_SKIP=true CI=true bundle exec rake test:func:android
     ```bash
     # shell 1
     $ appium --log-level warn:error # show only warning and error logs
-    
+
     # shell 2
     $ ruby test.rb
     ```
 
-More examples are in [test/functional](test/functional)    
+[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/Rakefile

@@ -38,6 +38,7 @@ namespace :test do
   namespace :unit do
     desc('Run all iOS related unit tests in test directory')
     Rake::TestTask.new(:ios) do |t|
+      ENV['UNIT_TEST'] = '1'
       t.libs << 'test'
       t.libs << 'lib'
       t.test_files = FileList['test/unit/ios/**/*_test.rb']
@@ -45,6 +46,7 @@ namespace :test do
 
     desc('Run all Android related unit tests in test directory')
     Rake::TestTask.new(:android) do |t|
+      ENV['UNIT_TEST'] = '1'
       t.libs << 'test'
       t.libs << 'lib'
       t.test_files = FileList['test/unit/android/**/*_test.rb']
@@ -52,6 +54,7 @@ namespace :test do
 
     desc('Run all common related unit tests in test directory')
     Rake::TestTask.new(:common) do |t|
+      ENV['UNIT_TEST'] = '1'
       t.libs << 'test'
       t.libs << 'lib'
       t.test_files = FileList['test/unit/common/**/*_test.rb']
@@ -59,6 +62,7 @@ namespace :test do
 
     desc('Run all Windows related unit tests in test directory')
     Rake::TestTask.new(:windows) do |t|
+      ENV['UNIT_TEST'] = '1'
       t.libs << 'test'
       t.libs << 'lib'
       t.test_files = FileList['test/unit/windows/**/*_test.rb']

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.4'
+  spec.required_ruby_version = Gem::Requirement.new('>= 3.0')
 
   spec.name          = 'appium_lib_core'
   spec.version       = Appium::Core::VERSION
@@ -16,25 +16,22 @@ 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', '~> 3.14', '>= 3.14.1'
+  spec.add_runtime_dependency 'selenium-webdriver', '~> 4.2', '< 4.12'
   spec.add_runtime_dependency 'faye-websocket', '~> 0.11.0'
 
-  spec.add_development_dependency 'bundler', '>= 1.14'
   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.11.0'
-  spec.add_development_dependency 'rubocop', '1.7.0'
+  spec.add_development_dependency 'webmock', '~> 3.18.1'
+  spec.add_development_dependency 'rubocop', '1.56.0'
   spec.add_development_dependency 'appium_thor', '~> 1.0'
-  spec.add_development_dependency 'pry'
-  spec.add_development_dependency 'pry-byebug'
   spec.add_development_dependency 'parallel_tests'
   spec.add_development_dependency 'simplecov'
 end

data/bin/console

@@ -6,9 +6,5 @@ require "appium_lib_core"
 # You can add fixtures and/or initialization code here to make experimenting
 # with your gem easier. You can also use a different console, if you like.
 
-# (If you use this, don't forget to add pry to your Gemfile!)
-# require "pry"
-# Pry.start
-
 require "irb"
 IRB.start(__FILE__)

data/lib/appium_lib_core/android/device/auth_finger_print.rb

@@ -21,7 +21,8 @@ module Appium
             ::Appium::Core::Device.add_endpoint_method(:finger_print) do
               def finger_print(finger_id)
                 unless (1..10).cover? finger_id.to_i
-                  raise ArgumentError, "finger_id should be integer between 1 to 10. Not #{finger_id}"
+                  raise ::Appium::Core::Error::ArgumentError,
+                        "finger_id should be integer between 1 to 10. Not #{finger_id}"
                 end
 
                 execute(:finger_print, {}, { fingerprintId: finger_id.to_i })

data/lib/appium_lib_core/android/device.rb

@@ -106,6 +106,43 @@ module Appium
         #   @driver.toggle_data
         #
 
+        # @!method location
+        # Get the location of the device.
+        #
+        # @return [::Appium::Location]
+        #
+        # @example
+        #
+        #   driver.location #=> ::Appium::Location.new(10, 10, 10)
+        #
+
+        # @!method location=
+        # Set the location of the device.
+        #
+        # @param [::Appium::Location] location Set the location.
+        #
+        # @example
+        #
+        #   driver.location = ::Appium::Location.new(10, 10, 10)
+        #
+
+        # @!method set_location
+        # Set the location of the device.
+        #
+        # @param [String, Number] latitude Set the latitude.
+        # @param [String, Number] longitude Set the longitude.
+        # @param [String, Number] altitude Set the altitude.
+        # @param [String, Number] speed Set the speed to apply the location on Android real devices
+        #                               in meters/second @since Appium 1.21.0 and in knots for emulators @since Appium 1.22.0.
+        # @param [String, Number] satellites Sets the count of geo satellites being tracked in range 1..12 @since Appium 1.22.0.
+        #                                    This number is respected on Emulators.
+        # @param [::Appium::Location]
+        #
+        # @example
+        #
+        #   driver.set_location 10, 10, 0
+        #
+
         # @!method toggle_location_services
         #   Switch the state of the location service
         #
@@ -290,18 +327,22 @@ module Appium
         #   @driver.finger_print 1
         #
 
-        # @!method execute_cdp(cmd, params)
+        # @!method execute_cdp(cmd, **params)
         #     Execute Chrome Devtools protocol commands
         #     https://chromedevtools.github.io/devtools-protocol
         #
         # @param [String] cmd The name of command
-        # @param [Hash] params The parameter for the command as hash.
+        # @option params The parameter for the command as keyword options.
         #
         # @example
         #
-        #   @driver.execute_cdp 'Page.captureScreenshot', { quality: 50, format: 'jpeg' }
+        #   @driver.execute_cdp 'Page.captureScreenshot', quality: 50, format: 'jpeg'
         #   @driver.execute_cdp 'Page.getResourceTree'
         #
+        #   # for Ruby 2,7 and 3+ compatibility
+        #   params = {'timezoneId': 'Asia/Tokyo'}
+        #   driver.execute_cdp 'Emulation.setTimezoneOverride', **params
+        #
 
         ####
         ## class << self
@@ -415,7 +456,7 @@ module Appium
               # SeleniumWebdriver could already define this method
               return if method_defined? :execute_cdp
 
-              def execute_cdp(cmd, params = {})
+              def execute_cdp(cmd, **params)
                 execute :chrome_send_command, {}, { cmd: cmd, params: params }
               end
             end