How to Use the BrowserStack SDK for Cross-Browser Testing

BrowserStack SDK connects an existing automated test suite to BrowserStack so the suite can run against the browser and operating-system combinations you configure. For Selenium, configure those combinations in browserstack.yml; the documented setup flow does not require changing the test scripts. Every configured platform receives the tests, while parallelsPerPlatform separately controls test threads per platform. If the app is private or local, enable BrowserStack Local Testing for network access. [BrowserStack: How BrowserStack SDK works]

1. Check your test stack and target

Before installing anything, identify the test framework and runner, the language, and where the application runs. BrowserStack documents SDK support across Java, Node.js, C#, and Python ecosystems, but installation steps and runner configuration vary. Use the official quickstart for your specific combination; there is no single package command that applies to all stacks.

Runner and language: Record the framework, test runner, and SDK integration documented for that stack.
Target reachability: A public URL can be accessed normally; localhost, staging, and private-network targets may need Local Testing.
Coverage goal: Choose browser, OS, version, and device combinations based on your supported users and product risk.

Start with BrowserStack’s Selenium SDK guide for the workflow below, then select the official setup guide matching your language and runner for exact dependency and launch commands.

2. Install and connect the SDK for your runner

Follow the current BrowserStack quickstart for your chosen language and runner to add its SDK package or project dependency and provide the credentials and configuration required by that integration. The exact package name, version, file location, and command depend on the stack; do not copy a command from another language’s guide.

In the Selenium SDK flow, configuration in browserstack.yml directs execution to BrowserStack and the SDK adapts the run at runtime. BrowserStack says that test scripts can remain unchanged in this documented flow. Keep credentials in your CI secret store or environment rather than committing them to source control, and use the runner-specific instructions to pass them to the SDK.

3. Define a platform matrix

In the Selenium SDK, platforms selects the browser and operating-system combinations for the run. BrowserStack’s configuration examples place shared capabilities at the root and platform-specific details inside each platform entry. Tests run on every configured platform. Treat sample combinations as examples, not a universal compatibility recommendation. See BrowserStack’s SDK configuration reference for the supported fields and current examples.

A conceptual YAML shape looks like this; fill it with platform entries and capability names from the current Selenium SDK documentation, because valid values and catalog availability depend on the target environment:

# browserstack.yml — conceptual structure; use documented fields for your stack
common_capability: value
platforms:
  - browser: documented-browser-value
    operating_system: documented-os-value
  - browser: another-documented-browser-value
    operating_system: another-documented-os-value

Choose combinations using this checklist:

Include the browser families and versions you promise to support.
Include operating systems or device classes that materially affect rendering or behavior.
Prioritize combinations based on customer usage and product risk, rather than attempting every possible permutation.
Verify current platform availability in BrowserStack’s live platform list when finalizing the matrix.

A matrix multiplies the work: if you configure three platforms, each test is run on all three. Begin with a small representative set, then add coverage where it can catch a meaningful compatibility issue.

4. Set matrix breadth and test parallelism independently

platforms determines which browser/OS/device combinations are included. parallelsPerPlatform determines how many test threads run per platform. BrowserStack’s arithmetic example is three platforms × two parallels per platform = six parallel threads. It describes configured concurrency, not a guaranteed completion time or a promise that every account has six simultaneous sessions available. Check your account’s entitlements and ensure tests are independent before raising concurrency. [BrowserStack: Key BrowserStack SDK configurations]

Configuration choice	Effect
Add entries to `platforms`	Run the suite across more browser/OS/device combinations.
Increase `parallelsPerPlatform`	Run more test threads for each configured platform.
Omit `parallelsPerPlatform`	Run the configured platform matrix without that additional per-platform parallel setting.
Omit `platforms` and retain the parallel setting	Use the documented test-parallelism behavior without creating a platform matrix.

More parallel threads can reduce elapsed time when the suite and account support them, but they do not make unsafe shared test data independent. Avoid tests that race on the same account, records, or environment state; isolate data or serialize those cases.

5. Reach a private app with BrowserStack Local

BrowserStack Local Testing provides a connection from BrowserStack to sites and apps on localhost, staging, or private networks, including environments behind firewalls, proxies, or VPNs. Configure the Local connection using the SDK option suitable for your team: the Selenium SDK reference describes SDK-managed binary initialization and using a local identifier with an existing Local binary. Follow the relevant Local Testing overview and environment-specific network and flags documentation.

The tunnel provides reachability; it does not deploy the app or configure application authentication, test users, or test data. Confirm the target URL resolves from the local machine or network where the tunnel runs, then verify the team’s proxy and firewall setup using BrowserStack’s network guidance.

6. Understand configuration precedence

For Selenium, when the same capability is defined in both test code and browserstack.yml, the YAML value takes precedence according to BrowserStack’s SDK documentation. If a run uses a different browser, OS, or capability than expected, inspect the YAML configuration first, including shared root settings and platform-specific entries. [BrowserStack: How BrowserStack SDK works]

7. Run the suite and inspect the result

Use the runner-specific BrowserStack quickstart to launch the suite with the SDK and configuration file.
Confirm the build or session appears in BrowserStack and that each intended platform is represented.
Check the test runner’s results and BrowserStack session details for failures, capabilities, and logs.
On failure, determine whether it is a product defect, a test assumption, a configuration mismatch, a network issue, or an account concurrency limit before expanding the matrix.

CI/CD setup is runner-specific. Use the same language-specific SDK integration in CI, supply credentials through the CI’s secret mechanism, and make sure the configuration and Local Testing process are available to that job. BrowserStack’s generic SDK FAQ links to topics including CI/CD, multiple configuration files, environment variables, protocol compatibility, and logs.

8. Troubleshooting

Symptom	Likely cause	What to check
The run uses an unexpected browser or capability	`browserstack.yml` overrides duplicate test-code capabilities in the Selenium SDK.	Review shared and platform-level YAML values, then compare them with the test setup.
A localhost or staging URL cannot load	BrowserStack cannot reach the private target without a correctly configured Local connection.	Enable Local Testing and verify tunnel status, target reachability, and the environment’s proxy/firewall requirements.
The run does not cover all expected combinations	The platform matrix may not contain the intended entries, or the wrong configuration file may be used.	Inspect the loaded configuration and confirm every desired platform is listed.
Tests run more slowly than expected	Matrix breadth increases executions; parallelism may be omitted, limited, or constrained by account capacity.	Separate the number of platforms from `parallelsPerPlatform`; check account limits and test independence.
Parallel runs interfere with one another	Tests may share mutable users, records, or environment state.	Use isolated test data or serialize conflicting tests.
Capabilities or runner startup fail	Configuration syntax, capability names, SDK dependency, or runner integration may not match the selected stack.	Use the official guide for that exact language and runner, and validate fields against the current SDK parameter reference.
Local tunnel does not connect behind a proxy or firewall	The network setup may need environment-specific configuration.	Consult BrowserStack’s Local Testing network, flags, and generic FAQ documentation for the relevant setup.

For issues involving Local identifiers, CLI or environment variables, multiple config files, W3C versus JSON Wire Protocol, logs, or firewall allowlisting, use the relevant entry in the BrowserStack SDK generic FAQ; the correct fix depends on the runner and network.

9. Performance, reliability, and cost

Test count grows with platform breadth: every configured platform receives the suite. Per-platform parallelism can distribute work, but actual elapsed time depends on suite duration, test independence, account concurrency, startup overhead, and the selected environments. The cited BrowserStack documentation provides configuration arithmetic, not benchmark or completion-time guarantees.

For reliability, keep the matrix focused on supported customer environments, make tests independent where possible, and verify private-network connectivity before treating browser failures as application defects. For cost and capacity, consult your BrowserStack account entitlements and current plan details; no price or account limit is established by the SDK configuration documentation cited here.

10. Or skip the browser setup

If the job is to capture a clean page image or PDF rather than execute interactive browser tests, ScreenshotNeo is a website screenshot API and MCP server for developers. It does not replace a cross-browser test suite; it can handle screenshot capture with one request.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

See the ScreenshotNeo API documentation for request options. Its API also has runnable Python and Node.js examples for the same capture:

# Python
import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)

// Node.js
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

Cookie banners are accepted like a visitor and removed before capture, along with supported newsletter popups and chat widgets.
Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed; response headers report the page verdict and billing status.
An MCP server lets Claude, Cursor, and other MCP clients capture screenshots and PDFs or get page information.
The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 screenshots.

FAQ

Do I need to rewrite my existing Selenium tests?

BrowserStack’s documented Selenium SDK flow integrates at runtime and says test scripts can remain unchanged. Follow the exact integration guide for your runner.

Does adding a platform run only selected tests on it?

In the documented Selenium configuration, all tests run on every configured platform. Use runner-specific mechanisms to select tests if needed.

Can I use BrowserStack SDK with a private staging site?

Yes. Configure BrowserStack Local Testing to provide network reachability to private, staging, or localhost targets.

Does ScreenshotNeo replace BrowserStack cross-browser testing?

No. ScreenshotNeo captures pages as images or PDFs; BrowserStack SDK runs automated tests across configured browser and OS environments.