appium_lib 9.7.1 → 9.7.2

data/lib/appium_lib/appium.rb

@@ -75,6 +75,7 @@ module Appium
 
       data
     end
+    # @see load_settings
     alias load_appium_txt load_settings
 
     # @param [String] base_dir parent directory of loaded appium.txt (toml)
@@ -119,6 +120,9 @@ module Appium
     # 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.
+    #
+    # @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?
 
@@ -153,25 +157,27 @@ module Appium
     ##
     # Promote appium methods to class instance methods
     #
-    # @param class_array [Array<Class>] An array of classes
+    # @param [Array<Class>] class_array An array of classes
+    # @param [Driver] driver A driver to extend for
     #
     # To promote methods to all classes:
     #
-    # ```ruby
-    # Appium.promote_appium_methods Object
-    # ```
+    # @example
+    #
+    #   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
-    # ```
+    # @example
+    #
+    #   # promote on rspec
+    #   Appium.promote_appium_methods RSpec::Core::ExampleGroup
+    #
+    # @example
+    #
+    #   # promote on minispec
+    #   Appium.promote_appium_methods Minitest::Spec
     #
-    # ```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
@@ -198,5 +204,5 @@ module Appium
       end
       nil # return nil
     end
-  end
-end
+  end # class << self
+end # module Appium

data/lib/appium_lib/common/helper.rb

@@ -1,5 +1,4 @@
-# Generic helper methods not specific
-# to a particular tag name
+# Generic helper methods not specific to a particular tag name
 module Appium
   module Common
     # iOS .name returns the accessibility attribute if it's set. if not set, the string value is used.
@@ -26,6 +25,12 @@ module Appium
     end
 
     # For Sauce Labs reporting. Returns the current session id.
+    # @return [String]
+    #
+    # @example
+    #
+    #   @driver.session_id #=> "some-session-ids"
+    #
     def session_id
       @driver.session_id
     end
@@ -81,6 +86,14 @@ module Appium
     end # class CountElements
 
     # Returns a string of class counts of visible elements.
+    # @return [String]
+    #
+    # @example
+    #
+    #   get_page_class #=> "24x XCUIElementTypeStaticText\n12x XCUIElementTypeCell\n8x XCUIElementTypeOther\n
+    #                  #    2x XCUIElementTypeWindow\n1x XCUIElementTypeStatusBar\n1x XCUIElementTypeTable\n1
+    #                  #    x XCUIElementTypeNavigationBar\n1x XCUIElementTypeApplication"
+    #
     def get_page_class
       parser = @count_elements_parser ||= Nokogiri::XML::SAX::Parser.new(CountElements.new)
 
@@ -92,6 +105,20 @@ module Appium
 
     # Count all classes on screen and print to stdout.
     # Useful for appium_console.
+    # @return [nil]
+    #
+    # @example
+    #
+    #   page_class
+    #     # 24x XCUIElementTypeStaticText
+    #     # 12x XCUIElementTypeCell
+    #     # 8x XCUIElementTypeOther
+    #     # 2x XCUIElementTypeWindow
+    #     # 1x XCUIElementTypeStatusBar
+    #     # 1x XCUIElementTypeTable
+    #     # 1x XCUIElementTypeNavigationBar
+    #     # 1x XCUIElementTypeApplication
+    #
     def page_class
       puts get_page_class
       nil
@@ -99,9 +126,10 @@ module Appium
 
     # Converts pixel values to window relative values
     #
-    # ```ruby
-    # px_to_window_rel x: 50, y: 150
-    # ```
+    # @example
+    #
+    #   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)
       w = driver.window_size
       x = opts.fetch :x, 0
@@ -142,6 +170,7 @@ module Appium
       @strings_xml[id]
     end
 
+    # @private
     class HTMLElements < Nokogiri::XML::SAX::Document
       attr_reader :filter
 

data/lib/appium_lib/common/http_client.rb

@@ -4,6 +4,7 @@ require_relative '../version'
 module Appium
   module Http
     class Default < ::Appium::Core::Base::Http::Default
+      # Default HTTP client inherit Appium::Core::Base::Http::Default, but has different DEFAULT_HEADERS
       DEFAULT_HEADERS = { 'Accept' => CONTENT_TYPE, 'User-Agent' => "appium/ruby_lib/#{::Appium::VERSION}" }.freeze
     end
   end

data/lib/appium_lib/common/log.rb

@@ -4,6 +4,7 @@ module Appium
     # @return [[Selenium::WebDriver::LogEntry]] A list of logs data.
     #
     # @example
+    #
     #   @driver.get_log("syslog") #=> [[Selenium::WebDriver::LogEntry]]
     #   @driver.get_log(:syslog)  #=> [[Selenium::WebDriver::LogEntry]]
     #
@@ -14,7 +15,9 @@ module Appium
     # 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

data/lib/appium_lib/common/multi_touch.rb

@@ -6,25 +6,23 @@ module Appium
   # 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)
+  # @example
   #
-  # multi_touch_action = MultiTouch.new
-  # multi_touch_action.add action_1
-  # multi_touch_action.add action_2
-  # multi_touch_action.perform
-  # ```
+  #   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
   #
-  # ```
-  # # 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.
@@ -33,23 +31,23 @@ module Appium
       # @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
-      # ```
+      # @example
+      #
+      #   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.
-      # ```
+      # @example
+      #
+      #   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
-      # ```
+      # @example
+      #   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
@@ -60,23 +58,24 @@ module Appium
       # @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.
-      # ```
+      # @example
+      #
+      #   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.
-      # ```
+      # @example
+      #
+      #   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.
-      # ```
+      # @example
+      #
+      #   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

data/lib/appium_lib/common/touch_actions.rb

@@ -4,28 +4,31 @@ module Appium
   #
   # Each method returns the object itself, so calls can be chained.
   #
-  # ```ruby
-  # action = TouchAction.new.press(x: 45, y: 100).wait(5).release
-  # action.perform
-  # action = TouchAction.new.swipe(....)
-  # action.perform
-  # ```
+  # @example
+  #
+  #   action = TouchAction.new.press(x: 45, y: 100).wait(5).release
+  #   action.perform
+  #   action = TouchAction.new.swipe(....)
+  #   action.perform
   #
   # Or each methods can call without `TouchAction.new` as the following.
   # In this case, `perform` is called automatically.
-  # ```ruby
-  # # called `swipe(...).perform` in this method.
-  # swipe(start_x: 75, start_y: 500, offset_x: 75, offset_y: 20, duration: 500)
-  # ```
+  #
+  # @example
+  #
+  #   # called `swipe(...).perform` in this method.
+  #   swipe(start_x: 75, start_y: 500, offset_x: 75, offset_y: 20, duration: 500)
   #
   # If you'd like to perform the chain with an arbitrary driver:
-  # ```ruby
-  # driver =  Appium::Driver.new(opts, false).start_driver
-  # action = TouchAction.new.press(x: 45, y: 100).wait(5).release
-  # action.perform(@driver)
-  # action = TouchAction.new.swipe(....)
-  # action.perform(@driver)
-  # ```
+  #
+  # @example
+  #
+  #   driver =  Appium::Driver.new(opts, false).start_driver
+  #   action = TouchAction.new.press(x: 45, y: 100).wait(5).release
+  #   action.perform(@driver)
+  #   action = TouchAction.new.swipe(....)
+  #   action.perform(@driver)
+  #
   class TouchAction < ::Appium::Core::TouchAction
     COMPLEX_ACTIONS = ::Appium::Core::TouchAction::COMPLEX_ACTIONS
 

data/lib/appium_lib/core/common/error.rb

@@ -3,6 +3,11 @@ module Appium
     module Error
       class CoreError < StandardError; end
 
+      # Capability related errors
+      class NoCapabilityError < CoreError; end
+      class CapabilityStructureError < CoreError; end
+
+      # Appium related errors
       class NotSupportedAppiumServer < CoreError; end
       class NoSuchElementError < CoreError; end
 

data/lib/appium_lib/core/core.rb

@@ -31,6 +31,34 @@ module Appium
   end
 
   module Core
+    # Creates a new global driver and extend particular methods to `target`
+    # @param [Class] target Extend particular methods to this target.
+    # @param [Hash] opts A options include capabilities for the Appium Server and for the client.
+    #
+    # @example
+    #
+    #     require 'rubygems'
+    #     require 'appium_lib'
+    #
+    #     # Start iOS driver
+    #     opts = {
+    #              caps: {
+    #                platformName: :ios,
+    #                app: '/path/to/MyiOS.app'
+    #              },
+    #              appium_lib: {
+    #                server_url: "http://custom-host:8080/wd/hub.com",
+    #                export_session: false,
+    #                port: 8080,
+    #                wait: 0,
+    #                wait_timeout: 20,
+    #                wait_interval: 0.3,
+    #                listener: nil,
+    #              }
+    #            }
+    #     @core_driver = Appium::Core.for(self, opts) # create a core driver with `opts` and extend methods into `self`
+    #     @core_driver.start_driver(server_url: server_url, http_client_ops: http_client_ops) # start driver
+    #
     def self.for(*args)
       Core::Driver.for(*args)
     end

data/lib/appium_lib/core/driver.rb

@@ -2,36 +2,53 @@ module Appium
   module Core
     class Driver
       # Selenium webdriver capabilities
+      # @return [Core::Base::Capabilities]
       attr_reader :caps
-      # Custom URL for the selenium server
+
+      # Return http client called in start_driver()
+      # @return [Appium::Core::Base::Http::Default] the http client
+      attr_reader :http_client
+
+      # Device type to request from the appium server
+      attr_reader :device
+
+      # Automation name sent to appium server or received from server
+      # If automation_name is nil, it is not set both client side and server side.
+      # @return [Hash]
+      attr_reader :automation_name
+
+      # Custom URL for the selenium server. If set this attribute, ruby_lib try to handshake to the custom url.
+      # @return [String]
       attr_reader :custom_url
+
       # Export session id to textfile in /tmp for 3rd party tools
+      # @return [Boolean]
       attr_reader :export_session
+
       # Default wait time for elements to appear
       # Returns the default client side wait.
       # This value is independent of what the server is using
+      # Provide Appium::Drive like { appium_lib: { wait: 20 } }
       # @return [Integer]
       attr_reader :default_wait
+
       # Appium's server port
+      # Provide Appium::Drive like { appium_lib: { port: 8080 } }
+      # @return [Integer]
       attr_reader :port
-      # Device type to request from the appium server
-      attr_reader :device
-      # Automation name sent to appium server or received from server
-      # If automation_name is nil, it is not set both client side and server side.
-      attr_reader :automation_name
+
       # Return a time wait timeout
       # Wait time for ::Appium::Common.wait or ::Appium::Common.wait_true.
       # Provide Appium::Drive like { appium_lib: { wait_timeout: 20 } }
       # @return [Integer]
       attr_reader :wait_timeout
+
       # Return a time wait timeout
       # Wait interval time for ::Appium::Common.wait or ::Appium::Common.wait_true.
       # Provide Appium::Drive like { appium_lib: { wait_interval: 20 } }
       # @return [Integer]
       attr_reader :wait_interval
-      # Return http client called in start_driver()
-      # @return [Appium::Core::Base::Http::Default] the http client
-      attr_reader :http_client
+
       # instance of AbstractEventListener for logging support
       attr_reader :listener
 
@@ -54,6 +71,8 @@ module Appium
       # @private
       def initialize(target, opts = {})
         opts = Appium.symbolize_keys opts
+        validate_keys(opts)
+
         @caps = get_caps(opts)
 
         set_appium_lib_specific_values(get_appium_lib_opts(opts))
@@ -69,8 +88,14 @@ module Appium
       # Creates a new global driver and quits the old one if it exists.
       # You can customise http_client as the following
       #
+      # @param [String] server_url Custom server url to send to requests. Default is "http://127.0.0.1:4723/wd/hub".
+      # @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
+      #
       # @example
-      #     ```ruby
+      #
       #     require 'rubygems'
       #     require 'appium_lib'
       #
@@ -83,17 +108,20 @@ module Appium
       #                app: '/path/to/MyiOS.app'
       #              },
       #              appium_lib: {
-      #                wait_timeout: 30
+      #                server_url: "http://custom-host:8080/wd/hub.com",
+      #                export_session: false,
+      #                port: 8080,
+      #                wait: 0,
+      #                wait_timeout: 20,
+      #                wait_interval: 0.3,
+      #                listener: nil,
       #              }
       #            }
-      #     Appium::Driver.new(opts).start_driver
+      #     @driver = Appium::Driver.new(opts).start_driver
       #
-      # @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
-      def start_driver(server_url:,
+      def start_driver(server_url: nil,
                        http_client_ops: { http_client: nil, open_timeout: 999_999, read_timeout: 999_999 })
+        server_url = server_url ? server_url : "http://127.0.0.1:#{@port}/wd/hub"
 
         # open_timeout and read_timeout are explicit wait.
         open_timeout = http_client_ops.delete(:open_timeout)
@@ -134,23 +162,24 @@ module Appium
       end
 
       # Returns the server's version info
+      # @return [Hash]
       #
-      # ```ruby
-      # {
-      #     "build" => {
-      #         "version" => "0.18.1",
-      #         "revision" => "d242ebcfd92046a974347ccc3a28f0e898595198"
+      # @example
+      #
+      #   @driver.appium_server_version
+      #     {
+      #         "build" => {
+      #             "version" => "0.18.1",
+      #             "revision" => "d242ebcfd92046a974347ccc3a28f0e898595198"
+      #         }
       #     }
-      # }
-      # ```
       #
       # Returns blank hash for Selenium Grid since `remote_status` gets 500 error
       #
-      # ```ruby
-      # {}
-      # ```
+      # @example
+      #
+      #   @driver.appium_server_version #=> {}
       #
-      # @return [Hash]
       def appium_server_version
         @driver.remote_status
       rescue Selenium::WebDriver::Error::ServerError => e
@@ -161,6 +190,11 @@ module Appium
 
       # Return the platform version as an array of integers
       # @return [Array<Integer>]
+      #
+      # @example
+      #
+      #     @driver.platform_version #=> [10.1.1]
+      #
       def platform_version
         p_version = @driver.capabilities['platformVersion']
         p_version.split('.').map(&:to_i)
@@ -168,10 +202,13 @@ module Appium
 
       # Takes a png screenshot and saves to the target path.
       #
-      # Example: screenshot '/tmp/hi.png'
-      #
       # @param png_save_path [String] the full path to save the png
       # @return [nil]
+      #
+      # @example
+      #
+      #   @driver.screenshot '/tmp/hi.png' #=> nil
+      #
       def screenshot(png_save_path)
         @driver.save_screenshot png_save_path
         nil
@@ -212,6 +249,28 @@ module Appium
         target
       end
 
+      # @private
+      def validate_keys(opts)
+        flatten_ops = flatten_hash_keys(opts)
+
+        raise Error::NoCapabilityError unless opts.member?(:caps)
+        if !opts.member?(:appium_lib) && flatten_ops.member?(:appium_lib)
+          raise Error::CapabilityStructureError, 'Please check the value of appium_lib in the capability'
+        end
+
+        true
+      end
+
+      # @private
+      def flatten_hash_keys(hash, flatten_keys_result = [])
+        hash.each do |key, value|
+          flatten_keys_result << key
+          flatten_hash_keys(value, flatten_keys_result) if value.is_a?(Hash)
+        end
+
+        flatten_keys_result
+      end
+
       # @private
       def get_caps(opts)
         Core::Base::Capabilities.create_capabilities(opts[:caps] || {})
@@ -269,6 +328,14 @@ module Appium
         return unless @automation_name.nil?
         @automation_name = @driver.capabilities['automationName']
       end
-    end
-  end
+
+      # @private
+      def write_session_id(session_id)
+        File.open('/tmp/appium_lib_session', 'w') { |f| f.puts session_id }
+      rescue IOError => e
+        ::Appium::Logger.warn e
+        nil
+      end
+    end # class Driver
+  end # module Core
 end # module Appium