appium_lib 15.1.0 → 15.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 796adeac9cf88dc053e753f5247424776c3fc76e7315faab0707a701b51626d1
-  data.tar.gz: 324af242f927a23024b497aa8ecbedd68dc83553473b2901e3a6dfc2da01849a
+  metadata.gz: f88a026a704b43d222f8d8bf91db42122ff2980d5035aa392ab4071713806d7f
+  data.tar.gz: 8d7dd97d70126fe283dc11d60a215301119f9463d2a90e03df701bf547ac9b78
 SHA512:
-  metadata.gz: '065363852318ced51ba308b9bc4b9708b66650d746e840f672721e58ae8a32351fd4be26df57f78794ba23f5de98ed22af77fceafeccf38cb80b3efc7545ab2e'
-  data.tar.gz: c03a4fd8b6966e60fd65fc33202a07a6fd4220f57eac3220acc82e8d33ec3562ccfa520ffc18996ac7758ba5019939320393733ad48c543371816788f67c36c2
+  metadata.gz: eb4fd237d52479e5209a04198184b280fc818bcca6a3e1f7c4498207229d4672cd78241b676aa266c076418f5885510c46fe02c5259aa7a9e11612bef111c77e
+  data.tar.gz: 7995667f533503dbc6e48d09bce54596ee771cab6675b6d3ea64d38f709310527a075fdf54e48505a095ac52151d641f2fdfe49ff78a8a6487951484faab7d83

data/CHANGELOG.md

@@ -3,8 +3,10 @@ Commit based release not is [release_notes.md](./release_notes.md)
 
 Release tags are https://github.com/appium/ruby_lib/releases .
 
+## 15.2.0 - 2024-07-20
+- Raise defined errors instead of Ruby general errors by appium_lib's own errors
 
-## [15.1.0] - 2024-05-19
+## 15.1.0 - 2024-05-19
 - Use appium_lib_core 9.0.0
 
 ## 15.0.1 - 2024-04-26

data/appium_lib.gemspec

@@ -24,7 +24,7 @@ Gem::Specification.new do |s|
   s.add_development_dependency 'minitest-reporters', '~> 1.1'
   s.add_development_dependency 'pry'
   s.add_development_dependency 'rake', '~> 13.0'
-  s.add_development_dependency 'rubocop', '1.63.5'
+  s.add_development_dependency 'rubocop', '1.65.0'
   s.add_development_dependency 'yard', '~> 0.9.11'
 
   s.files = `git ls-files`.split("\n").reject { |v| v.match(/\A^(ios_tests|android_tests|grid|test_apps)\/.+/) }

data/lib/appium_lib/android/common/helper.rb

@@ -150,7 +150,7 @@ module Appium
         index = results.length
         index -= 1 if index >= 0
       else
-        raise 'Index must be >= 1' unless index >= 1
+        raise ArgumentError, 'Index must be >= 1' unless index >= 1
 
         index -= 1 if index >= 1
       end

data/lib/appium_lib/android/element/button.rb

@@ -29,7 +29,7 @@ module Appium
       # Android needs to combine button and image button to match iOS.
       if value.is_a? Numeric
         index = value
-        raise "#{index} is not a valid index. Must be >= 1" if index <= 0
+        raise ArgumentError, "#{index} is not a valid index. Must be >= 1" if index <= 0
 
         # 1 indexed
         return find_element :uiautomator, _button_visible_selectors(index: index)

data/lib/appium_lib/android/espresso/element/button.rb

@@ -25,7 +25,7 @@ module Appium
           # Android needs to combine button and image button to match iOS.
           if value.is_a? Numeric
             index = value
-            raise "#{index} is not a valid index. Must be >= 1" if index <= 0
+            raise ArgumentError, "#{index} is not a valid index. Must be >= 1" if index <= 0
 
             # zero index
             _button_visible_selectors_xpath(index: index - 1)

data/lib/appium_lib/android/uiautomator2/element/button.rb

@@ -25,7 +25,7 @@ module Appium
           # Android needs to combine button and image button to match iOS.
           if value.is_a? Numeric
             index = value
-            raise "#{index} is not a valid index. Must be >= 1" if index <= 0
+            raise ArgumentError, "#{index} is not a valid index. Must be >= 1" if index <= 0
 
             result = find_elements :uiautomator, _button_visible_selectors(index: index)
             raise _no_such_element if result.empty?

data/lib/appium_lib/appium.rb

@@ -56,11 +56,11 @@ module Appium
     # @param opts [Hash] file: '/path/to/appium.txt', verbose: true
     # @return [hash] the symbolized hash with updated :app and :require keys
     def load_settings(opts = {})
-      raise 'opts must be a hash' unless opts.is_a? Hash
-      raise 'opts must not be empty' if opts.empty?
+      raise ArgumentError, 'opts must be a hash' unless opts.is_a? Hash
+      raise ArgumentError, 'opts must not be empty' if opts.empty?
 
       toml = opts[:file]
-      raise 'Must pass a capability file which has [caps] and [appium_lib]' unless toml
+      raise ArgumentError, 'Must pass a capability file which has [caps] and [appium_lib]' unless toml
 
       verbose = opts.fetch :verbose, false
 
@@ -69,7 +69,7 @@ module Appium
       toml_exists = File.exist? toml
       Appium::Logger.info "Exists? #{toml_exists}" if verbose
 
-      raise "toml doesn't exist #{toml}" unless toml_exists
+      raise ArgumentError, "toml doesn't exist #{toml}" unless toml_exists
 
       require 'tomlrb'
       Appium::Logger.info "Loading #{toml}" if verbose
@@ -151,7 +151,7 @@ module Appium
     # @param [Array<Module>] modules An array of modules
     # @param [Driver] driver A driver to extend for
     def promote_singleton_appium_methods(modules, driver = $driver)
-      raise 'Global $driver is nil' if driver.nil?
+      raise ArgumentError, 'Global $driver is nil' if driver.nil?
 
       target_modules = []
 
@@ -160,7 +160,7 @@ module Appium
           target_modules << modules.const_get(sub_module)
         end
       else
-        raise 'modules must be a module or an array' unless modules.is_a? Array
+        raise ArgumentError, 'modules must be a module or an array' unless modules.is_a? Array
 
         target_modules = modules
       end
@@ -205,7 +205,7 @@ module Appium
     #   Appium.promote_appium_methods Minitest::Spec
     #
     def promote_appium_methods(class_array, driver = $driver)
-      raise 'Driver is nil' if driver.nil?
+      raise ArgumentError, 'Driver is nil' if driver.nil?
 
       # Wrap single class into an array
       class_array = [class_array] unless class_array.instance_of? Array

data/lib/appium_lib/driver.rb

@@ -156,7 +156,7 @@ module Appium
 
       $driver&.driver_quit if global_driver
 
-      raise 'opts must be a hash' unless opts.is_a? Hash
+      raise ArgumentError, 'opts must be a hash' unless opts.is_a? Hash
 
       @core = ::Appium::Core.for(opts)
       extend ::Appium::Core::Device
@@ -329,7 +329,7 @@ module Appium
     #     action.click(element).perform # The `click` is a part of `PointerActions`
     #
     def action
-      @driver.action
+      @driver&.action
     end
 
     # Returns the server's version info
@@ -384,12 +384,12 @@ module Appium
     #
     # @return [String] APP_PATH as an absolute path
     def self.absolute_app_path(opts)
-      raise 'opts must be a hash' unless opts.is_a? Hash
+      raise ArgumentError, 'opts must be a hash' unless opts.is_a? Hash
 
       # FIXME: 'caps' and 'app' will be correct
       caps            = opts[:caps] || opts['caps'] || {}
       app_path        = caps[:app] || caps['app']
-      raise 'absolute_app_path invoked and app is not set!' if app_path.nil? || app_path.empty?
+      raise ArgumentError, 'absolute_app_path invoked and app is not set!' if app_path.nil? || app_path.empty?
       # Sauce storage API. http://saucelabs.com/docs/rest#storage
       return app_path if app_path.start_with? 'sauce-storage:'
       return app_path if app_path =~ URI::DEFAULT_PARSER.make_regexp # public URL for Sauce
@@ -431,7 +431,7 @@ module Appium
     # @param png_save_path [String] the full path to save the png
     # @return [File]
     def screenshot(png_save_path)
-      @driver.save_screenshot png_save_path
+      @driver&.save_screenshot png_save_path
     end
 
     # Takes a png screenshot of particular element's area
@@ -445,7 +445,7 @@ module Appium
     # @param [String] png_save_path the full path to save the png
     # @return [File]
     def element_screenshot(element, png_save_path)
-      @driver.take_element_screenshot element, png_save_path
+      @driver&.take_element_screenshot element, png_save_path
       nil
     end
 
@@ -469,6 +469,9 @@ module Appium
     #   size.height #=> Integer
     #
     def window_size
+      # maybe exception is expected as no driver created
+      raise NoDriverInstanceError if @driver.nil?
+
       @driver.window_size
     end
 
@@ -484,6 +487,8 @@ module Appium
     #   size.y #=> Integer
     #
     def window_rect
+      raise NoDriverInstanceError if @driver.nil?
+
       @driver.window_rect
     end
 
@@ -555,7 +560,7 @@ module Appium
 
     # Set implicit wait to zero.
     def no_wait
-      @driver.manage.timeouts.implicit_wait = 0
+      @driver&.manage&.timeouts&.implicit_wait = 0
     end
 
     # Set implicit wait. Default to @default_wait.
@@ -570,7 +575,7 @@ module Appium
     # @return [void]
     def set_wait(timeout = nil)
       timeout = @default_wait if timeout.nil?
-      @driver.manage.timeouts.implicit_wait = timeout
+      @driver&.manage&.timeouts&.implicit_wait = timeout
     end
 
     # Returns existence of element.
@@ -589,9 +594,9 @@ module Appium
       # do not uset set_wait here.
       # it will cause problems with other methods reading the default_wait of 0
       # which then gets converted to a 1 second wait.
-      @driver.manage.timeouts.implicit_wait = pre_check
+      @driver&.manage&.timeouts&.implicit_wait = pre_check
       # the element exists unless an error is raised.
-      exists                                = true
+      exists = true
 
       begin
         yield # search for element
@@ -600,7 +605,7 @@ module Appium
       end
 
       # restore wait
-      @driver.manage.timeouts.implicit_wait = post_check if post_check != pre_check
+      @driver&.manage&.timeouts&.implicit_wait = post_check if post_check != pre_check
 
       exists
     end
@@ -610,6 +615,8 @@ module Appium
     # @param [*args] args The args to pass to the script
     # @return [Object]
     def execute_script(script, *args)
+      raise NoDriverInstanceError if @driver.nil?
+
       @driver.execute_script script, *args
     end
 
@@ -618,6 +625,8 @@ module Appium
     ###
     # Get the window handles of open browser windows
     def execute_async_script(script, *args)
+      raise NoDriverInstanceError if @driver.nil?
+
       @driver.execute_async_script script, *args
     end
 
@@ -650,41 +659,59 @@ module Appium
     #      r.logs   #=> The `logs` key part as `{'log' => [], 'warn' => [], 'error' => []}`
     #
     def execute_driver(script: '', type: 'webdriverio', timeout_ms: nil)
+      raise NoDriverInstanceError if @driver.nil?
+
       @driver.execute_driver(script: script, type: type, timeout_ms: timeout_ms)
     end
 
     def window_handles
+      raise NoDriverInstanceError if @driver.nil?
+
       @driver.window_handles
     end
 
     # Get the current window handle
     def window_handle
+      raise NoDriverInstanceError if @driver.nil?
+
       @driver.window_handle
     end
 
     def navigate
+      raise NoDriverInstanceError if @driver.nil?
+
       @driver.navigate
     end
 
     def manage
+      raise NoDriverInstanceError if @driver.nil?
+
       @driver.manage
     end
 
     def get(url)
+      raise NoDriverInstanceError if @driver.nil?
+
       @driver.get(url)
     end
 
     def current_url
+      raise NoDriverInstanceError if @driver.nil?
+
       @driver.current_url
     end
 
     def title
+      raise NoDriverInstanceError if @driver.nil?
+
       @driver.title
     end
 
     # @return [TargetLocator]
     # @see TargetLocator
     def switch_to
+      raise NoDriverInstanceError if @driver.nil?
+
       @driver.switch_to
     end
     ###
@@ -712,6 +739,8 @@ module Appium
     # @param [*args] args The args to use
     # @return [Array<Element>] Array is empty when no elements are found.
     def find_elements(*args)
+      raise NoDriverInstanceError if @driver.nil?
+
       @driver.find_elements(*args)
     end
 
@@ -728,6 +757,8 @@ module Appium
     # @param [*args] args The args to use
     # @return [Element]
     def find_element(*args)
+      raise NoDriverInstanceError if @driver.nil?
+
       @driver.find_element(*args)
     end
 
@@ -743,6 +774,8 @@ module Appium
     #     @driver.find_element_by_image './test/functional/data/test_element_image.png'
     #
     def find_element_by_image(png_img_path)
+      raise NoDriverInstanceError if @driver.nil?
+
       @driver.find_element_by_image(png_img_path)
     end
 
@@ -758,6 +791,8 @@ module Appium
     #     @driver.find_elements_by_image ['./test/functional/data/test_element_image.png']
     #
     def find_elements_by_image(png_img_paths)
+      raise NoDriverInstanceError if @driver.nil?
+
       @driver.find_elements_by_image(png_img_paths)
     end
 
@@ -771,6 +806,8 @@ module Appium
     # @option opts [Float] :altitude the altitude, defaulting to 75
     # @return [Selenium::WebDriver::Location] the location constructed by the selenium webdriver
     def set_location(opts = {})
+      raise NoDriverInstanceError if @driver.nil?
+
       latitude = opts.fetch(:latitude)
       longitude = opts.fetch(:longitude)
       altitude = opts.fetch(:altitude, 75)
@@ -794,10 +831,13 @@ module Appium
     #              #          'appium:anotherEvent' => 1572959315}
     #
     def log_event(vendor:, event:)
+      raise NoDriverInstanceError if @driver.nil?
+
       @driver.logs.event vendor: vendor, event: event
     end
 
     def log_event=(log_event)
+      raise if @driver.nil?
       unless log_event.is_a?(Hash)
         raise ::Appium::Core::Error::ArgumentError('log_event should be Hash like { vendor: "appium", event: "funEvent"}')
       end
@@ -817,6 +857,8 @@ module Appium
     #   log_events #=> {'commands' => [{'cmd' => 123455, ....}], 'startTime' => 1572954894127, }
     #
     def log_events(type = nil)
+      raise NoDriverInstanceError if @driver.nil?
+
       @driver.logs.events(type)
     end
 

data/lib/appium_lib/error.rb

@@ -0,0 +1,22 @@
+# 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
+  class Error < StandardError; end
+
+  # Driver instance hasn't been created yet.
+  class NoDriverInstanceError < Appium::Error; end
+
+  class ArgumentError < ArgumentError; end
+end

data/lib/appium_lib/ios/common/helper.rb

@@ -107,7 +107,7 @@ module Appium
     # @param index [Integer] the index
     # @return [Element]
     def ele_index(class_name, index)
-      raise 'Index must be >= 1' unless index == 'last()' || (index.is_a?(Integer) && index >= 1)
+      raise ArgumentError, 'Index must be >= 1' unless index == 'last()' || (index.is_a?(Integer) && index >= 1)
 
       elements = tags(class_name)
 
@@ -376,7 +376,7 @@ module Appium
     #
     def _all_pred(opts)
       predicate = opts[:predicate]
-      raise 'predicate must be provided' unless predicate
+      raise ArgumentError, 'predicate must be provided' unless predicate
 
       visible = opts.fetch :visible, true
       %($.mainApp().getAllWithPredicate("#{predicate}", #{visible});)
@@ -404,23 +404,23 @@ module Appium
     end
 
     def _validate_object(*objects)
-      raise 'objects must be an array' unless objects.is_a? Array
+      raise ArgumentError, 'objects must be an array' unless objects.is_a? Array
 
       objects.each do |obj|
         next unless obj # obj may be nil. if so, ignore.
 
         valid_keys   = %i[target substring insensitive]
         unknown_keys = obj.keys - valid_keys
-        raise "Unknown keys: #{unknown_keys}" unless unknown_keys.empty?
+        raise ArgumentError, "Unknown keys: #{unknown_keys}" unless unknown_keys.empty?
 
         target = obj[:target]
-        raise 'target must be a string' unless target.is_a? String
+        raise ArgumentError, 'target must be a string' unless target.is_a? String
 
         substring = obj[:substring]
-        raise 'substring must be a boolean' unless [true, false].include? substring
+        raise ArgumentError, 'substring must be a boolean' unless [true, false].include? substring
 
         insensitive = obj[:insensitive]
-        raise 'insensitive must be a boolean' unless [true, false].include? insensitive
+        raise ArgumentError, 'insensitive must be a boolean' unless [true, false].include? insensitive
       end
     end
 
@@ -456,16 +456,16 @@ module Appium
     def _by_json(opts)
       valid_keys = %i(typeArray onlyFirst onlyVisible name label value)
       unknown_keys = opts.keys - valid_keys
-      raise "Unknown keys: #{unknown_keys}" unless unknown_keys.empty?
+      raise ArgumentError, "Unknown keys: #{unknown_keys}" unless unknown_keys.empty?
 
       type_array = opts[:typeArray]
-      raise 'typeArray must be an array' unless type_array.is_a? Array
+      raise ArgumentError, 'typeArray must be an array' unless type_array.is_a? Array
 
       only_first = opts[:onlyFirst]
-      raise 'onlyFirst must be a boolean' unless [true, false].include? only_first
+      raise ArgumentError, 'onlyFirst must be a boolean' unless [true, false].include? only_first
 
       only_visible = opts[:onlyVisible]
-      raise 'onlyVisible must be a boolean' unless [true, false].include? only_visible
+      raise ArgumentError, 'onlyVisible must be a boolean' unless [true, false].include? only_visible
 
       # name/label/value are optional. when searching for class only, then none
       # will be present.

data/lib/appium_lib/ios/element/textfield.rb

@@ -42,7 +42,7 @@ module Appium
     def textfield(value)
       if value.is_a? Numeric
         index = value
-        raise "#{index} is not a valid index. Must be >= 1" if index <= 0
+        raise ArgumentError, "#{index} is not a valid index. Must be >= 1" if index <= 0
 
         index -= 1 # eles_by_json and _textfields_with_predicate is 0 indexed.
         result = eles_by_json(_textfield_visible)[index]

data/lib/appium_lib/ios/xcuitest/element/textfield.rb

@@ -37,7 +37,7 @@ module Appium
         def textfield(value)
           if value.is_a? Numeric
             index = value
-            raise "#{index} is not a valid index. Must be >= 1" if index <= 0
+            raise ArgumentError, "#{index} is not a valid index. Must be >= 1" if index <= 0
 
             index -= 1 # eles_by_json and _textfields_with_predicate is 0 indexed.
             result = _textfields_with_predicate[index]

data/lib/appium_lib/version.rb

@@ -14,6 +14,6 @@
 
 module Appium
   # Version and Date are defined on the 'Appium' module, not 'Appium::Common'
-  VERSION = '15.1.0' unless defined? ::Appium::VERSION
-  DATE    = '2024-05-19' unless defined? ::Appium::DATE
+  VERSION = '15.2.0' unless defined? ::Appium::VERSION
+  DATE    = '2024-07-20' unless defined? ::Appium::DATE
 end

data/release_notes.md

@@ -1,3 +1,13 @@
+#### v15.2.0 2024-07-20
+
+- [d73525e](https://github.com/appium/ruby_lib/commit/d73525eec584c3c31690dcd55a6c52d641d43f9f) Release 15.2.0
+- [6b5d969](https://github.com/appium/ruby_lib/commit/6b5d9693f10e64a521f6ac5d31c78d71e5f0f6be) feat: raise its own defined errors (#1035)
+- [4a74c60](https://github.com/appium/ruby_lib/commit/4a74c60937e66bf028a66e4f05a324ce8b2077ce) chore: Update rubocop requirement from = 1.64.1 to = 1.65.0 (#1034)
+- [fa4cea4](https://github.com/appium/ruby_lib/commit/fa4cea4e5bea0aa4e3ed7052ba77812c82684fe0) chore: Update rubocop requirement from = 1.64.0 to = 1.64.1 (#1033)
+- [96ce262](https://github.com/appium/ruby_lib/commit/96ce26264d985b5260e99573486e8f712bfb12e3) chore: Update rubocop requirement from = 1.63.5 to = 1.64.0 (#1032)
+- [14590cc](https://github.com/appium/ruby_lib/commit/14590cce6f6cbef8c20e12ae10b00bf3f7b5ab3a) chore: tweak changelog format
+
+
 #### v15.1.0 2024-05-19
 
 - [b1534cc](https://github.com/appium/ruby_lib/commit/b1534cc8e781e37f9632fa1cbaa6e2422b6a768d) Release 15.1.0

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: appium_lib
 version: !ruby/object:Gem::Version
-  version: 15.1.0
+  version: 15.2.0
 platform: ruby
 authors:
 - code@bootstraponline.com
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-05-20 00:00:00.000000000 Z
+date: 2024-07-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: appium_lib_core
@@ -169,14 +169,14 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 1.63.5
+        version: 1.65.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 1.63.5
+        version: 1.65.0
 - !ruby/object:Gem::Dependency
   name: yard
   requirement: !ruby/object:Gem::Requirement
@@ -247,6 +247,7 @@ files:
 - lib/appium_lib/common/log.rb
 - lib/appium_lib/common/wait.rb
 - lib/appium_lib/driver.rb
+- lib/appium_lib/error.rb
 - lib/appium_lib/ios/common/errors.rb
 - lib/appium_lib/ios/common/helper.rb
 - lib/appium_lib/ios/element/alert.rb