Skip to main content

Integrate Your Test Suite with BrowserStack

This section helps you migrate your existing test suite to run on BrowserStack Automate. It also covers key features and best practice recommendations for smooth integration.

Setup authentication

Step 1: Set environment variables for BrowserStack credentials

# Set these values in your ~/.zprofile (zsh) or ~/.profile (bash)
export BROWSERSTACK_USERNAME="YOUR_USERNAME"
export BROWSERSTACK_ACCESS_KEY="YOUR_ACCESS_KEY"
# setx.exe does not set the environment variable in the current command prompt, but it will be available in subsequent command prompts
setx BROWSERSTACK_USERNAME "YOUR_USERNAME"
setx BROWSERSTACK_ACCESS_KEY "YOUR_ACCESS_KEY"

# Verify whether the variables have been set
echo BROWSERSTACK_USERNAME
echo BROWSERSTACK_ACCESS_KEY

Alternatively, you can also add your BrowserStack credentials in the test cases as shown in the following example:

public static void main(String[] args) {
try (Playwright playwright = Playwright.create()) {
    JsonObject capabilitiesObject = new JsonObject();
    capabilitiesObject.addProperty("browserstack.username", "BROWSERSTACK_USERNAME");
    capabilitiesObject.addProperty("browserstack.accessKey", "BROWSERSTACK_ACCESS_KEY");    

In the previous section, we set up BrowserStack credentials directly in the test script and the sample build. However, for a production-grade integration we recommend you store your credentials as environment variables and use those environment variables in your code.

Step 2: Connect CDP endpoint

Connect to the CDP endpoint at BrowserStack as shown in the following example:

single.java
BrowserType chromium = playwright.chromium(); 
String caps = URLEncoder.encode(capabilitiesObject.toString(), "utf-8");
String ws_endpoint = "wss://cdp.browserstack.com/playwright?caps=" + caps;
Browser browser = chromium.connect(ws_endpoint);
Page page = browser.newPage();        

Migrate your test cases

This section helps you with all the configuration changes, commonly used features, and best practices for a smooth migration of your existing test cases to BrowserStack.

Step 1: Run test suite on a single browser

We recommend running your build using a single browser like Chrome, WebKit, or Firefox to begin with. This isolates issues during the migration phase and helps with faster debugging. Refer the capabilities as shown to use Chrome.
Once you’ve migrated your test cases or have achieved stability with Chrome or Firefox, you can set up cross-browser testing.

test-script.java
public static void main(String[] args) {
try (Playwright playwright = Playwright.create()) {
    JsonObject capabilitiesObject = new JsonObject();
    capabilitiesObject.addProperty("browser", "chrome");    // allowed browsers are `chrome`, `edge`, `playwright-chromium`, `playwright-firefox` and `playwright-webkit`
    capabilitiesObject.addProperty("browser_version", "latest");
    capabilitiesObject.addProperty("os", "osx");
    capabilitiesObject.addProperty("os_version", "catalina");

Step 2: Organize tests

Naming your tests and builds properly is crucial for effective debugging, test reporting, and analyzing your build execution time. Here are the capabilities you can use.

Capability Description
sessionName Name for your test case. Example, Homepage - Get started
buildName CI/CD job or build name. Example, Website build #23, staging_1.3.27
projectName Name of your project. Example, Marketing Website
Note: Check out how to name and organize your Playwright tests.
test-script.java
public class PlaywrightLocalUsingBindingsTest {
public static void main(String[] args) {
try (Playwright playwright = Playwright.create()) {
    JsonObject capabilitiesObject = new JsonObject();
    capabilitiesObject.addProperty("name", "Playwright first local test");
    capabilitiesObject.addProperty("build", "playwright-java-3");
    capabilitiesObject.addProperty("project", "playwright-java-3");

Step 3: Mark test as passed or failed

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

test-script.java
try {
    page.navigate("http://localhost:45691");
    page.waitForFunction("document" +
            ".querySelector(\"body\")" +
            ".innerText" +
            ".includes(\"This is an internal server for BrowserStack Local\")");

    // following line of code is responsible for marking the status of the test on BrowserStack as 'passed'. You can use this code in your after hook after each test
    markTestStatus("<status>", "<reason>", page);
} catch (Exception err) {
    markTestStatus("status>", "<reason>", page);
}

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 value in string datatype
Note: Check out how to mark your Playwright tests as passed or failed.

Step 4: Set up debugging capabilities

BrowserStack provides the following debugging capabilities for your tests:

  • Use visual logs capability to capture screenshots at every Playwright command automatically. You can enable visual logs by using the browserstack.debug capability.
  • Console Logs with log level ‘errors’ are enabled by default. You can enable different log levels viz. warnings, info, verbose, errors, and disable using the browserstack.console capability.
  • Network Logs capture the browser’s performance data such as network traffic, latency, HTTP requests, and responses in a HAR format. You can enable network logs using the browserstack.networkLogs capability.

Enable these debugging capabilities as shown in the following code example:

test-script.java
public static void main(String[] args) {
try (Playwright playwright = Playwright.create()) {
    JsonObject capabilitiesObject = new JsonObject();
    HashMap<String, Boolean> networkLogsOptions = new HashMap<>();
    networkLogsOptions.put("captureContent", true);
    caps.setCapability("browserstack.networkLogs", true);
    caps.setCapability("browserstack.networkLogsOptions", networkLogsOptions);
    capabilitiesObject.addProperty("browserstack.debug", "true");
    capabilitiesObject.addProperty("browserstack.console", "disable");
    capabilitiesObject.addProperty("browserstack.local", "true");

Connect your website under test

BrowserStack can integrate with test suites pointing to your localhost URL, staging environment, and even websites behind one or more proxies/firewalls. To test using localhost, perform the following steps:

Step 1: Install the package

Install the BrowserStackLocal binary by adding it as a dependency in the pom.xml file.

pom.xml
<dependency>
    <groupId>com.browserstack</groupId>
    <artifactId>browserstack-local-java</artifactId>
    <version>1.0.6</version>
    <scope>compile</scope>
</dependency>

Step 2: Set the access credentials in your test script

Set the required dependecies such as Local configuration, Credentials, and browser-device combinations in your test script as follows:

test-script.java
public class PlaywrightLocalUsingBindingsTest {
public static void main(String[] args) {
try (Playwright playwright = Playwright.create()) {
    JsonObject capabilitiesObject = new JsonObject();
    capabilitiesObject.addProperty("browser", "chrome");    // allowed browsers are `chrome`, `edge`, `playwright-chromium`, `playwright-firefox` and `playwright-webkit`
    capabilitiesObject.addProperty("browser_version", "latest");
    capabilitiesObject.addProperty("os", "osx");
    capabilitiesObject.addProperty("os_version", "catalina");
    capabilitiesObject.addProperty("name", "Playwright first local test");
    capabilitiesObject.addProperty("build", "playwright-java-3");
    capabilitiesObject.addProperty("browserstack.username", "BROWSERSTACK_USERNAME");
    capabilitiesObject.addProperty("browserstack.accessKey", "BROWSERSTACK_ACCESS_KEY");
    capabilitiesObject.addProperty("browserstack.local", "true");

    //Creates an instance of Local
    Local bsLocal = new Local();

    // You can also set an environment variable - "BROWSERSTACK_ACCESS_KEY".
    HashMap<String, String> bsLocalArgs = new HashMap<String, String>();
    bsLocalArgs.put("key", "BROWSERSTACK_ACCESS_KEY");

    // Starts the Local instance with the required arguments
    bsLocal.start(bsLocalArgs);

Set the bslocalArgs variable to your BrowserStack Access key and and use the following methods provided by the local library to manage your local connection:

Method Description
bs_local.start() Expects bs_local object. Returns a callback when the tunnel has started successfully. Your test script should start executing after this callback has been invoked.
bs_local.stop() Call this method after your test suite is complete.
bs_local.isRunning() Check if the BrowserStack local instance is running.

Step 3: Add the browserstack.local capability

Copy and set the browserstack.local capability to true in your test script file as shown in the following code example:

test-script.java
public static void main(String[] args) {
try (Playwright playwright = Playwright.create()) {
    JsonObject capabilitiesObject = new JsonObject();
    capabilitiesObject.addProperty("browserstack.local", "true");

You may face errors running your test script if any other capability is enabled before setting up browserstack.local.

Step 4: Run a test using Browserstack Local

Execute the command to run your local test.

Step 1: Download BrowserStack Local

mac OS
Windows (XP and above)
Linux(64 bit)
Linux(32 bit)

Step 2: Unzip the binary

Unzip the downloaded file and move it to a folder/directory from which you have permission to start it using your command line or terminal.

Step 3: Run the binary using your command line or terminal

Copy the following command to initiate the BrowserStack Local connection:

# Run this command in your terminal to start the BrowserStack Local binary. Your working directory should be where you have the downloaded binary.
./BrowserStackLocal --key <YOUR_ACCESS_KEY>

Step 4: Set up configuration to enable browserstack.local

Copy the capabilities as shown into your configuration file:

test-script.java
 capabilitiesObject.addProperty("browserstack.local", "true");

Next Steps

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

Is this page helping you?

Yes
No

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!

Talk to an Expert
Talk to an Expert