appium_lib 9.7.2 → 9.7.3

data/lib/appium_lib/core/driver.rb

@@ -10,6 +10,7 @@ module Appium
       attr_reader :http_client
 
       # Device type to request from the appium server
+      # @return [Symbol] :android and :ios, for example
       attr_reader :device
 
       # Automation name sent to appium server or received from server
@@ -24,6 +25,8 @@ module Appium
       # Export session id to textfile in /tmp for 3rd party tools
       # @return [Boolean]
       attr_reader :export_session
+      # @return [String] By default, session id is exported in '/tmp/appium_lib_session'
+      attr_reader :export_session_path
 
       # Default wait time for elements to appear
       # Returns the default client side wait.
@@ -38,13 +41,13 @@ module Appium
       attr_reader :port
 
       # Return a time wait timeout
-      # Wait time for ::Appium::Common.wait or ::Appium::Common.wait_true.
+      # Wait time for ::Appium::Core::Base::Wait, wait and 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.
+      # Wait interval time for ::Appium::Core::Base::Wait, wait and wait_true
       # Provide Appium::Drive like { appium_lib: { wait_interval: 20 } }
       # @return [Integer]
       attr_reader :wait_interval
@@ -52,13 +55,9 @@ module Appium
       # instance of AbstractEventListener for logging support
       attr_reader :listener
 
-      private
-
       # @return [Appium::Core::Base::Driver]
       attr_reader :driver
 
-      public
-
       # @private
       # @see Appium::Core.for
       #
@@ -117,7 +116,8 @@ module Appium
       #                listener: nil,
       #              }
       #            }
-      #     @driver = Appium::Driver.new(opts).start_driver
+      #     @core = Appium::Driver.new(opts)
+      #     @driver = @core.start_driver
       #
       def start_driver(server_url: nil,
                        http_client_ops: { http_client: nil, open_timeout: 999_999, read_timeout: 999_999 })
@@ -141,7 +141,7 @@ module Appium
                                                      listener: @listener)
 
           # export session
-          write_session_id(@driver.session_id) if @export_session
+          write_session_id(@driver.session_id, @export_session_path) if @export_session
         rescue Errno::ECONNREFUSED
           raise "ERROR: Unable to connect to Appium. Is the server running on #{server_url}?"
         end
@@ -155,6 +155,11 @@ module Appium
 
       # Quits the driver
       # @return [void]
+      #
+      # @example
+      #
+      #   @core.quit_driver
+      #
       def quit_driver
         @driver.quit
       rescue
@@ -166,7 +171,7 @@ module Appium
       #
       # @example
       #
-      #   @driver.appium_server_version
+      #   @core.appium_server_version
       #     {
       #         "build" => {
       #             "version" => "0.18.1",
@@ -178,7 +183,7 @@ module Appium
       #
       # @example
       #
-      #   @driver.appium_server_version #=> {}
+      #   @core.appium_server_version #=> {}
       #
       def appium_server_version
         @driver.remote_status
@@ -193,7 +198,7 @@ module Appium
       #
       # @example
       #
-      #     @driver.platform_version #=> [10.1.1]
+      #     @core.platform_version #=> [10.1.1]
       #
       def platform_version
         p_version = @driver.capabilities['platformVersion']
@@ -207,15 +212,81 @@ module Appium
       #
       # @example
       #
-      #   @driver.screenshot '/tmp/hi.png' #=> nil
+      #   @core.screenshot '/tmp/hi.png' #=> nil
+      #   # same as `@driver.save_screenshot png_save_path`
       #
       def screenshot(png_save_path)
         @driver.save_screenshot png_save_path
         nil
       end
 
+      # Check every interval seconds to see if yield returns a truthy value.
+      # Note this isn't a strict boolean true, any truthy value is accepted.
+      # false and nil are considered failures.
+      # Give up after timeout seconds.
+      #
+      # Wait code from the selenium Ruby gem
+      # https://github.com/SeleniumHQ/selenium/blob/cf501dda3f0ed12233de51ce8170c0e8090f0c20/rb/lib/selenium/webdriver/common/wait.rb
+      #
+      # If only a number is provided then it's treated as the timeout value.
+      #
+      # @param [Hash] opts Options
+      # @option opts [Numeric] :timeout Seconds to wait before timing out. Set default by `appium_wait_timeout` (30).
+      # @option opts [Numeric] :interval Seconds to sleep between polls. Set default by `appium_wait_interval` (0.5).
+      # @option opts [String] :message Exception message if timed out.
+      # @option opts [Array, Exception] :ignore Exceptions to ignore while polling (default: Exception)
+      #
+      # @example
+      #
+      #   @core.wait_true { @driver.find_element :accessibility_id, 'something' }
+      #
+      def wait_true(opts = {})
+        opts = process_wait_opts(opts).merge(return_if_true: true)
+
+        opts[:timeout]  ||= @wait_timeout
+        opts[:interval] ||= @wait_interval
+
+        wait = ::Appium::Core::Base::Wait.new opts
+        wait.until { yield }
+      end
+
+      # Check every interval seconds to see if yield doesn't raise an exception.
+      # Give up after timeout seconds.
+      #
+      # Wait code from the selenium Ruby gem
+      # https://github.com/SeleniumHQ/selenium/blob/cf501dda3f0ed12233de51ce8170c0e8090f0c20/rb/lib/selenium/webdriver/common/wait.rb
+      #
+      # If only a number is provided then it's treated as the timeout value.
+      #
+      # @param [Hash] opts Options
+      # @option opts [Numeric] :timeout Seconds to wait before timing out. Set default by `appium_wait_timeout` (30).
+      # @option opts [Numeric] :interval Seconds to sleep between polls. Set default by `appium_wait_interval` (0.5).
+      # @option opts [String] :message Exception message if timed out.
+      # @option opts [Array, Exception] :ignore Exceptions to ignore while polling (default: Exception)
+      #
+      # @example
+      #
+      #   @core.wait_true { @driver.find_element :accessibility_id, 'something' }
+      #
+      def wait(opts = {})
+        opts = process_wait_opts(opts).merge(return_if_true: false)
+
+        opts[:timeout]  ||= @wait_timeout
+        opts[:interval] ||= @wait_interval
+
+        wait = ::Appium::Core::Base::Wait.new opts
+        wait.until { yield }
+      end
+
       private
 
+      # @private
+      def process_wait_opts(opts)
+        opts = { timeout: opts } if opts.is_a?(Numeric)
+        raise 'opts must be a hash' unless opts.is_a? Hash
+        opts
+      end
+
       # @private
       def extend_for(device:, automation_name:, target:)
         target.extend Appium::Core
@@ -224,6 +295,8 @@ module Appium
         case device
         when :android
           case automation_name
+          when :espresso
+            ::Appium::Core::Android::Espresso::Bridge.for(self)
           when :uiautomator2
             ::Appium::Core::Android::Uiautomator2::Bridge.for(self)
           else # default and UiAutomator
@@ -291,9 +364,12 @@ module Appium
 
       # @private
       def set_appium_lib_specific_values(appium_lib_opts)
-        @custom_url       = appium_lib_opts.fetch :server_url, false
-        @export_session   = appium_lib_opts.fetch :export_session, false
-        @default_wait     = appium_lib_opts.fetch :wait, 0
+        @custom_url          = appium_lib_opts.fetch :server_url, false
+        @default_wait        = appium_lib_opts.fetch :wait, 0
+
+        # bump current session id into a particular file
+        @export_session      = appium_lib_opts.fetch :export_session, false
+        @export_session_path = appium_lib_opts.fetch :export_session_path, '/tmp/appium_lib_session'
 
         @port      = appium_lib_opts.fetch :port, 4723
 
@@ -330,8 +406,8 @@ module Appium
       end
 
       # @private
-      def write_session_id(session_id)
-        File.open('/tmp/appium_lib_session', 'w') { |f| f.puts session_id }
+      def write_session_id(session_id, export_path = '/tmp/appium_lib_session')
+        File.open(export_path, 'w') { |f| f.puts session_id }
       rescue IOError => e
         ::Appium::Logger.warn e
         nil

data/lib/appium_lib/core/ios.rb

@@ -1,6 +1,7 @@
 # loaded in common/driver.rb
 require_relative 'ios/search_context'
 require_relative 'ios/device'
+require_relative 'ios/touch'
 
 require_relative 'ios/uiautomation/patch'
 require_relative 'ios/uiautomation/bridge'

data/lib/appium_lib/core/ios/touch.rb

@@ -0,0 +1,16 @@
+module Appium
+  module Core
+    module Ios
+      module Touch
+        def self.extend_touch_actions
+          ::Appium::Core::TouchAction.class_eval do
+            def swipe_coordinates(start_x: 0, start_y: 0, offset_x: 0, offset_y: 0)
+              Appium::Logger.info "start_x: #{start_x}, start_y: #{start_y}, offset_x: #{offset_x}, offset_y: #{offset_y}"
+              { offset_x: offset_x, offset_y: offset_y }
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/appium_lib/core/ios/uiautomation/bridge.rb

@@ -10,6 +10,8 @@ module Appium
             target.extend Appium::Ios::Device
 
             Core::Ios::Uiautomation.patch_webdriver_element
+
+            Core::Ios::Touch.extend_touch_actions
           end
         end
       end

data/lib/appium_lib/core/ios/xcuitest/bridge.rb

@@ -10,6 +10,8 @@ module Appium
             Core::Ios::Xcuitest::SearchContext.extend
             target.extend Appium::Ios::Device
             target.extend Appium::Ios::Xcuitest::Device
+
+            Core::Ios::Touch.extend_touch_actions
           end
         end
       end

data/lib/appium_lib/core/ios/xcuitest/search_context.rb

@@ -7,18 +7,29 @@ module Appium
           #   Only for XCUITest(WebDriverAgent)
           #   find_element/s can be used with a [class chain]( https://github.com/facebook/WebDriverAgent/wiki/Queries)
           #
-          #   ```ruby
-          #    # select the third child button of the first child window element
-          #    find_elements :class_chain, 'XCUIElementTypeWindow/XCUIElementTypeButton[3]'
-          #    # select all the children windows
-          #    find_elements :class_chain, 'XCUIElementTypeWindow'
-          #    # select the second last child of the second child window
-          #    find_elements :class_chain, 'XCUIElementTypeWindow[2]/XCUIElementTypeAny[-2]'
-          #    # matching predicate. <code>`</code> is the mark.
-          #    find_elements :class_chain, 'XCUIElementTypeWindow[`visible = 1][`name = \"bla\"`]'
-          #    # containing predicate. `$` is the mark.
-          #    find_elements :class_chain, 'XCUIElementTypeWindow[$name = \"bla$$$bla\"$]'
-          #   ```
+          # @example
+          #
+          #   # select the third child button of the first child window element
+          #   find_elements :class_chain, 'XCUIElementTypeWindow/XCUIElementTypeButton[3]'
+          #
+          #   # select all the children windows
+          #   find_elements :class_chain, 'XCUIElementTypeWindow'
+          #
+          #   # select the second last child of the second child window
+          #   find_elements :class_chain, 'XCUIElementTypeWindow[2]/XCUIElementTypeAny[-2]'
+          #
+          #   # matching predicate. <code>`</code> is the mark.
+          #   find_elements :class_chain, 'XCUIElementTypeWindow[`visible = 1][`name = \"bla\"`]'
+          #
+          #   # containing predicate. `$` is the mark.
+          #   # Require appium-xcuitest-driver 2.54.0+
+          #   # PR: https://github.com/facebook/WebDriverAgent/pull/707/files
+          #   find_elements :class_chain, 'XCUIElementTypeWindow[$name = \"bla$$$bla\"$]'
+          #   e = find_element :class_chain, "**/XCUIElementTypeWindow[$name == 'Buttons'$]"
+          #   e.tag_name #=> "XCUIElementTypeWindow"
+          #   e = find_element :class_chain, "**/XCUIElementTypeStaticText[$name == 'Buttons'$]"
+          #   e.tag_name #=> "XCUIElementTypeStaticText"
+          #
           def self.extend
             ::Appium::Core::Base::SearchContext.add_finders(class_chain: '-ios class chain')
           end

data/lib/appium_lib/core/ios_xcuitest.rb

@@ -1,6 +1,7 @@
 # loaded in common/driver.rb
 require_relative 'ios/search_context'
 require_relative 'ios/device'
+require_relative 'ios/touch'
 
 require_relative 'ios/xcuitest/search_context'
 require_relative 'ios/xcuitest/device'

data/lib/appium_lib/driver.rb

@@ -39,6 +39,7 @@ module Appium
     attr_reader :caps
     attr_reader :custom_url
     attr_reader :export_session
+    attr_reader :export_session_path
     attr_reader :default_wait
     attr_reader :appium_port
     attr_reader :appium_device
@@ -129,6 +130,7 @@ module Appium
       @caps = @core.caps
       @custom_url = @core.custom_url
       @export_session = @core.export_session
+      @export_session_path = @core.export_session_path
       @default_wait = @core.default_wait
       @appium_port = @core.port
       @appium_wait_timeout = @core.wait_timeout
@@ -214,20 +216,21 @@ module Appium
     # Returns a hash of the driver attributes
     def driver_attributes
       {
-          caps:             @core.caps,
-          automation_name:  @core.automation_name,
-          custom_url:       @core.custom_url,
-          export_session:   @core.export_session,
-          default_wait:     @core.default_wait,
-          sauce_username:   @sauce.username,
-          sauce_access_key: @sauce.access_key,
-          sauce_endpoint:   @sauce.endpoint,
-          port:             @core.port,
-          device:           @core.device,
-          debug:            @appium_debug,
-          listener:         @listener,
-          wait_timeout:     @core.wait_timeout,
-          wait_interval:    @core.wait_interval
+          caps:                @core.caps,
+          automation_name:     @core.automation_name,
+          custom_url:          @core.custom_url,
+          export_session:      @core.export_session,
+          export_session_path: @core.export_session_path,
+          default_wait:        @core.default_wait,
+          sauce_username:      @sauce.username,
+          sauce_access_key:    @sauce.access_key,
+          sauce_endpoint:      @sauce.endpoint,
+          port:                @core.port,
+          device:              @core.device,
+          debug:               @appium_debug,
+          listener:            @listener,
+          wait_timeout:        @core.wait_timeout,
+          wait_interval:       @core.wait_interval
       }
     end
 
@@ -431,7 +434,7 @@ module Appium
     # @return [Selenium::WebDriver] the new global driver
     def start_driver(http_client_ops =
                          { http_client: ::Appium::Http::Default.new, open_timeout: 999_999, read_timeout: 999_999 })
-      driver_quit
+      @core.quit_driver
 
       # If automationName is set only in server side, then the following automation_name should be nil before
       # starting driver.

data/lib/appium_lib/ios/xcuitest/bridge.rb

@@ -9,6 +9,7 @@ module Appium
           target.extend Appium::Ios::Device
           target.extend Appium::Ios::Xcuitest
           target.extend Appium::Ios::Xcuitest::Command
+          target.extend Appium::Ios::Xcuitest::Source
           target.extend Appium::Ios::Xcuitest::Helper
           target.extend Appium::Ios::Xcuitest::Gesture
           target.extend Appium::Ios::Xcuitest::Element

data/lib/appium_lib/ios/xcuitest/command.rb

@@ -1,5 +1,6 @@
 require_relative 'command/pasteboard'
 require_relative 'command/gestures'
+require_relative 'command/source'
 
 module Appium
   module Ios

data/lib/appium_lib/ios/xcuitest/command/source.rb

@@ -0,0 +1,20 @@
+module Appium
+  module Ios
+    module Xcuitest
+      module Source
+        # @param [String|Symbol] format :xml or :json. :xml is by default.
+        # @option opts [Element] :element Element to swipe on
+        #
+        #   ```ruby
+        #   xcuitest_source format: :json
+        #   ```
+        def xcuitest_source(format: :xml)
+          format = format.to_s if format.is_a? Symbol
+          args = { format: format }
+
+          @driver.execute_script 'mobile: source', args
+        end
+      end # module Gesture
+    end # module Xcuitest
+  end # module Ios
+end # module Appium

data/lib/appium_lib/version.rb

@@ -1,5 +1,5 @@
 module Appium
   # Version and Date are defined on the 'Appium' module, not 'Appium::Common'
-  VERSION = '9.7.2'.freeze unless defined? ::Appium::VERSION
-  DATE    = '2017-10-07'.freeze unless defined? ::Appium::DATE
+  VERSION = '9.7.3'.freeze unless defined? ::Appium::VERSION
+  DATE    = '2017-10-21'.freeze unless defined? ::Appium::DATE
 end

data/readme.md

@@ -11,36 +11,34 @@
 - [appium_lib on RubyGems](https://rubygems.org/gems/appium_lib)
 - [Documentation for appium_lib](https://github.com/appium/ruby_lib/tree/master/docs)
 - [Appium Ruby Console](https://github.com/appium/ruby_console)
-- [Bootcamp quick start guide](http://sauceio.com/index.php/tag/appium-bootcamp/) & [Bootcamp example source](https://github.com/tourdedave/appium-getting-started-code-exampes)
-- [Mobile automation walkthrough with Ruby and Sauce](http://stackshare.io/sauce-labs/mobile-automation-with-appium-and-sauce-labs) & [code examples](https://github.com/jlipps/appium-ruby-example)
+- [Getting Started](https://github.com/appium/appium/blob/master/docs/en/about-appium/getting-started.md)
+- [code examples](https://github.com/appium/sample-code/tree/master/sample-code/examples/ruby)
 
 Helper methods for writing cross platform (iOS, Android) tests in Ruby using Appium. Note that user waits should not exceed 120 seconds if they're going to run on Sauce Labs.
 
 Make sure you're using Appium 1.0.0 or newer and Ruby 2.2+ with upgraded rubygems and bundler.
 
-XCUITest for iOS requires `Appium 1.6.0+`. `appium_lib9.1.0+` requires `selenium-webdriver3.0.2+`.(`appium_lib9.0.0` or less requires `selenium-webdriver2.x`)
-
 #### Start appium server
 
-`node .`
+```bash
+$ npm install -g appium
+$ appium
+```
 
 #### Install / Upgrade
-
-Update rubygems and bundler.
-
-```ruby
-gem update --system ;\
-gem update bundler
+- Update rubygems and bundler
+```bash
+$ gem update --system
+$ gem update bundler
 ```
 
-Install the latest gem release.
-
-```ruby
-gem uninstall -aIx appium_lib ;\
+- Install the latest gem release
+```bash
+gem uninstall -aIx appium_lib
 gem install --no-rdoc --no-ri appium_lib
 ```
 
-#### Sauce Labs env vars
+#### [Sauce Labs env vars](https://github.com/appium/ruby_lib/blob/master/lib/appium_lib/sauce_labs.rb)
 
 - `SAUCE_USERNAME` Sauce username
 - `SAUCE_ACCESS_KEY` Sauce API key
@@ -48,11 +46,6 @@ gem install --no-rdoc --no-ri appium_lib
 
 (Note: If these variables are set, all tests will use Sauce Labs unless over-ridden in configuration.)
 
-#### Troubleshooting
-
-1. Does `adb kill-server; adb devices` list an active Android device?
-3. Are you running appium from source? `node .`
-
 #### Documentation
 
 - [Installing Appium on OS X](https://github.com/appium/ruby_console/blob/master/osx.md)
@@ -62,13 +55,5 @@ gem install --no-rdoc --no-ri appium_lib
     - [Tips for XCUITest for iOS](https://github.com/appium/ruby_lib/blob/master/docs/ios_xcuitest.md)
 - [Appium Server docs](https://github.com/appium/appium/tree/master/docs)
 
-#### Logging
-
-[Log level](https://github.com/appium/ruby_lib/blob/1673a694121d2ae24ffd1530eb71b7015d44dc52/lib/appium_lib/logger.rb) can be adjusted. The default level is `Logger::WARN`
-
-```ruby
-Appium::Logger.level = Logger::INFO
-```
-
 #### Load Pry
 `Pry.config.pager = false` is set if you have no `.pryrc` files and `Pry` is defined.