Parallel Testing with App Automate

Parallel Testing is a BrowserStack feature that allows you to run same test or different tests simultaneously across different device and OS version combinations. It will help you to reduce the run time of your test suite, resulting in faster build times and releases.

For example, execution time of a test suite which takes 30 minutes running sequentially can be brought down to as low as 3 minutes by running 10 parallel tests (with the assumption that all your test cases take approximately the same time).

Note: Your App Automate plan needs to have sufficient licenses to be able to run parallel tests. If you trigger more tests than what you subscribed for, they will either be queued or discarded.

In this guide, you will learn how to :

Setup your environment
Upload your app
Configure and run parallel tests
View test execution results

Note: If you have already gone through our Run your first test guide, you can skip to the Configure and run parallel tests section.

1. Setup your environment

You will need a BrowserStack username and access_key. If you haven’t created an account yet, sign up for a free trial or purchase a paid plan. After signup, you can obtain your access credentials from account settings
Ensure you have Python 2.7+ installed on your system. You can download updated Python versions from Python.org. Please note that Lettuce framework doesn’t support Python 3 yet.
Ensure you have the package manager pip installed on your system. To install pip, follow steps outlined in the installation guide
You will need access to your Android app (.apk or .aab file) or 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 or sample iOS app.

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 app on App Automate :

OS X and Linux
Windows

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

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

Ensure that @ symbol is prepended to the file path in the above request. A sample response for the above request is shown below:

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

Please note the app_url value returned in the API response (bs://j3c874..... in the above example). We will use this value to set the application under test while configuring the test later on.

Note:

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.
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 parallel tests

Setup your project

Clone the Lettuce sample integration code from our GitHub repository.

git clone https://github.com/browserstack/lettuce-appium-app-browserstack.git

Next, execute the following command from the project’s base directory to install required dependencies:

# Test an android app
pip install -r android/requirements.txt

# Test an iOS app
pip install -r ios/requirements.txt

This will install requisite dependencies including Appium’s Python client library :

lettuce==0.2.23
lettuce_webdriver==0.3.5
selenium==3.141.0
Appium-Python-Client==0.52
browserstack-local==1.2.2
nose==1.3.7
paver==1.3.4
psutil==5.7.2

Configure Appium’s desired capabilities

Desired capabilities are a series of key-value pairs that allow you to configure your Appium tests on BrowserStack. The following capabilities are required :

browserstack.user capability : Its used to specify your Browserstack username credential
browserstack.key capability : Its used to specify your Browserstack access_key credential
app capability : Its used to specify your uploaded app that will be installed on device during test execution. Use the app_url obtained in Upload your App section to set its value.
device capability : Its used to specify the BrowserStack device you want to run the test on.

In the Lettuce sample integration code, Appium’s desired capabilities are defined in the config.json file located in the examples/run-parallel-tests directory. Note the use of environments key to specify a list of devices for parallel test execution.

Android
iOS

{
    "capabilities": {
        "browserstack.user" : "YOUR_USERNAME",
        "browserstack.key" : "YOUR_ACCESS_KEY",
        "project": "First Lettuce Android Project",
        "build": "Lettuce Android Parallel",
        "name": "parallel_test",
        "browserstack.debug": true,
        "app": "bs://<app-id>"
    },
    "environments": [{
      "device": "Google Pixel 3",
      "os_version": "9.0"
    }, {
      "device": "Samsung Galaxy S10e",
      "os_version": "9.0"
    }]
  }

{
    "capabilities": {
        "browserstack.user" : "YOUR_USERNAME",
        "browserstack.key" : "YOUR_ACCESS_KEY",
        "project": "First Lettuce iOS Project",
        "build": "Lettuce iOS Parallel",
        "name": "parallel_test",
        "browserstack.debug": true,
        "app": "bs://<app-id>"
    },
    "environments": [{
      "device": "iPhone 11 Pro",
      "os_version": "13"
    }, {
      "device": "iPhone 11 Pro Max",
      "os_version": "13"
    }]
}

Note:

You can also provide BrowserStack access credentials by setting BROWSERSTACK_USERNAME & BROWSERSTACK_ACCESS_KEY environment variables
You can explore other Appium capabilities using our Capabilities Builder

Create remote Webdriver

Once you have configured desired capabilities, you can initialize an Appium webdriver to test remotely on BrowserStack. In order to do so, you need to use a remote BrowserStack URL along with desired capabilities.

In the Lettuce sample integration code, the remote Webdriver is initialised in the terrain.py file located in the examples/run-parallel-tests/features directory as shown below :

#...

# Initialize the remote Webdriver using BrowserStack remote URL
# and desired capabilities defined above
 context.browser = webdriver.Remote (
        desired_capabilities=desired_capabilities,
        command_executor="https://hub-cloud.browserstack.com/wd/hub"
 )

#...

Setup your test-case

This step will help you setup a test case with Lettuce framework that will execute in parallel on multiple devices. In the Lettuce sample integration code, we have provided a sample test-case in examples/run-parallel-tests/features directory for BrowserStack’s sample apps. If you are testing your own app, please modify the test case accordingly.

Android
iOS

Define the scenario you want to test in the app in parallel_test.feature file:

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

Provide the implementation for the steps used in the scenario in steps.py file:

import time
from lettuce import *
from nose.tools import assert_equals
from lettuce_webdriver.util import AssertContextManager
from appium.webdriver.common.mobileby import MobileBy
from selenium.webdriver.support.ui import WebDriverWait
from selenium.webdriver.support import expected_conditions as EC

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

Define the scenario you want to test in the app in parallel_test.feature file:

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

Provide the implementation for the steps used in the scenario in steps.py file:

import time
from lettuce import *
from nose.tools import assert_equals
from lettuce_webdriver.util import AssertContextManager
from appium.webdriver.common.mobileby import MobileBy
from selenium.webdriver.support.ui import WebDriverWait
from selenium.webdriver.support import expected_conditions as EC
import os

@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

Run the test

You are ready to run parallel tests on BrowserStack. In the Lettuce sample integration code, switch to examples/run-parallel-tests directory, and run the test using command :

# Run using paver
paver run parallel_tests

4. View test execution results

You can access the test execution results, and debugging information such as video recording, network and device logs on App Automate dashboard or using our REST APIs.