appium_lib 16.4.0 → 16.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 737cac2a7befc3590331dca750b538fa83574b34a1e3120d13b16abc46fdbbba
-  data.tar.gz: 6e98a1456c2ce0eadf278a27472a78ce7975a28b962fdf8fe152c75721563789
+  metadata.gz: 06a3340368cd4c4f7018982593d00ae926d13b3d7ed7208f40dadfed018c6804
+  data.tar.gz: 032e623a9d4993338857eda7400f5de42b3aa93ddabe0529611a12b626d605b6
 SHA512:
-  metadata.gz: 32bb9c6dbfd35f25836f194e07b1f93314027747035754a8fe39fe06a717e1f76bb7d84ef4a24e7ea3a5534a05f892d9f8c15e0513c771f015eceadabe36cc3e
-  data.tar.gz: bb57e7f98300da2da9bd53a26e83439a4df63abc1d7d80f1dea66942b14d428d7f30c40ae400aa533decc4962232c62e32764a6230be9f216f576cf1d2c782d4
+  metadata.gz: ff709d53c045b29ff31fdddbad7ee3a888e7e85dadcae4c1c7e1eb25b49748ce172c7e71428301331333fe4d8fe152a90b051230addc623417aaa5f7e6570253
+  data.tar.gz: 67563e9a99af3741b58cb719a40ebc550b8a8f3534d5460cf2aeb798f4832a619532241afc85029e0c4001713ba2e4f52a083c488ee488aea200f19682376446

data/CHANGELOG.md

@@ -4,6 +4,29 @@ New entries are maintained by Release Please.
 
 Release tags are https://github.com/appium/ruby_lib/releases .
 
+## [16.5.0](https://github.com/appium/ruby_lib/compare/v16.4.1...v16.5.0) (2026-10-30)
+
+
+### Features
+
+* support independent non-global drivers while preserving explicit global-driver usage and the existing non-global default ([203da2d](https://github.com/appium/ruby_lib/commit/203da2dfe9a2299f24acb52a95161584d5c1d285))
+
+
+### Bug Fixes
+
+* clear session and app-string cache on quit and reload app strings for replacement sessions ([203da2d](https://github.com/appium/ruby_lib/commit/203da2dfe9a2299f24acb52a95161584d5c1d285))
+* honor symbol and string global_driver hash options when the constructor's second argument is omitted or nil; true now replaces the global driver and quits its previous session, while an explicit boolean argument takes precedence ([203da2d](https://github.com/appium/ruby_lib/commit/203da2dfe9a2299f24acb52a95161584d5c1d285))
+* make start_driver quit only its own previous session; callers relying on cleanup of another global driver must quit that driver explicitly ([203da2d](https://github.com/appium/ruby_lib/commit/203da2dfe9a2299f24acb52a95161584d5c1d285))
+* refresh generated singleton methods on re-promotion so they use the newly supplied driver rather than the previous driver ([203da2d](https://github.com/appium/ruby_lib/commit/203da2dfe9a2299f24acb52a95161584d5c1d285))
+* use the receiving driver's session for coordinate conversion and Android inspection instead of an unrelated global driver ([203da2d](https://github.com/appium/ruby_lib/commit/203da2dfe9a2299f24acb52a95161584d5c1d285))
+
+## [16.4.1](https://github.com/appium/ruby_lib/compare/v16.4.0...v16.4.1) (2026-10-28)
+
+
+### Bug Fixes
+
+* require error definitions, use next in HTMLElements#result, and fix Driver#log_event= error raising ([#1140](https://github.com/appium/ruby_lib/issues/1140)) ([1b28f90](https://github.com/appium/ruby_lib/commit/1b28f9008c488b8945cfbc41458bb430b2f7a546))
+
 ## [16.4.0](https://github.com/appium/ruby_lib/compare/v16.3.2...v16.4.0) (2026-10-26)
 
 

data/appium_lib.gemspec

@@ -18,6 +18,7 @@ Gem::Specification.new do |s|
 
   s.add_dependency 'appium_lib_core', '>= 13.0.0', '< 14.0'
   s.add_dependency 'nokogiri', '~> 1.8', '>= 1.8.1'
+  s.add_dependency 'ostruct', '~> 0.6'
   s.add_dependency 'tomlrb', '>= 1.1', '< 4.0'
 
   s.files = Dir.glob('lib/**/*.rb', base: __dir__) + %w[appium_lib.gemspec readme.md LICENSE-2.0.txt CHANGELOG.md]

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

@@ -27,9 +27,10 @@ module Appium
         @filter = value.to_s.downcase
       end
 
-      def initialize # rubocop:disable Lint/MissingSuper
+      def initialize(driver = $driver) # rubocop:disable Lint/MissingSuper
         reset
         @filter = false
+        @driver = driver
       end
 
       def reset
@@ -38,7 +39,7 @@ module Appium
       end
 
       # http://nokogiri.org/Nokogiri/XML/SAX/Document.html
-      def start_element(name, attrs = [], driver = $driver)
+      def start_element(name, attrs = [], driver = @driver)
         return if filter && !name.downcase.include?(filter)
 
         attributes = {}
@@ -49,7 +50,7 @@ module Appium
 
         # scoped to: text resource-id content-desc view-tag
         attributes_values = attributes.values
-        strings           = driver.lazy_load_strings
+        strings           = driver ? driver.lazy_load_strings : {}
         id_matches = strings.empty? ? [] : strings.select { |_key, value| attributes_values.include? value }
 
         string_ids = nil
@@ -104,7 +105,7 @@ module Appium
       parser = if source_is_html # parse html from webview
                  @android_html_parser ||= Nokogiri::HTML::SAX::Parser.new(Appium::Common::HTMLElements.new)
                else
-                 @android_native_parser ||= Nokogiri::XML::SAX::Parser.new(AndroidElements.new)
+                 @android_native_parser ||= Nokogiri::XML::SAX::Parser.new(AndroidElements.new(self))
                end
       parser.document.reset # ensure document is reset before parsing
       parser.document.filter = class_name

data/lib/appium_lib/appium.rb

@@ -19,6 +19,7 @@ require 'nokogiri'
 require 'appium_lib_core'
 
 # base
+require_relative 'error'
 require_relative 'driver'
 require_relative 'sauce_labs'
 
@@ -151,7 +152,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 ArgumentError, 'Global $driver is nil' if driver.nil?
+      raise ArgumentError, 'Driver is nil' if driver.nil?
 
       target_modules = []
 
@@ -166,16 +167,24 @@ module Appium
       end
 
       target_modules.each do |const|
+        promoted_methods = const.instance_variable_get(:@_appium_promoted_singleton_methods) || {}
+        const.instance_variable_set(:@_appium_promoted_singleton_methods, promoted_methods)
         # noinspection RubyResolve
         driver.public_methods(false).each do |m|
-          # override unless there's an existing method with matching arity
-          next if const.respond_to?(m) && const.method(m).arity == driver.method(m).arity
+          # Preserve user methods, but refresh wrappers that captured an earlier driver.
+          if const.respond_to?(m)
+            existing = const.method(m)
+            next if existing != promoted_methods[m] && existing.arity == driver.method(m).arity
+
+            const.singleton_class.send(:remove_method, m) if existing == promoted_methods[m]
+          end
 
           const.send(:define_singleton_method, m) do |*args, **kwargs, &block|
             super(*args, **kwargs, &block) # promote.rb
-          rescue NoMethodError, ArgumentError
+          rescue NoMethodError, ::ArgumentError
             driver.send m, *args, **kwargs, &block if driver.respond_to?(m)
           end
+          promoted_methods[m] = const.method(m)
         end
       end
     end
@@ -229,7 +238,7 @@ module Appium
               # minitest also defines a name method,
               # so rescue argument error
               # and call the name method on $driver
-            rescue NoMethodError, ArgumentError
+            rescue NoMethodError, ::ArgumentError
               if args.size == 1 && args.first.is_a?(Hash)
                 # To prevent warnings by keyword arguments (for Ruby 2.7 and 3)
                 driver.send method, **args.first, &block if driver.respond_to?(method)

data/lib/appium_lib/common/helper.rb

@@ -68,6 +68,7 @@ module Appium
 
     # json and ap are required for the source method.
     require 'json'
+    require 'ostruct'
 
     # @private
     # http://nokogiri.org/Nokogiri/XML/SAX.html
@@ -162,7 +163,7 @@ module Appium
     #
     #   px_to_window_rel x: 50, y: 150 #=> #<OpenStruct x="50.0 / 375.0", y="150.0 / 667.0">
     #
-    def px_to_window_rel(opts = {}, driver = $driver)
+    def px_to_window_rel(opts = {}, driver = self)
       w = driver.window_size
       x = opts.fetch :x, 0
       y = opts.fetch :y, 0
@@ -173,6 +174,8 @@ module Appium
 
     # @private
     def lazy_load_strings
+      return {} if @driver.nil?
+
       # app strings only works on local apps.
       # on disk apps (ex: com.android.settings) will error
       @lazy_load_strings ||= ignore { app_strings } || {}
@@ -182,24 +185,21 @@ module Appium
     # @param target [String] the target to search for in strings.xml values
     # @return [Array]
     def xml_keys(target)
-      lazy_load_strings
-      @lazy_load_strings.select { |key, _value| key.downcase.include? target.downcase }
+      lazy_load_strings.select { |key, _value| key.downcase.include? target.downcase }
     end
 
     # Search strings.xml's keys for target.
     # @param target [String] the target to search for in strings.xml keys
     # @return [Array]
     def xml_values(target)
-      lazy_load_strings
-      @lazy_load_strings.select { |_key, value| value.downcase.include? target.downcase }
+      lazy_load_strings.select { |_key, value| value.downcase.include? target.downcase }
     end
 
     # Resolve id in strings.xml and return the value.
     # @param id [String] the id to resolve
     # @return [String]
     def resolve_id(id)
-      lazy_load_strings
-      @lazy_load_strings[id]
+      lazy_load_strings[id]
     end
 
     # @private
@@ -233,7 +233,7 @@ module Appium
             "#{string}  #{attr[0]}: #{attr1}\n"
           end
 
-          return r if attr_string.nil? || attr_string.empty?
+          next r if attr_string.nil? || attr_string.empty?
 
           "#{r}\n#{name}\n#{attr_string}"
         end

data/lib/appium_lib/driver.rb

@@ -130,7 +130,7 @@ module Appium
     # Instance of Appium::Core::Driver
     attr_reader :core
 
-    # Creates a new driver. The driver is defined as global scope by default.
+    # Creates a new driver without a global reference by default.
     # We can avoid defining global driver.
     #
     # @example
@@ -195,15 +195,18 @@ module Appium
     #   appium_driver.start_driver
     #
     # @param opts [Object] A hash containing various options.
-    # @param global_driver [Bool] A bool require global driver before initialize.
+    # @param global_driver [Boolean, nil] Register as $driver when true. nil uses opts[:global_driver], default false.
     # @return [Driver]
-    def initialize(opts = {}, global_driver = false)
-      # Capybara can't put `global_driver` as the 2nd argument.
-      global_driver = opts.delete :global_driver if global_driver.nil?
+    def initialize(opts = {}, global_driver = nil)
+      raise ArgumentError, 'opts must be a hash' unless opts.is_a? Hash
 
-      $driver&.driver_quit if global_driver
+      # Support options-only callers without changing their options hash.
+      # An explicit second argument takes precedence over the hash option.
+      opts = opts.dup
+      configured_global_driver = opts.delete(:global_driver) { opts.delete('global_driver') { false } }
+      global_driver = configured_global_driver if global_driver.nil?
 
-      raise ArgumentError, 'opts must be a hash' unless opts.is_a? Hash
+      $driver&.driver_quit if global_driver
 
       @core = ::Appium::Core.for(opts)
       extend ::Appium::Core::Device
@@ -495,9 +498,12 @@ module Appium
     # @return [void]
     def driver_quit
       @driver&.quit
-      @driver = nil
+      nil
     rescue Selenium::WebDriver::Error::WebDriverError
       nil
+    ensure
+      @driver = nil
+      @lazy_load_strings = nil
     end
     alias quit_driver driver_quit
 
@@ -534,7 +540,7 @@ module Appium
       @driver.window_rect
     end
 
-    # Creates a new global driver and quits the old one if it exists.
+    # Creates a new session and quits this instance's previous session if it exists.
     # You can customise http_client as the following
     #
     # Read http://www.rubydoc.info/github/appium/ruby_lib_core/Appium/Core/Device to understand more what the driver
@@ -562,7 +568,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] the underlying driver for the new session
     def start_driver(http_client_ops = { http_client: nil, open_timeout: 999_999, read_timeout: 999_999 })
       http_client = http_client_ops[:http_client]
       if http_client.nil?
@@ -570,12 +576,8 @@ module Appium
                                                   read_timeout: http_client_ops[:read_timeout])
       end
 
-      # TODO: do not kill the previous session in the future version.
-      if $driver.nil?
-        driver_quit
-      else
-        $driver.driver_quit
-      end
+      # Each wrapper owns its session, even when another wrapper is global.
+      driver_quit
 
       # If automationName is set only in server side, then the following automation_name should be nil before
       # starting driver.
@@ -888,9 +890,9 @@ module Appium
     end
 
     def log_event=(log_event)
-      raise if @driver.nil?
+      raise NoDriverInstanceError if @driver.nil?
       unless log_event.is_a?(Hash)
-        raise ::Appium::Core::Error::ArgumentError('log_event should be Hash like { vendor: "appium", event: "funEvent"}')
+        raise ::Appium::Core::Error::ArgumentError, 'log_event should be Hash like { vendor: "appium", event: "funEvent"}'
       end
 
       @driver.logs.event vendor: log_event[:vendor], event: log_event[:event]

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 = '16.4.0' unless defined? ::Appium::VERSION
-  DATE    = '2026-10-26' unless defined? ::Appium::DATE # x-release-please-date
+  VERSION = '16.5.0' unless defined? ::Appium::VERSION
+  DATE    = '2026-10-30' unless defined? ::Appium::DATE # x-release-please-date
 end

data/readme.md

@@ -15,6 +15,9 @@ Helper methods for writing cross platform (iOS, Android) tests in Ruby using App
 Ordinary, `ruby_lib` worked with class driver, `$driver`, mainly.
 We can avoid the class driver with current `ruby_lib`, but if you'd like to implement your test cases based on instance driver, `@driver`, you can consider using `ruby_lib_core` first.
 
+See [non-global drivers and migration](docs/parallel.md) for instance-based usage,
+Page Objects, and coexistence with legacy global drivers.
+
 # Setup
 ## Requirement
 - [Appium](https://github.com/appium/appium#requirements)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: appium_lib
 version: !ruby/object:Gem::Version
-  version: 16.4.0
+  version: 16.5.0
 platform: ruby
 authors:
 - code@bootstraponline.com
@@ -50,6 +50,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 1.8.1
+- !ruby/object:Gem::Dependency
+  name: ostruct
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
 - !ruby/object:Gem::Dependency
   name: tomlrb
   requirement: !ruby/object:Gem::Requirement