Integrate BrowserStack Automate with Jenkins

Learn how to integrate your Cypress tests with Jenkins using BrowserStack’s plugin.

Overview

Jenkins is a continuous integration tool that enables continuous testing, build, and deployment of iterative code changes. CI/CD tools help catch failures ahead of the production stage and mitigate them as they occur.

In this guide, you’ll learn to:

1. Install and configure the BrowserStack Jenkins plugin
2. Integrate Jenkins in your existing test suite
3. Integrate Jenkins for privately hosted websites

Prerequisites

Before you can start integration, ensure that the following tasks are complete:

• Jenkins CI server (v1.653+) is installed on your machine.
• Access to the BrowserStack account credentials, namely Access Key and Username.
• Jenkins server is running locally on the default port http://localhost:8080/, and have created a pipeline.
• You are a maintainer or owner of your project repository.
• Jenkinsfile is created in your project repository.

Install and configure the BrowserStack Jenkins plugin

The BrowserStack Jenkins plugin eases the process of configuring Jenkins to run tests on BrowserStack. This section explains how to:

1. Install the BrowserStack plugin
2. Configure your BrowserStack credentials in plugin

Step 1: Install the BrowserStack Plugin

To install the BrowserStack plugin, complete the following steps:

1. Navigate to your Jenkins page, running by default on http://localhost:8080/, and click Manage jenkins in the left navigation bar.
2. On the Manage Jenkins page, click Manage Plugins.
3. On the Plugin Manager page, click the Available tab.
4. Search for BrowserStack in the search box.
5. Select BrowserStack and click either Install without restart or Download now and install after restart, depending on your preference.
6. On the Installing Plugins/Upgrades page, view the installation status of the plugin.
7. After installation is successful, click Go back to the top page to configure the plugin.

Step 2: Configure BrowserStack credentials in Jenkins

After installing the plugin, complete the following steps to configure your BrowserStack credentials in the plugin:

1. On your Jenkins page (http://localhost:8080/), click Manage Jenkins > Configure System.
2. Under the BrowserStack Credentials section, click Add > Jenkins.
3. In the Jenkins Credentials Provider: Jenkins window, enter your Username and Access Key.
4. Click Authenticate. After the plugin verifies your BrowserStack credentials, a Success text appears.
5. Click Add at the bottom of the Jenkins Credentials Provider: Jenkins window. You will be redirected to the configuration page.
6. On the configuration page, click Save.
7. On your Jenkins Dashboard, click Manage Jenkins > Manage Credentials.
8. In the Credentials section, note down the ID of the credential shown in the ID column. This ID will be used in the Jenkinsfile of your project.
9. In the Jenkinsfile of your project, add the browserstack(credentialsId: '<credential_id>') statement and wrap all the test commands inside it, as follows:

        browserstack(credentialsId: '<credential_id>') {
            # your test commands
        }
   

The following sample Jenkinsfile defines the setup stage, credential ID, and a sample shell command:

pipeline {
   agent any
   stages {
      stage('setup') {
         steps {
            browserstack(credentialsId: '<credential-id>') {
               echo "hello"
            }
         }
      }
    }
  }

Integrate existing test cases

Running tests in CI/CD is similar to how you run the tests from your local machine. It involves the following steps:

1. Clone your project or test repository

2. Install the BrowserStack-Cypress CLI

3. Configure the capabilities in the browserstack.json file generated after installing the BrowserStack-Cypress CLI

4. Execute the command to run tests on Automate.

Integrate your test suite

Setting environment variables

You can set the authentication and local-testing related settings via environment variables, instead of specifying them in the browserstack.json file. This makes it easier to test using the appropriate settings depending on whether you are running from your local machine or from your CI setup.

The CLI currently reads configuration from the following environment variables:

If you are using the Browserstack-jenkins plugin, these environment variables are automatically captured depending on the plugin configuration.

All necessary installations such as Cypress and npm packages are installed automatically on the CI machine before running the test.

Following is a sample pipeline script for executing Cypress tests:

    pipeline {
      agent any
      stages {
          stage('setup') {
            steps {
                browserstack(credentialsId: '<credential_ID>') {
                    // add commands to run test
                    // Following are some of the example commands -----
                    sh 'npm install'
                    sh 'browserstack-cypress run'
                }
            }
            # ...
          }
        }
      }

Integrate test cases for privately hosted websites

If you are testing websites hosted locally as part of your testing or development environment, you need to configure your Jenkins pipeline to use Local testing.

Using the Local testing feature, remote browsers on the BrowserStack cloud can access websites hosted on your private or internal networks. To learn more about how Local testing works, check out the Local Testing guide.

Local connection setup using BrowserStack Jenkins plugin

Navigate to your projects Jenkinsfile and, in addition to the credentials ID, add the localConfig option to the browserstack statement as follows:

browserstack(credentialsId: '<credentials_ID>', localConfig: [localOptions: '<local-options>', localPath: '/path/to/local']) {
    // commands for executing tests
}

Adding this option sets the BROWSERSTACK_LOCAL variable to true in your Jenkins pipeline.

Parameters specified within the localConfig parameter are as follows:

Once you have added the above code snippet to your JenkinsFile, the local parameter will be set to true for the connection_settings in the browserstack.json file. This will enable local testing for your current Automate build.

Edit the localOptions of the localConfig parameter for any other local test configuration.

Local connection setup by making changes in capabilities

To set up Local testing with BrowserStack, set the local key as true within connections_settings in the browserstack.json file.

The following code snippet shows the sample configuration file:

...
      {
        "connection_settings": {
          "local": true,
          "local_mode": "always-on"
        }
      }
...