Skip to main content

Testing Lighthouse scores and page performance on Bitbucket

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


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​

Select Repository settings in the sidebar, then open Repository variables.

Add Bitbucket environment variable

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

Creating a pipeline​

Add DebugBear to your existing pipeline or create a new one from the Pipelines on Bitbucket, for example using the Node template.

Create Bitbucket pipeline

Running DebugBear in the pipeline​

Update the bitbucket-pipelines.yml code as follows. Replace the page ID and URL to match your project.

image: node:12

- parallel:
- step:
name: Run DebugBear
- npm install debugbear
- >

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
  • – 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 BitBucket pipeline.

DebugBear performance budget to fail builds

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

Failed pipeline based on web performance