appium_lib 1.0.0 → 2.0.0

data/lib/appium_lib/device/multi_touch.rb

@@ -74,7 +74,7 @@ module Appium
         zoom.perform
       end
     end
-    
+
     # Create a new multi-action
     def initialize
       @actions = []

data/lib/appium_lib/device/touch_actions.rb

@@ -9,20 +9,20 @@ module Appium
   # action = TouchAction.new.press(x: 45, y: 100).wait(5).release
   # action.perform
   class TouchAction
-    ACTIONS = [:move_to, :press_for_duration, :press, :release, :tap, :wait, :perform]
+    ACTIONS         = [:move_to, :long_press, :press, :release, :tap, :wait, :perform]
     COMPLEX_ACTIONS = [:swipe]
-    
+
     class << self
       COMPLEX_ACTIONS.each do |action|
         define_method(action) do |opts|
-          auto_perform = opts.delete(:auto_perform) {|k| true}
-          ta = TouchAction.new
+          auto_perform = opts.delete(:auto_perform) { |k| true }
+          ta           = TouchAction.new
           ta.send(action, opts)
           return ta unless auto_perform
           ta.perform
         end
       end
-    end  
+    end
 
     attr_reader :actions
 
@@ -40,13 +40,14 @@ module Appium
     end
 
     # Press down for a specific duration.
-    # @param element [WebDriver::Element] the element to press.
-    # @param x [integer] x co-ordinate to press on.
-    # @param y [integer] y co-ordinate to press on.
-    # @param duration [integer] Number of seconds to press.
-    def press_for_duration(element, x, y, duration)
-      @actions << {element: element.ref, x: x, y: y, duration: duration}
-      chain_method(:longPress, args)
+    # @option element [WebDriver::Element] the element to press.
+    # @option x [integer] x co-ordinate to press on.
+    # @option y [integer] y co-ordinate to press on.
+    # @option duration [integer] Number of milliseconds to press.
+    def long_press(opts)
+      args = opts.select { |k, v| [:element, :x, :y, :duration].include? k }
+      args = args_with_ele_ref(args)
+      chain_method(:longPress, args) # longPress is what the appium server expects
     end
 
     # Press a finger onto the screen.  Finger will stay down until you call
@@ -56,7 +57,7 @@ module Appium
     # @option opts [integer] :x x co-ordinate to press on
     # @option opts [integer] :y y co-ordinate to press on
     def press(opts)
-      args = opts.select {|k, v| [:element, :x, :y].include? k}
+      args = opts.select { |k, v| [:element, :x, :y].include? k }
       args = args_with_ele_ref(args)
       chain_method(:press, args)
     end
@@ -78,15 +79,16 @@ module Appium
     # @option opts [integer] :y y co-ordinate to tap
     # @option opts [integer] :fingers how many fingers to tap with (Default 1)
     def tap(opts)
-      opts[:count] = opts.delete(:fingers) if opts[:fingers]
-      opts_with_defaults = {count: 1}.merge opts
-      chain_method(:tap, opts_with_defaults)
+      opts[:count]       = opts.delete(:fingers) if opts[:fingers]
+      opts_with_defaults = { count: 1 }.merge opts
+      args               = args_with_ele_ref opts
+      chain_method(:tap, args)
     end
 
-    # Pause for a number of seconds before the next action
-    # @param seconds [integer] Number of seconds to pause for
-    def wait(seconds)
-      args = {ms: seconds}
+    # Pause for a number of milliseconds before the next action
+    # @param milliseconds [integer] Number of milliseconds to pause for
+    def wait(milliseconds)
+      args = { ms: milliseconds }
       chain_method(:wait, args)
     end
 
@@ -95,12 +97,12 @@ module Appium
     # @option opts [int] :start_y Where to start swiping, on the y axis.  Default 0.
     # @option opts [int] :end_x Where to end swiping, on the x axis.  Default 0.
     # @option opts [int] :end_y Where to end swiping, on the y axis.  Default 0.
-    # @option opts [int] :duration How long the actual swipe takes to complete.
+    # @option opts [int] :duration How long the actual swipe takes to complete in milliseconds.
     def swipe(opts)
-      start_x = opts.fetch :start_x, 0
-      start_y = opts.fetch :start_y, 0
-      end_x = opts.fetch :end_x, 0
-      end_y = opts.fetch :end_y, 0
+      start_x  = opts.fetch :start_x, 0
+      start_y  = opts.fetch :start_y, 0
+      end_x    = opts.fetch :end_x, 0
+      end_y    = opts.fetch :end_y, 0
       duration = opts[:duration]
 
       self.press x: start_x, y: start_y
@@ -118,7 +120,7 @@ module Appium
 
     # Does nothing, currently.
     def cancel
-      @actions << {action: cancel}
+      @actions << { action: cancel }
       $driver.touch_actions @actions
       self
     end
@@ -127,9 +129,9 @@ module Appium
 
     def chain_method(method, args=nil)
       if args
-        @actions << {action: method, options: args}
+        @actions << { action: method, options: args }
       else
-        @actions << {action: method}
+        @actions << { action: method }
       end
       self
     end

data/lib/appium_lib/driver.rb

@@ -105,7 +105,7 @@ module Appium
       # ensure files are absolute
       r.map! do |file|
         file = File.exists?(file) ? file :
-            File.join(parent_dir, file)
+          File.join(parent_dir, file)
         file = File.expand_path file
 
         File.exists?(file) ? file : nil
@@ -162,7 +162,7 @@ module Appium
           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
+          const.method(m).arity == $driver.method(m).arity
       end
     end
   end
@@ -296,7 +296,7 @@ module Appium
         @@loaded = true
         # load device methods exactly once
         extend Appium::Device
-        
+
         # Promote only on Minitest::Spec (minitest 5) by default
         Appium.promote_appium_methods ::Minitest::Spec
       end

data/lib/appium_lib/ios/element/button.rb

@@ -13,10 +13,12 @@ module Appium
       xpath_visible_contains UIAButton, value
     end
 
-    # Find all UIAButtons containing value
+    # Find all UIAButtons containing value.
+    # If value is omitted, all UIAButtons are returned.
     # @param value [String] the value to search for
     # @return [Array<UIAButton>]
-    def buttons value
+    def buttons value=false
+      return tags UIAButton unless value
       xpaths_visible_contains UIAButton, value
     end
 
@@ -45,11 +47,5 @@ module Appium
     def buttons_exact value
       xpaths_visible_exact UIAButton, value
     end
-
-    # Find all UIAButtons.
-    # @return [Array<UIAButton>]
-    def e_buttons
-      tags UIAButton
-    end
   end # module Ios
 end # module Appium

data/lib/appium_lib/ios/element/text.rb

@@ -7,48 +7,44 @@ module Appium
     # @param value [String, Integer] the value to find.
     # If int then the UIAStaticText at that index is returned.
     # @return [UIAStaticText]
-    def s_text value
+    def text value
       return ele_index UIAStaticText, value if value.is_a? Numeric
       xpath_visible_contains UIAStaticText, value
     end
 
     # Find all UIAStaticText containing value.
+    # If value is omitted, all UIAStaticTexts are returned
     # @param value [String] the value to search for
     # @return [Array<UIAStaticText>]
-    def s_texts value
+    def texts value=false
+      return tags UIAStaticText unless value
       xpaths_visible_contains UIAStaticText, value
     end
 
     # Find the first UIAStaticText.
     # @return [UIAStaticText]
-    def first_s_text
+    def first_text
       first_ele UIAStaticText
     end
 
     # Find the last UIAStaticText.
     # @return [UIAStaticText]
-    def last_s_text
+    def last_text
       last_ele UIAStaticText
     end
 
     # Find the first UIAStaticText that exactly matches value.
     # @param value [String] the value to match exactly
     # @return [UIAStaticText]
-    def s_text_exact value
+    def text_exact value
       xpath_visible_exact UIAStaticText, value
     end
 
     # Find all UIAStaticTexts that exactly match value.
     # @param value [String] the value to match exactly
     # @return [Array<UIAStaticText>]
-    def s_texts_exact value
+    def texts_exact value
       xpaths_visible_exact UIAStaticText, value
     end
-
-    # Find all UIAStaticTexts.
-    # @return [Array<UIAStaticText>]
-    def e_s_texts
-      tags UIAStaticText
-    end
   end # module Ios
 end # module Appium

data/lib/appium_lib/ios/element/textfield.rb

@@ -49,9 +49,11 @@ module Appium
     end
 
     # Find all TextFields containing value.
+    # If value is omitted, all TextFields are returned.
     # @param value [String] the value to search for
     # @return [Array<TextField>]
-    def textfields value
+    def textfields value=false
+      return xpaths _textfield_visible_string unless value
       xpaths _textfield_contains_string value
     end
 
@@ -80,11 +82,5 @@ module Appium
     def textfields_exact value
       xpaths _textfield_exact_string value
     end
-
-    # Find all TextFields.
-    # @return [Array<TextField>]
-    def e_textfields
-      xpaths _textfield_visible_string
-    end
   end # module Ios
 end # module Appium

data/lib/appium_lib/ios/helper.rb

@@ -1,4 +1,4 @@
-module Appium
+module Appium
   module Ios
     # iOS only. On Android uiautomator always returns an empty string for EditText password.
     #
@@ -6,7 +6,7 @@
     # @param length [Integer] the length of the password to generate
     # @return [String] the returned string is of size length
     def ios_password length=1
-      '•' * length
+      8226.chr('UTF-8') * length
     end
 
     # Returns a string of interesting elements. iOS only.
@@ -14,10 +14,12 @@
     # Defaults to inspecting the 1st windows source only.
     # use get_page(get_source) for all window sources
     #
-    # @param element [Object] the element to search. omit to search everything
+    # @option element [Object] the element to search. omit to search everything
+    # @option class_name [String,Symbol] the class name to filter on. case insensitive include match.
     # @return [String]
     def get_page element=source_window(0), class_name=nil
       lazy_load_strings # populate @strings_xml
+      class_name = class_name.to_s.downcase
 
       # @private
       def empty ele
@@ -50,43 +52,54 @@
         type    = fix_space element['type']
 
         # if class_name is set, mark non-matches as invisible
-        visible = (type == class_name).to_s if class_name
-
-        if name == label && name == value
-          puts "#{type}" if name || label || value || hint
-          puts "   name, label, value: #{name}" if name
-          puts "   hint: #{hint}" if hint
-        elsif name == label
-          puts "#{type}" if name || label || value || hint
-          puts "   name, label: #{name}" if name
-          puts "   value: #{value}" if value
-          puts "   hint: #{hint}" if hint
-        elsif name == value
-          puts "#{type}" if name || label || value || hint
-          puts "   name, value: #{name}" if name
-          puts "  label: #{label}" if label
-          puts "   hint: #{hint}" if hint
-        else
-          puts "#{type}" if name || label || value || hint
-          puts "   name: #{name}" if name
-          puts "  label: #{label}" if label
-          puts "  value: #{value}" if value
-          puts "   hint: #{hint}" if hint
-        end if visible && visible == 'true'
-
-        # there may be many ids with the same value.
-        # output all exact matches.
-        id_matches = @strings_xml.select do |key, val|
-          val == name || val == label || val == value
-        end
+        visible = (type.downcase.include?(class_name)).to_s if class_name
+        if visible && visible == 'true'
+          if name == label && name == value
+            puts "#{type}" if name || label || value || hint
+            puts "   name, label, value: #{name}" if name
+            puts "   hint: #{hint}" if hint
+          elsif name == label
+            puts "#{type}" if name || label || value || hint
+            puts "   name, label: #{name}" if name
+            puts "   value: #{value}" if value
+            puts "   hint: #{hint}" if hint
+          elsif name == value
+            puts "#{type}" if name || label || value || hint
+            puts "   name, value: #{name}" if name
+            puts "  label: #{label}" if label
+            puts "   hint: #{hint}" if hint
+          else
+            puts "#{type}" if name || label || value || hint
+            puts "   name: #{name}" if name
+            puts "  label: #{label}" if label
+            puts "  value: #{value}" if value
+            puts "   hint: #{hint}" if hint
+          end
+
+          # there may be many ids with the same value.
+          # output all exact matches.
+          attributes = [name, label, value, hint].select { |attr| !attr.nil? }
+          partial    = {}
+          id_matches = @strings_xml.select do |key, val|
+            next if val.nil? || val.empty?
+            partial[key] = val if attributes.detect { |attr| attr.include?(val) }
+            attributes.detect { |attr| val == attr }
+          end
+
+          # If there are no exact matches, display partial matches.
+          id_matches = partial if id_matches.empty?
+
+          unless id_matches.empty?
+            match_str = ''
+            max_len   = id_matches.keys.max_by(&:length).length
 
-        if id_matches && id_matches.length > 0
-          match_str = ''
-          # [0] = key, [1] = value
-          id_matches.each do |match|
-            match_str += ' ' * 7 + "#{match[0]}\n"
+            # [0] = key, [1] = value
+            id_matches.each do |key, value|
+              arrow_space = ' ' * (max_len - key.length).to_i
+              match_str   += ' ' * 7 + "#{key} #{arrow_space}=> #{value}\n"
+            end
+            puts "   id: #{match_str.strip}\n"
           end
-          puts "   id: #{match_str.strip}\n"
         end
       end
 
@@ -96,10 +109,27 @@
     end
 
     # Prints a string of interesting elements to the console.
+    #
+    # Example
+    #
+    # ```ruby
+    # page class: :UIAButton # filter on buttons
+    # page window: 1 # show source for window 1
+    # page class: :UIAButton, window: 1
+    # ```
+    #
+    # @option window [Integer] window index. -1 for default
+    # @option class [Symbol] class name to filter on
+    #
     # @return [void]
     def page opts={}
-      window_number = opts.fetch :window, -1
-      class_name    = opts.fetch :class, nil
+      if opts.is_a?(Hash)
+        window_number = opts.fetch :window, -1
+        class_name    = opts.fetch :class, nil
+      else
+        window_number = -1
+        class_name    = opts
+      end
 
       if window_number == -1
         # if the 0th window has no children, find the next window that does.

data/readme.md

@@ -6,11 +6,11 @@
 
 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 Ruby 1.9.3+ with upgraded rubygems and bundler.
+Make sure you're using Appium 1.0.0 or newer and Ruby 1.9.3+ with upgraded rubygems and bundler.
 
 #### Start appium server
 
-`node server.js`
+`node .`
 
 #### Install / Upgrade
 
@@ -28,84 +28,20 @@ gem uninstall -aIx appium_lib ;\
 gem install --no-rdoc --no-ri appium_lib
 ```
 
-#### Simple Usage
-
-```ruby
-require 'rubygems'
-require 'appium_lib'
-
-# Start iOS driver
-
-# use appium's specific capability names
-appium_capabilities = { launchTimeout: 123 }
-# there are also built in capabilities such as device that don't require 'raw'
-caps = { device: :ios, app_path: '/Users/user/woven/ruby_lib_ios/UICatalog.app', raw: appium_capabilities }
-Appium::Driver.new(caps).start_driver
-
-# Start Android driver
-apk = { 
-        device: :android,
-        app_path: '/path/to/the.apk',
-        app_package: 'com.example.pkg',
-        app_activity: '.act.Start',
-        app_wait_activity: '.act.Start'
-      }
-Appium::Driver.new(apk).start_driver
-
-# Define the methods on all objects.
-# Note that this can also be scoped to limit the potential for conflicts.
-# Example: Appium.promote_appium_methods ::Minitest::Spec
-# Another alternative is to not promote at all. Instead access methods via $driver
-Appium.promote_appium_methods Object
-```
-
-```ruby
-# Example of automating Settings preinstalled app on Android
-# Find these values using arc then type current_app
-apk = { 
-        device: :android,
-        app_path: '',
-        app_package: 'com.android.settings',
-        app_activity: '.Settings',
-        app_wait_activity: '.Settings'
-      }
-Appium::Driver.new(apk).start_driver
-```
-
-#### Other capabilities
-
-- `no_reset` If true, the app will not be reset
-- `full_reset` If true, the app will be uninstalled. When false, fast reset is activated.
-
-#### iOS env vars
-
-- `APP_PATH` Path to the .app folder
-
-#### Android env vars
-
-- `APP_PATH` Path to the apk
-- `APP_PACKAGE` The APK's package
-- `APP_ACTIVITY` Activity to start
-- `APP_WAIT_ACTIVITY` Optional. Activity to wait for.
-
 #### Sauce Labs env vars
 
-- `APP_NAME` Name of the test run
 - `SAUCE_USERNAME` Sauce username
 - `SAUCE_ACCESS_KEY` Sauce API key
 
 #### Troubleshooting
 
 1. Does `adb kill-server; adb devices` list an active Android device?
-2. Have you defined the proper env vars? `APP_PATH, APP_PACKAGE, APP_ACTIVITY, APP_WAIT_ACTIVITY`
-3. Are you running appium from source? `node server.js`
+3. Are you running appium from source? `node .`
 
 #### Documentation
 
 - [Installing Appium on OS X](https://github.com/appium/ruby_console/blob/master/osx.md)
 - [Overview](https://github.com/appium/ruby_lib/blob/master/docs/docs.md) 
-- [Android methods](https://github.com/appium/ruby_lib/blob/master/docs/android_docs.md)
-- [iOS methods](https://github.com/appium/ruby_lib/blob/master/docs/ios_docs.md)
-- [Appium docs](https://github.com/appium/appium/tree/master/docs)
-- [Ruby iOS tests](https://github.com/appium/ruby_lib_ios)
-- [Ruby Android tests](https://github.com/appium/ruby_lib_android)
+- [Ruby Android methods](https://github.com/appium/ruby_lib/blob/master/docs/android_docs.md)
+- [Ruby iOS methods](https://github.com/appium/ruby_lib/blob/master/docs/ios_docs.md)
+- [Appium Server docs](https://github.com/appium/appium/tree/master/docs)