Skip to main content
Transform your testing process with: Real Device Features, Company-wide Licences, & Test Observability
No Result Found

Integrate GitHub Actions with BrowserStack

Learn how to integrate your GitHub Actions workflow with the BrowserStack device cloud to run your Playwright tests.

In this guide, you will learn how to:

  1. Set up BrowserStack Username and Access-key as GitHub Action Secrets
  2. Set up a workflow to run your tests on BrowserStack
  3. Use BrowserStack’s setup-env GitHub Action to set up useful environment variables
  4. Use BrowserStack’s setup-local GitHub Action to establish BrowserStackLocal tunnel connection
  5. Sample test script depicting the use of environment variables as BrowserStack capabilities
  6. Sample GitHub workflow showing a BrowserStack test

Set up GitHub secrets in your repository

You need to have username and access-key from BrowserStack to be able to run tests on the BrowserStack infrastructure. This section shows how to set them as Secrets in your GitHub repository. You can sign-up for free trial if you do not have an existing account.

If you want to test your open source project on BrowserStack, then sign-up here for lifetime free access to all our products.

Go to Settings in your repository and click on Secrets option in the left-hand pane

As the picture above suggests, navigate to Settings in your repository where you will find the Secrets option in the left pane. Navigate to Secrets and add new secrets as shown in the following image:

GitHub Actions Setting New Secrets

Add YOUR_USERNAME as the BROWSERSTACK_USERNAME secret and similarly, add YOUR_ACCESS_KEY as the BROWSERSTACK_ACCESS_KEY secret. After these two steps, the secrets page should contain entries like this:

GitHub Actions Setting Secrets View

Set up a GitHub workflow to run BrowserStack tests

Perform the following steps to run BrowserStack tests from GitHub Actions (check out the sample GitHub workflow):

  1. Create the workflow file(s) <filename>.yml in the .github/workflows directory in your repository. (Check out how to create GitHub Workflow files)
  2. The starting of the workflow specifies on what events the workflow must run. We recommend you to run on both push and pull_request so that you have a 1:1 build mapping against every commit
  3. You can run on any GitHub Actions runner e.g. ubuntu-latest (Check out how to host your own runners)
  4. In the initial workflow steps, you must build your web application and start the web server on the runner
  5. Thereafter, invoke setup-env BrowserStack Action to set up environment variables in the runner
  6. Invoke setup-local BrowserStack Action to set up a tunnel connection between the GitHub Actions runner environment and the BrowserStack device cloud so that the application server on the runner environment can be accessed by the browsers in BrowserStack’s device cloud
  7. Run the test scripts from the workflow. Visit the Sample Test section to see how you can use the environment variables in your test script to set BrowserStack capabilities
  8. Invoke setup-local BrowserStack Action again to terminate the tunnel connection

You can see the sample GitHub workflow to run a BrowserStack test. The next section explains the purpose and usage of the BrowserStack GitHub Actions in your workflow.

Use BrowserStack GitHub Actions in your workflow

You can find the BrowserStack GitHub Actions in the GitHub Marketplace. The following two Actions are used to set up the required environment variables in the runner environment and set up BrowserStack Local tunnel connection which will be used to route all browser traffic from BrowserStack’s device cloud to the runner environment which hosts your web application.

You can find the Action’s GitHub repository. This Action should be invoked from the runner environment before any other BrowserStack Action is invoked. This Action sets up the following environment variables in the runner environment which will later be used by other BrowserStack Actions and also in your test scripts to set BrowserStack specific capabilities:

  • BROWSERSTACK_BUILD_NAME: By default, this variable will be populated with a name for your build consisting of workflow run specific data. For e.g.
    On pull_request[<Branch-Name>] PR <PR#>: <PR-title> [Workflow: Workflow#] will be set
  • BROWSERSTACK_PROJECT_NAME: By default, the repository name will be set
  • BROWSERSTACK_USERNAME: Input of username will be set, to be used in test scripts.
  • BROWSERSTACK_ACCESS_KEY: Input of access-key will be set, to be used in test scripts.

Inputs

  1. username: (Mandatory) Your BrowserStack username to be passed ideally as a GitHub Secret
  2. access-key: (Mandatory) Your BrowserStack access-key to be ideally passed as a GitHub Secret
  3. build-name: (Optional) Sets the environment variable BROWSERSTACK_BUILD_NAME
    • Default is BUILD_INFO which will be replaced with meaningful workflow related information
    • You can pass any string. E.g. build-name: 'my-string'
    • You can also use a string along with the keyword BUILD_INFO in the input
      E.g. build-name: 'string1 - BUILD_INFO - string2'
  4. project-name: (Optional) Sets the environment variable BROWSERSTACK_PROJECT_NAME
    • Default is REPO_NAME which will be replaced with the repository name
    • You can pass any string that you want to set as the BROWSERSTACK_PROJECT_NAME
      E.g. project-name: 'My Project Name Goes Here'

Usage

      - name: 'BrowserStack Env Setup'
        uses: 'browserstack/github-actions/setup-env@master'
        with:
          username:  ${{ secrets.BROWSERSTACK_USERNAME }}
          access-key: ${{ secrets.BROWSERSTACK_ACCESS_KEY }}
          build-name: 'BUILD_INFO'
          project-name: 'REPO_NAME'

Or, pass the required arguments only:

      - name: 'BrowserStack Env Setup'
        uses: 'browserstack/github-actions/setup-env@master'
        with:
          username:  ${{ secrets.BROWSERSTACK_USERNAME }}
          access-key: ${{ secrets.BROWSERSTACK_ACCESS_KEY }}
Note:
  • The setup-env Action is a pre-requisite for any other BrowserStack related Actions.
  • This action should be invoked prior to the execution of tests on BrowserStack to be able to utilise the environment variables in your tests.
  • You have to use the environment variables set in this Action in your test script (Sample test script).

The console logs of GitHub Workflow, on running this Action is as follows:

Env Action Console Screenshot

Using local testing, you can access your local as well as restricted environments on BrowserStack’s Remote devices. You can see the BrowserStack GitHub Action’s repository. This Action fulfills the following objectives in your runner environment:

  • Download the BrowserStackLocal binary in your runner based on the environment, i.e. Linux/Darwin/Win32.
  • Start (or stop) the binary so as to establish (or end) a tunnel connection between the runner environment and BrowserStack.
  • Allows to specify the logging-level of the binary and uploads the logs as artifacts in GitHub.
  • Allows to pass any additional argument in binary invocation as can be found in the documentation for local testing binary params.

Pre-requisites

The browserstack/github-actions/setup-env@master Action should be invoked prior to invoking this Action as a part of the same workflow job.

Inputs

  1. local-testing: (Mandatory) The value can be either start or stop
    • start input will download the BrowserStackLocal binary and start the binary.
    • stop input will stop any running binary and if any log-level was set by local-logging-level, then the logs will be uploaded as artifacts. If you do not stop the binary after the completion of your tests, the logs will not be uploaded as artifacts.
  2. local-logging-level: (Optional) The valid inputs are:
    • setup-logs: Logs to debug issues related to setting up connections will be saved.
    • network-logs: Logs related to the network information will be saved.
    • all-logs: All communication to local servers for each request and response will be saved.
    • Default: Input will be assumed as false when no input is provided and logs will not be saved.
  3. local-identifier: (Optional) The valid inputs are:
    • random (Recommended option): A random string will be used as the identifier to start and distinguish the local binary instance. It will be saved in the environment variable BROWSERSTACK_LOCAL_IDENTIFIER and must be used in your test script as the capability ‘browserstack.localIdentifier’. (See sample code snippet)
    • <string>: Any string can be an input which will be saved in the same environment variable as above and must be used in your test scripts.
    • Default: No tunnel identifier will be used.
  4. local-args: (Optional) Any additional argument to local binary can be passed using this input as a single string. See the complete list of supported local-binary arguments.
    Example → local-args: '--force-local --proxy-host <HOST> --proxy-port <PORT> --proxy-user <USER> --proxy-pass <PASSWORD>'

    The following arguments are already being included in the invocation of the local binary and hence, if you include any of them again in the local-args string, they will be ignored:
    • --key
    • --local-identifier
    • --daemon
    • --only-automate
    • --verbose
    • --log-file
Note:
  • local-identifier argument is strongly recommended to be set to ‘random’ so that the tunnel connection is distinguished by the identifier.
  • local-args is an optional argument and under normal circumstances, if the application is not hosted behind any proxy, this input would not be required. See the supported BrowserStackLocal binary parameters
Warning: For local-logging-level input, the logs will only be saved and uploaded as artifacts only if this Action is invoked again with local-testing: stop as the input (after your test scripts have completed running)

Usage

Use the following code snippet in your workflow to start the BrowserStackLocal binary and establish the tunnel connection:

      - name: 'Start BrowserStackLocal Tunnel'
        uses: 'browserstack/github-actions/setup-local@master'
        with:
          local-testing: 'start'
          local-logging-level: 'all-logs'
          local-identifier: 'random'

Use the following code snippet at the end of your workflow after the tests have completed. This will stop the BrowserStackLocal binary and upload the local binary logs (if any):

      - name: 'Stop BrowserStackLocal'
        uses: 'browserstack/github-actions/setup-local@master'
        with:
          local-testing: 'stop'

The console logs on GitHub Workflow console, on running this Action is as follows:

Selenium Github Actions Console Logs on Github Workflow console

Sample test script

The following sample test script assumes that there is a HTTP web-server running on the runner environment’s port 8099. This script is just for showing the use of environment variables in capabilities. See the complete list of capabilities

Note: To be able to run these test scripts in the GitHub Actions runner environment, you have to add a step(s) in the workflow to install the required Playwright bindings for the language of your choice.
public static final String AUTOMATE_USERNAME = System.getenv("BROWSERSTACK_USERNAME");
public static final String AUTOMATE_ACCESS_KEY = System.getenv("BROWSERSTACK_ACCESS_KEY");
public static final String LOCAL_IDENTIFIER = System.getenv("BROWSERSTACK_LOCAL_IDENTIFIER");
public static final String BUILD_NAME = System.getenv("BROWSERSTACK_BUILD_NAME");
public static final String PROJECT_NAME = System.getenv("BROWSERSTACK_PROJECT_NAME");

DesiredCapabilities caps = new DesiredCapabilities();
caps.setCapability("os", "Windows");
caps.setCapability("os_version", "10");
caps.setCapability("browser", "Chrome");
caps.setCapability("browser_version", "latest");
caps.setCapability("browserstack.local", "true");
caps.setCapability("browserstack.localIdentifier", LOCAL_IDENTIFIER);
caps.setCapability("project", PROJECT_NAME);
caps.setCapability("build", BUILD_NAME);
var capabilities = {
  'os': 'windows',
  'os_version': '10',
  'browserName': 'chrome',
  'browser_version' : 'latest',
  'browserstack.local': 'true',
  'build': process.env.BROWSERSTACK_BUILD_NAME,
  'project': process.env.BROWSERSTACK_PROJECT_NAME,
  'browserstack.localIdentifier': process.env.BROWSERSTACK_LOCAL_IDENTIFIER,
  'browserstack.user': process.env.BROWSERSTACK_USERNAME,
  'browserstack.key': process.env.BROWSERSTACK_ACCESS_KEY
}
var userName = Environment.GetEnvironmentVariable("BROWSERSTACK_USERNAME");
var accessKey = Environment.GetEnvironmentVariable("BROWSERSTACK_ACCESS_KEY");
var localIdentifier = Environment.GetEnvironmentVariable("BROWSERSTACK_LOCAL_IDENTIFIER");
var buildName = Environment.GetEnvironmentVariable("BROWSERSTACK_BUILD_NAME");
var projectName = Environment.GetEnvironmentVariable("BROWSERSTACK_PROJECT_NAME");

DesiredCapabilities capability = new DesiredCapabilities();
capability.setCapability("os", "Windows");
capability.setCapability("os_version", "10");
capability.setCapability("browser", "Chrome");
capability.setCapability("browser_version", "latest");
capability.SetCapability("browserstack.local", "true");
capability.SetCapability("browserstack.user", userName);
capability.SetCapability("browserstack.key", accessKey);
capability.SetCapability("browserstack.localIdentifier", localIdentifier);
capability.SetCapability("build", buildName);
capability.SetCapability("project", projectName);
userName = os.environ['BROWSERSTACK_USERNAME']
accessKey = os.environ['BROWSERSTACK_ACCESS_KEY']
localIdentifier = os.environ['BROWSERSTACK_LOCAL_IDENTIFIER']
buildName = os.environ['BROWSERSTACK_BUILD_NAME']
projectName = os.environ['BROWSERSTACK_PROJECT_NAME']

desired_cap = {
 'os': 'Windows',
 'os_version': '10',
 'browser': 'Chrome',
 'browser_version': 'latest',
 'browserstack.local': 'true',
 'browserstack.localIdentifier': localIdentifier,
 'build': buildName,
 'project': projectName
}

Sample GitHub workflow showing a BrowserStack test

name: 'BrowserStack Test'
on: [push, pull_request]
jobs:
  ubuntu-job:
    name: 'BrowserStack Test on Ubuntu'
    runs-on: ubuntu-latest  # Can be self-hosted runner also
    steps:

      - name: 'BrowserStack Env Setup'  # Invokes the setup-env action
        uses: browserstack/github-actions/setup-env@master
        with:
          username:  ${{ secrets.BROWSERSTACK_USERNAME }}
          access-key: ${{ secrets.BROWSERSTACK_ACCESS_KEY }}

      - name: 'BrowserStack Local Tunnel Setup'  # Invokes the setup-local action
        uses: browserstack/github-actions/setup-local@master
        with:
          local-testing: start
          local-identifier: random

# The next 3 steps are for building the web application to be tested and starting the web server on the runner environment

      - name: 'Checkout the repository'
        uses: actions/checkout@v2

      - name: 'Building web application to be tested'
        run: npm install

      - name: 'Running application under test'
        run: ./node_modules/.bin/http-server -p 8099 &

      - name: 'Running test on BrowserStack'  # Invokes the actual test script that would run on BrowserStack browsers
        run: npm run test  # See sample test script above

      - name: 'BrowserStackLocal Stop'  # Terminating the BrowserStackLocal tunnel connection
        uses: browserstack/github-actions/setup-local@master
        with:
          local-testing: stop
Note:

If you are building and running your web application in a separate workflow job and the tests on a different job, then (this is NOT the recommended way of integrating GitHub Actions with the BrowserStack cloud):
  • You need to invoke the browserstack/github-actions/setup-env@master and browserstack/github-actions/setup-local@master GitHub Actions in the job where your application is being built and run
  • You need to invoke the browserstack/github-actions/setup-env@master GitHub Action also in the job where test scripts will run because this Action sets up the environment variables BROWSERSTACK_USERNAME, BROWSERSTACK_ACCESS_KEY, BROWSERSTACK_BUILD_NAME and BROWSERSTACK_PROJECT_NAME, which are to be used in your test scripts
  • Additionally, you must ensure that you use the same local-identifier while invoking the setup-local action and also inside your test script. As these activities are not happening in the same job, you have to take care of this manually and you cannot simply use BROWSERSTACK_LOCAL_IDENTIFIER in your test scripts to set the browserstack.localIdentifier capability

Additional References

Below are some quick links for your ready reference:

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
Download Copy Check Circle