Selenium with Gauge

Your guide to running Selenium Webdriver tests with Gauge on BrowserStack.

Gauge repo on Github


Running your Gauge tests on our cloud setup is simple and straightforward. For the code to run successfully on your machine, please ensure the following:

Get started with a sample test, which opens Google’s homepage, searches for BrowserStack, and asserts for the title of the search results page


The following scenario performs a Google search and makes sure that
the results match.

Search for BrowserStack
tags: search, smoke

* On the homepage
* Search for term "BrowserStack"
* Make sure the page title is "BrowserStack - Google Search"
package com.browserstack.gauge.pages;

import static org.junit.Assert.assertEquals;
import org.openqa.selenium.By;
import org.openqa.selenium.WebDriver;
import org.openqa.selenium.WebElement;

import com.thoughtworks.gauge.Step;

public class SearchSpec {
    private final WebDriver driver;
    private WebElement element;

    public SearchSpec() {
        this.driver = DriverFactory.getDriver();

    @Step("On the homepage")
    public void navigateToHomePage() {

    @Step("Search for term <term>")
    public void searchFor(String term) {
        element = driver.findElement("q"));

    @Step("Make sure the page title is <term>")
    public void checkPageTitle(String term) {
        assertEquals(term, driver.getTitle());

To actually run the test case, we need to integrate with BrowserStack as follows.

Integration with BrowserStack

Note: Running your Gauge tests on BrowserStack requires a username and an access key.

Integrating your Gauge tests with BrowserStack involves updating the .properties files with your BrowserStack Username and Access Key

To obtain your username and access keys, sign up for a Free Trial or purchase a plan.

# The credentials associated with your BrowserStack account.

Additionally, you will need to create a remote webdriver that points to the BrowserStack hub and sets the capabilities based on the .properties files

package com.browserstack.gauge.pages;

import com.thoughtworks.gauge.AfterSpec;
import com.thoughtworks.gauge.BeforeSpec;
import org.openqa.selenium.WebDriver;
import org.openqa.selenium.remote.DesiredCapabilities;
import org.openqa.selenium.remote.RemoteWebDriver;

import java.util.concurrent.TimeUnit;

public class DriverFactory {
    private static final String USERNAME = System.getenv("BROWSERSTACK_USERNAME");
    private static final String AUTOMATE_KEY = System.getenv("BROWSERSTACK_ACCESS_KEY");
    private static final String URL = "https://" + USERNAME + ":" + AUTOMATE_KEY + "";

    private static WebDriver driver;

    public static WebDriver getDriver() {
        return driver;

    public void setUp() {
        try {
            DesiredCapabilities caps = new DesiredCapabilities();

            // Capabilities from environment
            caps.setCapability("browser", System.getenv("BROWSER"));
            caps.setCapability("browser_version", System.getenv("BROWSER_VERSION"));
            caps.setCapability("name", "Bstack-[Gauge] Sample Test");
            caps.setCapability("build", System.getenv("BUILD"));
            caps.setCapability("os", System.getenv("OS"));
            caps.setCapability("os_version", System.getenv("OS_VERSION"));

            // Hardcoded capabilities
            caps.setCapability("browserstack.debug", "true");

            URL remoteURL = new URL(URL);

            driver = new RemoteWebDriver(remoteURL, caps);
            driver.manage().timeouts().implicitlyWait(10, TimeUnit.SECONDS);

        } catch (MalformedURLException e) {



    public void tearDown() {

Run your test on BrowserStack using the following command:

mvn test

Mark tests as pass / fail

It is possible to mark tests as either a pass or a fail, using the following snippet:

// Method to mark test as pass / fail

public static void mark() throws URISyntaxException, UnsupportedEncodingException, IOException {
  URI uri = new URI("<session-id>.json");
  HttpPut putRequest = new HttpPut(uri);

  ArrayList<NameValuePair> nameValuePairs = new ArrayList<NameValuePair>();
  nameValuePairs.add((new BasicNameValuePair("status", "completed")));
  nameValuePairs.add((new BasicNameValuePair("reason", "")));
  putRequest.setEntity(new UrlEncodedFormEntity(nameValuePairs));


The two potential values for status can either be passed or failed. Optionally, a reason can also be passed.

Debug your app

BrowserStack provides a range of debugging tools to help you quickly identify and fix bugs you discover through your automated tests.

  • Text Logs

Text Logs are a comprehensive record of your test. They are used to identify all the steps executed in the test and troubleshoot errors for the failed step. Text Logs are accessible from the Automate dashboard or via our REST API.

  • Visual Logs

Visual Logs automatically capture the screenshots generated at every Selenium command run through your Gauge script. Visual logs help with debugging the exact step and the page where failure occurred. They also help identify any layout or design related issues with your web pages on different browsers.

Visual Logs are disabled by default. In order to enable Visual Logs you will need to set browserstack.debug capability to true:

caps.setCapability("browserstack.debug", "true");
  • Video Recording

Every test run on the BrowserStack Selenium grid is recorded exactly as it is executed on our remote machine. This feature is particularly helpful whenever a browser test fails. You can access videos from Automate Dashboard for each session. You can also download the videos from the Dashboard or retrieve a link to download the video using our REST API.

Note: Video recording increases test execution time slightly. You can disable this feature by setting the capability to false.

caps.setCapability("", "false");

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?


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

Talk to automation expert