Appium with Ruby

BrowserStack gives you instant access to 2000+ real devices. Running your Appium test automation with Ruby for native and hybrid mobile apps on BrowserStack is simple. This guide will help you:

1. Run a sample Appium test on BrowserStack
2. Setup your environment to be able to test your app against your internal network
3. Understand and configure the core capabilities in your Appium test suite
4. Explore advanced features

Follow 3 easy steps to get started with your first Appium test on BrowserStack cloud.

Step 1: Setup environment

Ensure you have Ruby libraries installed.

#Install using rubygems
gem install 'appium_lib'
gem install selenium-webdriver

Step 2: Upload your app

Upload your Android app (.apk file) or iOS app (.ipa file) to the BrowserStack servers using the REST API.

curl -u "USERNAME:ACCESS_KEY" \
-X POST "https://api-cloud.browserstack.com/app-automate/upload" \
-F "file=@/path/to/app/file/Application-debug.apk"

Please note the App URL (bs://<hashed appid>) returned in the response of this call:

{"app_url":"bs://<hashed appid>"}

Upload app from a Public Location

If you do not have your app file on the local machine from where you are running the test and it is hosted on a different location, you can upload it to the BrowserStack servers from any public hosted location. You can achieve that by just providing the app public url in the API call to upload an app. The url should be accessible over the internet so that BrowserStack can directly upload it from that location. Use the below API call to upload app from a publicly accessible location.

curl -u "USERNAME:ACCESS_KEY" \
-X POST "https://api-cloud.browserstack.com/app-automate/upload" \
-F "data={\"url\": \"https://www.browserstack.com/app-automate/sample-apps/android/WikipediaSample.apk\"}"

Define Custom Id for your app

If you would like to set a constant value in your 'app' capability instead updating your test code to change the App URL everytime you upload an app, define a Custom Id for your apps. Use the same Custom Id for every build you upload. Custom Id is optional.

curl -u "USERNAME:ACCESS_KEY" \
-X POST "https://api-cloud.browserstack.com/app-automate/upload" \
-F "file=@/path/to/app/file/Application-debug.apk" \
-F "data={\"custom_id\": \"MyApp\"}"

Sample response of the API call

{"custom_id":"MyApp", "app_url":"bs://<hashed appid>", "shareable_id":"USERNAME/MyApp"}

You can use either of the above values in the 'app' capability of your test.

custom_id: If you use custom_id value in the 'app' capability, Appium will pick the latest app uploaded by you using that custom_id. For example, if you upload 3 different builds of your app using the same custom_id, and if you are using custom_id in your 'app' capability, Appium will pick the last uploaded build and execute your test.

shareable_id: If you would like some other user with in your group to run test using the app uploaded by you, provide the shareable_id to that user. The user can set shareable_id value in the 'app' capability and run the test.

Step 3: Configure and run test

Copy sample code provided in Ruby for Android and iOS. Update the desired capability "app" with the App URL returned from the above API call.

require 'rubygems'
require 'appium_lib'
 
username = 'USERNAME'
access_key = 'ACCESS_KEY'
 
caps = {}
caps['build'] = 'Ruby Appium Sample'
caps['name'] = 'single_test'
caps['device'] = 'Samsung Galaxy S8 Plus'
caps['platformName'] = 'android'
caps['browserstack.debug'] = true
caps['app'] = 'bs://'

appium_driver = Appium::Driver.new({
    'caps' => caps,
    'appium_lib' => {
        :server_url => "http://#{username}:#{access_key}@hub-cloud.browserstack.com/wd/hub"
    }}, true)
driver = appium_driver.start_driver
 
wait = Selenium::WebDriver::Wait.new(:timeout => 30)
wait.until { driver.find_element(:accessibility_id, "Search Wikipedia").displayed? }
element = driver.find_element(:accessibility_id, "Search Wikipedia")
element.click
 
wait.until { driver.find_element(:id, "org.wikipedia.alpha:id/search_src_text").displayed? }
search_box = driver.find_element(:id, "org.wikipedia.alpha:id/search_src_text")
search_box.send_keys("BrowserStack")
sleep 5
 
results = driver.find_elements(:class, "android.widget.TextView")
if results.count > 0
    puts "Found results - Test Passed"
else
    puts "No results found - Test Failed"
end
 
driver.quit

require 'rubygems'
require 'appium_lib'
 
username = 'USERNAME'
access_key = 'ACCESS_KEY'
 
caps = {}
caps['build'] = 'Ruby Appium Sample'
caps['name'] = 'single_test'
caps['device'] = 'iPhone 7 Plus'
caps['platformName'] = 'iOS'
caps['browserstack.debug'] = true
caps['app'] = 'bs://'

appium_driver = Appium::Driver.new({
    'caps' => caps,
    'appium_lib' => {
        :server_url => "http://#{username}:#{access_key}@hub-cloud.browserstack.com/wd/hub"
    }}, true)
driver = appium_driver.start_driver
 
wait = Selenium::WebDriver::Wait.new(:timeout => 30)
wait.until { driver.find_element(:accessibility_id, "Text Button").displayed? }
textButton = driver.find_element(:accessibility_id, "Text Button")
textButton.click
 
wait.until { driver.find_element(:accessibility_id, "Text Input").displayed? }
textInput = driver.find_element(:accessibility_id, "Text Input")
textInput.send_keys("hello@browserstack.com"+"\n")
 
sleep 5

wait.until { driver.find_element(:accessibility_id, "Text Output").displayed? }
result = driver.find_element(:accessibility_id, "Text Output")
 
if (!result.nil?) && (result.text.eql? "hello@browserstack.com")
  puts "Test Passed"
else
  puts "Test Failed"
end
 
driver.quit

BrowserStack enables you to run automated tests on your apps against your internal development environments or environments behind a corporate firewall. This feature is called "Local Testing".

Local Testing establishes a secure connection between your machine and the BrowserStack cloud. Once you set up Local Testing, all URLs work out of the box, including HTTPS URLs and those behind a proxy or firewall.

Getting Started

In two steps, configure your Appium tests for Local Testing:

1. Download and run the BrowserStackLocal binary:

   Download the appropriate binary:

   • OS X (Recommended for your system)
   • Linux 32-bit
   • Linux 64-bit
   • Windows

   The download links are secure. The binaries are digitally signed, identifying the publisher as BrowserStack Ltd. Read more about our security.

   Navigate to the folder containing the binary, and run it from the terminal.

   • OS X & Linux
   • Windows

   ./BrowserStackLocal --key ACCESS_KEY
   

2. Once the connection is made you need to set the browserstack.local capability to true.

   caps['browserstack.local'] = True
   

Capabilities are a series of key-value pairs that allow customization of testing from within BrowserStack Automate.

Appium provides a series of capabilities that you can set for the Appium version you are running. Appium server on the BrowserStack will receive all the capabilities you set on the client side. You can also use BrowserStack specific capabilities to configure your tests. Visit Capabilities page to view the complete list of BrowserStack capabilities.

Use the drop down below to select your device and configure the capabilities.

desired_caps = {'device': 'iPhone 7 Plus', 'os_version': '10.0'}

Debugging

BrowserStack provides a range of debugging tools to help you quickly identify and fix bugs you discover through your automated tests.

Text Logs

Text Logs are a comprehensive record of your test. They are used to identify all the steps executed in the test and troubleshoot errors for the failed step. Text Logs are accessible from the App Automate dashboard or via our REST API.

Visual Logs

Visual Logs automatically capture the screenshots generated at every Appium command run through your test suite. Visual logs help with debugging the exact step and the page where failure occurred. They also help identify any layout or design related issues with your app pages on different devices.

Visual Logs are disabled by default. In order to enable Visual Logs you will need to set browserstack.debug capability to 'true':

caps['browserstack.debug'] = 'true'

Video Recording

Every test run on the BrowserStack is recorded exactly as it is executed on our remote device. This feature is particularly helpful whenever a test fails. You can access videos from App Automate Dashboard for each session. You can also download the videos from the Dashboard or retrieve a link to download the video using our REST API.

caps['browserstack.video'] = 'false'

Device Logs

Device Logs capture the logs of the device for every test run. This helps in troubleshooting any app failures or crashes. Device Logs are enabled by default. You can also download the Device Logs from the Dashboard or retrieve a link to download the Device Logs using our REST API.

The BrowserStack device cloud gives you the infrastructure you need to scale. Features like Parallel Testing and Queuing enable you to scale faster.

Parallel Testing

On BrowserStack, you can run multiple Appium tests at the same time across various device and OS combinations. This is "Parallel Testing". Parallel Testing gives you the same benefits as running a multi-threaded application.

With Parallel Testing, you can run the same test on different device/os combinations, or run different tests on the same device/os combination. Parallel Testing will help you reduce the run time of your test suite, resulting in faster build times and faster releases.

To start Parallel testing, you can use any of the popular test frameworks like Cucumber which work with Ruby and Appium.

Queuing

With queuing, you can launch an additional number of parallel tests with different browser configurations that will be queued in a sequence. For instance, if you want to run 5 additional tests, apart from your subscribed limit of 2 parallel tests, BrowserStack will queue the additional 5 tests until one of the 2 initial tests finish, and a slot is available for execution. With queuing, you don't need to worry about managing your test pipeline - we automatically take care of scheduling and execution for you.

With this feature, accounts up to 5 parallel tests can queue 5 tests. Beyond 5 parallel tests, an equivalent number of tests will be queued.