appium_lib 9.6.1 → 9.7.0

data/docs/migration.md

@@ -1,3 +1,20 @@
+### Breaking Changes in 9.6.0
+Raise warning if users call `Appium::Driver.new(opts)`.
+
+- After
+
+```ruby
+Appium::Driver.new(opts).start_driver # Raise warning.
+Appium::Driver.new(opts, true).start_driver # $driver is defined.
+Appium::Driver.new(opts, false).start_driver # $driver isn't defined.
+```
+
+- Before
+
+```ruby
+Appium::Driver.new(opts).start_driver # $driver is defined.
+```
+
 ### Breaking Changes in 9.3.7
 change `@selenium_driver.find_element/s_with_appium` to `@selenium_driver.find_element/s`.
 ref: https://github.com/appium/ruby_lib/pull/532

data/lib/appium_lib.rb

@@ -7,5 +7,4 @@ require 'forwardable' unless defined? Forwardable
 # Init global driver
 $driver = nil
 
-require_relative 'appium_lib/logger'
-require_relative 'appium_lib/driver'
+require_relative 'appium_lib/appium'

data/lib/appium_lib/android/android.rb

@@ -0,0 +1,20 @@
+require_relative 'common/helper'
+
+require_relative 'element/alert'
+require_relative 'element/button'
+require_relative 'element/generic'
+require_relative 'element/textfield'
+require_relative 'element/text'
+
+# android - uiautomator2
+require_relative 'uiautomator2'
+
+module Appium
+  module Android
+    class Bridge
+      def self.for(target)
+        target.extend Appium::Android
+      end
+    end
+  end
+end

data/lib/appium_lib/android/{helper.rb → common/helper.rb}

@@ -91,7 +91,7 @@ module Appium
       source_is_html = source_header.start_with?(doctype_string, '<html')
 
       parser = if source_is_html # parse html from webview
-                 @android_html_parser ||= Nokogiri::HTML::SAX::Parser.new(Common::HTMLElements.new)
+                 @android_html_parser ||= Nokogiri::HTML::SAX::Parser.new(Appium::Common::HTMLElements.new)
                else
                  @android_native_parser ||= Nokogiri::XML::SAX::Parser.new(AndroidElements.new)
                end

data/lib/appium_lib/android/uiautomator2.rb

@@ -1,10 +1,11 @@
 require_relative 'uiautomator2/helper'
 require_relative 'uiautomator2/element'
+require_relative 'uiautomator2/bridge'
 
 module Appium
-  module Ios
-    module Xcuitest
+  module Android
+    module Uiautomator2
       # parent
-    end # module Xcuitest
-  end # module Ios
+    end # module Uiautomator2
+  end # module Android
 end # module Appium

data/lib/appium_lib/android/uiautomator2/bridge.rb

@@ -0,0 +1,16 @@
+require_relative '../android'
+
+module Appium
+  module Android
+    module Uiautomator2
+      class Bridge
+        def self.for(target)
+          target.extend Appium::Android
+          target.extend Appium::Android::Uiautomator2
+          target.extend Appium::Android::Uiautomator2::Helper
+          target.extend Appium::Android::Uiautomator2::Element
+        end
+      end
+    end
+  end
+end

data/lib/appium_lib/appium.rb

@@ -0,0 +1,201 @@
+require 'rubygems'
+require 'selenium-webdriver'
+require 'nokogiri'
+
+# base
+require_relative 'driver'
+require_relative 'sauce_labs'
+
+# common
+require_relative 'common/wait'
+require_relative 'common/log'
+require_relative 'common/helper'
+require_relative 'common/multi_touch'
+require_relative 'common/touch_actions'
+
+# core
+require_relative 'core/core'
+
+# ios
+require_relative 'ios/ios'
+
+# android
+require_relative 'android/android'
+
+module Appium
+  class << self
+    # Load arbitrary text ([toml format](https://github.com/toml-lang/toml))
+    # The toml is parsed by https://github.com/fbernier/tomlrb .
+    #
+    # ```
+    # [caps]
+    # app = "path/to/app"
+    #
+    # [appium_lib]
+    # port = 8080
+    # ```
+    #
+    # :app is expanded
+    # :require is expanded
+    # all keys are converted to symbols
+    #
+    # @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?
+
+      toml = opts[:file]
+      raise 'Must pass a capability file which has [caps] and [appium_lib]' unless toml
+      verbose = opts.fetch :verbose, false
+
+      Appium::Logger.info "appium settings path: #{toml}" if verbose
+
+      toml_exists = File.exist? toml
+      Appium::Logger.info "Exists? #{toml_exists}" if verbose
+
+      raise "toml doesn't exist #{toml}" unless toml_exists
+      require 'tomlrb'
+      Appium::Logger.info "Loading #{toml}" if verbose
+
+      data = Tomlrb.load_file(toml, symbolize_keys: true)
+      if verbose
+        Appium::Logger.ap_info data unless data.empty?
+      end
+
+      if data && data[:caps] && data[:caps][:app] && !data[:caps][:app].empty?
+        data[:caps][:app] = Appium::Driver.absolute_app_path data
+      end
+
+      if data && data[:appium_lib] && data[:appium_lib][:require]
+        parent_dir = File.dirname toml
+        data[:appium_lib][:require] = expand_required_files(parent_dir, data[:appium_lib][:require])
+      end
+
+      data
+    end
+    alias load_appium_txt load_settings
+
+    # @param [String] base_dir parent directory of loaded appium.txt (toml)
+    # @param [String] file_paths
+    # @return [Array] list of require files as an array, nil if require doesn't exist
+    def expand_required_files(base_dir, file_paths)
+      # ensure files are absolute
+      Array(file_paths).map! do |f|
+        file = File.exist?(f) ? f : File.join(base_dir, f)
+        file = File.expand_path file
+
+        File.exist?(file) ? file : nil
+      end
+      file_paths.compact! # remove nils
+
+      files = []
+
+      # now expand dirs
+      file_paths.each do |item|
+        unless File.directory? item
+          # save file
+          files << item
+          next # only look inside folders
+        end
+        Dir.glob(File.expand_path(File.join(item, '**', '*.rb'))) do |f|
+          # do not add folders to the file list
+          files << File.expand_path(f) unless File.directory? f
+        end
+      end
+
+      files
+    end
+
+    # This method is intended to work with page objects that share
+    # a common module. For example, Page::HomePage, Page::SignIn
+    # those could be promoted on with Appium.promote_singleton_appium_methods Page
+    #
+    # If you are promoting on an individual class then you should use
+    # Appium.promote_appium_methods instead. The singleton method is intended
+    # only for the shared module use case.
+    #
+    # if modules is a module instead of an array, then the constants of
+    # that module are promoted on.
+    # otherwise, the array of modules will be used as the promotion target.
+    def promote_singleton_appium_methods(modules, driver = $driver)
+      raise 'Global $driver is nil' if driver.nil?
+
+      target_modules = []
+
+      if modules.is_a? Module
+        modules.constants.each do |sub_module|
+          target_modules << modules.const_get(sub_module)
+        end
+      else
+        raise 'modules must be a module or an array' unless modules.is_a? Array
+        target_modules = modules
+      end
+
+      target_modules.each do |const|
+        # noinspection RubyResolve
+        # rubocop:disable Style/MultilineIfModifier
+        driver.public_methods(false).each do |m|
+          const.send(:define_singleton_method, m) do |*args, &block|
+            begin
+              super(*args, &block) # promote.rb
+            rescue NoMethodError, ArgumentError
+              driver.send m, *args, &block if driver.respond_to?(m)
+            end
+            # override unless there's an existing method with matching arity
+          end unless const.respond_to?(m) && const.method(m).arity == driver.method(m).arity
+        end
+        # rubocop:enable Style/MultilineIfModifier
+      end
+    end
+
+    ##
+    # Promote appium methods to class instance methods
+    #
+    # @param class_array [Array<Class>] An array of classes
+    #
+    # To promote methods to all classes:
+    #
+    # ```ruby
+    # Appium.promote_appium_methods Object
+    # ```
+    #
+    # It's better to promote on specific classes instead of Object
+    #
+    # ```ruby
+    # # promote on rspec
+    # Appium.promote_appium_methods RSpec::Core::ExampleGroup
+    # ```
+    #
+    # ```ruby
+    # # promote on minispec
+    # Appium.promote_appium_methods Minitest::Spec
+    # ```
+    def promote_appium_methods(class_array, driver = $driver)
+      raise 'Driver is nil' if driver.nil?
+      # Wrap single class into an array
+      class_array = [class_array] unless class_array.class == Array
+      # Promote Appium driver methods to class instance methods.
+      class_array.each do |klass|
+        driver.public_methods(false).each do |m|
+          klass.class_eval do
+            define_method m do |*args, &block|
+              begin
+                # Prefer existing method.
+                # super will invoke method missing on driver
+                super(*args, &block)
+
+                # minitest also defines a name method,
+                # so rescue argument error
+                # and call the name method on $driver
+              rescue NoMethodError, ArgumentError
+                driver.send m, *args, &block if driver.respond_to?(m)
+              end
+            end
+          end
+        end
+      end
+      nil # return nil
+    end
+  end
+end

data/lib/appium_lib/common/helper.rb

@@ -1,14 +1,7 @@
-require 'selenium/webdriver/common/error'
-
 # Generic helper methods not specific
 # to a particular tag name
 module Appium
   module Common
-    # json and ap are required for the source method.
-    require 'json'
-    require 'ap' # awesome print
-    require 'timeout' # for wait
-
     # iOS .name returns the accessibility attribute if it's set. if not set, the string value is used.
     # Android .name returns the accessibility attribute and nothing if it's not set.
     #
@@ -42,7 +35,7 @@ module Appium
     # @param xpath_str [String] the XPath string
     # @return [Element]
     def xpath(xpath_str)
-      find_element :xpath, xpath_str
+      @driver.find_element :xpath, xpath_str
     end
 
     # Returns all elements that match the provided xpath.
@@ -50,18 +43,12 @@ module Appium
     # @param xpath_str [String] the XPath string
     # @return [Array<Element>]
     def xpaths(xpath_str)
-      find_elements :xpath, xpath_str
+      @driver.find_elements :xpath, xpath_str
     end
 
-    def _print_source(source)
-      opts = Nokogiri::XML::ParseOptions::NOBLANKS | Nokogiri::XML::ParseOptions::NONET
-      doc = if source.start_with? '<html'
-              Nokogiri::HTML(source) { |cfg| cfg.options = opts }
-            else
-              Nokogiri::XML(source)  { |cfg| cfg.options = opts }
-            end
-      puts doc.to_xml indent: 2
-    end
+    # json and ap are required for the source method.
+    require 'json'
+    require 'ap' # awesome print
 
     # @private
     # http://nokogiri.org/Nokogiri/XML/SAX.html
@@ -219,5 +206,16 @@ module Appium
       error_message = 'An element could not be located on the page using the given search parameters.'
       raise Selenium::WebDriver::Error::NoSuchElementError, error_message
     end
-  end # module Common
-end # module Appium
+
+    # @private
+    def _print_source(source)
+      opts = Nokogiri::XML::ParseOptions::NOBLANKS | Nokogiri::XML::ParseOptions::NONET
+      doc = if source.start_with? '<html'
+              Nokogiri::HTML(source) { |cfg| cfg.options = opts }
+            else
+              Nokogiri::XML(source)  { |cfg| cfg.options = opts }
+            end
+      puts doc.to_xml indent: 2
+    end
+  end
+end

data/lib/appium_lib/common/log.rb

@@ -0,0 +1,24 @@
+module Appium
+  module Common
+    # @param [String|Hash] type You can get particular type's logs.
+    # @return [[Selenium::WebDriver::LogEntry]] A list of logs data.
+    #
+    # @example
+    #   @driver.get_log("syslog") #=> [[Selenium::WebDriver::LogEntry]]
+    #   @driver.get_log(:syslog)  #=> [[Selenium::WebDriver::LogEntry]]
+    #
+    def get_log(type)
+      Appium::Core::Logs.new(@driver.manage.logs).get type
+    end
+
+    # Get a list of available log types
+    #
+    # @return [[String]] A list of available log types.
+    # @example
+    #   @driver.get_available_log_types #=> [:syslog, :crashlog, :performance]
+    #
+    def get_available_log_types
+      Appium::Core::Logs.new(@driver.manage.logs).available_types
+    end
+  end # module Common
+end # module Appium

data/lib/appium_lib/common/multi_touch.rb

@@ -0,0 +1,89 @@
+module Appium
+  # MultiTouch actions allow for multiple touches to happen at the same time,
+  # for instance, to simulate multiple finger swipes.
+  #
+  # Create a series of touch actions by themselves (without a `prepare()`), then
+  # add to a new MultiTouch action.  When ready, call `prepare()` and all
+  # actions will be executed simultaneously.
+  #
+  # ```ruby
+  # action_1 = TouchAction.new.press(x: 45, y: 100).wait(5).release
+  # action_2 = TouchAction.new.tap(element: el, x: 50, y:5, count: 3)
+  #
+  # multi_touch_action = MultiTouch.new
+  # multi_touch_action.add action_1
+  # multi_touch_action.add action_2
+  # multi_touch_action.perform
+  # ```
+  #
+  # ```
+  # # with an arbitrary driver
+  # driver =  Appium::Driver.new(opts, false).start_driver
+  # multi_touch_action = MultiTouch.new(driver)
+  # multi_touch_action.add action_1
+  # multi_touch_action.add action_2
+  # multi_touch_action.perform
+  # ```
+
+  class MultiTouch < ::Appium::Core::MultiTouch
+    class << self
+      # Convenience method for pinching the screen.
+      # Places two fingers at the edges of the screen and brings them together.
+      # @param percentage (int) The percent size by which to shrink the screen when pinched.
+      # @param auto_perform (boolean) Whether to perform the action immediately (default true)
+      # @param driver (Driver) Set a driver to conduct the action. DEfault is global driver($driver)
+      #
+      # ```ruby
+      # pinch 75 #=> Pinch the screen from the top right and bottom left corners
+      # ```
+      #
+      # Without auto_perform
+      #
+      # ```ruby
+      # action = pinch 75, false #=> Pinch the screen from the top right and bottom left corners
+      # action.perform    #=> to 25% of its size.
+      # ```
+      #
+      # With driver
+      #
+      # ```ruby
+      # driver =  Appium::Driver.new(opts, false).start_driver
+      # pinch 75, true, driver #=> Pinch the screen from the top right and bottom left corners
+      # ```
+      def pinch(percentage = 25, auto_perform = true, driver = $driver)
+        ::Appium::Core::MultiTouch.pinch percentage: percentage, auto_perform: auto_perform, driver: driver
+      end
+
+      # Convenience method for zooming the screen.
+      # Places two fingers at the edges of the screen and brings them together.
+      # @param percentage (int) The percent size by which to shrink the screen when pinched.
+      # @param auto_perform (boolean) Whether to perform the action immediately (default true)
+      # @param driver (Driver) Set a driver to conduct the action. DEfault is global driver($driver)
+      #
+      # ```ruby
+      # action = zoom 200 #=> Zoom in the screen from the center until it doubles in size.
+      # ```
+      #
+      # Without auto_perform
+      #
+      # ```ruby
+      # action = zoom 200, false #=> Zoom in the screen from the center until it doubles in size.
+      # action.perform    #=> to 25% of its size.
+      # ```
+      #
+      # With driver
+      #
+      # ```ruby
+      # driver =  Appium::Driver.new(opts, false).start_driver
+      # pinch 200, true, driver #=> Zoom in the screen from the center until it doubles in size.
+      # ```
+      def zoom(percentage = 200, auto_perform = true, driver = $driver)
+        ::Appium::Core::MultiTouch.zoom percentage: percentage, auto_perform: auto_perform, driver: driver
+      end
+    end # self
+
+    def initialize(driver = $driver)
+      super driver
+    end
+  end # class MultiTouch
+end # module Appium