Integrate GitHub Actions with BrowserStack

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

The console logs of GitHub Workflow, on running this Action is shown below:

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

Usage

Use the below 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 code snippet below 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 like shown below: