Integrate BrowserStack Automate with Jenkins

Integrate your Selenium test suite with Jenkins and the BrowserStack Selenium grid using our plugin.

Introduction

Jenkins is an open-source Continuous Integration (CI) server, which automates the build and deploy process of your web applications. By running your Selenium test suite in Jenkins, you also automate testing as part of the build process. Add BrowserStack to the mix, and your web apps can be tested across 2000+ real devices and desktop browsers. BrowserStack lets you integrate your Selenium tests with Jenkins using a plugin that connects your Jenkins CI server to the BrowserStack Selenium Grid.

Use the BrowserStack Jenkins plugin to:

  • Configure your BrowserStack credentials for your Jenkins jobs.
  • Set up and tear down the BrowserStack Local binary for testing internal, development and staging environments.
  • Embed BrowserStack test results, including video, logs, and screenshots in your Jenkins job results.

Prerequisites

You need the following set up before you begin

  • An existing Jenkins CI server (version 1.580.1+)
  • A BrowserStack account

Installing the Jenkins plugin

To run your Selenium tests with Jenkins on BrowserStack, you will first need to download our Jenkins plugin. Before installing the plugin, ensure you have the necessary privileges to administer your Jenkins installation. We recommend doing this when there are no active build jobs running on Jenkins.

  1. Click on Manage Jenkins > Manage Plugins.
  2. Click on the Available Plugins tab.
  3. In the search box type BrowserStack.
  4. Choose BrowserStack from the list of available plugins. browserstack automate jenkins plugin
  5. Check the box and install the plugin.
  6. Once the plugin has been successfully installed you will be able to see it in the list of Installed plugins. browserstack automate jenkins plugin
Note: If the BrowserStack plugin doesn’t show up in the list of Available plugins, click on the Check Now button to force Jenkins to pull the latest available plugins from Jenkins update center.

Configuring BrowserStack credentials

Once you’ve installed the plugin, you will need to configure your BrowserStack credentials to complete the integration between Jenkins and your Selenium Webdriver tests. This can be done by either using Jenkins UI or using a Jenkinsfile.

Follow these steps to configure BrowserStack inside Jenkins:

  1. Go to Manage Jenkins > Configure System.
  2. Under the BrowserStack section, click on the Add button next to BrowserStack Credentials. browserstack automate jenkins plugin
  3. Enter your BrowserStack Username and Access Key which you can find on your BrowserStack Account Settings page. browserstack automate jenkins plugin
  4. Save your changes.

Once you add your credentials as mentioned in the above section, Jenkins generates an ID which is used in the Jenkinsfile.

From the Jenkins home page, click on Credentials from the left menu. You can copy the ID for BrowserStack credentials. browserstack automate jenkins plugin

Use the sample code in your Jenkinsfile:

browserstack(credentialsId: '<browserstackCredentialsID>') {
    // code for executing test cases
}

The above Jenkinsfile code block can also be generated with the help of Pipeline Syntax generator tool available in Jenkins.

To generate the step snippet with Snippet Generator:

  1. Navigate to the Pipeline Syntax from a configured Pipeline, or at <jenkins-ip>:<port>/pipeline-syntax.
  2. Select the browserstack:BrowserStack in the Sample Step dropdown menu.
  3. Use the dynamically populated area below the Sample Step dropdown to configure the selected step.
  4. Click Generate Pipeline Script to create a snippet of Pipeline which can be copied and pasted into a Pipeline. browserstack automate jenkins plugin

Configuring BrowserStack Local

BrowserStack Local Testing allows you to test web applications hosted on private, development, and internal servers. With the Local testing binary, you can create a secure, private connection between the BrowserStack Selenium Grid and your internal servers. The BrowserStack Jenkins plugin is responsible for:

  • Downloading the BrowserStack local binary for every platform that the build job is running on
  • Setting up and tearing down the secure tunnel.
Note: BrowserStack Local can only be configured per job and not via global configuration.

The BrowserStack Jenkins plugin sets the following environment variables:

BROWSERSTACK_USERNAME
BROWSERSTACK_ACCESS_KEY
BROWSERSTACK_LOCAL
BROWSERSTACK_LOCAL_IDENTIFIER

Use these environment variables to set the capabilities in your tests. For example:

String username = System.getenv("BROWSERSTACK_USERNAME");
String accessKey = System.getenv("BROWSERSTACK_ACCESS_KEY");
String browserstackLocal = System.getenv("BROWSERSTACK_LOCAL");
String browserstackLocalIdentifier = System.getenv("BROWSERSTACK_LOCAL_IDENTIFIER");

DesiredCapabilities capabilities = new DesiredCapabilities();
capabilities.setCapability("os", "Windows");
capabilities.setCapability("browser", "chrome");
capabilities.setCapability("browserstack.local", browserstackLocal);
capabilities.setCapability("browserstack.localIdentifier", browserstackLocalIdentifier);
driver = new RemoteWebDriver(new URL("https://" + username + ":" + accessKey + "@hub.browserstack.com/wd/hub"), capabilities);
var username = process.env.BROWSERSTACK_USERNAME;
var accessKey = process.env.BROWSERSTACK_ACCESS_KEY;
var browserstackLocal = process.env.BROWSERSTACK_LOCAL;
var browserstackLocalIdentifier = process.env.BROWSERSTACK_LOCAL_IDENTIFIER;

var capabilities = {
 "os" : "Windows",
 "browser" : "chrome",
 "browserstack.local" : browserstackLocal,
 "browserstack.localIdentifier" : browserstackLocalIdentifier,
 "browserstack.user" : username,
 "browserstack.key" : accessKey
};

var driver = new webdriver.Builder().
  usingServer("https://hub-cloud.browserstack.com/wd/hub").
  withCapabilities(capabilities).
  build();
username = Environment.GetEnvironmentVariable("BROWSERSTACK_USERNAME");
accessKey = Environment.GetEnvironmentVariable("BROWSERSTACK_ACCESS_KEY");
browserstackLocal = Environment.GetEnvironmentVariable("BROWSERSTACK_LOCAL");
browserstackLocalIdentifier = Environment.GetEnvironmentVariable("BROWSERSTACK_LOCAL_IDENTIFIER");

DesiredCapabilities caps = new DesiredCapabilities();
caps.setCapability("os", "Windows");
caps.setCapability("browser", "chrome");
caps.setCapability("browserstack.local", browserstackLocal);
caps.setCapability("browserstack.localIdentifier", browserstackLocalIdentifier);
driver = new RemoteWebDriver(new URL("https://" + username + ":" + accessKey + "@hub.browserstack.com/wd/hub"), caps);
$username = getenv("BROWSERSTACK_USERNAME");
$accessKey = getenv("BROWSERSTACK_ACCESS_KEY");
$browserstackLocal = getenv("BROWSERSTACK_LOCAL");
$browserstackLocalIdentifier = getenv("BROWSERSTACK_LOCAL_IDENTIFIER");

$caps = array(
  "os" => "Windows",
  "browser" => "chrome",
  "browserstack.local" => $browserstackLocal,
  "browserstack.localIdentifier" => $browserstackLocalIdentifier
);

$web_driver = RemoteWebDriver::create(
  "https://" . $username . ":" . $accessKey . "@hub-cloud.browserstack.com/wd/hub",
  $caps
);
username = os.getenv("BROWSERSTACK_USERNAME")
access_key = os.getenv("BROWSERSTACK_ACCESS_KEY")
browserstack_local = os.getenv("BROWSERSTACK_LOCAL")
browserstack_local_identifier = os.getenv("BROWSERSTACK_LOCAL_IDENTIFIER")

caps = {
 'os': 'Windows',
 'browser': 'chrome',
 'browserstack.local': browserstack_local,
 'browserstack.localIdentifier': browserstack_local_identifier,
 'browserstack.user': username,
 'browserstack.key': access_key
}

driver = webdriver.Remote(
    command_executor='https://hub-cloud.browserstack.com/wd/hub',
    desired_capabilities=caps)
username = ENV["BROWSERSTACK_USERNAME"]
access_key = ENV["BROWSERSTACK_ACCESS_KEY"]
browserstack_local = ENV["BROWSERSTACK_LOCAL"]
browserstack_local_identifier = ENV["BROWSERSTACK_LOCAL_IDENTIFIER"]
caps = Selenium::WebDriver::Remote::Capabilities.new
caps["os"] = "Windows"
caps["browser"] = "chrome"
caps["browserstack.local"] = browserstack_local
caps["browserstack.localIdentifier"] = browserstack_local_identifier
caps["browserstack.user"] = username
caps["browserstack.key"] = access_key

driver = Selenium::WebDriver.for(:remote,
  :url => "https://hub-cloud.browserstack.com/wd/hub",
  :desired_capabilities => caps)
my $username = $ENV{"BROWSERSTACK_USERNAME"};
my $accessKey = $ENV{"BROWSERSTACK_ACCESS_KEY"};
my $browserstackLocal = $ENV{"BROWSERSTACK_LOCAL"};
my $browserstackLocalIdentifier = $ENV{"BROWSERSTACK_LOCAL_IDENTIFIER"};

my $caps = {
  "os" => "Windows",
  "browser" => "chrome",
  "browserstack.local" => $browserstackLocal,
  "browserstack.localIdentifier" => $browserstackLocalIdentifier
};

my $host = "$username:$accessKey\@hub-cloud.browserstack.com";

my $driver = new Selenium::Remote::Driver('remote_server_addr' => $host,
  'port' => '80', 'extra_capabilities' => $caps);
Note: You must pass browserstack.local and browserstack.localIdentifier capabilities to test on your local development servers.

To enable BrowserStack Local follow these steps:

Under the Build Environment section check the box next to BrowserStack Local. browserstack automate jenkins plugin

Note:
  1. If you are using an externally downloaded binary, you can enter its location at BrowserStack Local Path. If left empty, the plugin will automatically download the binary (recommended). This is recommended especially if you are using Jenkins in master-slave configurations, since the plugin will download the appropriate binary for the build agent OS.
  2. Use BrowserStack Local Options to set any additional configuration options when running the binary (Full list of options available here)

To enable BrowserStack Local using a Jenkinsfile add localConfig option as shown in the sample code:

browserstack(credentialsId: '<browserstackCredentialsId>', localConfig: [localOptions: '<local-options>', localPath: '/path/to/local']) {
    // code for executing test cases
}
Note:
  1. If you are using an externally downloaded binary, you can enter its location at localPath. If left empty, the plugin will automatically download the binary (recommended). This is recommended especially if you are using Jenkins in master-slave configurations, since the plugin will download the appropriate binary for the build agent OS.
  2. Use localOptions to set any additional configuration options when running the binary (Full list of options available here) ) Once you’ve integrated BrowserStack Local through the Jenkinsfile, you can run your Selenium tests on websites hosted on private, development, and internal servers safely and securely.

Once you’ve integrated BrowserStack Local through the Jenkins plugin, you can run your Selenium tests on websites hosted on private, development, and internal servers safely and securely.

Generating and Embedding test reports

The BrowserStack Jenkins plugin enables you to embed the test results from BrowserStack into Jenkins. We currently support viewing test reports in Jenkins with a select set of languages and frameworks, which are Java with JUnit or TestNG, and Node with Protractor or WebdriverIO. The sections below describe how to embed your BrowserStack test results in Jenkins.

Generating test reports

Follow the below steps to generate test reports.

TestNG and JUnit

A prerequisite for embedding test reports is that the Java project must be built with Maven and use either TestNG or JUnit for testing.

To configure your project:

Add the following dependencies to your pom.xml file:

<dependency>
    <groupId>com.browserstack</groupId>
    <artifactId>automate-testassist</artifactId>
    <version>1.1.0</version>
</dependency>

Add the following repositories to your pom.xml file:

<repositories>
  <repository>
    <id>sonatype-nexus-snapshots</id>
    <url>https://oss.sonatype.org/content/repositories/snapshots</url>
  </repository>
</repositories>
<pluginRepositories>
  <pluginRepository>
   <id>sonatype-nexus-snapshots</id>
      <url>https://oss.sonatype.org/content/repositories/snapshots</url>
  </pluginRepository>
</pluginRepositories>

Add the following plugin to your pom.xml file:

<build>
    <plugins>
      <plugin>
        <groupId>com.browserstack</groupId>
        <artifactId>automate-maven-plugin</artifactId>
        <version>1.0.0-SNAPSHOT</version>
        <configuration>
            <source>${jdk.source.version}</source>
            <target>${jdk.target.version}</target>
            <complianceLevel>${jdk.source.version}</complianceLevel>
        </configuration>
        <executions>
          <execution>
            <goals>
              <goal>test-compile</goal>
            </goals>
          </execution>
        </executions>
      </plugin>
    </plugins>
</build>

You must define the Maven properties, jdk.source.version and jdk.target.version to match the Java versions of your project.

To configure WebdriverIO project, add wdio-browserstack-reporter as a dependency in your package.json file.

{
  "dependencies": {
    "wdio-browserstack-reporter": "~0.1.1"
  }
}

Add browserstack as a reporter in your conf file.

// wdio.conf.js
module.exports = {
    // ...
    reporters: ['browserstack'],
    reporterOptions: {
        browserstack: {
            outputDir: './'
        }
    },
    // ...
};

outputDir (optional): defines a directory location for storing browserstack report files. Here is the link for the GitHub repository.

To configure Protractor project, add protractor-browserstack-reporter as a dependency in your package.json file.

{
  "dependencies": {
    "protractor-browserstack-reporter": "~0.1.1"
  }
}

Add browserstack as a plugin in your conf file.

// conf.js
'plugins': [{
  'package': "browserstack-protractor-reporter"
}]

outputDir (optional): defines a directory location for storing browserstack report files.

Here is the link for the GitHub repository.

Embedding test reports

The below steps for embedding test reports are same for Java - JUnit and TestNG, Protractor and WebdriverIO.

Embedding of report can be configured by either using Jenkins UI or using a Jenkinsfile.

Once you have completed the above steps, you can configure your Jenkins CI server to embed all the BrowserStack Selenium reports and logs in Jenkins.

  1. Click on Add post-build action in Post-build Actions. browserstack automate jenkins plugin

  2. Click on Publish JUnit test result report. browserstack automate jenkins plugin

  3. In the Test report XMLs,
    • Enter *target/surefire-reports/TEST-.xml** for TestNG and JUnit
    • Enter */browserstack-reports/REPORT-.xml for WebdriverIO and Protractor
  4. In the Additional test report features section, add Embed BrowserStack Report. browserstack automate jenkins plugin

Use the code in your Jenkinsfile

junit testDataPublishers: [[$class: 'AutomateTestDataPublisher']], testResults: 'target/surefire-reports/TEST-*.xml'

This is a post build step and should be added after browserstack block in the Jenkinsfile.

With this integration, you can now view the results of your Selenium Webdriver tests within Jenkins.

Conclusion

By following the steps outlined in this guide, you should have a seamless integration between your existing automation in Jenkins, your Selenium tests and the BrowserStack Selenium grid. This will help you leverage all the benefits of test automation and the scale and coverage offered by BrowserStack.