{ "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": "ce02913654e2655ee63448bdc92bb92c7b46a619", "updated_at": "2026-04-22T19:37:51.587Z", "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\n" }, { "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\n\"Default build environment\" of the Bitbucket Cloud documentation\n" }, { "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\n" }, { "type": "link", "title": null, "url": "https://github.com/cypress-io/cypress-docker-images", "children": [ { "type": "text", "value": "Docker Images" } ] }, { "type": "text", "value": " for running\nCypress locally and in CI, with some images including Chrome, Firefox and Edge. For\nexample, this allows us to run the tests in Firefox by passing the\n`--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": "code", "lang": "yaml", "meta": "title=\"bitbucket-pipelines.yml\"", "value": "image: cypress/browsers:22.15.0\n\npipelines:\n default:\n - step:\n script:\n # install dependencies\n - npm ci\n # start the server in the background\n - npm run start &\n # run Cypress tests in Firefox\n - 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\nPipelines using the Cypress Docker image. It will run the pipelines defined in the\n`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\n" }, { "type": "link", "title": null, "url": "https://support.atlassian.com/bitbucket-cloud/docs/cache-dependencies/", "children": [ { "type": "text", "value": "Caches documentation" } ] }, { "type": "text", "value": ",\nBitbucket offers options for caching dependencies and\nbuild artifacts across many different workflows." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "To cache `node_modules`, the npm cache across builds, the `cache` attribute and\nconfiguration has been added below." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Artifacts from a job can be defined by providing paths to the `artifacts`\nattribute." } ] }, { "type": "code", "lang": "yaml", "meta": "title=\"bitbucket-pipelines.yml\"", "value": "image: cypress/browsers:22.15.0\n\npipelines:\n default:\n - step:\n caches:\n - node\n script:\n # install dependencies\n - npm ci\n # start the server in the background\n - npm run start &\n # run Cypress tests in Firefox\n - npx cypress run --browser firefox\n artifacts:\n # store any generates images and videos as artifacts\n - cypress/screenshots/**\n - cypress/videos/**" }, { "type": "paragraph", "children": [ { "type": "text", "value": "Using the\n" }, { "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": "\nblock we can define additional caches for npm and Cypress." } ] }, { "type": "code", "lang": "yaml", "meta": "title=\"bitbucket-pipelines.yml\"", "value": "definitions:\n caches:\n npm: $HOME/.npm\n 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\n" }, { "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": "\nalong 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\nCypress tests." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Before diving into an example of a parallelization setup, it is important to\nunderstand 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\nby 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\nthe 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\nparallel 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\n" }, { "type": "link", "title": null, "url": "https://support.atlassian.com/bitbucket-cloud/docs/yaml-anchors/", "children": [ { "type": "text", "value": "YAML anchor" } ] }, { "type": "text", "value": ",\n`&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\n" }, { "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\nrecording 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": "code", "lang": "yaml", "meta": "title=\"bitbucket-pipelines.yml\"", "value": "image: cypress/base:22.15.0\n\n## job definition for running E2E tests in parallel\ne2e: &e2e\n name: E2E tests\n caches:\n - node\n - cypress\n script:\n - npm run start &\n - npm run e2e:record -- --parallel --group UI-Chrome --ci-build-id $BITBUCKET_BUILD_NUMBER\n artifacts:\n # store any generates images and videos as artifacts\n - cypress/screenshots/**\n - 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\nin parallel." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "We can use the `e2e`\n" }, { "type": "link", "title": null, "url": "https://support.atlassian.com/bitbucket-cloud/docs/yaml-anchors/", "children": [ { "type": "text", "value": "YAML anchor" } ] }, { "type": "text", "value": "\nin our definition of the pipeline to execute parallel jobs using the `parallel`\nattribute. This will allow us to run multiples instances of Cypress at same\ntime." } ] }, { "type": "code", "lang": "yaml", "meta": "title=\"bitbucket-pipelines.yml\"", "value": "## job definition for running E2E tests in parallel\n## ...\n\npipelines:\n default:\n - step:\n name: Install dependencies\n caches:\n - npm\n - cypress\n - node\n script:\n - npm ci\n - parallel:\n # run N steps in parallel\n - step:\n <<: *e2e\n - step:\n <<: *e2e\n - step:\n <<: *e2e\ndefinitions:\n caches:\n npm: $HOME/.npm\n cypress: $HOME/.cache/Cypress" }, { "type": "paragraph", "children": [ { "type": "text", "value": "The complete `bitbucket-pipelines.yml` is below:" } ] }, { "type": "code", "lang": "yaml", "meta": "title=\"bitbucket-pipelines.yml\"", "value": "image: cypress/base:22.15.0\n\n## job definition for running E2E tests in parallel\ne2e: &e2e\n name: E2E tests\n caches:\n - node\n - cypress\n script:\n - npm run start &\n - npm run e2e:record -- --parallel --group UI-Chrome --ci-build-id $BITBUCKET_BUILD_NUMBER\n artifacts:\n # store any generates images and videos as artifacts\n - cypress/screenshots/**\n - cypress/videos/**\n\npipelines:\n default:\n - step:\n name: Install dependencies\n caches:\n - npm\n - cypress\n - node\n script:\n - npm ci\n - parallel:\n # run N steps in parallel\n - step:\n <<: *e2e\n - step:\n <<: *e2e\n - step:\n <<: *e2e\ndefinitions:\n caches:\n npm: $HOME/.npm\n 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\nsection, we are leveraging three useful features of\n" }, { "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": false, "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": "\nto 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\n" }, { "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\ntraces, 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": "\nvia\n" }, { "type": "link", "title": null, "url": "/llm/markdown/cloud/integrations/github.md#Status-checks", "children": [ { "type": "text", "value": "commit status check guards" } ] }, { "type": "text", "value": "\nand convenient\n" }, { "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\nthem 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\n" }, { "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": "\nand optimizing their execution via\n" }, { "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": "\nof 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\ninto a single report within " }, { "type": "link", "title": null, "url": "https://on.cypress.io/cloud", "children": [ { "type": "text", "value": "Cypress Cloud" } ] }, { "type": "text", "value": ". In\nthe 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": 1365 }