{ "doc": { "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": "/llm/markdown/app/continuous-integration/bitbucket-pipelines.md", "version": "3cf5b86b3403f604bdf7f3e35025c3bc3865e02c", "updated_at": "2026-05-07T17:44:31.931Z", "headings": [ { "id": "app/continuous-integration/bitbucket-pipelines#run-cypress-in-bitbucket-pipelines", "text": "Run Cypress in Bitbucket Pipelines", "level": 1 }, { "id": "app/continuous-integration/bitbucket-pipelines#what-youll-learn", "text": "What you'll learn", "level": 5 }, { "id": "app/continuous-integration/bitbucket-pipelines#basic-setup", "text": "Basic Setup", "level": 2 }, { "id": "app/continuous-integration/bitbucket-pipelines#testing-with-cypress-docker-images", "text": "Testing with Cypress Docker Images", "level": 2 }, { "id": "app/continuous-integration/bitbucket-pipelines#caching-dependencies-and-build-artifacts", "text": "Caching Dependencies and Build Artifacts", "level": 2 }, { "id": "app/continuous-integration/bitbucket-pipelines#parallelization", "text": "Parallelization", "level": 2 }, { "id": "app/continuous-integration/bitbucket-pipelines#install-job", "text": "Install Job", "level": 3 }, { "id": "app/continuous-integration/bitbucket-pipelines#worker-jobs", "text": "Worker Jobs", "level": 3 }, { "id": "app/continuous-integration/bitbucket-pipelines#using-cypress-cloud-with-bitbucket-pipelines", "text": "Using Cypress Cloud with Bitbucket Pipelines", "level": 2 } ] }, "chunks": [ { "id": "app/continuous-integration/bitbucket-pipelines#what-youll-learn", "doc_id": "app/continuous-integration/bitbucket-pipelines", "heading": "What you'll learn", "heading_level": 5, "content_markdown": "##### What you'll learn\n\n* How to set up Bitbucket Pipelines to run Cypress tests\n* How to cache dependencies and build artifacts\n* How to parallelize Cypress tests with Bitbucket Pipelines\n* How to use Cypress Cloud with Bitbucket Pipelines\n", "section": "app", "anchors": [ "what-youll-learn" ], "path": "/llm/json/chunked/app/continuous-integration/bitbucket-pipelines.json", "token_estimate": 55 }, { "id": "app/continuous-integration/bitbucket-pipelines#basic-setup", "doc_id": "app/continuous-integration/bitbucket-pipelines", "heading": "Basic Setup", "heading_level": 2, "content_markdown": "## Basic Setup\n\nDetailed documentation is available in the [Bitbucket Pipelines Documentation](https://support.atlassian.com/bitbucket-cloud/docs/get-started-with-bitbucket-pipelines/).\n\nBitbucket runs most builds in Docker containers as described in [Docker image options](https://support.atlassian.com/bitbucket-cloud/docs/docker-image-options/).\n\nIf 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).\n\nFor a simpler setup, use a Cypress Docker image, as described in the following section.\n", "section": "app", "anchors": [ "basic-setup" ], "path": "/llm/json/chunked/app/continuous-integration/bitbucket-pipelines.json", "token_estimate": 101 }, { "id": "app/continuous-integration/bitbucket-pipelines#testing-with-cypress-docker-images", "doc_id": "app/continuous-integration/bitbucket-pipelines", "heading": "Testing with Cypress Docker Images", "heading_level": 2, "content_markdown": "## Testing with Cypress Docker Images\n\nThe 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`.\n\nRead about [Cypress Docker variants](/llm/markdown/app/continuous-integration/overview.md#Cypress-Docker-variants) to decide which image is best for your project.\n\nbitbucket-pipelines.yml\n\n```\nimage: cypress/browsers:22.15.0pipelines: 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\n```\n\n**How this `bitbucket-pipelines.yml` works:**\n\n* 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.\n* The code is checked out from the Bitbucket repository.\n* Finally, our scripts will:\n * Install npm dependencies\n * Start the project web server (`npm start`)\n * Run the Cypress tests within the Bitbucket repository using Firefox\n", "section": "app", "anchors": [ "testing-with-cypress-docker-images" ], "path": "/llm/json/chunked/app/continuous-integration/bitbucket-pipelines.json", "token_estimate": 235 }, { "id": "app/continuous-integration/bitbucket-pipelines#caching-dependencies-and-build-artifacts", "doc_id": "app/continuous-integration/bitbucket-pipelines", "heading": "Caching Dependencies and Build Artifacts", "heading_level": 2, "content_markdown": "## Caching Dependencies and Build Artifacts\n\nPer 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.\n\nTo cache `node_modules`, the npm cache across builds, the `cache` attribute and configuration has been added below.\n\nArtifacts from a job can be defined by providing paths to the `artifacts` attribute.\n\nbitbucket-pipelines.yml\n\n```\nimage: cypress/browsers:22.15.0pipelines: 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/**\n```\n\nUsing 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.\n\nbitbucket-pipelines.yml\n\n```\ndefinitions: caches: npm: $HOME/.npm cypress: $HOME/.cache/Cypress\n```\n", "section": "app", "anchors": [ "caching-dependencies-and-build-artifacts" ], "path": "/llm/json/chunked/app/continuous-integration/bitbucket-pipelines.json", "token_estimate": 176 }, { "id": "app/continuous-integration/bitbucket-pipelines#parallelization", "doc_id": "app/continuous-integration/bitbucket-pipelines", "heading": "Parallelization", "heading_level": 2, "content_markdown": "## Parallelization\n\n[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.\n\nBefore diving into an example of a parallelization setup, it is important to understand the two different types of jobs that we will declare:\n\n* **Install Job**: A job that installs and caches dependencies that will be used by subsequent jobs later in the Bitbucket Pipelines workflow.\n* **Worker Job**: A job that handles execution of Cypress tests and depends on the _install job_.\n\n### Install Job\n\nThe separation of installation from test running is necessary when running parallel jobs. It allows for reuse of various build steps aided by caching.\n\nFirst, 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.\n\nThe 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).\n\nbitbucket-pipelines.yml\n\n```\nimage: cypress/base:22.15.0## job definition for running E2E tests in parallele2e: &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/**\n```\n\n### Worker Jobs\n\nNext, the worker jobs under `pipelines` that will run Cypress tests with Chrome in parallel.\n\nWe 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.\n\nbitbucket-pipelines.yml\n\n```\n## 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: <<: *e2edefinitions: caches: npm: $HOME/.npm cypress: $HOME/.cache/Cypress\n```\n\nThe complete `bitbucket-pipelines.yml` is below:\n\nbitbucket-pipelines.yml\n\n```\nimage: cypress/base:22.15.0## job definition for running E2E tests in parallele2e: &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: <<: *e2edefinitions: caches: npm: $HOME/.npm cypress: $HOME/.cache/Cypress\n```\n", "section": "app", "anchors": [ "parallelization" ], "path": "/llm/json/chunked/app/continuous-integration/bitbucket-pipelines.json", "token_estimate": 555 }, { "id": "app/continuous-integration/bitbucket-pipelines#install-job", "doc_id": "app/continuous-integration/bitbucket-pipelines", "heading": "Install Job", "heading_level": 3, "content_markdown": "### Install Job\n\nThe separation of installation from test running is necessary when running parallel jobs. It allows for reuse of various build steps aided by caching.\n\nFirst, 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.\n\nThe 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).\n\nbitbucket-pipelines.yml\n\n```\nimage: cypress/base:22.15.0## job definition for running E2E tests in parallele2e: &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/**\n```\n", "section": "app", "anchors": [ "install-job" ], "path": "/llm/json/chunked/app/continuous-integration/bitbucket-pipelines.json", "token_estimate": 165 }, { "id": "app/continuous-integration/bitbucket-pipelines#worker-jobs", "doc_id": "app/continuous-integration/bitbucket-pipelines", "heading": "Worker Jobs", "heading_level": 3, "content_markdown": "### Worker Jobs\n\nNext, the worker jobs under `pipelines` that will run Cypress tests with Chrome in parallel.\n\nWe 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.\n\nbitbucket-pipelines.yml\n\n```\n## 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: <<: *e2edefinitions: caches: npm: $HOME/.npm cypress: $HOME/.cache/Cypress\n```\n\nThe complete `bitbucket-pipelines.yml` is below:\n\nbitbucket-pipelines.yml\n\n```\nimage: cypress/base:22.15.0## job definition for running E2E tests in parallele2e: &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: <<: *e2edefinitions: caches: npm: $HOME/.npm cypress: $HOME/.cache/Cypress\n```\n", "section": "app", "anchors": [ "worker-jobs" ], "path": "/llm/json/chunked/app/continuous-integration/bitbucket-pipelines.json", "token_estimate": 275 }, { "id": "app/continuous-integration/bitbucket-pipelines#using-cypress-cloud-with-bitbucket-pipelines", "doc_id": "app/continuous-integration/bitbucket-pipelines", "heading": "Using Cypress Cloud with Bitbucket Pipelines", "heading_level": 2, "content_markdown": "## Using Cypress Cloud with Bitbucket Pipelines\n\nIn 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):\n\n1. [Recording test results with the `--record` flag](/llm/markdown/cloud/get-started/setup.md) to Cypress Cloud.\n \n * In-depth and shareable [test reports](/llm/markdown/cloud/features/recorded-runs.md#Latest-Runs).\n * 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.\n * [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).\n * [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).\n2. [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.\n \n3. 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.\n", "section": "app", "anchors": [ "using-cypress-cloud-with-bitbucket-pipelines" ], "path": "/llm/json/chunked/app/continuous-integration/bitbucket-pipelines.json", "token_estimate": 221 } ] }