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:
- Real Devices & Browsers on-demand — Ease of configuring the real devices and browsers you want to run tests on.
- Parallelization — Effortlessly manage test orchestration across parallel threads.
- 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.
View list of supported frameworks
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
Note: Platform-specific capabilities will take precedence over root-level capabilities.
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.
Example scenarios of using Selenium W3C or Selenium Legacy JSON
# 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:
Set in script/config | Set in browserstack.yml | Value considered | |
---|---|---|---|
"acceptInsecureCerts": true |
- | "acceptInsecureCerts": true |
|
"acceptInsecureCerts": true |
"acceptInsecureCerts": false |
"acceptInsecureCerts": false |
|
- | "acceptInsecureCerts": false |
"acceptInsecureCerts": false |
Use our BrowserStack SDK Configurator to set up your config file to run tests on BrowserStack.
Next steps
Check out some of the frequently asked questions.
We're sorry to hear that. Please share your feedback so we can do better
Contact our Support team for immediate help while we work on improving our docs.
We're continuously improving our docs. We'd love to know what you liked
We're sorry to hear that. Please share your feedback so we can do better
Contact our Support team for immediate help while we work on improving our docs.
We're continuously improving our docs. We'd love to know what you liked
Thank you for your valuable feedback!