appium_lib 16.4.1 → 16.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5206e8a735fef077d8eae00bd61c72be9d9845bd5e552ed5cc117b712d118ccf
-  data.tar.gz: 1e4b652e6c3a190612a46a514d56f040fe2cfc8a5caf30e64c6273b38608192e
+  metadata.gz: 06a3340368cd4c4f7018982593d00ae926d13b3d7ed7208f40dadfed018c6804
+  data.tar.gz: 032e623a9d4993338857eda7400f5de42b3aa93ddabe0529611a12b626d605b6
 SHA512:
-  metadata.gz: b9288fcfbc87a7ef1de6fbecf09591eb6961b25f779c50a6a8a29d7cbe0a8f37e66c94fef47233f3fab5cf6df26b6624580ccbd83e0662d79d896b342d11f3f1
-  data.tar.gz: 0ffba8aae6f9bdcedc9da7c3aebb2db10cac1e067e38d89b373068555d242a8df18c4b94070c0f4851856f1e9478e136d1db07b2adc203f77c95a870e1a4bbd5
+  metadata.gz: ff709d53c045b29ff31fdddbad7ee3a888e7e85dadcae4c1c7e1eb25b49748ce172c7e71428301331333fe4d8fe152a90b051230addc623417aaa5f7e6570253
+  data.tar.gz: 67563e9a99af3741b58cb719a40ebc550b8a8f3534d5460cf2aeb798f4832a619532241afc85029e0c4001713ba2e4f52a083c488ee488aea200f19682376446

data/CHANGELOG.md

@@ -4,6 +4,22 @@ 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)
 
 

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

@@ -152,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 = []
 
@@ -167,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
             driver.send m, *args, **kwargs, &block if driver.respond_to?(m)
           end
+          promoted_methods[m] = const.method(m)
         end
       end
     end

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

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.

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.1' unless defined? ::Appium::VERSION
-  DATE    = '2026-10-28' 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.1
+  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