Browserstack logo Open Menu Close Menu
  • Products
  • Developers
  • Solutions
  • Pricing
  • Products
      • Test your websites
      • Live
        Interactive cross browser testing
      • Automate
        Selenium testing at scale
      • Test your mobile apps
      • App Live
        Interactive native & hybrid app testing
      • App Automate
        Test automation for native & hybrid mobile apps
      • For Teams
      • Enterprise
      • Tools
      • Screenshots
      • Responsive

      Use BrowserStack with your favourite products. See our Integrations ⟶

  • Developers
    • Documentation
    • Support
    • Status
    • Release Notes
    • Open Source
  • Solutions
    • Functional Testing
    • Regression Testing
    • Real User Condition Testing
    • Geolocation Testing
    • Testing in Local Environments
  • Pricing
  • Sign in
  • Free Trial
  • Products
  • Test your websites
  • Live
    Interactive cross browser testing
  • Automate
    Selenium testing at scale
  • Test your mobile apps
  • App Live
    Interactive native & hybrid app testing
  • App Automate
    Test automation for native & hybrid mobile apps
  • For Teams
  • Enterprise
  • Tools
  • Screenshots
  • Responsive
  • Developers
  • Documentation
  • Support
  • Status
  • Release Notes
  • Open Source
  • Solutions
  • Functional Testing
  • Regression Testing
  • Real User Condition Testing
  • Geolocation testing
  • Testing in local environments
  • Get help
  • Documentation
  • Appium
  • Espresso
  • XCUITest
  • EarlGrey
  • Test dev environments
  • Speed up your test suite
  • References
  • Features
  • Browsers & Devices
  • Emulator vs Real Device
  • Simulator vs Real Device
  • Security
  • Debugging
  • Device Features
  • Status

Home Documentation App Automate Ruby

Appium with Ruby

Your guide to running mobile app tests using Appium with Ruby on BrowserStack real device cloud.

Introduction

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

Getting Started

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>"}

Note: If you do not have an .apk or .ipa file and are looking to simply try App Automate, you can download our Android sample app or iOS sample app and upload to the BrowserStack servers using the above API. Complete list of REST APIs can be found here.

Note:

  1. App upload will take few seconds to about a minute depending on the size of your app. Do not interrupt the curl command until you get the response back.
  2. If you upload an iOS app, we will resign the app with our own provisioning profile to be able to install your app on our devices during test execution.
  3. We will delete the uploaded app after 30 days from the date of upload.

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.

Note: Complete list of REST API's can be found here. Use browserstack.app_version capability if you would like to test older version of apps uploaded under the custom_id. Refer Capabilities page for more details.

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.

  • Android
  • iOS

If you are using our Sample App, the sample test below will install the Sample App (Wikipedia App) on the device, search for 'browserstack' and asserts for the list of results. If you are using your own app, modify the code as per your test cases. Copy the code below into your editor, and run the test from the command-line interface.

Note: Refer our sample repo for ruby on Github: ruby-appium-app-browserstack

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://<hashed app-id>'
 
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

If you are using our iOS Sample App, the sample test below will install the Sample App (BStackSample App) on the device, navigate to the Login screen, enters the login email and check whether the email is registered on WordPress. If you are using your own app, modify the code as per your test cases. Copy the code below into your editor, and run the test from the command-line interface.

Note: Refer our sample repo for ruby on Github: ruby-appium-app-browserstack

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://<hashed app-id>'
 
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

Warning: The driver.quit statement is required, otherwise the test continues to execute, leading to a timeout.

The test results are available on the command-line interface, as well as the App Automate dashboard. You have now run your first test on BrowserStack App Automate.

Note:

  1. UIAutomator2 is the default automation engine for Android.
  2. Pass automationName as 'Appium' if you are using Appium automation engine
  3. If your app uses webview, set the webview debugging flag to true when creating the webview object as described in the Android remote debugging docs: WebView.setWebContentsDebuggingEnabled(true);

Testing on Internal Networks

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
    

Multiple Local Testing connections

If you are using same account to test multiple applications, you can setup a named connection using localIdentifier.

  1. Run the BrowserStackLocal binary with the localIdentifier option
    • OS X & Linux
    • Windows
    ./BrowserStackLocal --key ACCESS_KEY --local-identifier Test123

    Here, we have created a named connection called Test123.

  2. Once the connection is made, you need to set the browserstack.localIdentifier capability with the correct named connection

    caps['browserstack.local'] = 'true'
    caps['browserstack.localIdentifier'] = 'Test123'
    

Note: In order to try a local test, upload our Local Sample App for Android and iOS. Learn more about other common local testing use cases such as testing behind a firewall, proxy, browsermob proxy and whitelisting IPs.

Configuring Capabilities

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.

1. Select an Operating System
iOS
Mobile
  • iOS
  • Android
Desktop
2. Select a browser
Windows XP
2. Select a device
iOS
3. Select a resolution
1024 x 768
Resolution
    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.

    Note: Video recording increases test execution time slightly. You can disable this feature by setting the browserstack.video capability to false.

    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.

    Speed up testing

    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.

    Note: Achieve your test coverage and build execution time goals by using our calculator to understand how many parallel sessions you need.

    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.

    Note: The wait limit for the execution of a pending queued job is 15 minutes and will be cancelled if exceeded.

    Using test frameworks?

    Ruby has several popular testing frameworks, and we have provided examples on how to use them in conjunction with Automate. Check out our complete documentation for writing automate test scripts in Cucumber.

    In This Article

    • Introduction
    • Getting Started
    • Test on Internal Networks
      • Getting Started
      • Multiple local testing connections
    • Configuring Capabilities
      • Debugging
    • Speed up testing
      • Parallel Testing
      • Queuing
    • Using testing frameworks

    Related Articles

    Capabilities

    Local Testing

    Rest API

    Jenkins

    Products
    • Live
    • Automate
    • App Live New
    • App Automate New
    • Screenshots
    • Responsive
    • Enterprise
    Mobile
    • Test on Right Devices
    • Mobile Features
    • Mobile Emulators
    • Test on iPhone
    • Test on iPad
    • Test on Galaxy
    • Android testing
    • iOS testing
    Other Links
    • Customers
    • Open Source
    • Test in IE
    • Careers We're hiring!
    • Support
    • Contact
    • Status
    • Release Notes
    • Company
    • Press
    • Case Studies
    • Sitemap
    Knowledge
    • Cross Browser Testing
    • Emulators & Simulators
    • Selenium
    • Android Emulators
    • Responsive Design
    • Guide
    • Blog
    Social
    Browserstack logo

    © 2011-2019 BrowserStack - The Most Reliable Mobile App & Cross Browser Testing Company

    • Terms of Service
    • Privacy Policy
    • Cookie Policy

    We use cookies to enhance user experience, analyze site usage, and assist in our marketing efforts. By continuing to browse or closing this banner, you acknowledge that you have read and agree to our Cookie Policy, Privacy Policy and Terms of Service.

    Got it