How to Run Selenium 4 Tests on BrowserStack Automate

To run Selenium 4 tests on BrowserStack Automate, connect your existing test suite to BrowserStack using its language SDK or a documented remote WebDriver setup, provide your BrowserStack username and access key securely, select browser and operating system targets, and run your usual test command. For Java Maven, BrowserStack currently lists JDK 11+, Maven 3.6+, and Selenium 4.23+ as prerequisites; those requirements are specific to that route. For a private or local application, establish BrowserStack Local and enable the local capability as well. BrowserStack’s Selenium getting-started guide supports three entry points: a sample build, an existing suite, or a local app.

Choose an integration route

Use the route that matches your project and test framework:

Sample project: Learn the cloud build and results workflow before changing a production suite.
BrowserStack SDK: Let the SDK read BrowserStack configuration, including target platforms and supported execution settings. This is the documented path for the Java and Python integration guides.
Direct remote session: Supply remote WebDriver capabilities through your Selenium binding when that is the appropriate documented route for your language and framework. Verify the current endpoint and capability syntax in BrowserStack’s language-specific documentation rather than copying a configuration from another language.

Before choosing, check language and framework support, how the project manages capabilities, whether the application is publicly reachable, and how many browser/platform combinations you need to run. SDK behavior and platform availability can change, so confirm current details in the relevant official guide.

Prepare credentials and prerequisites

Create or use a BrowserStack account with Automate access. You need the account username and access key.
Store credentials in environment variables or your CI secret store. Do not commit the access key to source control.
Check the official getting-started page for prerequisites specific to your language and build tool.
Choose browser and operating system combinations from BrowserStack’s current capability catalog.

Java Maven prerequisites

BrowserStack’s reviewed Java Maven getting-started instructions list JDK 11 or newer, Maven 3.6 or newer, and Selenium 4.23 or newer using W3C capabilities. Treat these as requirements for that documented Java Maven path, not as universal Selenium or Python requirements.

Java Maven SDK setup

The Java SDK workflow adds BrowserStack’s SDK to the project and places a browserstack.yml file at the project root. The file describes credentials, target platforms, and BrowserStack options. Use the exact dependency and CLI instructions in the current Java getting-started guide; dependency versions and commands can change.

# Example environment setup for a POSIX shell; use your CI secret manager in CI
export BROWSERSTACK_USERNAME="your_username"
export BROWSERSTACK_ACCESS_KEY="your_access_key"

# From the Java project root, run the build command used by your project
mvn test

Create the configuration according to BrowserStack’s current Java SDK schema. A conceptual shape is:

# browserstack.yml (illustrative structure; verify current schema and option names)
userName: ${BROWSERSTACK_USERNAME}
accessKey: ${BROWSERSTACK_ACCESS_KEY}
platforms:
  - browserName: Chrome
    os: Windows
    osVersion: "11"

The platform values above illustrate the configuration shape, not a promise that every combination is currently available. Select a supported combination from the live capability catalog. BrowserStack documents that when a capability appears both in the test script and browserstack.yml, the configuration-file value takes precedence. If a setting seems ignored, inspect both locations.

Run the project using its regular Maven test command after SDK integration. For a Gradle project or another Java setup, follow the matching official integration instructions rather than assuming Maven commands apply.

Python SDK setup

BrowserStack’s Python onboarding guide uses Python 3 and pip, and its integration guide describes installing the BrowserStack Python SDK, configuring credentials as environment variables, setting up the project, and creating browserstack.yml. Follow the guide’s current install and setup commands because package and CLI details may change. The reviewed integration documentation describes support for Chrome on desktop and Android; do not infer a broader matrix from that page.

# Set credentials without putting them in the test file
export BROWSERSTACK_USERNAME="your_username"
export BROWSERSTACK_ACCESS_KEY="your_access_key"

# After following BrowserStack's current SDK installation and setup steps:
pytest

Use the test runner command appropriate for your suite. If you use unittest or another runner, configure the SDK integration for that runner as documented. See the official Python integration guide for supported configuration and platform details.

Configure capabilities and browser targets

Capabilities are key-value settings for a cloud test session. They identify the browser and platform and can include BrowserStack-specific options. Keep the requested matrix small while debugging, then add the remaining targets once one session succeeds.

Browser and OS: Choose supported combinations from the current capability catalog.
Parallel execution: Configure concurrency using the SDK settings and account capacity available to your project.
Local Testing: Enable it only when the remote browser must reach a local, staging, or internally hosted app.
Configuration precedence: For the documented SDK behavior, browserstack.yml overrides a duplicate capability in the test script.

Read the BrowserStack configuration documentation and capability reference for the current property names and supported values.

Test a local or staging application

A remote browser cannot ordinarily reach a web app bound only to your machine or an internal network. BrowserStack Local creates a connection that gives the remote session access to that app. Start the Local tunnel using the current language-binding or command-line instructions, then enable the local capability in the session configuration. Both parts are needed: the tunnel must be running, and the test session must request local access.

Start BrowserStack Local using the setup instructions for your integration.
Set the documented local capability or SDK option.
Navigate the test to the app’s reachable local or staging address.
Keep the tunnel alive until the test sessions finish, then stop it.

See BrowserStack Local Testing documentation for the current tunnel and capability instructions.

Run the suite and inspect results

Start with one test and one supported browser/platform combination.
Run the normal project command, such as mvn test or the configured Python test runner.
Check the command output for session startup or authentication errors.
Open the Automate dashboard and inspect the build and session results.
After the first session passes, expand the platform matrix and enable the desired parallelization settings.

BrowserStack’s get-started workflow includes inspecting dashboard results for sample and integrated builds. Use those session results alongside local test output when diagnosing failures.

Troubleshooting

Symptom	Likely cause	What to check
Authentication fails	Missing, misspelled, or stale username/access key; environment variables are not available to the process.	Confirm the secret names and values in the shell or CI job. Ensure secrets are available to the test process, and rotate exposed credentials.
Requested browser session does not start	The browser/OS combination or capability value is unsupported or incorrectly named.	Validate the combination and capability keys against BrowserStack’s current catalog and reference.
A script capability appears ignored	The same capability is set in `browserstack.yml`, whose value takes precedence in the documented SDK behavior.	Search both the test code and configuration file, then keep one intentional value or align them.
Remote browser cannot open localhost or staging	BrowserStack Local is not running, or the session did not enable the local capability.	Start the tunnel, enable local access in session configuration, and verify the app address from the tunnel host.
Tests pass locally but fail remotely	Different browser behavior, viewport, timing, network access, or environment assumptions.	Inspect the Automate session result, make waits explicit, and confirm the target environment is reachable by the remote session.
SDK setup command or dependency fails	Instructions or versions do not match the project’s language/build setup, or have changed.	Use the current language-specific official guide; do not apply Java Maven prerequisites to a Python project.
CI starts tests but no build is visible	The configured SDK integration did not launch or associate the run as expected.	Review setup output, configuration location, test command, and the integration guide’s run instructions.

Performance, reliability, and cost considerations

Remote execution adds session startup and network time, so a single cloud test may take longer than a local browser run. Parallel execution can shorten total suite time when configured and available, but it does not fix tests that share mutable state or depend on execution order. Begin with a small matrix, stabilize one session, and then add targets.

For reliability, keep credentials in a secret store, pin dependencies in the project’s normal dependency mechanism, verify current platform support, and use explicit waits for asynchronous page behavior. For private applications, treat tunnel lifecycle as part of the test job and ensure it remains available for all sessions.

Automate is a paid cloud testing service; exact plan limits and pricing can change. Check BrowserStack’s current plan and account details before estimating suite costs. The cited setup material does not establish a fixed per-session price or a performance benchmark.

Or skip the browser setup

If the task is to capture a page image or PDF rather than run interactive Selenium assertions, ScreenshotNeo provides a one-request screenshot API. See the ScreenshotNeo API documentation.

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

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)

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, newsletter popups, and chat widgets are removed before capture; each cleanup step can be turned off.
Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers identify the page verdict and billing status.
An MCP server lets Claude, Cursor, and other MCP clients use screenshot, page-info, and PDF tools.
The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000.

Create a free ScreenshotNeo account for 1,000 screenshots a month with no card.

FAQ

Can I start without integrating my full suite?

Yes. BrowserStack documents a sample-build path, which lets you learn the workflow before integrating an existing project.

Does BrowserStack Local replace the application server?

No. It provides remote access through a tunnel; your local or internal application still needs to be running and reachable from the tunnel host.

Does a screenshot API run Selenium assertions?

No. ScreenshotNeo captures an image or PDF. Use BrowserStack Automate when you need to execute interactive browser tests and assertions.