appium_lib_core 4.1.0 → 9.3.0

data/README.md

@@ -2,7 +2,9 @@
 
 [![Gem Version](https://badge.fury.io/rb/appium_lib_core.svg)](https://badge.fury.io/rb/appium_lib_core)
 
-[![Build Status](https://dev.azure.com/AppiumCI/Appium%20CI/_apis/build/status/appium.ruby_lib_core?branchName=master)](https://dev.azure.com/AppiumCI/Appium%20CI/_build/latest?definitionId=54&branchName=master)
+[![Runs lint and unit tests](https://github.com/appium/ruby_lib_core/actions/workflows/unittest.yml/badge.svg)](https://github.com/appium/ruby_lib_core/actions/workflows/unittest.yml)
+[![Functional Tests](https://github.com/appium/ruby_lib_core/actions/workflows/functional-test.yml/badge.svg)](https://github.com/appium/ruby_lib_core/actions/workflows/functional-test.yml)
+
 
 This library is a Ruby client for Appium.  The gem is available via [appium_lib_core](https://rubygems.org/gems/appium_lib_core).
 
@@ -10,7 +12,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 +27,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 +96,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 +110,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 +125,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 +133,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']
@@ -109,28 +113,12 @@ end
 
 desc('Execute RuboCop static code analysis')
 RuboCop::RakeTask.new(:rubocop) do |t|
-  t.patterns = %w(lib test script)
+  t.patterns = %w(lib test)
   t.options = %w(-D)
   t.fail_on_error = true
 end
 
-desc('print commands which Ruby client has not implemented them yet')
-namespace :commands do
-  require './script/commands'
-
-  desc('Mobile JSON protocol')
-  task :mjsonwp do |_t, _args|
-    c = Script::CommandsChecker.new
-    c.get_mjsonwp_routes
-    c.get_all_command_path './mjsonwp_routes.js'
-    c.all_diff_commands_mjsonwp.each { |key, value| puts("command: #{key}, method: #{value}") }
-  end
-
-  desc('W3C protocol')
-  task :w3c do |_t, _args|
-    c = Script::CommandsChecker.new
-    c.get_mjsonwp_routes
-    c.get_all_command_path './mjsonwp_routes.js'
-    c.all_diff_commands_w3c.each { |key, value| puts("command: #{key}, method: #{value}") }
-  end
+desc('Run Steep type check')
+task :steep do
+  system('steep check')
 end

data/Steepfile

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+target :lib do
+  signature 'sig'
+  check 'lib' # Directory name
+
+  # Standard libraries used in the project
+  library(
+    'forwardable'
+  )
+end

data/appium_lib_core.gemspec

@@ -1,40 +1,38 @@
-# coding: utf-8
-lib = File.expand_path('../lib', __FILE__)
+lib = File.expand_path('lib', __dir__)
 $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
   spec.authors       = ['Kazuaki MATSUO']
   spec.email         = ['fly.49.89.over@gmail.com']
 
-  spec.summary       = %q{Minimal Ruby library for Appium.}
-  spec.description   = %q{Minimal Ruby library for Appium.}
+  spec.summary       = 'Minimal Ruby library for Appium.'
+  spec.description   = 'Minimal Ruby library for Appium.'
   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 'faye-websocket', '~> 0.11.0'
+  spec.add_runtime_dependency 'selenium-webdriver', '~> 4.21'
 
-  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 'appium_thor', '~> 2.0'
   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 '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 'rake', '~> 13.0'
+  spec.add_development_dependency 'rubocop', '1.69.1'
   spec.add_development_dependency 'simplecov'
+  spec.add_development_dependency 'steep', '~> 1.7.0'
+  spec.add_development_dependency 'webmock', '~> 3.24.0'
+  spec.add_development_dependency 'yard', '~> 0.9.11'
+  spec.metadata['rubygems_mfa_required'] = 'true'
 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

@@ -20,8 +20,11 @@ module Appium
           def self.add_methods
             ::Appium::Core::Device.add_endpoint_method(:finger_print) do
               def finger_print(finger_id)
+                ::Appium::Logger.warn "[DEPRECATION] Please use 'mobile: fingerprint' extension instead"
+
                 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/clipboard.rb

@@ -23,7 +23,8 @@ module Appium
             ::Appium::Core::Device.add_endpoint_method(:get_clipboard) do
               def get_clipboard(content_type: :plaintext)
                 unless ::Appium::Core::Base::Device::Clipboard::CONTENT_TYPE.member?(content_type)
-                  raise "content_type should be #{::Appium::Core::Base::Device::Clipboard::CONTENT_TYPE}"
+                  raise ::Appium::Core::Error::ArgumentError,
+                        "content_type should be #{::Appium::Core::Base::Device::Clipboard::CONTENT_TYPE}"
                 end
 
                 params = { contentType: content_type }
@@ -36,7 +37,8 @@ module Appium
             ::Appium::Core::Device.add_endpoint_method(:set_clipboard) do
               def set_clipboard(content:, content_type: :plaintext, label: nil)
                 unless ::Appium::Core::Base::Device::Clipboard::CONTENT_TYPE.member?(content_type)
-                  raise "content_type should be #{::Appium::Core::Base::Device::Clipboard::CONTENT_TYPE}"
+                  raise ::Appium::Core::Error::ArgumentError,
+                        "content_type should be #{::Appium::Core::Base::Device::Clipboard::CONTENT_TYPE}"
                 end
 
                 params = {

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

@@ -122,7 +122,7 @@ module Appium
             ::Appium::Core::Device.add_endpoint_method(:gsm_call) do
               def gsm_call(phone_number:, action:)
                 unless GSM_CALL_ACTIONS.member? action.to_sym
-                  raise "action: should be member of #{GSM_CALL_ACTIONS}. Not #{action}."
+                  raise ::Appium::Core::Error::ArgumentError, "action: should be member of #{GSM_CALL_ACTIONS}. Not #{action}."
                 end
 
                 execute(:gsm_call, {}, { phoneNumber: phone_number, action: action })
@@ -131,7 +131,10 @@ module Appium
 
             ::Appium::Core::Device.add_endpoint_method(:gsm_signal) do
               def gsm_signal(signal_strength)
-                raise "#{signal_strength} should be member of #{GSM_SIGNALS.keys} " if GSM_SIGNALS[signal_strength.to_sym].nil?
+                if GSM_SIGNALS[signal_strength.to_sym].nil?
+                  raise ::Appium::Core::Error::ArgumentError,
+                        "#{signal_strength} should be member of #{GSM_SIGNALS.keys} "
+                end
 
                 execute(:gsm_signal, {}, { signalStrength: GSM_SIGNALS[signal_strength],
                                            signalStrengh: GSM_SIGNALS[signal_strength] })
@@ -141,7 +144,7 @@ module Appium
             ::Appium::Core::Device.add_endpoint_method(:gsm_voice) do
               def gsm_voice(state)
                 unless GSM_VOICE_STATES.member? state.to_sym
-                  raise "The state should be member of #{GSM_VOICE_STATES}. Not #{state}."
+                  raise ::Appium::Core::Error::ArgumentError, "The state should be member of #{GSM_VOICE_STATES}. Not #{state}."
                 end
 
                 execute(:gsm_voice, {}, { state: state })
@@ -150,7 +153,10 @@ module Appium
 
             ::Appium::Core::Device.add_endpoint_method(:set_network_speed) do
               def set_network_speed(netspeed)
-                raise "The netspeed should be member of #{NET_SPEED}. Not #{netspeed}." unless NET_SPEED.member? netspeed.to_sym
+                unless NET_SPEED.member? netspeed.to_sym
+                  raise ::Appium::Core::Error::ArgumentError,
+                        "The netspeed should be member of #{NET_SPEED}. Not #{netspeed}."
+                end
 
                 execute(:set_network_speed, {}, { netspeed: netspeed })
               end
@@ -169,7 +175,7 @@ module Appium
             ::Appium::Core::Device.add_endpoint_method(:set_power_ac) do
               def set_power_ac(state)
                 unless POWER_AC_STATE.member? state.to_sym
-                  raise "The state should be member of #{POWER_AC_STATE}. Not #{state}."
+                  raise ::Appium::Core::Error::ArgumentError, "The state should be member of #{POWER_AC_STATE}. Not #{state}."
                 end
 
                 execute(:set_power_ac, {}, { state: state })

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

@@ -20,24 +20,32 @@ module Appium
           def self.add_methods
             ::Appium::Core::Device.add_endpoint_method(:get_network_connection) do
               def get_network_connection
+                ::Appium::Logger.warn "[DEPRECATION] Please use 'mobile: getConnectivity' extension instead"
+
                 execute :get_network_connection
               end
             end
 
             ::Appium::Core::Device.add_endpoint_method(:toggle_wifi) do
               def toggle_wifi
+                ::Appium::Logger.warn "[DEPRECATION] Please use 'mobile: setConnectivity' extension instead"
+
                 execute :toggle_wifi
               end
             end
 
             ::Appium::Core::Device.add_endpoint_method(:toggle_data) do
               def toggle_data
+                ::Appium::Logger.warn "[DEPRECATION] Please use 'mobile: setConnectivity' extension instead"
+
                 execute :toggle_data
               end
             end
 
             ::Appium::Core::Device.add_endpoint_method(:set_network_connection) do
               def set_network_connection(mode)
+                ::Appium::Logger.warn "[DEPRECATION] Please use 'mobile: setConnectivity' extension instead"
+
                 # same as ::Selenium::WebDriver::DriverExtensions::HasNetworkConnection
                 # But this method accept number
                 connection_type = { airplane_mode: 1, wifi: 2, data: 4, all: 6, none: 0 }
@@ -49,6 +57,8 @@ module Appium
 
             ::Appium::Core::Device.add_endpoint_method(:toggle_airplane_mode) do
               def toggle_airplane_mode
+                ::Appium::Logger.warn "[DEPRECATION] Please use 'mobile: setConnectivity' extension instead"
+
                 execute :toggle_airplane_mode
               end
               alias_method :toggle_flight_mode, :toggle_airplane_mode

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

@@ -20,12 +20,15 @@ module Appium
           def self.add_methods
             ::Appium::Core::Device.add_endpoint_method(:get_performance_data_types) do
               def get_performance_data_types
+                ::Appium::Logger.warn "[DEPRECATION] Please use 'mobile: getPerformanceDataTypes' extension instead"
                 execute :get_performance_data_types
               end
             end
 
             ::Appium::Core::Device.add_endpoint_method(:get_performance_data) do
               def get_performance_data(package_name:, data_type:, data_read_timeout: 1000)
+                ::Appium::Logger.warn "[DEPRECATION] Please use 'mobile: getPerformanceData' extension instead"
+
                 execute(:get_performance_data, {},
                         packageName: package_name, dataType: data_type, dataReadTimeout: data_read_timeout)
               end

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

@@ -20,6 +20,8 @@ module Appium
           def self.add_methods
             ::Appium::Core::Device.add_endpoint_method(:get_display_density) do
               def get_display_density
+                ::Appium::Logger.warn "[DEPRECATION] Please use 'mobile: getDisplayDensity' extension instead"
+
                 execute :get_display_density
               end
             end
@@ -39,7 +41,9 @@ module Appium
                 option[:bitRate] = bit_rate unless bit_rate.nil?
 
                 unless bug_report.nil?
-                  raise 'bug_report should be true or false' unless [true, false].member?(bug_report)
+                  unless [true, false].member?(bug_report)
+                    raise ::Appium::Core::Error::ArgumentError, 'bug_report should be true or false'
+                  end
 
                   option[:bugReport] = bug_report
                 end