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 Lettuce on real Android and iOS devices on BrowserStack. This guide will help you get started with your first test.

1. Setup

Ensure you have Lettuce libraries installed.

# Install using pip
pip install lettuce

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.

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 Lettuce.

# Wikipedia Feature
Feature: Wikipedia Search Functionality
    Scenario: can find search results
        Given I open the app and search for keyword "BrowserStack"
            Then Search results should appear

@step('I open the app and search for keyword "(.*?)"')
def search_with_keyword(step, keyword):
    with AssertContextManager(step):
        search_element = WebDriverWait(world.browser, 10).until(
            EC.presence_of_element_located((MobileBy.ACCESSIBILITY_ID, "Search Wikipedia"))
        )
        search_element.click()

        search_input = WebDriverWait(world.browser, 30).until(
            EC.element_to_be_clickable((MobileBy.ID, "org.wikipedia.alpha:id/search_src_text"))
        )
        search_input.send_keys(keyword)
        time.sleep(5)


@step(u'Search results should appear')
def verfiy_result_should_present(step):
    elems = world.browser.find_elements_by_class_name("android.widget.TextView")
    assert len(elems) > 0, "results not populated"

# WordPress Feature
Feature: Text Verification in Sample App
    Scenario: Displayed Text should match Input Text
        Given I open the app and click on Text Button
            Then Type "hello@browserstack.com" and hit enter
            Then Verify displayed text matches input text

@step('I open the app and click on Text Button')
def click_on_textbutton(step):
    with AssertContextManager(step):
        element = WebDriverWait(world.browser, 30).until(
            EC.presence_of_element_located((MobileBy.ACCESSIBILITY_ID, "Text Button"))
        )
        element.click()


@step(u'Type "(.*?)" and hit enter')
def enter_text(step, text):
    text_input = WebDriverWait(world.browser, 30).until(
        EC.element_to_be_clickable((MobileBy.ACCESSIBILITY_ID, "Text Input"))
    )
    text_input.send_keys(text+"\n")
    time.sleep(5)


@step(u'Verify displayed text matches input text')
def verfiy_match(step):
    text_output = WebDriverWait(world.browser, 30).until(
        EC.element_to_be_clickable((MobileBy.ACCESSIBILITY_ID, "Text Output"))
    )
    if text_output!=None and text_output.text=="hello@browserstack.com":
        assert True
    else:
        assert False

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

Integration with BrowserStack

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

from lettuce import before, after, world
from browserstack.local import Local
from appium import webdriver
import os, json

CONFIG_FILE = os.environ['CONFIG_FILE'] if 'CONFIG_FILE' in os.environ else 'config/single.json'
TASK_ID = int(os.environ['TASK_ID']) if 'TASK_ID' in os.environ else 0

with open(CONFIG_FILE) as data_file:
    CONFIG = json.load(data_file)

bs_local = None

BROWSERSTACK_USERNAME = os.environ['BROWSERSTACK_USERNAME'] if 'BROWSERSTACK_USERNAME' in os.environ else CONFIG['user']
BROWSERSTACK_ACCESS_KEY = os.environ['BROWSERSTACK_ACCESS_KEY'] if 'BROWSERSTACK_ACCESS_KEY' in os.environ else CONFIG['key']

def start_local():
    """Code to start browserstack local before start of test."""
    global bs_local
    bs_local = Local()
    bs_local_args = { "key": BROWSERSTACK_ACCESS_KEY, "forcelocal": "true" }
    # bs_local.stop()
    bs_local.start(**bs_local_args)

def stop_local():
    """Code to stop browserstack local after end of test."""
    global bs_local
    if bs_local is not None:
        bs_local.stop()


@before.each_feature
def setup_browser(feature):
    desired_capabilities = CONFIG['devices'][TASK_ID]

    for key in CONFIG["capabilities"]:
        if key not in desired_capabilities:
            desired_capabilities[key] = CONFIG["capabilities"][key]

    if 'BROWSERSTACK_APP_ID' in os.environ:
        desired_capabilities['app'] = os.environ['BROWSERSTACK_APP_ID']

    if "browserstack.local" in desired_capabilities and desired_capabilities["browserstack.local"]:
        start_local()

    world.browser = webdriver.Remote(
        desired_capabilities=desired_capabilities,
        command_executor="https://%s:%s@%s/wd/hub" % (BROWSERSTACK_USERNAME, BROWSERSTACK_ACCESS_KEY, CONFIG['server'])
    )

@after.each_feature
def cleanup_browser(feature):
    world.browser.quit()
    stop_local()

The module reads from 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 a 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",

  "capabilities": {
    "build": "lettuce-browserstack",
    "name": "single_test",
    "browserstack.debug": true,
    "app": "your_app_url"
  },

  "devices": [{
    "device": "Google Pixel"
  }]
}

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

  "capabilities": {
    "build": "lettuce-browserstack",
    "name": "single_test",
    "browserstack.debug": true,
    "app": "your_app_url"
  },

  "devices": [{
    "device": "iPhone 7"
  }]
}

Run your test on BrowserStack using following command:

# Run using paver
paver run single

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.