Prerequisites

• You need to have BrowserStack Username and Access Key, which you can find in your account profile. If you have not created an account yet, you can sign up for a Free Trial.
• Pytestv4+, Python3 and Pip3 is installed on your machine.

Run a sample build

Run a sample Pytest test build on BrowserStack:

1. Get our sample project using one of the following options:

   • Option 1: Download the project browserstack/pytest-browserstack

   • Option 2: Clone the sample repository:

       # Clone sample Python repository
       git clone -b main https://github.com/browserstack/pytest-browserstack
       cd pytest-browserstack
     

2. Set up the dependencies: Run the following commands on your terminal/command prompt to install the required dependencies.

   MacOS/Linux:

    # Create virtual environment
    python3 -m venv env
    source env/bin/activate
    # Install the required packages
    pip3 install -r requirements.txt
   

   Windows:

    # Create virtual environment
    python3 -m venv env
    env\Scripts\activate
    # Install the required packages
    pip3 install -r requirements.txt
   

3. Configure the browserstack.yml file: Make sure to keep the turboScale flag as true.

The parallelsPerPlatform property determines the number of parallel threads to be executed. BrowserStack’s SDK runner will select the best strategy based on the configured value.

• Example 1: If you have configured 3 platforms and set parallelsPerPlatform as 2: a total of 6 (3 x 2) parallel threads will be used on BrowserStack. Your test suite would be split into 2 parts, each part running on all 3 configured platforms concurrently.

• Example 2: If you have configured 1 platform and set parallelsPerPlatform as 15: a total of 15 (1 x 15) parallel threads will be used on BrowserStack. Your test suite would be split into 15 parts, each part running on the configured platform concurrently.

1. Run your build on BrowserStack: From the root directory of this project, run the following command:

    browserstack-sdk pytest -s tests/bstack-sample-test.py
   

2. View test results on the Automate TurboScale dashboard to see your test results.

Integrate your test suite

a. Install BrowserStack Python SDK

Execute the following commands to install BrowserStack Python SDK for plug-and-play integration of your test suite with BrowserStack.

python3 -m pip install browserstack-sdk
browserstack-sdk setup --username YOUR_BROWSERSTACK_USERNAME --key YOUR_BROWSERSTACK_ACCESSKEY

b. Configure your browserstack.yml file

The auto-generated browserstack.yml file situated in the root location of your project holds all the required settings to run tests on BrowserStack. Make sure to keep the turboScale flag as true.

By default, BrowserStack Automate TurboScale provides prettified session logs and a video of the entire test. Additionally, you can enable the following features:

• Test Observability: Enables Test Observability, an advanced test reporting and debugging tool that helps you analyze test failures dramatically faster. If enabled, Test Observability collects test data using the SDK. This capability is enabled (set to true) by default.

• Network logs: Enables network capture for the session in HAR format. Might reduce session performance slightly.

• Console logs: Set the remote browser’s console log levels.

c. Test Localhost/Staging websites

BrowserStack Local Testing feature connects with test suites that test your localhost URL or staging websites. Enable browserstackLocal to true in the browserstack.yml file to turn on this feature.

d. Use BrowserStack’s reporting features

You can leverage BrowserStack’s extensive reporting features using the following capabilities:

• Build Name: Set a name to your build (usually the same as the build ID that’s on your CI/CD platform).
  • Accepted characters: A-Z, a-z, 0-9, ., :, -, [], /, @, &, ', _. All other characters are ignored.
  • Character limit: 255

• Build Identifier: Select a dynamic build identifier that appends to the build name and generates a unique name on the BrowserStack dashboard.

• Project Name: Set a project name for your project.

e. Run your test suite on BrowserStack

Your test suite is now ready to run on BrowserStack! Prepend browserstack-sdk before your existing run commands to execute your tests on BrowserStack using the Pytest SDK.

Before:

pytest <path-to-test-files>

After:

browserstack-sdk pytest <path-to-test-files>

Setup authentication

Set environment variables for BrowserStack credentials:

# Set these values in your ~/.zprofile (zsh) or ~/.profile (bash)
export BROWSERSTACK_USERNAME=YOUR_BROWSERSTACK_USERNAME
export BROWSERSTACK_ACCESS_KEY=YOUR_BROWSERSTACK_ACCESSKEY

It is recommended that you store your credentials as environment variables and use those environment variables in your test script.

Step 2: Migrate your test cases

a. Use BrowserStack credentials in your test cases

Update your test cases to read BrowserStack credentials from environment variables and update the Selenium hub URL to the BrowserStack remote hub URL: https://hub-ft.browserstack.com/wd/hub

import os
from selenium import webdriver

# Other imports and desired_cap definition goes here

BROWSERSTACK_USERNAME = os.environ.get("BROWSERSTACK_USERNAME")
BROWSERSTACK_ACCESS_KEY = os.environ.get("BROWSERSTACK_ACCESS_KEY")
URL = "https://{}:{}@hub-ft.browserstack.com/wd/hub".format(BROWSERSTACK_USERNAME, BROWSERSTACK_ACCESS_KEY)

driver = webdriver.Remote(command_executor=URL, options=options)

# Rest of the test case goes here

b. Add configurations and capabilities

After you set up authentication in your test scripts, you can now add configurations, such as adding browser-OS combinations, test suite organization details, test status that you want to track, and then run your tests.

# Add the following options to your test script
from selenium.webdriver.chrome.options import Options

options = Options()
bstack_options = {
    'os': 'Linux',
    'browserVersion': 'latest'
}
options.set_capability('bstack:options', bstack_options)
options.set_capability('browserName', 'Chrome')

c. Organize tests

# Testing the home page
bstack_options.update({
    'projectName': 'Marketing Website v2',
    'buildName': 'alpha_0.1.7',
    'sessionName': 'Home page must have a title'
})
options.set_capability('bstack:options', bstack_options)

Use the following capabilities for naming your tests and builds. This ensures effective debugging, test reporting, and build execution time analysis.

• Use a new buildName name every time you run your test cases. This ensures that sessions are logically grouped under a unique build name and helps you monitor the health of your test suite effectively.
  
  
• A build can only have a maximum of 1000 tests and post that a new build gets created with a -1 suffixed to the original build name.

d. Mark Test as Passed or Failed

To mark whether your test has passed or failed on BrowserStack, use the JavaScript executor in your test script. You can mark a test as passed or failed based on your test assertions.

The arguments passed in the JavaScript method for setting the status and the corresponding reason of the test are status and reason:

• status accepts either passed or failed as the value.
• reason accepts a string value.

For marking test as passed

driver.execute_script('browserstack_executor: {"action": "setSessionStatus", "arguments": {"status":"passed", "reason": "Yaay! my sample test passed"}}')

For marking test as failed

driver.execute_script('browserstack_executor: {"action": "setSessionStatus", "arguments": {"status":"failed","reason": "Oops! my sample test failed"}}')

e. Set Up Debugging Capabilities

Use the following common debugging capabilities for your tests:

bstack_options.update({
    'networkLogs': 'true',  # To enable network logs
    'consoleLogs': 'info',  # To enable console logs at the info level. You can also use other log levels here
})
options.set_capability('bstack:options', bstack_options)

• Console Logs with log level errors are enabled by default. Set the consoleLogs capability to enable different log levels, such as warnings, info, verbose, errors, and disable.

• Set the networkLogs capability to capture the browser’s performance data such as network traffic, latency, HTTP requests, and responses in a HAR format.