View build reports in GitLab

Publish your Test Reporting & Analytics build report to the GitLab job log and job artifacts using the BrowserStack pipeline template.

GitLab CI/CD doesn’t support plugins, so BrowserStack provides the reporting jobs as a pipeline template that you include in your .gitlab-ci.yml file. After you add the template, every pipeline run prints a plain text summary of your Test Reporting & Analytics build to the job log and uploads the full HTML report as a job artifact.

Prerequisites

Before you start, ensure that:

• You have a BrowserStack Test Reporting & Analytics account, and your tests already report build data to it.
• You are a maintainer or owner of the GitLab project.
• The .gitlab-ci.yml file exists for your project.
• Your BrowserStack Username and Access key are set as GitLab CI/CD variables named BROWSERSTACK_USERNAME and BROWSERSTACK_ACCESS_KEY.

Include the BrowserStack pipeline template

Add the BrowserStack template to your .gitlab-ci.yml file. The template defines the two hidden jobs that the following sections extend, .set_browserstack_config and .set_browserstack_test_report:

Pin the tag, as shown, so that a new release doesn’t change your pipeline. To always track the latest release, replace refs/tags/v1.0.0 with refs/heads/main.

Add the config job

The config job validates your credentials and generates a build name, then writes your username, access key, and the generated build name to a browserstack_vars.env artifact that later jobs read. Add the config job as the first BrowserStack job in your pipeline:

Run your tests with the generated build name

Add browserstack_set_config to the needs list of your test job, then source browserstack_vars.env so that your tests run under the generated build name:

If your test script reads the build name directly, load browserstack_vars.env in the script. For example, a Node.js suite can load it with require('dotenv').config({ path: './browserstack_vars.env' }) and then read process.env.BROWSERSTACK_BUILD_NAME.

Add the report job

The report job polls Test Reporting & Analytics for the build report and publishes it. It must run after both the config job and your test job, so list both in needs:

The REPORT_TIMEOUT parameter specifies the maximum time, in seconds, before the job times out while retrieving the report. The value must be between 20 and 600. If omitted, the default value is 130 seconds.

View the build report

Commit your changes and run the pipeline. When the report job finishes, you can view the report in two places:

• Job log: open the browserstack_test_report job to read the plain text summary, which lists the build status and the test counts.
• Artifacts: on the job page, select Browse under Job artifacts and open browserstack/testreport.html for the full report with charts and test-level detail.

The report job always exits successfully, so a missing or incomplete report doesn’t fail your pipeline.

Rerun failed tests

You can rerun failed tests from the Test Reporting & Analytics dashboard after you integrate GitLab. For the steps, see Rerun tests on GitLab.