{ "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": "24a73f8a97175663aaffd3b016289fb2a523a4ea", "updated_at": "2026-05-14T20:17:33.301Z", "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 } ] }, "content": { "type": "root", "children": [ { "type": "heading", "depth": 1, "children": [ { "type": "text", "value": "Run Cypress in Bitbucket Pipelines" } ] }, { "type": "heading", "depth": 5, "children": [ { "type": "text", "value": "What you'll learn" } ] }, { "type": "list", "ordered": false, "start": null, "spread": false, "children": [ { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "How to set up Bitbucket Pipelines to run Cypress tests" } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "How to cache dependencies and build artifacts" } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "How to parallelize Cypress tests with Bitbucket Pipelines" } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "How to use Cypress Cloud with Bitbucket Pipelines" } ] } ] } ] }, { "type": "heading", "depth": 2, "children": [ { "type": "text", "value": "Basic Setup" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Detailed documentation is available in the " }, { "type": "link", "title": null, "url": "https://support.atlassian.com/bitbucket-cloud/docs/get-started-with-bitbucket-pipelines/", "children": [ { "type": "text", "value": "Bitbucket Pipelines Documentation" } ] }, { "type": "text", "value": "." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Bitbucket runs most builds in Docker containers as described in " }, { "type": "link", "title": null, "url": "https://support.atlassian.com/bitbucket-cloud/docs/docker-image-options/", "children": [ { "type": "text", "value": "Docker image options" } ] }, { "type": "text", "value": "." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "If you use the currently available default Bitbucket / Atlassian Linux images listed in the \"Default build environment\" of the Bitbucket Cloud documentation " }, { "type": "link", "title": null, "url": "https://support.atlassian.com/bitbucket-cloud/docs/use-docker-images-as-build-environments/", "children": [ { "type": "text", "value": "Use Docker images as build environments" } ] }, { "type": "text", "value": " you must additionally install " }, { "type": "link", "title": null, "url": "/llm/markdown/app/get-started/install-cypress.md#Linux-Prerequisites", "children": [ { "type": "text", "value": "Cypress Linux prerequisites" } ] }, { "type": "text", "value": "." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "For a simpler setup, use a Cypress Docker image, as described in the following section." } ] }, { "type": "heading", "depth": 2, "children": [ { "type": "text", "value": "Testing with Cypress Docker Images" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "The Cypress team maintains the official " }, { "type": "link", "title": null, "url": "https://github.com/cypress-io/cypress-docker-images", "children": [ { "type": "text", "value": "Docker Images" } ] }, { "type": "text", "value": " 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`." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Read about " }, { "type": "link", "title": null, "url": "/llm/markdown/app/continuous-integration/overview.md#Cypress-Docker-variants", "children": [ { "type": "text", "value": "Cypress Docker variants" } ] }, { "type": "text", "value": " to decide which image is best for your project." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "bitbucket-pipelines.yml" } ] }, { "type": "code", "lang": null, "meta": null, "value": "image: 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" }, { "type": "paragraph", "children": [ { "type": "text", "value": "How this `bitbucket-pipelines.yml` works:" } ] }, { "type": "list", "ordered": false, "start": null, "spread": false, "children": [ { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "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." } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "The code is checked out from the Bitbucket repository." } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "Finally, our scripts will:" } ] }, { "type": "list", "ordered": false, "start": null, "spread": false, "children": [ { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "Install npm dependencies" } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "Start the project web server (`npm start`)" } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "Run the Cypress tests within the Bitbucket repository using Firefox" } ] } ] } ] } ] } ] }, { "type": "heading", "depth": 2, "children": [ { "type": "text", "value": "Caching Dependencies and Build Artifacts" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Per the " }, { "type": "link", "title": null, "url": "https://support.atlassian.com/bitbucket-cloud/docs/cache-dependencies/", "children": [ { "type": "text", "value": "Caches documentation" } ] }, { "type": "text", "value": ", Bitbucket offers options for caching dependencies and build artifacts across many different workflows." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "To cache `node_modules`, the npm cache across builds, the `cache` attribute and configuration has been added below." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Artifacts from a job can be defined by providing paths to the `artifacts` attribute." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "bitbucket-pipelines.yml" } ] }, { "type": "code", "lang": null, "meta": null, "value": "image: 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/**" }, { "type": "paragraph", "children": [ { "type": "text", "value": "Using the " }, { "type": "link", "title": null, "url": "https://support.atlassian.com/bitbucket-cloud/docs/configure-bitbucket-pipelinesyml/#Global-configuration-options", "children": [ { "type": "text", "value": "definitions" } ] }, { "type": "text", "value": " block we can define additional caches for npm and Cypress." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "bitbucket-pipelines.yml" } ] }, { "type": "code", "lang": null, "meta": null, "value": "definitions: caches: npm: $HOME/.npm cypress: $HOME/.cache/Cypress" }, { "type": "heading", "depth": 2, "children": [ { "type": "text", "value": "Parallelization" } ] }, { "type": "paragraph", "children": [ { "type": "link", "title": null, "url": "/llm/markdown/cloud/get-started/introduction.md", "children": [ { "type": "text", "value": "Cypress Cloud" } ] }, { "type": "text", "value": " offers the ability to " }, { "type": "link", "title": null, "url": "/llm/markdown/cloud/features/smart-orchestration/parallelization.md", "children": [ { "type": "text", "value": "parallelize and group test runs" } ] }, { "type": "text", "value": " along with additional insights and " }, { "type": "link", "title": null, "url": "/llm/markdown/cloud/features/analytics/overview.md", "children": [ { "type": "text", "value": "analytics" } ] }, { "type": "text", "value": " for Cypress tests." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Before diving into an example of a parallelization setup, it is important to understand the two different types of jobs that we will declare:" } ] }, { "type": "list", "ordered": false, "start": null, "spread": false, "children": [ { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "Install Job: A job that installs and caches dependencies that will be used by subsequent jobs later in the Bitbucket Pipelines workflow." } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "Worker Job: A job that handles execution of Cypress tests and depends on the install job." } ] } ] } ] }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "Install Job" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "The separation of installation from test running is necessary when running parallel jobs. It allows for reuse of various build steps aided by caching." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "First, we break the pipeline up into reusable chunks of configuration using a " }, { "type": "link", "title": null, "url": "https://support.atlassian.com/bitbucket-cloud/docs/yaml-anchors/", "children": [ { "type": "text", "value": "YAML anchor" } ] }, { "type": "text", "value": ", `&e2e`. This will be used by the worker jobs." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "The following configuration using the `--parallel` and `--record` flags to " }, { "type": "link", "title": null, "url": "/llm/markdown/app/references/command-line.md#cypress-run", "children": [ { "type": "text", "value": "cypress run" } ] }, { "type": "text", "value": " requires setting up recording test results to " }, { "type": "link", "title": null, "url": "/llm/markdown/cloud/get-started/introduction.md", "children": [ { "type": "text", "value": "Cypress Cloud" } ] }, { "type": "text", "value": "." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "bitbucket-pipelines.yml" } ] }, { "type": "code", "lang": null, "meta": null, "value": "image: 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/**" }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "Worker Jobs" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Next, the worker jobs under `pipelines` that will run Cypress tests with Chrome in parallel." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "We can use the `e2e` " }, { "type": "link", "title": null, "url": "https://support.atlassian.com/bitbucket-cloud/docs/yaml-anchors/", "children": [ { "type": "text", "value": "YAML anchor" } ] }, { "type": "text", "value": " 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." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "bitbucket-pipelines.yml" } ] }, { "type": "code", "lang": null, "meta": null, "value": "## 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" }, { "type": "paragraph", "children": [ { "type": "text", "value": "The complete `bitbucket-pipelines.yml` is below:" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "bitbucket-pipelines.yml" } ] }, { "type": "code", "lang": null, "meta": null, "value": "image: 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" }, { "type": "heading", "depth": 2, "children": [ { "type": "text", "value": "Using Cypress Cloud with Bitbucket Pipelines" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "In the Bitbucket Pipelines configuration we have defined in the previous section, we are leveraging three useful features of " }, { "type": "link", "title": null, "url": "/llm/markdown/cloud/get-started/introduction.md", "children": [ { "type": "text", "value": "Cypress Cloud" } ] }, { "type": "text", "value": ":" } ] }, { "type": "list", "ordered": true, "start": 1, "spread": true, "children": [ { "type": "listItem", "spread": true, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "link", "title": null, "url": "/llm/markdown/cloud/get-started/setup.md", "children": [ { "type": "text", "value": "Recording test results with the `--record` flag" } ] }, { "type": "text", "value": " to Cypress Cloud." } ] }, { "type": "list", "ordered": false, "start": null, "spread": false, "children": [ { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "In-depth and shareable " }, { "type": "link", "title": null, "url": "/llm/markdown/cloud/features/recorded-runs.md#Latest-Runs", "children": [ { "type": "text", "value": "test reports" } ] }, { "type": "text", "value": "." } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "Visibility into test failures via quick access to " }, { "type": "link", "title": null, "url": "/llm/markdown/cloud/features/test-replay.md", "children": [ { "type": "text", "value": "Test Replay" } ] }, { "type": "text", "value": ", error messages, stack traces, screenshots, videos, and contextual details." } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "link", "title": null, "url": "/llm/markdown/cloud/integrations/github.md", "children": [ { "type": "text", "value": "Integrating testing with the pull-request (PR) process" } ] }, { "type": "text", "value": " via " }, { "type": "link", "title": null, "url": "/llm/markdown/cloud/integrations/github.md#Status-checks", "children": [ { "type": "text", "value": "commit status check guards" } ] }, { "type": "text", "value": " and convenient " }, { "type": "link", "title": null, "url": "/llm/markdown/cloud/integrations/github.md#Pull-request-comments", "children": [ { "type": "text", "value": "test report comments" } ] }, { "type": "text", "value": "." } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "link", "title": null, "url": "/llm/markdown/cloud/features/flaky-test-management.md", "children": [ { "type": "text", "value": "Detecting flaky tests" } ] }, { "type": "text", "value": " and surfacing them via " }, { "type": "link", "title": null, "url": "/llm/markdown/cloud/features/flaky-test-management.md#Slack", "children": [ { "type": "text", "value": "Slack alerts" } ] }, { "type": "text", "value": " or " }, { "type": "link", "title": null, "url": "/llm/markdown/cloud/features/flaky-test-management.md#GitHub", "children": [ { "type": "text", "value": "GitHub PR status checks" } ] }, { "type": "text", "value": "." } ] } ] } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "link", "title": null, "url": "/llm/markdown/cloud/features/smart-orchestration/parallelization.md", "children": [ { "type": "text", "value": "Parallelizing test runs" } ] }, { "type": "text", "value": " and optimizing their execution via " }, { "type": "link", "title": null, "url": "/llm/markdown/cloud/features/smart-orchestration/load-balancing.md#Balance-strategy", "children": [ { "type": "text", "value": "intelligent load-balancing" } ] }, { "type": "text", "value": " of test specs across CI machines with the `--parallel` flag." } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "Organizing and consolidating multiple `cypress run` calls by labeled groups into a single report within " }, { "type": "link", "title": null, "url": "https://on.cypress.io/cloud", "children": [ { "type": "text", "value": "Cypress Cloud" } ] }, { "type": "text", "value": ". 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." } ] } ] } ] } ] }, "token_estimate": 1351 }