# Run Appium tests using Ruby

Run your Appium tests written in Ruby on real Android and iOS devices with BrowserStack App Automate.

BrowserStack App Automate enables you to test native and hybrid mobile applications using Appium automation framework. Its easy to run your Appium tests written in Ruby on real Android and iOS devices on BrowserStack. This guide will help you get started with your first test.

#### Onboard faster with Test Companion

Launch in your IDE. Chat with the AI assistant to configure and run your first build instantly.

## 1. Setup

- You will need a BrowserStack `username` and `access key`. To obtain your access credentials, [sign up for a free trial](/content/users/sign_up/index.html) or [purchase a plan](/content/pricing/index.html).
- Ensure you have Appium’s [Ruby client library](https://github.com/appium/ruby_lib) installed.
- Access to an Android app (`.apk`, `.aab`, or `.xapk` file) or an iOS app (`.ipa` file)

**Note:** If you do not have an `.apk` or `.ipa` file and are looking to simply try App Automate, you can download and test using our [sample Android app](/content/app-automate/sample-apps/android/WikipediaSample.apk) or [sample iOS app](/content/app-automate/sample-apps/ios/BStackSampleApp.ipa).

## 2. Upload your app

Upload your Android app (`.apk`, `.aab`, or `.xapk` file) or iOS app (`.ipa` file) to BrowserStack servers using our REST API. Here is an example `cURL` request to upload the app :

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

A sample response for the above request is shown below:

```json
{
    "app_url":"bs://j3c874f21852ba57957a3fdc33f47514288c4ba4"
}
```

Note the value of `app_url` returned in the API response (`bs://j3c874f21852b.....` in the above example). This value will be used later to set the `app` capability to specify application under test in your Appium test scripts.

**Note:**

1. App upload will take a 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 re-sign the app with our own provisioning profile to be able to install your app on our devices during test execution.

## 3. Setup and run your test

In this step, you will learn how to configure your Appium test script using desired capabilities to test remotely on BrowserStack’s real device cloud. You will need to make the following changes in your Ruby test script :

- Specify the application under test using the `app` capability. Use the `app_url` value returned at the time of app upload (Step 2) to set this capability.
- Specify the real Android or iOS device you want to test on using the `device` capability.
- In order to initialize an Appium driver, use a remote **BrowserStack URL** along with your BrowserStack access credentials as shown below :

```bash
    https://YOUR_USERNAME:YOUR_ACCESS_KEY@hub-cloud.browserstack.com/wd/hub
```

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.

```ruby
require 'rubygems'
require 'appium_lib'

username = 'YOUR_USERNAME'
access_key = 'YOUR_ACCESS_KEY'

desired_caps = {
    'build': 'Ruby Appium Sample',
    'device': 'Google Pixel 3',
    'browserstack.debug': 'true',
    'app': '<app_url>'
}

appium_driver = Appium::Driver.new({
    'caps' => desired_caps,
    'appium_lib' => {
        :server_url => "https://#{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.

```ruby
require 'rubygems'
require 'appium_lib'

username = 'YOUR_USERNAME'
access_key = 'YOUR_ACCESS_KEY'

desired_caps = {
    'build': 'Ruby Appium Sample',
    'device': 'iPhone 11 Pro',
    'app': '<app_url>'
}
appium_driver = Appium::Driver.new({
    'caps' => desired_caps,
    'appium_lib' => {
        :server_url => "https://#{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
```

## 4. Viewing test results

You can access results of your test sessions on the [App Automate dashboard](https://app-automate.browserstack.com/dashboard) as well as using our [REST API](/content/app-automate/rest-api?framework=appium/index.html). You can drill down into the details of a specific test session to view its execution details and debugging information such as video recording, network logs and device logs.