Skip to main content

Testing Lighthouse scores and page performance in GitLab pipelines

This guide explains how to run DebugBear tests in CI using GitLab pipelines.

Prerequisites​

Before getting started makes sure that:

If you are not able to deploy your branch consider using ngrok and the --ngrokWebPort 4040 option of the DebugBear CLI.

Setting up the DEBUGBEAR_API_KEY environment variable​

Under Settings > CI/CD, scroll down to Variables and click Expand.

Add GitLab environment variable

Set the variable key to DEBUGBEAR_API_KEY and enter the API key obtained from the Project API tab on the DebugBear website. Then click Add variable.

Configure GitLab environment variable

Running DebugBear in the pipeline​

Create a new pipeline or update your .gitlab-ci.yml file as follows. Replace the page ID and URL to match your project.

image: node:latest

debugbear:
  script:
    - npm install debugbear
    - >
      ./node_modules/.bin/debugbear
      --pageId=123
      --inferBuildInfo
      --waitForResult
      --baseBranch=main
      --fail
      https://my-branch.example.com/

This code assumes that your source code already contains an npm package. If that isn't the case you need to run npm init -y before running npm install debugbear.

The following options are passed to the DebugBear command-line interface:

  • pageId – Tells DebugBear which page in your project to test
  • inferBuildInfo – Pick up details like commit hash and message from the CI environment
  • waitForResult – Wait until the test is complete before exiting the CLI
  • fail – If the test status is failure then exit with a non-zero exit code, failing the pipeline
  • https://my-branch.example.com/ – override the default test URL with the URL where the current branch is deployed

Once the test is complete DebugBear will print a summary of changes compared to the base branch, or compared to the scheduled tests if no build exists on the branch.

DebugBear CLI output in pipeline

Failing the build if a performance budget is exceeded​

By default all tests on DebugBear finish with a neutral status. Set up performance budgets to get success and failure statuses and fail the GitLab pipeline.

DebugBear performance budget to fail builds

The GitLab pipeline will now fail if the budget is exceeded.

Failed pipeline based on web performance

Last updated on