Fix Ruby sample code so it works on Sauce Labs

Add Android cucumber example

Fix #1458

sample-code/examples/ruby/Gemfile

@@ -1,9 +1,10 @@
 source 'https://www.rubygems.org'
 
-gem 'appium_lib'
-gem 'rest-client'
-gem 'rspec'
-gem 'cucumber'
-gem 'rspec-expectations'
-gem 'spec'
-gem 'sauce_whisk'
+gem 'appium_lib',         '~> 3.0.2'
+gem 'rest-client',        '~> 1.6.7'
+gem 'rspec',              '~> 2.14.1'
+gem 'cucumber',           '~> 1.3.15'
+gem 'rspec-expectations', '~> 2.14.5'
+gem 'spec',               '~> 5.3.4'
+gem 'sauce_whisk',        '~> 0.0.13'
+gem 'test-unit',          '~> 2.5.5' # required for bundle exec ruby xunit_android.rb

sample-code/examples/ruby/README.md

@@ -1,9 +1,9 @@
-Ruby Examples
-=============
+# Ruby Examples
 
-Before you test
----------------
-All these commands are done from a terminal window.  If you've already done a step, you can safely ignore that command.
+## Before you test
+
+All these commands are done from a terminal window.  If you've already done
+a step, you can safely ignore that command.
 
 Open this directory:  `cd APPIUM-LOCATION/sample-code/examples/ruby`
 
@@ -11,33 +11,35 @@ Install Ruby:  `\curl -L https://get.rvm.io | bash -s stable --ruby`
 
 Install Bundler:  `gem install bundle`
 
-Install Gems:  `bundle install`
+Install Gems:  `bundle update`
 
 You're ready to go!
 
-[simple_test.rb](simple_test.rb)
---------------
+## [simple_test.rb](simple_test.rb)
+
 A sanity check and simple example of driving a calculator app.  Run this to see
 the bare minimum you need to get a test running for Appium.
 
 Run the test by making sure Appium is running in another terminal, then from
 the terminal you opened above, running `rspec simple_test.rb`
 
-For more information, check out the comments at the top of [simple_test.rb](simple_test.rb#L1)
+For more information, check out the comments at the top of
+[simple_test.rb](simple_test.rb#L1)
+
+## [u\_i\_catalog.rb](u_i_catalog.rb)
 
-[u\_i\_catalog.rb](u_i_catalog.rb)
---------------
 (NB: This example is not yet 1.0 Compliant)
 A demonstration of various things you can do with Appium.  Check this if you
 need a recipe for a specific task, or just to see how simple and powerful iOS
 testing can be.
 
-Run the test by making sure Appium is running in another terminal, then from the terminal you opened above, running `rspec u_i_catalog.rb`
+Run the test by making sure Appium is running in another terminal, then from
+the terminal you opened above, running `rspec u_i_catalog.rb`
 
 For more information, check out the comments at the top of [u_i_catalog.rb](u_i_catalog.rb#L1)
 
-[Cucumber](cucumber)
---------
+## [Cucumber](cucumber)
+
 Cucumber is a Behaviour Driven Design framework that lots of people are keen on.
 It lets you describe test actions in a clean, concise, English-like manner.
 
@@ -51,12 +53,17 @@ from the commandline, run `cucumber`.
 For more information, check out the comments at the top of the files in the 
 cucumber directory.
 
-[Sauce Example](sauce_example.rb)
----------------
-Shows how to run Appium 1.0.0-beta.2 on Sauce Labs.  [Sauce Labs](http://www.saucelabs.com) is a Selenium Platform as a Service company which helps you scale your web and mobile test automation.
+## [Sauce Example](sauce_example.rb)
 
-This example demonstrates how to request an Appium session using a publically accessible test application, as well as how to inform Sauce Labs of test success or failure.
+Shows how to run Appium on Sauce Labs. [Sauce Labs](http://www.saucelabs.com)
+is a Selenium Platform as a Service company which helps you scale your web and
+mobile test automation.
 
-[XUnit Android](xunit_android.rb)
-----------------
-(NB This example is not yet 1.0 compliant)
+This example demonstrates how to request an Appium session using a publicly
+accessible test application, as well as how to inform Sauce Labs of test
+success or failure.
+
+## [XUnit Android](xunit_android.rb)
+
+A test unit example that uses advanced xpath to launch the system's settings
+app and extract the current version of Android.

sample-code/examples/ruby/android_on_sauce.rb

@@ -8,7 +8,7 @@
 #   SAUCE_ACCESS_KEY = your-sauce-key
 #
 # Then just:
-#   $ ruby android_on_sauce.rb
+#   bundle exec ruby android_on_sauce.rb
 #
 # Of note compared to the iOS example, here we're giving the package and
 # activity, no OS and an empty browserName
@@ -25,12 +25,12 @@ describe 'Notepad' do
   def desired_caps
     {
       caps:       {
-        'appium-version'  => '1.0.0',
-        'platformName'    => 'Android',
-        'platformVersion' => '4.3',
-        'deviceName'      => 'Android Emulator',
-        'app'             => 'http://appium.s3.amazonaws.com/NotesList.apk',
-        'name'            => 'Ruby Appium Android example'
+        :'appium-version' => '1.1.0',
+        platformName:     'Android',
+        platformVersion:  '4.3',
+        deviceName:       'Android Emulator',
+        app:              'http://appium.s3.amazonaws.com/NotesList.apk',
+        name:             'Ruby Appium Android example'
       },
       appium_lib: {
         wait: 60
@@ -48,7 +48,7 @@ describe 'Notepad' do
 
   it 'can create and save new notes' do
     find('New note').click
-    find_element(:class, 'android.widget.EditText').type 'This is a new note, from Ruby'
+    first_textfield.type 'This is a new note, from Ruby'
 
     find('Save').click
 

sample-code/examples/ruby/cucumber_android/features/settings.feature

@@ -0,0 +1,43 @@
+# WHAT ARE FEATURES?
+# ------------------
+# Features describe what something should allow a user to accomplish.  They're
+# high-level things, like you'd put in your manual or marketing copy.  Each
+# line describes a "step" which should pass for the feature to be 
+# implemented.  They're usually written with non-developers in mind, so should
+# be nice, plain and English like.
+#
+# WHAT ARE THE OTHER FILES?
+# -------------------------
+# The 'steps' are implemented in a step definition file, which is created by 
+# developers.  Ideally, once steps have been created, anyone can write a
+# feature by using step definitions to do so.  The step definitions for this 
+# example can be found in the cucumber/features/step_definitions/steps.rb file.
+#
+# RUNNING THE TEST:
+# -----------------
+# Assuming you've (successfully) run the examples in the simple_test.rb file,
+# all you should need for Cucumber is:
+#
+# 1.  Start Appium in a terminal window
+# 2.  From another terminal window, open the cucumber example directory at 
+#     appium/sample-code/examples/ruby/cucumber_android/
+# 3.  type 'cucumber' and hit enter
+# 4.  If you see '1 scenario (1 passed)' and some other stuff, SUCCESS! The
+#     test passed.  If you didn't, BOOOO, that's not right.  Make sure you've
+#     followed all the instructions for setup in the simple_test.rb file and
+#     give it another shot.  If that doesn't work, log a support ticket on
+#     Github at https://github.com/appium/appium/issues/new
+#
+# ADDITIONAL INFORMATION:
+# -----------------------
+# 
+# For more information about features, check out the documentation at:
+# https://github.com/cucumber/cucumber/wiki/Feature-Introduction
+
+
+Feature: Version check
+  Settings must display the Android version
+
+  Scenario: Settings
+    Given I click about phone
+    Then the Android version is a number

sample-code/examples/ruby/cucumber_android/features/step_definitions/steps.rb

@@ -0,0 +1,37 @@
+# These are the 'step definitions' which Cucumber uses to implement features.
+#
+# Each step starts with a regular expression matching the step you write in
+# your feature description.  Any variables are parsed out and passed to the
+# step block.
+#
+# The instructions in the step are then executed with those variables.
+#
+# In this example, we're using rspec's assertions to test that things are happening,
+# but you can use any ruby code you want in the steps.
+#
+# The '$driver' object is the appium_lib driver, set up in the cucumber/support/env.rb
+# file, which is a convenient place to put it as we're likely to use it often.
+# This is a different use to most of the examples;  Cucumber steps are instances
+# of `Object`, and extending Object with Appium methods (through 
+# `promote_appium_methods`) is a bad idea.
+#
+# For more on step definitions, check out the documentation at
+# https://github.com/cucumber/cucumber/wiki/Step-Definitions
+#
+# For more on rspec assertions, check out
+# https://www.relishapp.com/rspec/rspec-expectations/docs
+
+Given /^I click about phone$/ do
+  scroll_to('About phone').click
+end
+
+Given /^the Android version is a number$/ do
+  android_version = 'Android version'
+  scroll_to android_version
+
+  view    = 'android.widget.TextView'
+  version = xpath(%Q(//#{view}[preceding-sibling::#{view}[@text="#{android_version}"]])).text
+  valid   = !version.match(/\d/).nil?
+
+  expect(valid).to eq(true)
+end

sample-code/examples/ruby/cucumber_android/features/support/appium.txt

@@ -0,0 +1,8 @@
+[caps]
+platformName = "Android"
+appActivity = ".Settings"
+appPackage = "com.android.settings"
+
+[appium_lib]
+sauce_username = false
+sauce_access_key = false

sample-code/examples/ruby/cucumber_ios/features/calculator.feature

@@ -20,7 +20,7 @@
 #
 # 1.  Start Appium in a terminal window
 # 2.  From another terminal window, open the cucumber example directory at 
-#     appium/sample-code/examples/ruby/cucumber/
+#     appium/sample-code/examples/ruby/cucumber_ios/
 # 3.  type 'cucumber' and hit enter
 # 4.  If you see '1 scenario (1 passed)' and some other stuff, SUCCESS! The
 #     test passed.  If you didn't, BOOOO, that's not right.  Make sure you've

sample-code/examples/ruby/cucumber_ios/features/calculator2.feature

@@ -20,7 +20,7 @@
 #
 # 1.  Start Appium in a terminal window
 # 2.  From another terminal window, open the cucumber example directory at 
-#     appium/sample-code/examples/ruby/cucumber/
+#     appium/sample-code/examples/ruby/cucumber_ios/
 # 3.  type 'cucumber' and hit enter
 # 4.  If you see '1 scenario (1 passed)' and some other stuff, SUCCESS! The
 #     test passed.  If you didn't, BOOOO, that's not right.  Make sure you've

sample-code/examples/ruby/cucumber_ios/features/support/appium.txt

@@ -2,4 +2,8 @@
 platformName = "ios"
 device = "iPhone Simulator"
 platformVersion = "7.1"
-app = "../../../apps/TestApp/build/release-iphonesimulator/TestApp.app"
+app = "../../../apps/TestApp/build/release-iphonesimulator/TestApp.app"
+
+[appium_lib]
+sauce_username = false
+sauce_access_key = false

sample-code/examples/ruby/cucumber_ios/features/support/env.rb

@@ -0,0 +1,26 @@
+# This file provides setup and common functionality across all features.  It's
+# included first before every test run, and the methods provided here can be 
+# used in any of the step definitions used in a test.  This is a great place to
+# put shared data like the location of your app, the capabilities you want to
+# test with, and the setup of selenium.
+
+require 'rspec/expectations'
+require 'appium_lib'
+require 'cucumber/ast'
+
+# Create a custom World class so we don't pollute `Object` with Appium methods
+class AppiumWorld
+end
+
+# Load the desired configuration from appium.txt, create a driver then
+# Add the methods to the world
+caps = Appium.load_appium_txt file: File.expand_path('./', __FILE__), verbose: true
+Appium::Driver.new(caps)
+Appium.promote_appium_methods AppiumWorld
+
+World do
+  AppiumWorld.new
+end
+
+Before { $driver.start_driver }
+After { $driver.driver_quit }

sample-code/examples/ruby/sauce_example.rb

@@ -27,18 +27,20 @@
 # Run with:
 #
 # bundle exec rspec sauce_example.rb
+#
+
 require 'rspec'
 require 'appium_lib'
 require 'json'
 require 'rest_client'
 
-SAUCE_USERNAME = ENV['SAUCE_USERNAME']
+SAUCE_USERNAME   = ENV['SAUCE_USERNAME']
 SAUCE_ACCESS_KEY = ENV['SAUCE_ACCESS_KEY']
 
 # This is the test itself
 describe 'Computation' do
   before(:each) do
-    Appium::Driver.new(caps: desired_caps).start_driver
+    Appium::Driver.new(desired_caps).start_driver
     Appium.promote_appium_methods RSpec::Core::ExampleGroup
   end
 
@@ -51,7 +53,7 @@ describe 'Computation' do
   end
 
   it 'should add two numbers' do
-    values = [rand(10), rand(10)]
+    values       = [rand(10), rand(10)]
     expected_sum = values.reduce(&:+)
 
     textfields.each_with_index do |element, index|
@@ -67,20 +69,22 @@ describe 'Computation' do
 end
 
 def desired_caps
-  {
-    'appium-version' => '1.0.0',
-    'platformName' => 'iOS',
-    'platformVersion' => '7.1',
-    'deviceName' => 'iPhone Simulator',
-    'app' => 'http://appium.s3.amazonaws.com/TestApp6.0.app.zip',
-    'name' => 'Ruby Example for Appium'
+  { caps:
+      {
+        'appium-version' => '1.1.0',
+        platformName:    'iOS',
+        platformVersion: '7.1',
+        deviceName:      'iPhone Simulator',
+        app:             'http://appium.s3.amazonaws.com/TestApp6.0.app.zip',
+        name:            'Ruby Example for Appium'
+      }
   }
 end
 
 def auth_details
   un = SAUCE_USERNAME
   pw = SAUCE_ACCESS_KEY
-  
+
   unless un && pw
     STDERR.puts <<-EOF
       Your SAUCE_USERNAME or SAUCE_ACCESS_KEY environment variables 
@@ -110,5 +114,5 @@ end
 # Because WebDriver doesn't have the concept of test failure, use the Sauce
 # Labs REST API to record job success or failure
 def update_job_success(job_id, success)
-    RestClient.put "#{rest_jobs_url}/#{job_id}", {"passed" => success}.to_json, :content_type => :json
+  RestClient.put "#{rest_jobs_url}/#{job_id}", { 'passed' => success }.to_json, :content_type => :json
 end

sample-code/examples/ruby/simple_test.rb

@@ -6,24 +6,24 @@
 #
 # INSTALLING RVM
 # --------------
-# We're assuming you've got rvm installed, but if not, from a terminal
-# run the following line (removing the ""'s):
+# If you don't have rvm installed, run the following terminal command
 #
-# "\curl -L https://get.rvm.io | bash -s stable --ruby"
+# \curl -L https://get.rvm.io | bash -s stable --ruby
 #
 # INSTALLING GEMS
 # ---------------
 # Then, change to the example directory:
-#   "cd appium-location/sample-code/examples/ruby"
+#   cd appium-location/sample-code/examples/ruby
 #
 # and install the required gems with bundler by doing:
-#   "bundle install"
+#   bundle install
 #
 # RUNNING THE TESTS
 # -----------------
-# To actually run the tests, make sure appium is running in another terminal
+# To run the tests, make sure appium is running in another terminal
 # window, then from the same window you used for the above commands, type
-#   "ruby simple_test.rb"
+#
+# bundle exec ruby simple_test.rb
 #
 # It will take a while, but once it's done you should get nothing but a line
 # telling you "Tests Succeeded";  You'll see the iOS Simulator cranking away
@@ -34,13 +34,19 @@ require 'appium_lib'
 APP_PATH = '../../apps/TestApp/build/release-iphonesimulator/TestApp.app'
 
 desired_caps = {
-  'platformName'  => 'ios',
-  'versionNumber' => '7.1',
-  'app'           => APP_PATH
+  caps:       {
+    platformName:  'iOS',
+    versionNumber: '7.1',
+    app:           APP_PATH,
+  },
+  appium_lib: {
+    sauce_username:   nil, # don't run on Sauce
+    sauce_access_key: nil
+  }
 }
 
 # Start the driver
-Appium::Driver.new(caps: desired_caps).start_driver
+Appium::Driver.new(desired_caps).start_driver
 
 module Calculator
   module IOS
@@ -73,8 +79,6 @@ module Calculator
     # wait for alert to show
     wait { text 'this alert is so cool' }
 
-    # Elements can be found by their Class and value of an attribute
-    find_ele_by_attr 'UIATableCell', :label, 'Cancel'
     # Or by find
     find('Cancel').click
 

sample-code/examples/ruby/u_i_catalog.rb

@@ -5,9 +5,15 @@
 # It relies on the setup in simple_test.rb, which is also a good starting 
 # point to make sure you can run any tests at all.
 #
-# run with: rspec u_i_catalog.rb
+# run using:
 #
-# run only a tagged group: rspec --tag one u_i_catalog.rb
+# bundle exec rspec u_i_catalog.rb
+#
+# run only a tagged group:
+#
+# bundle exec rspec --tag one u_i_catalog.rb
+#
+
 require 'rubygems'
 require 'rspec'
 require 'appium_lib'
@@ -22,13 +28,16 @@ APP_PATH = './UICatalog.app.zip'
 def desired_caps
   {
     caps: {
-      'platformName'  => 'iOS',
-      'deviceName'    => 'iPhone Simulator',
-      'versionNumber' => '7.1',
-      'app'           => APP_PATH
+      platformName: 'iOS',
+      deviceName:  'iPhone Simulator',
+      versionNumber:  '7.1',
+      app: APP_PATH
     },
-    appium_lib:
-          { :wait => 10 }
+    appium_lib: {
+      sauce_username: nil, # don't run on sauce
+      sauce_access_key: nil,
+      wait: 10,
+    }
   }
 end
 

sample-code/examples/ruby/xunit_android.rb

@@ -2,14 +2,18 @@
 # it open the system settings ui, and click the 'About phone' item to find android version
 # create by testerhome.com
 # author: seveniruby
+#
+# run using:
+# bundle exec ruby xunit_android.rb
 
+require 'rubygems'
 require 'test/unit'
-require 'selenium-webdriver'
 require 'appium_lib'
 
 class SettingsTest < Test::Unit::TestCase
   def setup
-    caps   = { caps: { platformName: 'Android', appActivity: '.Settings', appPackage: 'com.android.settings' } }
+    caps   = { caps:       { platformName: 'Android', appActivity: '.Settings', appPackage: 'com.android.settings' },
+               appium_lib: { sauce_username: nil, sauce_access_key: nil } }
     driver = Appium::Driver.new(caps)
     Appium.promote_appium_methods self.class
     driver.start_driver.manage.timeouts.implicit_wait = 20 # seconds