appium_lib 0.3.16 → 0.4.0

data/docs_gen/docs_from_js.md

@@ -0,0 +1,44 @@
+Automatically convert yard's HTML output to Markdown. Run in Chrome Dev Tools console.
+
+```javascript
+// http://localhost:8808/docs/toplevel
+
+var methods = $x('//*[@id="content"]/ul/li');
+
+var sig = function(method) { return method.children[0].children[0].textContent.trim().substr(2); };
+var desc = function(method) { return method.children[1].children[0].textContent.trim(); };
+
+// All element methods must include the element name.
+// Check textfield before text because text is included in textfield.
+var elements = [ 'alert', 'button', 'textfield', 'text', 'window' ];
+var output = {};
+
+for (var b = 0; b < elements.length; b++) {
+  output[elements[b]] = [];
+}
+
+for (var a = 0; a < methods.length; a++) {
+  var name = sig(methods[a]);
+  var text = desc(methods[a]);
+  var index = '';
+
+  for (var b = 0; b < elements.length; b++) {
+    if (name.indexOf(elements[b]) !== -1 && name.indexOf('find_ele') === -1) {
+      index = elements[b];
+      break;
+    }
+  }
+
+  if (index === '') { continue; }
+  output[index].push( [name, text] );
+}
+
+for (var b = 0; b < elements.length; b++) {
+  var eles = output[elements[b]];
+  console.log("\n" + '#### ' + elements[b]);
+  for (var c = 0; c < eles.length; c++) {
+    var ele = eles[c];
+    console.log('0. `' + ele[0] + '` ' + ele[1]);
+  }
+}
+```

data/docs_gen/make_docs.rb

@@ -0,0 +1,81 @@
+# encoding: utf-8
+
+require 'rubygems'
+require 'yard'
+
+def space amount
+ ' ' * amount
+end
+
+def last_sha
+  `git rev-parse --verify HEAD`.strip
+end
+
+def mobj_to_md obj
+  out = ''
+  # skip objects without method signatures
+  sig = obj.signature
+  return out unless sig
+
+  # skip class vars
+  if sig.start_with?('@@') ||
+     # skip methods marked private
+     obj.tag('private') ||
+     # skip date and version from version.rb
+     obj.name.match(/DATE|VERSION/)
+     return out 
+  end
+
+  method_path = obj.file.split('/lib/').last
+  os = method_path.downcase.match /ios|android/
+  out += "##### [#{obj.name.to_s}](https://github.com/appium/ruby_lib/blob/#{last_sha}/lib/#{method_path}#L#{obj.line}) #{os}\n\n"
+  out += "> #{obj.signature}\n\n"
+  out += "#{obj.docstring}\n\n"
+
+
+  indent = space 5
+  params = obj.tags.select { |tag| tag.tag_name == 'param' }
+  if !params.empty?
+    out += "__Parameters:__\n\n"
+    params.each do |param|
+      out += indent + "[#{param.types.join ', '}] "
+      out += "#{param.name} - #{param.text}\n\n"
+    end
+  end
+
+  ret = obj.tag 'return'
+  if ret
+    out += "__Returns:__\n\n"
+    out += indent + "[#{ret.types.join ', '}] #{ret.text}\n\n"
+  end
+  out += "--\n\n"
+
+  out
+end
+
+def run out_file, globs
+  YARD::Registry.clear
+  puts "Globbing: #{globs}"
+  puts "Writing: #{out_file}"
+  YARD::Parser::SourceParser.parse globs
+  File.open(out_file, 'w') do | file |
+    YARD::Registry.entries.each do | entry |
+      file.write mobj_to_md entry
+    end
+  end
+end
+
+def globs paths
+  # Convert single string to array for map
+  paths = [ paths ] unless paths.kind_of? Array
+  # Adjust path based on system
+  paths.map! { |path| "#{ENV['HOME']}/Desktop/appium/ruby_lib#{path}" }
+end
+
+common_globs = '/lib/appium_lib/*.rb', '/lib/appium_lib/common/**/*.rb'
+android_globs = common_globs + [ '/lib/appium_lib/android/**/*.rb' ]
+ios_globs = common_globs + [ '/lib/appium_lib/ios/**/*.rb' ]
+
+run 'docs/android_docs.md', globs(android_globs)
+
+run 'docs/ios_docs.md', globs(ios_globs)

data/lib/appium_lib.rb

@@ -2,6 +2,7 @@
 
 $driver = nil
 
+# @private
 # Invoke top level methods on last created Appium driver.
 def self.method_missing method, *args, &block
   raise "driver is nil. called #{method}" if $driver == nil
@@ -12,6 +13,7 @@ def self.method_missing method, *args, &block
 end
 
 module Appium
+  # @private
   def self.add_to_path file, path=false
    path = path ? "../#{path}/" : '..'
    path = File.expand_path path, file
@@ -22,4 +24,4 @@ module Appium
   add_to_path __FILE__
 
   require 'appium_lib/driver'
-end
+end

data/lib/appium_lib/android/element/alert.rb

@@ -34,4 +34,4 @@ module Appium::Android
   def alert_dismiss_text
     first_button.text
   end
-end # module Appium::Android
+end # module Appium::Android

data/lib/appium_lib/android/element/generic.rb

@@ -8,22 +8,22 @@ In Android //* is used to find partial case insensitive text matches.
 
 find_element :name by default uses a partial case insensitive match.
 On iOS the default is an exact name match.
-=end
 
-=begin
-    // iOS version
-    // https://github.com/appium/ruby_lib/blob/37bb4e90b29e5adb4438b287b6387a504c94b5c4/lib/appium_lib/element/ios/generic.rb#L23
-    var search = "name contains[c] '#{text}' || label contains[c] '#{text}' || value contains[c] '#{text}'";
-    var a = w.secureTextFields().firstWithPredicate(search);
+```javascript
+// iOS version
+// https://github.com/appium/ruby_lib/blob/37bb4e90b29e5adb4438b287b6387a504c94b5c4/lib/appium_lib/element/ios/generic.rb#L23
+var search = "name contains[c] '#{text}' || label contains[c] '#{text}' || value contains[c] '#{text}'";
+var a = w.secureTextFields().firstWithPredicate(search);
+if ( isNil(a) ) {
+  a = w.textFields().firstWithPredicate(search);
+  if ( isNil(a) ) {
+    a = w.buttons().firstWithPredicate(search);
     if ( isNil(a) ) {
-      a = w.textFields().firstWithPredicate(search);
-      if ( isNil(a) ) {
-        a = w.buttons().firstWithPredicate(search);
-        if ( isNil(a) ) {
-          a = w.elements().firstWithPredicate(search);
-        }
-      }
+      a = w.elements().firstWithPredicate(search);
     }
+  }
+}
+```
 
 Android considers both a textfield and a secure textfield to be "EditText".
 Name (the content desc) is searched first and then we search for value (text).
@@ -35,6 +35,12 @@ so we consider the element a button if the class name contains the word button.
 After looking for textfields and buttons, then we search all elements. Find will return
 the first element that matches.
 =end
+
+  # Find the value contained in content description or text. Search elements
+  # in this order: EditText, Button, ImageButton
+  #
+  # @param val [String] the value to search for
+  # @return [Element]
   def find val
     # s.className('android.widget.EditText').descriptionContains(value);
     args = [ [4, 'android.widget.EditText'], [7, val] ],

data/lib/appium_lib/android/helper.rb

@@ -1,9 +1,12 @@
 # encoding: utf-8
 module Appium::Android
   # Returns an array of android classes that match the tag name
+  # @param tag_name [String] the tag name to convert to an android class
+  # @return [String]
   def tag_name_to_android tag_name
     tag_name = tag_name.to_s.downcase.strip
 
+    # @private
     def prefix *tags
       tags.map!{ |tag| "android.widget.#{tag}" }
     end
@@ -33,8 +36,11 @@ module Appium::Android
         raise "Invalid tag name #{tag_name}"
     end # return result of case
   end
-
-  # on android, assume the attr is name (which falls back to text).
+  # Find all elements matching the attribute
+  # On android, assume the attr is name (which falls back to text).
+  #
+  # @param tag_name [String] the tag name to search for
+  # @return [Element]
   def find_eles_attr tag_name
 =begin
     sel1 = [ [4, 'android.widget.Button'], [100] ]
@@ -54,7 +60,11 @@ module Appium::Android
     mobile :find, array
   end
 
+  # Selendroid only.
+  # Returns a string containing interesting elements.
+  # @return [String]
   def get_selendroid_inspect
+    # @private
     def run node
       r = []
 
@@ -116,7 +126,10 @@ module Appium::Android
   end
 
   # Android only.
+  # Returns a string containing interesting elements.
+  # @return [String]
   def get_android_inspect
+    # @private
     def run node
       r = []
 
@@ -161,11 +174,14 @@ module Appium::Android
     out
   end
 
+  # Automatically detects selendroid or android.
+  # Returns a string containing interesting elements.
+  # @return [String]
   def get_inspect
     @selendroid ? get_selendroid_inspect : get_android_inspect
   end
 
-  # Android only. Intended for use with console.
+  # Intended for use with console.
   # Inspects and prints the current page.
   def page
     puts get_inspect
@@ -174,8 +190,10 @@ module Appium::Android
 
   # JavaScript code from https://github.com/appium/appium/blob/master/app/android.js
   #
+  # ```javascript
   # Math.round((duration * 1000) / 200)
   # (.20 * 1000) / 200 = 1
+  # ```
   #
   # We want steps to be exactly 1. If it's zero then a tap is used instead of a swipe.
   def fast_duration

data/lib/appium_lib/android/patch.rb

@@ -1,5 +1,6 @@
 # encoding: utf-8
 module Appium::Android
+  # @private
   # class_eval inside a method because class Selenium::WebDriver::Element
   # will trigger as soon as the file is required. in contrast a method
   # will trigger only when invoked.

data/lib/appium_lib/common/dynamic.rb

@@ -0,0 +1,44 @@
+# encoding: utf-8
+
+module Appium
+  class Driver
+    @@map = {
+        1 => [ 'text(String text)', 'SELECTOR_TEXT', 1],
+        2 => [ 'textStartsWith(String text)', 'SELECTOR_START_TEXT', 2],
+        3 => [ 'textContains(String text)', 'SELECTOR_CONTAINS_TEXT', 3],
+        4 => [ 'className(String className)', 'SELECTOR_CLASS', 4],
+        5 => [ 'description(String desc)', 'SELECTOR_DESCRIPTION',  5],
+        6 => [ 'descriptionStartsWith(String desc)', 'SELECTOR_START_DESCRIPTION', 6],
+        7 => [ 'descriptionContains(String desc)', 'SELECTOR_CONTAINS_DESCRIPTION', 7],
+        8 => [ 'index(final int index)', 'SELECTOR_INDEX', 8],
+        9 => [ 'instance(final int instance)', 'SELECTOR_INSTANCE', 9],
+        10 => [ 'enabled(boolean val)', 'SELECTOR_ENABLED', 10],
+        11 => [ 'focused(boolean val)', 'SELECTOR_FOCUSED', 11],
+        12 => [ 'focusable(boolean val)', 'SELECTOR_FOCUSABLE', 12],
+        13 => [ 'scrollable(boolean val)', 'SELECTOR_SCROLLABLE', 13],
+        14 => [ 'clickable(boolean val)', 'SELECTOR_CLICKABLE', 14],
+        15 => [ 'checked(boolean val)', 'SELECTOR_CHECKED', 15],
+        16 => [ 'selected(boolean val)', 'SELECTOR_SELECTED',  16],
+        # // SELECTOR_ID = 17; // nothing.
+        18 => [ 'packageName(String name)', 'SELECTOR_PACKAGE_NAME', 18],
+        # // SELECTOR_CHILD              = 19; // childSelector(UiSelector selector)
+        # // SELECTOR_CONTAINER          = 20; // containerSelector(UiSelector selector)
+        # // SELECTOR_PATTERN            = 21; // ! private ! patternSelector(UiSelector selector)
+        # // SELECTOR_PARENT             = 22; // fromParent(UiSelector selector)
+        # // SELECTOR_COUNT              = 23; // nothing.
+        24 => [ 'longClickable(boolean val)', 'SELECTOR_LONG_CLICKABLE', 24],
+        25 => [ 'textMatches(String regex)', 'SELECTOR_TEXT_REGEX', 25],
+        26 => [ 'classNameMatches(String regex)', 'SELECTOR_CLASS_REGEX', 26],
+        27 => [ 'descriptionMatches(String regex)', 'SELECTOR_DESCRIPTION_REGEX', 27],
+        28 => [ 'packageNameMatches(String regex)', 'SELECTOR_PACKAGE_NAME_REGEX', 28],
+        # // start internal methods at 100
+        100 => [ 'getStringAttribute("name")', 'GET_NAME', 100]
+      }
+
+      def dynamic_code_to_string code, value=false
+        result = @@map[code].first
+        return result unless value
+        result.split('(').first + "( \"#{value}\" )"
+      end
+  end # class Driver
+end # module Appium

data/lib/appium_lib/common/helper.rb

@@ -58,33 +58,35 @@ module Appium::Common
   end
 
   # Find by id. Useful for selendroid
+  # @param id [String] the id to search for
+  # @return [Element]
   def id id
     find_element :id, id
   end
 
-  # Presses the back button on Android.
+  # Navigate back.
   # @return [void]
   def back
     @driver.navigate.back
   end
 
-  # For Sauce Labs reporting
+  # For Sauce Labs reporting. Returns the current session id.
   def session_id
     @driver.session_id
   end
 
-  def sauce_username
-    @sauce_username
-  end
-
-  def sauce_access_key
-    @sauce_access_key
-  end
-
+  # Returns the first element that matches the provided xpath.
+  #
+  # @param xpath_str [String] the XPath string
+  # @return [Element]
   def xpath xpath_str
     find_element :xpath, xpath_str
   end
 
+  # Returns all elements that match the provided xpath.
+  #
+  # @param xpath_str [String] the XPath string
+  # @return [Array<Element>]
   def xpaths xpath_str
     find_elements :xpath, xpath_str
   end
@@ -185,11 +187,19 @@ module Appium::Common
     JSON.parse @driver.page_source, max_nesting: 9999
   end
 
+  # Returns the first element that matches name
+  #
+  # @param name [String] the name to match
+  # @return [Element]
   def find_name name
     find_element :name, name
   end
 
+  # Returns all elements that match name
+  #
+  # @param name [String] the name to match
+  # @return [Array<Element>]
   def find_names name
     find_elements :name, name
   end
-end # module Appium::Common
+end # module Appium::Common

data/lib/appium_lib/common/patch.rb

@@ -4,19 +4,21 @@ module Appium::Common
   class Selenium::WebDriver::Element
     # Note: For testing .text should be used over value, and name.
 
-    # Fixes NoMethodError: undefined method `value' for #<Selenium::WebDriver::Element:0x..fa4a9148235390a44 id="1">
+    # Returns the value attribute
+    #
+    # Fixes NoMethodError: undefined method `value' for Selenium::WebDriver::Element
     def value
       self.attribute :value
     end
 
-    # Fixes NoMethodError: undefined method `name' for #<Selenium::WebDriver::Element
+    # Returns the name attribute
+    #
+    # Fixes NoMethodError: undefined method `name' for Selenium::WebDriver::Element
     def name
       self.attribute :name
     end
 
-    # Use tag_name to get element's type.
-    #
-    # Tag name appears to be the same as type.
+    # Returns the type attribute
     #
     # Fixes Selenium::WebDriver::Error::UnknownError: Not yet implemented
     def tag_name
@@ -25,7 +27,9 @@ module Appium::Common
 
     # For use with mobile tap.
     #
+    # ```ruby
     # execute_script 'mobile: tap', :x => 0.0, :y => 0.98
+    # ```
     #
     # https://github.com/appium/appium/wiki/Automating-mobile-gestures
     # @return [OpenStruct] the relative x, y in a struct. ex: { x: 0.50, y: 0.20 }
@@ -49,6 +53,7 @@ require 'selenium/webdriver/remote/commands'
 require 'selenium/webdriver/remote/http/common'
 require 'selenium/webdriver/remote/http/default'
 
+# @private
 # Show http calls to the Selenium server.
 #
 # Invaluable for debugging.
@@ -81,7 +86,40 @@ def patch_webdriver_bridge
       unless command_hash.nil? || command_hash.length == 0
         print_command = command_hash.clone
         print_command.delete :args if print_command[:args] == []
-        ap print_command
+
+        mobile_find = 'mobile: find'
+        if print_command[:script] == mobile_find
+          args = print_command[:args]
+          puts "#{mobile_find}"#" #{args}"
+
+          # [[[[3, "sign"]]]] => [[[3, "sign"]]]
+          #
+          # [[[[4, "android.widget.EditText"], [7, "z"]], [[4, "android.widget.EditText"], [3, "z"]]]]
+          # => [[[4, "android.widget.EditText"], [7, "z"]], [[4, "android.widget.EditText"], [3, "z"]]]
+          args = args[0]
+          option = args[0].to_s.downcase
+          has_option = ! option.match(/all|scroll/).nil?
+          puts option if has_option
+
+          start = has_option ? 1 : 0
+
+          start.upto(args.length-1) do |selector_index|
+            selectors = args[selector_index]
+            selectors_size = selectors.length
+            selectors.each_index do |pair_index|
+              pair = selectors[pair_index]
+              res = $driver.dynamic_code_to_string pair[0], pair[1]
+
+              if selectors_size == 1 || pair_index >= selectors_size - 1
+                puts res
+              elsif selectors_size > 1 && pair_index < selectors_size
+                print res + '.'
+              end
+            end
+          end # start.upto
+        else
+          ap print_command
+        end
       end
       # puts "verb: #{verb}, path #{path}, command_hash #{command_hash.to_json}"
       http.call verb, path, command_hash
@@ -91,6 +129,7 @@ end # def
 
 # Print Appium's origValue error messages.
 class Selenium::WebDriver::Remote::Response
+  # @private
   def error_message
     val = value