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:
- Run a sample Appium test on BrowserStack
- Setup your environment to be able to test your app against your internal network
- Understand and configure the core capabilities in your Appium test suite
- 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>"}
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.
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.
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.
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
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.
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:
Download and run the BrowserStackLocal binary:
Download the appropriate binary:
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.
./BrowserStackLocal --key ACCESS_KEY
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.
- Run the BrowserStackLocal binary with the localIdentifier option
./BrowserStackLocal --key ACCESS_KEY --local-identifier Test123
Here, we have created a named connection called Test123.
- 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'
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.
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.
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.
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.