BrowserStack SDK - Core Concepts

Learn about BrowserStack SDK concepts, understand the ease of integration it offers, and the important components of SDK.

Introduction

BrowserStack SDK is a plug-and-play solution available in multiple programming languages, such as Java, NodeJS, Python, and C# that enables you to run your entire test suite on the BrowserStack Cloud with no code changes. Using the SDK reduces the integration time from hours to a few minutes.

To get started, you need to install the SDK and set up the configuration file. Your tests will automatically run on the BrowserStack cloud with no modifications to your existing test suite.

Following are some of the key features that the SDK offers:

1. Real Devices & Browsers on-demand — Ease of configuring the real devices and browsers you want to run tests on.
2. Parallelization — Effortlessly manage test orchestration across parallel threads.
3. BrowserStack Local — Test your sites on localhost. developemnt, or staging environments without any manual network setup.

How it works

The BrowserStack SDK integrates into your existing test suite framework, intercepts your test scripts, and then modifies the execution during runtime to run tests on BrowserStack.

The capabilities defined in the SDK configuration override your existing Selenium/Appium webdriver URL and capabilities, that is, your tests will run on the BrowserStack cloud irrespective of your webdriver URL being configured to your local grid. Since all capabilities are defined through the SDK configuration, changes to your test script are not required.

SDK also integrates with popular test runners or frameworks to simplify cross-browser testing and device parallelism on BrowserStack.

Compatibility

The SDK is designed to be compatible with most testing frameworks, especially with those that are not optimized inherently to support Selenium-based testing. For example, JUnit, TestNG, NUnit etc. do not abstract webdriver management to run cross-browser or device tests in parallel.

SDK Configuration file

The SDK uses the browserstack.yml config file to set capabilities. It contains the platforms (browsers/devices) you want to test on along with other Selenium and BrowserStack capabilities.

Structure of your config file

The SDK config file contains the following pre-defined properties, and can also contain any desired Selenium/Appium capability as well.

• Access Credentials

  Your BrowserStack userName and accessKey are required to authenticate your tests.

• Framework

  The testing framework, for example, testng, that is used in your test suite. This enables BrowserStack’s SDK to automatically capture test context and send it to BrowserStack for reporting and insights.

• Platforms

  The different browser-device combinations you want to test on BrowserStack. Any platform-specific capability can be added within an individual object.

• Parallels per Platform

  The number of parallel threads to be used for each platform set. The SDK selects the best orchestration strategy based on the testing framework and configured value.

  Example scenarios:

  Example 1: If you have configured 3 platforms and set parallelsPerPlatform as 2, a total of 6 (2 * 3) parallel threads are used on BrowserStack.

  Example 2: If you have configured 1 platform and set parallelsPerPlatform as 5, a total of 5 (1 * 5) parallel threads are used on BrowserStack

• BrowserStack Local

  BrowserStack Local is a tunneling feature that enables testing your localhost or privately hosted websites (staging, pre-prod) on BrowserStack. The BrowserStack SDK automatically manages the BrowserStack Local tunnel when running your build.

  BrowserStack Local supports all advanced use cases and restricted networks. Contact our support team for assistance in configuring BrowserStack Local for your enterprise.

• Adding Selenium/Appium capabilities

  The capabilities defined in the SDK configuration file can be categorized as:

  • Root level: These capabilities are applied to all browsers and devices in the platforms.
  • Platform-specific level: These capabilities are applied only to the platform object they are defined under.

# browserstack.yml

# Platforms object contains all the browser/device combinations
# you want to test on.
platforms:
  - os: OS X
    osVersion: Big Sur
    browser: Chrome
    browserVersion: latest
    acceptInsecureCerts: false # Applies only to this platform and takes precedence
  - os: Windows
    osVersion: 10
    browser: Edge
    browserVersion: latest

# Root level capabilities apply to all platforms
acceptInsecureCerts: true

W3C and JSON wire Protocol Compatibility

Regardless of whether your test suite is based on legacy JSONWP or standardized W3C-based capabilities, the SDK config file is intelligent and compatible with both the Selenium protocols.

Both Selenium capabilities and BrowserStack-specific capabilities coexist in the SDK configuration file. You don’t need to nest capabilities under the bstack:options object.

The BrowserStack SDK automatically converts all the capabilities in the configuration file into valid W3C syntax.

# browserstack.yml

# Using Selenium W3C
acceptInsecureCerts: true

# Using Selenium Legacy JSON
acceptSslCerts: true

# Add BrowserStack features
networkLogs: true # bstack:options not required

Duplicate capabilities - order of precedence

The BrowserStack SDK merges capabilities from your test script with the SDK configuration file.

If the same capability is defined in your test script and the SDK configuration file, the values set in the SDK configuration file take precedence.

The following table lists some common scenarios with duplicate capabilities:

Next steps

Check out some of the frequently asked questions.