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.

Bitbucket runs most builds in Docker containers as described in Docker image options.

If you use the currently available default Bitbucket / Atlassian Linux images listed in the "Default build environment" of the Bitbucket Cloud documentation Use Docker images as build environments you must additionally install Cypress Linux prerequisites.

For a simpler setup, use a Cypress Docker image, as described in the following section.

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:22.12.0

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

How this bitbucket-pipelines.yml works:

  • On push to this repository, this job will provision and start Bitbucket Pipelines using the Cypress Docker image. It will run the pipelines defined in the pipelines section of the configuration.
  • The code is checked out from the Bitbucket repository.
  • Finally, our scripts will:
    • Install npm dependencies
    • Start the project web server (npm start)
    • Run the Cypress tests within the Bitbucket repository using 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:22.12.0

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.12.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.12.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