Skip to main content

Bitbucket Pipelines

info
What you'll learn​
  • How to set up Bitbucket Pipelines to run Cypress tests
  • How to cache dependencies and build artifacts
  • How to parallelize Cypress tests with Bitbucket Pipelines
  • How to use Cypress Cloud with Bitbucket Pipelines

Basic Setup​

Detailed documentation is available in the Bitbucket Pipelines Documentation.

The example below shows a basic setup and job to use Bitbucket Pipelines to run end-to-end tests with Cypress and Electron.

bitbucket-pipelines.yml
image: node:latest

pipelines:
  default:
    - step:
        script:
          # install dependencies
          - npm ci
          # start the server in the background
          - npm run start &
          # run Cypress tests
          - npm run e2e

How this bitbucket-pipelines.yml works:

  • On push to this repository, this job will provision and start Bitbucket Pipelines-hosted Linux instance for running the pipelines defined in the pipelines section of the configuration.
  • The code is checked out from our GitHub/Bitbucket repository.
  • Finally, our scripts will:
    • Install npm dependencies
    • Start the project web server (npm start)
    • Run the Cypress tests within our GitHub/Bitbucket repository within Electron

Testing with Cypress Docker Images​

The Cypress team maintains the official Docker Images for running Cypress locally and in CI, with some images including Chrome, Firefox and Edge. For example, this allows us to run the tests in Firefox by passing the --browser firefox attribute to cypress run.

Read about Cypress docker variants to decide which image is best for your project.

bitbucket-pipelines.yml
image: cypress/browsers:node-22.11.0-chrome-130.0.6723.69-1-ff-132.0-edge-130.0.2849.56-1

pipelines:
  default:
    - step:
        script:
          # install dependencies
          - npm ci
          # start the server in the background
          - npm run start &
          # run Cypress tests in Firefox
          - npx cypress run --browser firefox

Caching Dependencies and Build Artifacts​

Per the Caches documentation, Bitbucket offers options for caching dependencies and build artifacts across many different workflows.

To cache node_modules, the npm cache across builds, the cache attribute and configuration has been added below.

Artifacts from a job can be defined by providing paths to the artifacts attribute.

bitbucket-pipelines.yml
image: cypress/browsers:node-22.11.0-chrome-130.0.6723.69-1-ff-132.0-edge-130.0.2849.56-1

pipelines:
  default:
    - step:
        caches:
          - node
        script:
          # install dependencies
          - npm ci
          # start the server in the background
          - npm run start &
          # run Cypress tests in Firefox
          - npx cypress run --browser firefox
        artifacts:
          # store any generates images and videos as artifacts
          - cypress/screenshots/**
          - cypress/videos/**

Using the definitions block we can define additional caches for npm and Cypress.

bitbucket-pipelines.yml
definitions:
  caches:
    npm: $HOME/.npm
    cypress: $HOME/.cache/Cypress

Parallelization​

Cypress Cloud offers the ability to parallelize and group test runs along with additional insights and analytics for Cypress tests.

Before diving into an example of a parallelization setup, it is important to understand the two different types of jobs that we will declare:

  • Install Job: A job that installs and caches dependencies that will be used by subsequent jobs later in the Bitbucket Pipelines workflow.
  • Worker Job: A job that handles execution of Cypress tests and depends on the install job.

Install Job​

The separation of installation from test running is necessary when running parallel jobs. It allows for reuse of various build steps aided by caching.

First, we break the pipeline up into reusable chunks of configuration using a YAML anchor, &e2e. This will be used by the worker jobs.

info

The following configuration using the --parallel and --record flags to cypress run requires setting up recording test results to Cypress Cloud.

bitbucket-pipelines.yml
image: cypress/base:22.11.0

## job definition for running E2E tests in parallel
e2e: &e2e
  name: E2E tests
  caches:
    - node
    - cypress
  script:
    - npm run start &
    - npm run e2e:record -- --parallel --group UI-Chrome --ci-build-id $BITBUCKET_BUILD_NUMBER
  artifacts:
    # store any generates images and videos as artifacts
    - cypress/screenshots/**
    - cypress/videos/**

Worker Jobs​

Next, the worker jobs under pipelines that will run Cypress tests with Chrome in parallel.

We can use the e2e YAML anchor in our definition of the pipeline to execute parallel jobs using the parallel attribute. This will allow us to run multiples instances of Cypress at same time.

bitbucket-pipelines.yml
## job definition for running E2E tests in parallel
## ...

pipelines:
  default:
    - step:
        name: Install dependencies
        caches:
          - npm
          - cypress
          - node
        script:
          - npm ci
    - parallel:
      # run N steps in parallel
      - step:
          <<: *e2e
      - step:
          <<: *e2e
      - step:
          <<: *e2e
definitions:
  caches:
    npm: $HOME/.npm
    cypress: $HOME/.cache/Cypress

The complete bitbucket-pipelines.yml is below:

bitbucket-pipelines.yml
image: cypress/base:22.11.0

## job definition for running E2E tests in parallel
e2e: &e2e
  name: E2E tests
  caches:
    - node
    - cypress
  script:
    - npm run start &
    - npm run e2e:record -- --parallel --group UI-Chrome --ci-build-id $BITBUCKET_BUILD_NUMBER
  artifacts:
    # store any generates images and videos as artifacts
    - cypress/screenshots/**
    - cypress/videos/**

pipelines:
  default:
    - step:
        name: Install dependencies
        caches:
          - npm
          - cypress
          - node
        script:
          - npm ci
    - parallel:
        # run N steps in parallel
        - step:
            <<: *e2e
        - step:
            <<: *e2e
        - step:
            <<: *e2e
definitions:
  caches:
    npm: $HOME/.npm
    cypress: $HOME/.cache/Cypress

Using Cypress Cloud with Bitbucket Pipelines​

In the Bitbucket Pipelines configuration we have defined in the previous section, we are leveraging three useful features of Cypress Cloud:

  1. Recording test results with the --record flag to Cypress Cloud.

  2. Parallelizing test runs and optimizing their execution via intelligent load-balancing of test specs across CI machines with the --parallel flag.

  3. Organizing and consolidating multiple cypress run calls by labeled groups into a single report within Cypress Cloud. In the example above we use the --group UI-Chrome flag to organize all UI tests for the Chrome browser into a group labeled "UI-Chrome" inside the Cypress Cloud report.

Contents