Migrate your test suites

A migration guide to help you run your existing test suites on BrowserStack Automate.

Overview

Migrating your existing Selenium tests to run on BrowserStack Automate is simple. In this guide, we will see how you’ll authenticate your test session, use the desired capabilities in your tests and run tests on the browsers in our cloud.

Authentication

Every test that runs on BrowserStack needs a username and access key so that we can authenticate your test runs, associate the builds to your accounts and help you run tests in parallel as per the parallels you purchased.

You can find your username and access key in the Automate dashboard. You’ll need to use these credentials while connecting to our platform to run the tests. For example:

public static final String USERNAME = "YOUR_USERNAME";
public static final String AUTOMATE_KEY = "YOUR_ACCESS_KEY";
public static final String URL = "https://" + USERNAME + ":" + AUTOMATE_KEY + "@hub-cloud.browserstack.com/wd/hub";

var userName = "YOUR_USERNAME";
var accessKey = "YOUR_ACCESS_KEY"
var browserstackURL = 'https://' + userName + ':' + accessKey + '@hub-cloud.browserstack.com/wd/hub';

string USERNAME = "YOUR_USERNAME";
string AUTOMATE_KEY = "YOUR_ACCESS_KEY";

$USERNAME = "YOUR_USERNAME";
$AUTOMATE_KEY = "YOUR_ACCESS_KEY";
$BROWSERSTACK_URL = "https://$USERNAME:$AUTOMATE_KEY@hub-cloud.browserstack.com/wd/hub";

BROWSERSTACK_URL = 'https://YOUR_USERNAME:YOUR_ACCESS_KEY@hub-cloud.browserstack.com/wd/hub'

USERNAME = "YOUR_USERNAME"
AUTOMATE_KEY = "YOUR_ACCESS_KEY"
browserstack_url = "https://" + USERNAME + ":" + AUTOMATE_KEY + "@hub-cloud.browserstack.com/wd/hub"

Capabilities

Capabilities (or desired capabilities) are configuration options that let you specify your desired browser, OS or a device to run the tests on, and set up the browser for testing in a desired manner before running the test.

Let’s say you want to run your tests on Chrome (version 80) on Windows 10. This is how you’d mention the same in capabilities:

Selenium 4 W3C
Selenium Legacy JSON

      Java
    

      Node.js
    

      C#
    

      PHP
    

      Python
    

      Ruby
    
MutableCapabilities capabilities = new MutableCapabilities();
capabilities.setCapability("browserName", "Chrome");
capabilities.setCapability("browserVersion", "latest");
HashMap<String, Object> browserstackOptions = new HashMap<String, Object>();
browserstackOptions.put("os", "Windows");
browserstackOptions.put("osVersion", "11");
browserstackOptions.put("projectName", "Sample sandbox project");
browserstackOptions.put("buildName", "Build #1");
browserstackOptions.put("sessionName", "My First Test");
capabilities.setCapability("bstack:options", browserstackOptions);
var capabilities = {
'bstack:options' : {
"os" : "Windows",
"osVersion" : "11",
"projectName" : "Sample sandbox project",
"buildName" : "Build #1",
"sessionName" : "My First Test",
},
"browserName" : "Chrome",
"browserVersion" : "latest",
}
IWebDriver driver;
// for Chrome
OpenQA.Selenium.Chrome.ChromeOptions capability = new OpenQA.Selenium.Chrome.ChromeOptions();

// for Firefox
OpenQA.Selenium.Firefox.FirefoxOptions capability = new OpenQA.Selenium.Firefox.FirefoxOptions();

// for Safari
OpenQA.Selenium.Safari.SafariOptions capability = new OpenQA.Selenium.Safari.SafariOptions();

ChromeOptions capabilities = new ChromeOptions();
capabilities.BrowserVersion = "latest";
Dictionary<string, object> browserstackOptions = new Dictionary<string, object>();
browserstackOptions.Add("os", "Windows");
browserstackOptions.Add("osVersion", "11");
browserstackOptions.Add("projectName", "Sample sandbox project");
browserstackOptions.Add("buildName", "Build #1");
browserstackOptions.Add("sessionName", "My First Test");
capabilities.AddAdditionalOption("bstack:options", browserstackOptions);
$caps = array(
'bstack:options' => array(
    "os" => "Windows",
    "osVersion" => "11",
    "projectName" => "Sample sandbox project",
    "buildName" => "Build #1",
    "sessionName" => "My First Test",
),
"browserName" => "Chrome",
"browserVersion" => "latest",
)
desired_cap = {
'bstack:options' : {
"os" : "Windows",
"osVersion" : "11",
"projectName" : "Sample sandbox project",
"buildName" : "Build #1",
"sessionName" : "My First Test",
},
"browserName" : "Chrome",
"browserVersion" : "latest",
}
capabilities = {
'bstack:options' => {
"os" => "Windows",
"osVersion" => "11",
"projectName" => "Sample sandbox project",
"buildName" => "Build #1",
"sessionName" => "My First Test",
"local" => "false",
"seleniumVersion" => "4.0.0",
},
"browserName" => "Chrome",
"browserVersion" => "latest",
}

      Java
    

      Node.js
    

      C#
    

      PHP
    

      Python
    

      Ruby
    
DesiredCapabilities caps = new DesiredCapabilities();

caps.setCapability("os", "Windows");
caps.setCapability("os_version", "10");
caps.setCapability("browser", "Chrome");
caps.setCapability("browser_version", "80");
caps.setCapability("name", "My First Test");
caps.setCapability("build", "Build #1");
caps.setCapability("project", "Sample sandbox project");
var capabilities = {
  'os': 'Windows',
  'os_version': '10',
  'browserName': 'Chrome',
  'browser_version': '80',
  'name': 'My First Test',
  'build': 'Build #1',
  'project': 'Sample sandbox project'
}
IWebDriver driver;
// for Chrome
OpenQA.Selenium.Chrome.ChromeOptions capability = new OpenQA.Selenium.Chrome.ChromeOptions();

// for Firefox
OpenQA.Selenium.Firefox.FirefoxOptions capability = new OpenQA.Selenium.Firefox.FirefoxOptions();

// for Safari
OpenQA.Selenium.Safari.SafariOptions capability = new OpenQA.Selenium.Safari.SafariOptions();

capability.AddAdditionalCapability("os", "Windows", true);
capability.AddAdditionalCapability("os_version", "10", true);
capability.AddAdditionalCapability("browser", "Chrome", true);
capability.AddAdditionalCapability("browser_version", "latest", true);
capability.AddAdditionalCapability("browserstack.user", "YOUR_USERNAME", true);
capability.AddAdditionalCapability("browserstack.key", "YOUR_ACCESS_KEY", true);
capability.AddAdditionalCapability("name", "My First Test", true);
capability.AddAdditionalCapability("build", "Build #1", true);
capability.AddAdditionalCapability("project", "Sample sandbox project", true);
$caps = array(

  'os' => 'Windows',
  'os_version' => '10',
  'browser' => 'Chrome',
  'browser_version' => '80',
  'name' => 'My First Test',
  'build' => 'Build #1',
  'project' => 'Sample sandbox project'
);
desired_cap = {
    'os': 'Windows',
    'os_version': '10',
    'browser': 'Chrome',
    'browser_version': '80',
    'name': 'My First Test',
    'build': 'Build #1',
    'project': 'Sample sandbox project',
}
caps = Selenium::WebDriver::Remote::Capabilities.new

caps['os'] = 'Windows'
caps['os_version'] = '10'
caps['browser'] = 'Chrome'
caps['browser_version'] = '80'
caps['name'] = 'My First Test'
caps['build'] = 'Build #1'
caps['project'] = 'Sample sandbox project'

Running the tests on Remote WebDriver

Now that you are aware of how to authenticate and mention the capabilities, let’s see how to put it all together and start running your tests on Automate.

If you were running tests on your local machine until now, you will probably need to change your test script to start using a remote WebDriver along with your desired capabilities.

Just send the capabilities to https://hub-cloud.browserstack.com/wd/hub with your authentication details, and we are all set! Here is how it is done:

Selenium 4 W3C
Selenium Legacy JSON

      Java
    

      Node.js
    

      C#
    

      PHP
    

      Python
    

      Ruby
    
package com.browserstack.app;

import org.openqa.selenium.By;
import org.openqa.selenium.Platform;
import org.openqa.selenium.WebDriver;
import org.openqa.selenium.WebElement;
import org.openqa.selenium.MutableCapabilities;
import org.openqa.selenium.remote.RemoteWebDriver;
import java.net.URL;
import java.util.HashMap;

public class BrowserStackSampleTest {
    public static final String USERNAME = "YOUR_USERNAME";
    public static final String AUTOMATE_KEY = "YOUR_ACCESS_KEY";
    public static final String URL = "https://" + USERNAME + ":" + AUTOMATE_KEY + "@hub-cloud.browserstack.com/wd/hub";
    public static void main(String[] args) throws Exception {
        MutableCapabilities capabilities = new MutableCapabilities();
        capabilities.setCapability("browserName", "Chrome");
        capabilities.setCapability("browserVersion", "latest");
        HashMap<String, Object> browserstackOptions = new HashMap<String, Object>();
        browserstackOptions.put("os", "Windows");
        browserstackOptions.put("osVersion", "11");
        browserstackOptions.put("projectName", "Sample sandbox project");
        browserstackOptions.put("buildName", "Build #1");
        browserstackOptions.put("sessionName", "My First Test");
        capabilities.setCapability("bstack:options", browserstackOptions);
        WebDriver driver = new RemoteWebDriver(new URL(URL), capabilities);
        driver.get("http://www.google.com");

        // Your test script like you usually write

        driver.quit();
    }
}
var webdriver = require('selenium-webdriver');

var userName = "YOUR_USERNAME";
var accessKey = "YOUR_ACCESS_KEY"
var browserstackURL = 'https://' + userName + ':' + accessKey + '@hub-cloud.browserstack.com/wd/hub';


var capabilities = {
  'bstack:options' : {
  "os" : "Windows",
  "osVersion" : "11",
  "projectName" : "Sample sandbox project",
  "buildName" : "Build #1",
  "sessionName" : "My First Test",
  },
  "browserName" : "Chrome",
  "browserVersion" : "latest",
  }

var driver = new webdriver.Builder().
usingServer(browserstackURL).
withCapabilities(capabilities).
build();

driver.get('http://www.google.com').then(function() {
  // Your test script like you usually write

  driver.quit();
});
using System;
using OpenQA.Selenium;
using OpenQA.Selenium.Chrome;
using OpenQA.Selenium.Remote;

namespace run_browserstack
{
    class Program
    {
        static void Main(string[] args)
        {
            string USERNAME = "YOUR_USERNAME";
            string AUTOMATE_KEY = "YOUR_ACCESS_KEY";

            OpenQA.Selenium.Chrome.ChromeOptions capability = new OpenQA.Selenium.Chrome.ChromeOptions();

            // for Firefox
            // OpenQA.Selenium.Firefox.FirefoxOptions capability = new OpenQA.Selenium.Firefox.FirefoxOptions();

            // for Safari
            // OpenQA.Selenium.Safari.SafariOptions capability = new OpenQA.Selenium.Safari.SafariOptions();

            ChromeOptions capabilities = new ChromeOptions();
            capabilities.BrowserVersion = "latest";
            Dictionary<string, object> browserstackOptions = new Dictionary<string, object>();
            browserstackOptions.Add("userName", USERNAME);
            browserstackOptions.Add("accessKey", AUTOMATE_KEY);
            browserstackOptions.Add("os", "Windows");
            browserstackOptions.Add("osVersion", "11");
            browserstackOptions.Add("projectName", "Sample sandbox project");
            browserstackOptions.Add("buildName", "Build #1");
            browserstackOptions.Add("sessionName", "My First Test");
            capabilities.AddAdditionalOption("bstack:options", browserstackOptions);

            IWebDriver driver;
            driver = new RemoteWebDriver(
              new Uri("https://hub-cloud.browserstack.com/wd/hub/"), capabilities
            );
            driver.Navigate().GoToUrl("http://www.google.com");

            // Your test script like you usually write

            driver.Quit();
        }
    }
}
<?php

  require_once('vendor/autoload.php');
  use Facebook\WebDriver\Remote\RemoteWebDriver;
  use Facebook\WebDriver\WebDriverBy;

  $USERNAME = "YOUR_USERNAME";
  $AUTOMATE_KEY = "YOUR_ACCESS_KEY";
  $BROWSERSTACK_URL = "https://$USERNAME:$AUTOMATE_KEY@hub-cloud.browserstack.com/wd/hub";

  $caps = array(
  'bstack:options' => array(
    "os" => "Windows",
    "osVersion" => "11",
    "projectName" => "Sample sandbox project",
    "buildName" => "Build #1",
    "sessionName" => "My First Test",
  ),
  "browserName" => "Chrome",
  "browserVersion" => "latest",
  )

  $web_driver = RemoteWebDriver::create(
      $BROWSERSTACK_URL,
      $caps
  );

  $web_driver->get("https://google.com");

  // Your test script like you usually write

  $web_driver->quit();
from selenium import webdriver

BROWSERSTACK_URL = 'https://YOUR_USERNAME:YOUR_ACCESS_KEY@hub-cloud.browserstack.com/wd/hub'

desired_cap = {
'bstack:options' : {
"os" : "Windows",
"osVersion" : "11",
"projectName" : "Sample sandbox project",
"buildName" : "Build #1",
"sessionName" : "My First Test",
},
"browserName" : "Chrome",
"browserVersion" : "latest",
}

driver = webdriver.Remote(
    command_executor=BROWSERSTACK_URL,
    desired_capabilities=desired_cap
)

driver.get("https://www.google.com")

# Your test script like you usually write

driver.quit()
require 'rubygems'
require 'selenium-webdriver'

caps = Selenium::WebDriver::Remote::Capabilities.new

USERNAME = 'YOUR_USERNAME'.freeze
AUTOMATE_KEY = 'YOUR_ACCESS_KEY'.freeze
browserstack_url = 'https://' + USERNAME + ':' + AUTOMATE_KEY + '@hub-cloud.browserstack.com/wd/hub'

capabilities = {
'bstack:options' => {
"os" => "Windows",
"osVersion" => "11",
"projectName" => "Sample sandbox project",
"buildName" => "Build #1",
"sessionName" => "My First Test",
"local" => "false",
"seleniumVersion" => "4.0.0",
},
"browserName" => "Chrome",
"browserVersion" => "latest",
}

driver = Selenium::WebDriver.for(:remote,
                                 url: browserstack_url,
                                 desired_capabilities: caps)
driver.navigate.to 'https://www.google.com'

# Your test script like you usually write

driver.quit

      Java
    

      Node.js
    

      C#
    

      PHP
    

      Python
    

      Ruby
    
import org.openqa.selenium.By;
import org.openqa.selenium.Platform;
import org.openqa.selenium.WebDriver;
import org.openqa.selenium.WebElement;
import org.openqa.selenium.remote.DesiredCapabilities;
import org.openqa.selenium.remote.RemoteWebDriver;
import java.net.URL;

public class BrowserStackSampleTest {
public static final String USERNAME = "YOUR_USERNAME";
public static final String AUTOMATE_KEY = "YOUR_ACCESS_KEY";
public static final String URL = "https://" + USERNAME + ":" + AUTOMATE_KEY + "@hub-cloud.browserstack.com/wd/hub";
public static void main(String[] args) throws Exception {
        DesiredCapabilities caps = new DesiredCapabilities();

        caps.setCapability("os", "Windows");
        caps.setCapability("os_version", "10");
        caps.setCapability("browser", "Chrome");
        caps.setCapability("browser_version", "80");
        caps.setCapability("name", "My First Test");
        caps.setCapability("build", "Build #1");
        caps.setCapability("project", "Sample sandbox project");

        WebDriver driver = new RemoteWebDriver(new URL(URL), caps);
        driver.get("http://www.google.com");

        // Your test script like you usually write

        driver.quit();
}
}
var webdriver = require('selenium-webdriver');

var userName = "YOUR_USERNAME";
var accessKey = "YOUR_ACCESS_KEY"
var browserstackURL = 'https://' + userName + ':' + accessKey + '@hub-cloud.browserstack.com/wd/hub';

var capabilities = {
  'os': 'Windows',
  'os_version': '10',
  'browserName': 'Chrome',
  'browser_version': '80',
  'name': 'My First Test',
  'build': 'Build #1',
  'project': 'Sample sandbox project'
}

var driver = new webdriver.Builder().
usingServer(browserstackURL).
withCapabilities(capabilities).
build();

driver.get('http://www.google.com').then(function() {
  // Your test script like you usually write

  driver.quit();
});
using System;
using OpenQA.Selenium;
using OpenQA.Selenium.Chrome;
using OpenQA.Selenium.Remote;

namespace SeleniumTest {
  class Program {
    static void Main(string[] args) {
      string USERNAME = "YOUR_USERNAME";
      string AUTOMATE_KEY = "YOUR_ACCESS_KEY";

      OpenQA.Selenium.Chrome.ChromeOptions capability = new OpenQA.Selenium.Chrome.ChromeOptions();

      // for Firefox
      // OpenQA.Selenium.Firefox.FirefoxOptions capability = new OpenQA.Selenium.Firefox.FirefoxOptions();
      
      // for Safari
      // OpenQA.Selenium.Safari.SafariOptions capability = new OpenQA.Selenium.Safari.SafariOptions();

      capability.AddAdditionalCapability("os", "Windows", true);
      capability.AddAdditionalCapability("os_version", "10", true);
      capability.AddAdditionalCapability("browser", "Chrome", true);
      capability.AddAdditionalCapability("browser_version", "latest", true);
      capability.AddAdditionalCapability("browserstack.user", USERNAME, true);
      capability.AddAdditionalCapability("browserstack.key", AUTOMATE_KEY, true);
      capability.AddAdditionalCapability("name", "My First Test", true);
      capability.AddAdditionalCapability("build", "Build #1", true);
      capability.AddAdditionalCapability("project", "Sample sandbox project", true);

      IWebDriver driver;
      driver = new RemoteWebDriver(
        new Uri("https://hub-cloud.browserstack.com/wd/hub/"), capability
      );
      driver.Navigate().GoToUrl("http://www.google.com");

      // Your test script like you usually write

      driver.Quit();
    }
  }
}
<?php

  require_once('vendor/autoload.php');
  use Facebook\WebDriver\Remote\RemoteWebDriver;
  use Facebook\WebDriver\WebDriverBy;

  $USERNAME = "YOUR_USERNAME";
  $AUTOMATE_KEY = "YOUR_ACCESS_KEY";
  $BROWSERSTACK_URL = "https://$USERNAME:$AUTOMATE_KEY@hub-cloud.browserstack.com/wd/hub";

  $caps = array(

    'os' => 'Windows',
    'os_version' => '10',
    'browser' => 'Chrome',
    'browser_version' => '80',
    'name' => 'My First Test',
    'build' => 'Build #1',
    'project' => 'Sample sandbox project'
  );

  $web_driver = RemoteWebDriver::create(
      $BROWSERSTACK_URL,
      $caps
  );

  $web_driver->get("https://google.com");

  // Your test script like you usually write

  $web_driver->quit();
from selenium import webdriver

BROWSERSTACK_URL = 'https://YOUR_USERNAME:YOUR_ACCESS_KEY@hub-cloud.browserstack.com/wd/hub'

desired_cap = {
    'os': 'Windows',
    'os_version': '10',
    'browser': 'Chrome',
    'browser_version': '80',
    'name': 'My First Test',
    'build': 'Build #1',
    'project': 'Sample sandbox project',
}

driver = webdriver.Remote(
    command_executor=BROWSERSTACK_URL,
    desired_capabilities=desired_cap
)

driver.get("https://www.google.com")

# Your test script like you usually write

driver.quit()
require 'rubygems'
require 'selenium-webdriver'

caps = Selenium::WebDriver::Remote::Capabilities.new

USERNAME = 'YOUR_USERNAME'.freeze
AUTOMATE_KEY = 'YOUR_ACCESS_KEY'.freeze
browserstack_url = 'https://' + USERNAME + ':' + AUTOMATE_KEY + '@hub-cloud.browserstack.com/wd/hub'

caps['os'] = 'Windows'
caps['os_version'] = '10'
caps['browser'] = 'Chrome'
caps['browser_version'] = '80'
caps['name'] = 'My First Test'
caps['build'] = 'Build #1'
caps['project'] = 'Sample sandbox project'

driver = Selenium::WebDriver.for(:remote,
                                 url: browserstack_url,
                                 desired_capabilities: caps)
driver.navigate.to 'https://www.google.com'

# Your test script like you usually write

driver.quit

Note: Make sure you quit the driver (which basically closes the browser) once you are done with your test. We time out any test that is idle (i.e., no Selenium command received) for 90 seconds.

Test your private websites on BrowserStack

BrowserStack has a feature called Local testing, using which you can make the remote browsers of BrowserStack access your privately hosted websites. You can read more about Local testing and how it works.

Protip: See documentation for setting up Local testing in the language/framework of your choice.

How to migrate if you are using one of the test frameworks?

We have extensive documentation covering all the major test frameworks. Follow the steps below to migrate your test cases to run on BrowserStack:

Go to the getting-started page of your selected framework. (Note: Select the framework of your choice using the blue modal on the left sidebar, if not already done)
Every framework (not language) that we have documented, has a link to a repository right at the beginning of the page. Clone that repository.
Follow the instructions in the repo’s readme to run the sample single/parallel/local tests using the framework.
Next, you can start migrating your test cases in the structure of the repository which already has the basic code written to communicate with BrowserStack.

Do not worry if you do not find your framework listed. You can reach out to our support team and we assure you that if your framework is Selenium based and works locally, then you will be able to run your tests on BrowserStack as well.

Next Steps

Did this page help you?

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

This page has exactly what I am looking for
This content & code samples are accurate and up-to-date
The content on this page is easy to understand
Other (please tell us more below)

Any additional feedback?

Thank you for your valuable feedback

Is this page helping you?

Yes

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

This page has exactly what I am looking for
This content & code samples are accurate and up-to-date
The content on this page is easy to understand
Other (please tell us more below)

Any additional feedback?

Thank you for your valuable feedback!