appium_lib 0.0.27 → 0.0.28

checksums.yaml

@@ -1,15 +1,15 @@
 ---
 !binary "U0hBMQ==":
   metadata.gz: !binary |-
-    MjdhNGRmNDM4NjZlMjEwOTc3ZTMyYmUzNDA3NzI3NDViNzUzZGM0ZQ==
+    ZWUwOTFmNDhjOWQ4YzBhYTVhZmQ4N2YyZDUxZWUyYmE4YTk1ZmY5OQ==
   data.tar.gz: !binary |-
-    YmMwNGJlOTYzNGVjODA0MmYyODAwZWI0NWU4OTEzYWY4ZGUwMGVhZQ==
+    ZGU2MjI1OWE0M2JjNDZjNzRhYzBiNGE0NWYyYjhlYmViMGI4NjQwMQ==
 !binary "U0hBNTEy":
   metadata.gz: !binary |-
-    YWUzY2IyOGYzYjYxZGJlOTgxMWEzNTYxYmEzYzE5YzAyMDJhNDExZDhjYTQy
-    ZGY4ZDVkNTg3YmI4NTQ0MGVjOGVkNjI1MzQ5MjFkNDAzZWU2Y2IzYWJjNDhl
-    NTFhYTExMzQ5MDE0ZTYyYmM2MWE5ZjNmZjJhNzMxYWZlZWM3OTU=
+    MTM0NzQxNzdkNjc3YzhlMDJmMTEzNTViNzRmN2ZhNjFmMThhMGMzNzhmNGVk
+    NWRiMTg4M2IyZTE5ZWM1ZDdlM2NkNTEzMTJlMWVhYTU0OTczNDU4NDEyZGRk
+    MjVjYzY0M2ViYjg2MThkNGVmOTJlNjQxMDI0MDYwYjAwNmM4MmQ=
   data.tar.gz: !binary |-
-    ZTUwYjA2ZGMxYmFiM2RjOGM1NTM4MzA0ODU4Y2UwZGFlMjEyMDA2NzU5NzMw
-    YmFjZGUwNDc1NzE0ODYzZWViMzVmNjU0NjJmMGQ2NGRkMGQzZDkzNWRjOWUx
-    ODdkOTZkZTg5NThkZjZkOWNhMjI2YWIxYzVkNWUwMDk4MDE5ODg=
+    MzYyNTk0NmMwMDlmYmEzM2RjN2Q0MzMwNDQ2ZDM5MTU5MTlmYzgwMzY0MWEw
+    NmY5NzA4OWYzYTAyMGVhMDBkMzYzNDJhMDFhYzIwYTI0OWI5Nzc3YzRiMjNj
+    YWU1ZmI3ZWUzZWJkOGY3MWUwMjRlZDhkZTRlZWViNjZiNDY3MjI=

data/appium_lib.gemspec

@@ -24,7 +24,7 @@ Gem::Specification.new do |s|
   s.homepage = 'https://github.com/appium/ruby_lib' # published as appium_lib
   s.require_paths = [ 'lib' ]
 
-  s.add_runtime_dependency 'selenium-webdriver', '~> 2.31.0'
+  s.add_runtime_dependency 'selenium-webdriver', '~> 2.32.0'
   s.add_runtime_dependency 'awesome_print', '~> 1.1.0'
 
   s.add_development_dependency 'rake', '~> 10.0.3'

data/docs.md

@@ -0,0 +1,229 @@
+#### Documentation
+
+- find_elements returns an empty array [] when no elements are found.
+
+##### [app_lib on rubydoc.info](http://www.rubydoc.info/github/appium/ruby_lib/master/toplevel)
+
+- [iOS UI Automation](http://developer.apple.com/library/ios/#documentation/DeveloperTools/Reference/UIAutomationRef/_index.html) Example use `@driver.execute_script "UIATarget.localTarget().frontMostApp().mainWindow().rect()"
+`
+- [Android UIAutomator](http://developer.android.com/tools/help/uiautomator/index.html)
+- [UiSelector.java](https://android.googlesource.com/platform/frameworks/testing/+/master/uiautomator/library/src/com/android/uiautomator/core/UiSelector.java)
+- [Ruby selenium-webdriver](http://selenium.googlecode.com/svn/trunk/docs/api/rb/index.html)
+- [Appium](https://github.com/appium/appium/blob/master/README.md)
+- [Appium extension](https://github.com/appium/appium/wiki/Automating-mobile-gestures)
+- [mechanic names of elements](https://github.com/jaykz52/mechanic/blob/8c490e1d225f384847e47ffdafb47cc2248bb96c/src/mechanic-core.js#L28)
+- [All methods supported by Appium](https://github.com/appium/appium/wiki/JSON-Wire-Protocol:-Supported-Methods)
+- [Appium's mobile gesture docs](https://github.com/appium/appium/wiki/Automating-mobile-gestures)
+- 
+Example use of Appium's mobile gesture.
+
+> @driver.execute_script 'mobile: tap', :x => 0, :y => 500
+
+`console.rb` uses some code from [simple_test.rb](
+https://github.com/appium/appium/blob/82995f47408530c80c3376f4e07a1f649d96ba22/sample-code/examples/ruby/simple_test.rb) and is released under the [same license](https://github.com/appium/appium/blob/c58eeb66f2d6fa3b9a89d188a2e657cca7cb300f/LICENSE) as Appium. The [Accessibility Inspector](https://developer.apple.com/library/ios/#documentation/UserExperience/Conceptual/iPhoneAccessibility/Testing_Accessibility/Testing_Accessibility.html) is helpful for discovering button names and textfield values.
+
+--
+
+Tag Name  | UIA
+       --:|:--
+button    | UIAButton
+textfield | UIATextField
+secure    | UIASecureTextField
+text      | UIAStaticText
+
+
+--
+
+#### generic
+
+- `source` Prints a JSON view of the current page.
+- `page` Prints the content descriptions and text values on the current page.
+- `(Element) find(value)` Returns the first element that contains value.
+- `(Element) finds(value)` Returns all elements containing value (iOS only for now).
+- `(Element) name(name)` Returns the first element containing name. Android name is the content description.
+iOS uses accessibility label with a fallback to text.
+- `(Array<Element>) names(name)` Returns all elements containing name.
+- `(Element) text(text)` Returns the first element containing text.
+- `(Array<Element>) texts(text)` Returns all elements containing text.
+--
+
+#### alert
+0. `(void) alert_accept` Accept the alert.
+0. `(String) alert_accept_text` Get the text of the alert's accept button.
+0. `(void) alert_click(value)` iOS only Tap the alert button identified by value.
+0. `(void) alert_dismiss` Dismiss the alert.
+0. `(String) alert_dismiss_text` Get the text of the alert's dismiss button.
+0. `(String) alert_text` Get the alert message text.
+
+#### button
+0. `(Button) button(index)` Find a button by index.
+0. `(Button) button(text, number = 0)` Find a button by text and optionally number.
+0. `(Button) button_include(text)` Get the first button that includes text.
+0. `(Array<String>, Array<Buttons>) buttons(text = nil)` Get an array of button texts or button elements if text is provided.
+0. `(Array<Button>) buttons_include(text)` Get all buttons that include text.
+0. `(Button) first_button` Get the first button element.
+0. `(Button) last_button` Get the last button element.
+
+#### textfield
+0. `(Textfield) textfield(index)` Find a textfield by index.
+0. `(Array<Textfield>) e_textfields` Get an array of textfield elements.
+0. `(Textfield) first_textfield` Get the first textfield element.
+0. `(Textfield) last_textfield` Get the last textfield element.
+0. `(Textfield) textfield(text)` Get the first textfield that matches text.
+0. `(Textfield) textfield_include(text)` Get the first textfield that includes text.
+0. `(Array<String>) textfields` Get an array of textfield texts.
+
+#### text
+
+The Static Text methods have been prefixed with `s_` to avoid conflicting with the generic text methods.
+
+0. `(Text) s_text(index)` Find a text by index.
+0. `(Array<Text>) s_e_texts` Get an array of text elements.
+0. `(Text) s_first_text` Get the first text element.
+0. `(Text) s_last_text` Get the last text element.
+0. `(Text) s_text(text)` Get the first element that matches text.
+0. `(Text) s_text_include(text)` Get the first textfield that includes text.
+0. `(Array<String>) s_texts` Get an array of text texts.
+
+#### window
+0. `(Object) window_size` Get the window's size.
+
+--
+
+```ruby
+e.name # button, text
+e.value # secure, textfield
+e.type
+e.tag_name # calls .type (patch.rb)
+e.text
+e.size
+e.location
+e.rel_location
+e.click
+e.send_keys 'keys to send'
+e.set_value 'value to set' # ruby_console specific
+
+# alert example without helper methods
+alert = $driver.switch_to.alert
+alert.text
+alert.accept
+alert.dismiss
+
+# Secure textfield example.
+#
+# Find using default value
+s = secure 'Password'
+# Enter password
+s.send_keys 'hello'
+# Check value
+s.value == password('hello'.length)
+```
+
+[routing.js](https://github.com/appium/appium/blob/master/app/routing.js#L69) lists not yet implemented end points.
+
+--
+
+#### Driver
+
+`start_driver` will restart the driver.
+
+`x` will quit the driver and exit Pry.
+
+`execute_script` calls `$driver.execute_script`
+
+`find_element` calls `$driver.find_element`
+
+`find_elements` calls `$driver.find_elements`
+
+`mobile :swipe, endX: 100, endY: 100, duration: 0.01` calls `$driver.execute_script 'mobile: swipe', endX: 100, endY: 100, duration: 0.01`
+
+`no_wait` will set implicit wait to 0. `$driver.manage.timeouts.implicit_wait = 0`
+
+`set_wait` will set implicit wait to default 30 seconds. `$driver.manage.timeouts.implicit_wait = 30`
+
+`set_wait(timeout_seconds)` will set implicit wait to desired timeout. `$driver.manage.timeouts.implicit_wait = timeout`
+
+.click to tap an element.
+.send_keys to type on an element.
+
+#### Raw UIAutomation
+
+`execute_script "au.lookup('button')[0].tap()"` is the same as
+`execute_script 'UIATarget.localTarget().frontMostApp().buttons()[0].tap()'`
+
+See [app.js](https://github.com/appium/appium/blob/master/app/uiauto/appium/app.js#L3) for more au methods.
+Note that raw UIAutomation commands are not offically supported.
+
+Advanced au.
+
+In this example we lookup two tags, combine the results, wrap with $, and then return the elements.
+
+```ruby
+s = %(
+var t = au.lookup('textfield');
+var s = au.lookup('secure');
+var r = $(t.concat(s));
+au._returnElems(r);
+)
+
+execute_script s
+```
+
+#### XPath
+
+See [#194](https://github.com/appium/appium/pull/194/files) for details.
+
+```ruby
+find_element  :xpath, 'button'
+find_elements :xpath, 'button'
+
+find_element  :xpath, 'button[@name="Sign In"]'
+find_elements :xpath, 'button[@name="Sign In"]'
+
+find_element  :xpath, 'button[contains(@name, "Sign In")]'
+find_elements :xpath, 'button[contains(@name, "Sign")]'
+
+find_element :xpath, 'textfield[@value="Email"]'
+find_element :xpath, 'textfield[contains(@value, "Email")]'
+
+find_element  :xpath, 'text[contains(@name, "Reset")]'
+find_elements :xpath, 'text[contains(@name, "agree")]'
+```
+
+#### Cucumber Sauce Integration
+
+Reset after each test and when done report the result to Sauce after quiting the driver.
+
+```ruby
+require 'rest_client' # https://github.com/archiloque/rest-client
+require 'json' # for .to_json
+
+$passed = true
+
+After do |scenario|
+  # Reset scenario unless the feature was tagged @keep
+  $driver.execute_script 'mobile: reset' unless scenario.feature.source_tag_names.include? '@keep'
+
+  if $passed
+    $passed = false if scenario.failed?
+  end
+end
+
+at_exit do
+  ID = $driver.send(:bridge).session_id
+  $driver.quit
+  
+  if !SAUCE_USERNAME.nil? && !SAUCE_ACCESS_KEY.nil?
+    URL = "https://#{SAUCE_USERNAME}:#{SAUCE_ACCESS_KEY}@saucelabs.com/rest/v1/#{SAUCE_USERNAME}/jobs/#{ID}"
+
+    # Keep trying until passed is set correctly. Give up after 30 seconds.
+    wait do
+      response = RestClient.put URL, { 'passed' => $passed }.to_json, :content_type => :json, :accept => :json
+      response = JSON.parse(response)
+
+      # Check that the server responded with the right value.
+      response['passed'] == $passed
+    end
+  end
+end
+```

data/lib/appium_lib/console.rb

@@ -112,7 +112,10 @@ end
 def absolute_app_path
     raise 'APP_PATH environment variable not set!' if APP_PATH.nil?
     return APP_PATH if APP_PATH.match(/^http/) # public URL for Sauce
-    return APP_PATH if APP_PATH.match(/^\//) # absolute file path
+    if APP_PATH.match(/^\//) # absolute file path
+      raise "App doesn't exist. #{APP_PATH}" unless File.exist? APP_PATH 
+      return APP_PATH
+    end
     file = File.join(File.dirname(__FILE__), APP_PATH)
     raise "App doesn't exist #{file}" unless File.exist? file
     file

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

@@ -10,6 +10,47 @@ 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);
+    if ( isNil(a) ) {
+      a = w.textFields().firstWithPredicate(search);
+      if ( isNil(a) ) {
+        a = w.buttons().firstWithPredicate(search);
+        if ( isNil(a) ) {
+          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).
+There's no label in Android.
+
+Android buttons have different class names (android.widget.Button, android.widget.ImageButton)
+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
+def find val
+  # s.className('android.widget.EditText').descriptionContains(value);
+  args = [ [4, 'android.widget.EditText'], [7, val] ],
+  # s.className('android.widget.EditText').textContains(value);
+         [ [4, 'android.widget.EditText'], [3, val] ],
+  # s.classNameMatches('(?i).*button.*').descriptionContains(value);
+         [ [26, '(?i).*button.*'], [7, val] ],
+  # s.classNameMatches('(?i).*button.*').textContains(value);
+         [ [26, '(?i).*button.*'], [3, val] ],
+  # s.descriptionContains(value);
+         [ [7, val] ],
+  # s.textContains(value);
+         [ [3, val] ]
+  mobile :find, args
+end
+
 # Return the first element matching text.
 # @param text [String] the text to search for
 # @return [Element] the first matching element
@@ -44,4 +85,4 @@ def names name
   $driver.find_elements :name, name
 end
 
-end # if $os == :android
+end # if $os == :android

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

@@ -5,17 +5,76 @@ name, names, text, text should match substring and case insensitive.
 
 iOS .name() is the accessibility attribute. If not defined, then .label() is used instead.
 This differs from Android where name (the content description) is empty when not set.
+
+name defaults to label when undefined. value is never a default so that must be
+included in a new search.
+
+Find - search everything.
+
+The search order is:
+1. name
+2. label (implied by name)
+3. value
+
+Android name = iOS name & label
+Android text = iOS value
 =end
 
+def first_ele_js predicate
+  # returnElems requires a wrapped $(element).
+  # set to empty array when length is zero to prevent hang.
+  #
+  # UIAElementNil when not matched
+  #
+  # 1. secureTextFields
+  # 2. textFields
+  # 3. buttons
+  # 4. elements
+  %Q(
+    function isNil( a ) {
+      return a.type() === 'UIAElementNil';
+    }
+
+    var w = au.mainWindow;
+    var search = #{predicate};
+    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.elements().firstWithPredicate(search);
+        }
+      }
+    }
+
+    if ( a.length === 0 ) {
+      a = [];
+    }
+
+    au._returnElems($(a));
+  )
+end
+
+def all_ele_js predicate
+  %Q(
+    var w = au.mainWindow;
+    var search = #{predicate};
+    var a = w.elements().withPredicate(search).toArray();
+
+    if ( a.length === 0 ) {
+      a = [];
+    }
+
+    au._returnElems($(a));
+  )
+end
+
 # Return the first element matching text.
 # @param text [String] the text to search for
 # @return [Element] the first matching element
-def text text
-  # returnElems requires a wrapped $(element).
-  js = %Q(
-    var element = $(au.mainWindow.elements().firstWithPredicate("name contains[c] '#{text}'"));
-    au._returnElems(element);
-  )
+def find text
+  js = first_ele_js "name contains[c] '#{text}' || label contains[c] '#{text}' || value contains[c] '#{text}'"
 
   execute_script(js).first
 end
@@ -23,13 +82,32 @@ end
 # Return all elements matching text.
 # @param text [String] the text to search for
 # @return [Array<Element>] all matching elements
-def texts text
+def finds text
   # returnElems requires a wrapped $(element).
   # must call toArray when using withPredicate instead of firstWithPredicate.
-  js = %Q(
-    var a = au.mainWindow.elements().withPredicate("name contains[c] '#{text}'").toArray();
-    au._returnElems($(a));
-  )
+  js = all_ele_js "name contains[c] '#{text}' || label contains[c] '#{text}' || value contains[c] '#{text}'"
+
+  execute_script js
+end
+
+# Return the first element matching text.
+# @param text [String] the text to search for
+# @return [Element] the first matching element
+def text text
+  # TODO: Use XPath index once it's implemented
+  # https://github.com/appium/appium/issues/295
+  js = first_ele_js "value contains[c] '#{text}'"
+
+  execute_script(js).first
+end
+
+# Return all elements matching text.
+# @param text [String] the text to search for
+# @return [Array<Element>] all matching elements
+def texts text
+  # XPath //* is not implemented on iOS
+  # https://github.com/appium/appium/issues/430
+    js = all_ele_js "value contains[c] '#{text}'"
 
   execute_script js
 end
@@ -39,8 +117,10 @@ end
 # on iOS name is the accessibility label or the text.
 # @param name [String] the name to search for
 # @return [Element] the first matching element
-def name name
-  text name
+def name text
+  js = first_ele_js "name contains[c] '#{text}' || label contains[c] '#{text}'"
+
+  execute_script(js).first
 end
 
 # Return all elements matching name.
@@ -48,8 +128,13 @@ end
 # on iOS name is the accessibility label or the text.
 # @param name [String] the name to search for
 # @return [Array<Element>] all matching elements
-def names name
-  texts name
+def names text
+  # find_elements :name is not the same as on Android.
+  # it's case sensitive and exact on iOS and not on Android.
+  # https://github.com/appium/appium/issues/379
+  js = all_ele_js "name contains[c] '#{text}' || label contains[c] '#{text}''"
+
+  execute_script js
 end
 
 end # if ios

data/lib/appium_lib/helper.rb

@@ -219,11 +219,60 @@ def get_inspect
     out += "  name: #{e[:desc]}\n" unless e[:desc].nil?
   }
   out
-end
+end if $os == :android
 
 # Android only. Intended for use with console.
 # Inspects and prints the current page.
 def page
   puts get_inspect
   nil
+end if $os == :android
+
+def page element
+
+  def empty ele
+    (ele['name'] || ele['label'] || ele['value']) == nil
+  end
+
+  def fix_space s
+    # char code 160 (name, label) vs 32 (value) will break comparison.
+    # convert string to binary and remove 160.
+    # \xC2\xA0
+    s.force_encoding('binary').gsub("\xC2\xA0".force_encoding('binary'), ' ') if s
+  end
+
+  if ! empty( element )
+    puts "#{element['type']}"
+    name = fix_space element['name']
+    label = fix_space element['label']
+    value = fix_space element['value']
+
+    if name == label && name == value
+      puts "   name, label, value: #{name}" if name
+    elsif name == label
+      puts "   name, label: #{name}" if name
+      puts "   value: #{value}" if value
+    elsif name == value
+      puts "   name, value: #{name}" if name
+      puts "  label: #{label}" if label
+    else
+      puts "   name: #{name}" if name
+      puts "  label: #{label}" if label
+      puts "  value: #{value}" if value
+    end
+  end
+
+  children = element['children']
+  children.each { |c| page c } if children
+  nil
+end if $os == :ios
+
+# JavaScript code from https://github.com/appium/appium/blob/master/app/android.js
+#
+# 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
+  0.20
 end

data/lib/appium_lib/version.rb

@@ -1,4 +1,4 @@
 module AppiumLib
-  VERSION = '0.0.27' unless defined? ::AppiumLib::VERSION
-  DATE = '2013-04-05' unless defined? ::AppiumLib::DATE
+  VERSION = '0.0.28' unless defined? ::AppiumLib::VERSION
+  DATE = '2013-04-11' unless defined? ::AppiumLib::DATE
 end

data/readme.md

@@ -2,9 +2,9 @@
 
 - [appium_lib on RubyGems](https://rubygems.org/gems/appium_lib)
 - [Documentation for appium_lib](http://www.rubydoc.info/github/appium/ruby_lib/master/frames)
+- [Appium Ruby Console](https://github.com/appium/ruby_console)
 
 Helper methods for writing cross platform (iPad, iPhone, Android) tests in Ruby using Appium.
-There's also an [Appium Ruby Console](https://github.com/appium/ruby_console) which uses this lib.
 
 Make sure you're using Ruby 1.9.3+ with upgraded rubygems and bundler.
 
@@ -29,3 +29,7 @@ gem install --no-rdoc --no-ri appium_lib
 `pry -r ./lib/appium_lib.rb`
 
 Then `start_driver`
+
+#### Documentation
+
+See [docs.md](https://github.com/appium/ruby_lib/blob/master/docs.md)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: appium_lib
 version: !ruby/object:Gem::Version
-  version: 0.0.27
+  version: 0.0.28
 platform: ruby
 authors:
 - code@bootstraponline.com
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-04-05 00:00:00.000000000 Z
+date: 2013-04-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: selenium-webdriver
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: 2.31.0
+        version: 2.32.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: 2.31.0
+        version: 2.32.0
 - !ruby/object:Gem::Dependency
   name: awesome_print
   requirement: !ruby/object:Gem::Requirement
@@ -64,6 +64,7 @@ files:
 - LICENSE-2.0.txt
 - Rakefile
 - appium_lib.gemspec
+- docs.md
 - lib/appium_lib.rb
 - lib/appium_lib/console.rb
 - lib/appium_lib/element/android/alert.rb