Integrate GitHub Actions with BrowserStack

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

You can find the BrowserStack GitHub Actions in the GitHub Marketplace. The 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.

In this guide, we will cover the following sections:

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. Sample test script depicting the use of environment variables as BrowserStack capabilities
5. 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.

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

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

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 (You can also 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. Run the test scripts from the workflow. (You can visit the Sample Test section to see how you can use the environment variables in your test script to set BrowserStack capabilities)

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.

      - 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'

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

Sample browserstack.json Configuration file for integration

You can use the following configuration file in your tests to integrate your Cypress test suite with BrowserStack. Integrate your existing Cypress tests with BrowserStack

{
  "browsers": [{
      "browser": "chrome",
      "os": "Windows 10",
      "versions": ["latest", "latest - 1"]
    },
  ],
  "run_settings": {
    "cypress_config_file": "./cypress.config.js",
    "cypress_version": "12.3",
    "npm_dependencies": {
      "cypress": "12.3",
      "npm-package-you-need-to-run-tests-1": "^1.2.1",
      "npm-package-you-need-to-run-tests-2": "^7.1.6-beta.13"
    },
    "project_name": "Cypress sample build",
    "build_name": "Build no: 1",
    "parallels": 5,
    "exclude": ["some-folder/test.js", "static/*.pdf"]
  }
}

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:  $
          access-key: $

# 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: 'Installing browserstack-cypress-cli'
        run: npm install -g browserstack-cypress-cli

      - name: 'Running test on BrowserStack with local testing enabled'  # Invokes the actual test script that would run on BrowserStack browsers
        run: - run: BROWSERSTACK_LOCAL=true browserstack-cypress run # See sample test script above

Local testing Setup

You can set up local testing using the following methods:

Make changes in the BrowserStack configuration file:

Add the following parameter to the Browserstack.json file

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

Set the BROWSERSTACK_LOCAL environment variable to true inside the workflow file:

...
  #Setting BROWSERSTACK_LOCAL to true before executing the test
  - run: BROWSERSTACK_LOCAL=true browserstack-cypress run
...

Additional References

Below are some quick links for your ready reference:

• Migrate your existing test-suite to run on BrowserStack
• Get started with Selenium testing in the language/framework of your choice
• Name and organise your tests
• If you face errors while trying to start the local binary, visit the link with the relevant error code that you received in the GitHub Actions console:
  • Error Code: 1001
  • Error Code: 1004
  • Error Code: 2001
  • Error Code: 3001
  • Error Code: 3003
  • Error Code: 3005
  • Error Code: 3006
  • Error Code: 3009
  • Error Code: 3010
  • Error Code: 3012
  • Error Code: 3013
  • Error Code: 4002
  • Error Code: 4003