---
id: app/continuous-integration/bitbucket-pipelines
title: 'Run Cypress tests in Bitbucket Pipelines: Step-by-Step Guide'
description: >-
  Run Cypress tests in Bitbucket Pipelines with Docker images, caching,
  parallelization, and Cypress Cloud.
section: app
source_path: docs/app/continuous-integration/bitbucket-pipelines.mdx
version: ce02913654e2655ee63448bdc92bb92c7b46a619
updated_at: '2026-04-22T19:37:51.587Z'
---
# Run Cypress in Bitbucket Pipelines

#####  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](https://support.atlassian.com/bitbucket-cloud/docs/get-started-with-bitbucket-pipelines/).

Bitbucket runs most builds in Docker containers as described in [Docker image options](https://support.atlassian.com/bitbucket-cloud/docs/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](https://support.atlassian.com/bitbucket-cloud/docs/use-docker-images-as-build-environments/) you must additionally install [Cypress Linux prerequisites](/llm/markdown/app/get-started/install-cypress.md#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](https://github.com/cypress-io/cypress-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](/llm/markdown/app/continuous-integration/overview.md#Cypress-Docker-variants) to decide which image is best for your project.

```yaml title="bitbucket-pipelines.yml"
image: cypress/browsers:22.15.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](https://support.atlassian.com/bitbucket-cloud/docs/cache-dependencies/),
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.

```yaml title="bitbucket-pipelines.yml"
image: cypress/browsers:22.15.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](https://support.atlassian.com/bitbucket-cloud/docs/configure-bitbucket-pipelinesyml/#Global-configuration-options)
block we can define additional caches for npm and Cypress.

```yaml title="bitbucket-pipelines.yml"
definitions:
  caches:
    npm: $HOME/.npm
    cypress: $HOME/.cache/Cypress
```

## Parallelization

[Cypress Cloud](/llm/markdown/cloud/get-started/introduction.md) offers the ability to
[parallelize and group test runs](/llm/markdown/cloud/features/smart-orchestration/parallelization.md)
along with additional insights and [analytics](/llm/markdown/cloud/features/analytics/overview.md) 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](https://support.atlassian.com/bitbucket-cloud/docs/yaml-anchors/),
`&e2e`. This will be used by the worker jobs.

The following configuration using the `--parallel` and `--record` flags to
[cypress run](/llm/markdown/app/references/command-line.md#cypress-run) requires setting up
recording test results to [Cypress Cloud](/llm/markdown/cloud/get-started/introduction.md).

```yaml title="bitbucket-pipelines.yml"
image: cypress/base:22.15.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](https://support.atlassian.com/bitbucket-cloud/docs/yaml-anchors/)
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.

```yaml title="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:

```yaml title="bitbucket-pipelines.yml"
image: cypress/base:22.15.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](/llm/markdown/cloud/get-started/introduction.md):

1. [Recording test results with the `--record` flag](/llm/markdown/cloud/get-started/setup.md)
   to Cypress Cloud.
   - In-depth and shareable
     [test reports](/llm/markdown/cloud/features/recorded-runs.md#Latest-Runs).
   - Visibility into test failures via quick access to [Test Replay](/llm/markdown/cloud/features/test-replay.md), error messages, stack
     traces, screenshots, videos, and contextual details.
   - [Integrating testing with the pull-request (PR) process](/llm/markdown/cloud/integrations/github.md)
     via
     [commit status check guards](/llm/markdown/cloud/integrations/github.md#Status-checks)
     and convenient
     [test report comments](/llm/markdown/cloud/integrations/github.md#Pull-request-comments).
   - [Detecting flaky tests](/llm/markdown/cloud/features/flaky-test-management.md) and surfacing
     them via [Slack alerts](/llm/markdown/cloud/features/flaky-test-management.md#Slack) or
     [GitHub PR status checks](/llm/markdown/cloud/features/flaky-test-management.md#GitHub).

2. [Parallelizing test runs](/llm/markdown/cloud/features/smart-orchestration/parallelization.md)
   and optimizing their execution via
   [intelligent load-balancing](/llm/markdown/cloud/features/smart-orchestration/load-balancing.md#Balance-strategy)
   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](https://on.cypress.io/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.