Search by

Run your first test

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

1. Setup

Ensure you have Cucumber libraries installed.

# Install using gem
gem install cucumber

2. Upload your app

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

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:

{
    "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. Configure and run the 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. Here is a sample test case written for running with Cucumber:

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.

# Wikipedia Feature
Feature: Search in Wikipedia App

Background:
  Given I try to search using Wikipedia App

Scenario: Search for a term
  When I type in "BrowserStack"
  Then I should see results
When /^I try to search using Wikipedia App/ do
  $wait.until { $driver.find_element(:accessibility_id, "Search Wikipedia").displayed? }
  $driver.find_element(:accessibility_id, "Search Wikipedia").click
end

When("I type in {string}") do |search_keyword|
  $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_key(search_keyword)
  sleep 5
end

Then /^I should see results$/ do
  $driver.find_elements(:class, "android.widget.TextView").size.should > 0
end

If you are using our Sample App, the sample test below will install the Sample App (WordPress 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.

# WordPress Feature
Feature: Verify if displayed text matches entered text

Background:
  Given I try to find Text Button in Sample App

Scenario: Type a term
  When I type in "hello@browserstack.com" in the Text Input field
  Then I should get the entered text in the Text Output field
When /^I try to find Text Button in Sample App/ do
  $wait.until { $driver.find_element(:accessibility_id, "Text Button").displayed? }
  $driver.find_element(:accessibility_id, "Text Button").click
end

When("I type in {string} in the Text Input field") do |text|
  puts "Received #{text}"
  $wait.until { $driver.find_element(:accessibility_id, "Text Input").displayed? }
  text_input = $driver.find_element(:accessibility_id, "Text Input")
  text_input.send_keys(text+"\n")
  sleep 5
end

Then /^I should get the entered text in the Text Output field$/ do
  sleep 5
  text_output = $driver.find_element(:accessibility_id, "Text Output")
  text_output.text.should eq("hello@browserstack.com")
end

To actually run the test case, we need to integrate with BrowserStack as follows:

Integration with BrowserStack

Note: Running your Cucumber tests on BrowserStack requires a username and an access key.

Integration of Cucumber with BrowserStack is made possible by the use of the following module:

require 'yaml'
require 'rspec'
require 'selenium-cucumber'
require 'browserstack/local'
require 'appium_lib'

TASK_ID = (ENV['TASK_ID'] || 0).to_i
CONFIG_NAME = ENV['CONFIG_NAME'] || 'single'

CONFIG = YAML.load(File.read(File.join(File.dirname(__FILE__), "../../config/#{CONFIG_NAME}.config.yml")))
CONFIG['user'] = ENV['BROWSERSTACK_USERNAME'] || CONFIG['user']
CONFIG['key'] = ENV['BROWSERSTACK_ACCESS_KEY'] || CONFIG['key']

caps = CONFIG['common_caps'].merge(CONFIG['browser_caps'][TASK_ID])
$bs_local = nil

if ENV['BROWSERSTACK_APP_ID']
  caps['app'] = ENV['BROWSERSTACK_APP_ID']
end

if caps['browserstack.local'] && caps['browserstack.local'].to_s == 'true'
  $bs_local = BrowserStack::Local.new
  bs_local_args = { "key" => "#{CONFIG['key']}" }
  $bs_local.start(bs_local_args)
end

desired_caps = {
  caps: caps,
  appium_lib: {
    server_url: "https://#{CONFIG['user']}:#{CONFIG['key']}@#{CONFIG['server']}/wd/hub"
  }
}

begin
  $appium_driver = Appium::Driver.new(desired_caps, true)
  $driver = $appium_driver.start_driver
rescue Exception => e
  puts e.message
  Process.exit(0)
end

$wait = Selenium::WebDriver::Wait.new(:timeout => 30)

The module reads from the config file where you need to put the BrowserStack Hub URL and credentials. If the BROWSERSTACK_USERNAME and BROWSERSTACK_ACCESS_KEY are set in Environment variables, then that will take preference. Also, update the app_url(bs://….) obtained after uploading the App to the BrowserStack cloud in Step 2.

server: "hub-cloud.browserstack.com"
user: "YOUR_USERNAME"
key: "YOUR_ACCESS_KEY"

common_caps:
  "build": "cucumber-browserstack"
  "browserstack.debug": true

browser_caps:
    "device": "Google Pixel"
    "app": "your_app_url"
    "name": "single_test"
server: "hub-cloud.browserstack.com"
user: "YOUR_USERNAME"
key: "YOUR_ACCESS_KEY"

common_caps:
  "build": "cucumber-browserstack"
  "browserstack.debug": true

browser_caps:
    "device": "iPhone 7 Plus"
    "app": "your_app_url"
    "name": "single_test"

Run your test on BrowserStack using following command:

# Run using rake
bundle exec rake single
Note: Refer to our GitHub repository for a complete example: BrowserStack - Cucumber

4. Viewing test results

You can access results of your test sessions on the App Automate dashboard as well as using our REST API. 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.