{
  "doc": {
    "id": "app/continuous-integration/circleci",
    "title": "Run Cypress tests in CircleCI: A Step-by-Step Guide",
    "description": "Set up CircleCI to run Cypress tests with the Cypress Orb, cache dependencies and build artifacts, and parallelize Cypress tests.",
    "section": "app",
    "source_path": "/llm/markdown/app/continuous-integration/circleci.md",
    "version": "ce02913654e2655ee63448bdc92bb92c7b46a619",
    "updated_at": "2026-04-22T19:37:51.587Z",
    "headings": [
      {
        "id": "app/continuous-integration/circleci#run-cypress-in-circleci",
        "text": "Run Cypress in CircleCI",
        "level": 1
      },
      {
        "id": "app/continuous-integration/circleci#what-youll-learn",
        "text": " What you'll learn",
        "level": 5
      },
      {
        "id": "app/continuous-integration/circleci#basic-setup",
        "text": "Basic Setup",
        "level": 2
      },
      {
        "id": "app/continuous-integration/circleci#parallelization",
        "text": "Parallelization",
        "level": 2
      },
      {
        "id": "app/continuous-integration/circleci#additional-examples",
        "text": "Additional Examples",
        "level": 2
      },
      {
        "id": "app/continuous-integration/circleci#component-testing-example",
        "text": "Component Testing Example",
        "level": 3
      },
      {
        "id": "app/continuous-integration/circleci#yarn-example",
        "text": "Yarn Example",
        "level": 3
      },
      {
        "id": "app/continuous-integration/circleci#chrome-example",
        "text": "Chrome Example",
        "level": 3
      }
    ]
  },
  "content": {
    "type": "root",
    "children": [
      {
        "type": "heading",
        "depth": 1,
        "children": [
          {
            "type": "text",
            "value": "Run Cypress in CircleCI"
          }
        ]
      },
      {
        "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 CircleCI to run Cypress tests with the Cypress Orb"
                  }
                ]
              }
            ]
          },
          {
            "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 CircleCI"
                  }
                ]
              }
            ]
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "The\n"
          },
          {
            "type": "link",
            "title": null,
            "url": "https://circleci.com/developer/orbs/orb/cypress-io/cypress",
            "children": [
              {
                "type": "text",
                "value": "Cypress CircleCI Orb"
              }
            ]
          },
          {
            "type": "text",
            "value": "\nis the official CircleCI Orb of Cypress. Although you don't need to use the\norb to run your tests in CircleCI, the benefit of using the orb is that it\nallows you to easily install, cache and run Cypress tests in CircleCI with less\neffort. The orb abstracts common steps necessary for running your tests in\nCircleCI in order to make your life as a developer better!"
          }
        ]
      },
      {
        "type": "heading",
        "depth": 2,
        "children": [
          {
            "type": "text",
            "value": "Basic Setup"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "The "
          },
          {
            "type": "link",
            "title": null,
            "url": "https://github.com/cypress-io/circleci-orb",
            "children": [
              {
                "type": "text",
                "value": "Cypress CircleCI Orb"
              }
            ]
          },
          {
            "type": "text",
            "value": " is a\npiece of configuration set in your `.circleci/config.yml` file to correctly\ninstall, cache and run Cypress with very little effort."
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "For the Orb Quick Start Guide and usage cases, view the CircleCI\n"
          },
          {
            "type": "link",
            "title": null,
            "url": "https://circleci.com/developer/orbs/orb/cypress-io/cypress",
            "children": [
              {
                "type": "text",
                "value": "Cypress orb documentation"
              }
            ]
          },
          {
            "type": "text",
            "value": "."
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "A typical project can have:"
          }
        ]
      },
      {
        "type": "code",
        "lang": "yaml",
        "meta": "title=\".circleci/config.yml\"",
        "value": "version: 2.1\norbs:\n  # \"cypress-io/cypress@6\" installs the latest published\n  # version \"s.x.y\" of the orb. We recommend you then use\n  # the strict explicit version \"cypress-io/cypress@6.x.y\"\n  # to lock the version and prevent unexpected CI changes\n  cypress: cypress-io/cypress@6\nworkflows:\n  build:\n    jobs:\n      - cypress/run: # \"run\" job comes from \"cypress\" orb\n          start-command: 'npm run start'"
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "That's it! Your repo's dependencies will be installed and cached and your\nCypress tests will run in CircleCI"
          }
        ]
      },
      {
        "type": "heading",
        "depth": 2,
        "children": [
          {
            "type": "text",
            "value": "Parallelization"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "A more complex project that needs to install dependencies, start a server, and\nrun tests across 4 CI machines\n"
          },
          {
            "type": "link",
            "title": null,
            "url": "/llm/markdown/cloud/features/smart-orchestration/parallelization.md",
            "children": [
              {
                "type": "text",
                "value": "in parallel"
              }
            ]
          },
          {
            "type": "text",
            "value": " may have:"
          }
        ]
      },
      {
        "type": "code",
        "lang": "yaml",
        "meta": "title=\".circleci/config.yml\"",
        "value": "version: 2.1\norbs:\n  cypress: cypress-io/cypress@6\nworkflows:\n  build:\n    jobs:\n      - cypress/run:\n          start-command: 'npm run start'\n          cypress-command: 'npx cypress run --parallel --record --group all tests'\n          parallelism: 4"
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Using the orb brings simplicity and static checks of parameters to CircleCI\nconfiguration."
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "You can find additional examples at\n"
          },
          {
            "type": "link",
            "title": null,
            "url": "https://github.com/cypress-io/circleci-orb/blob/master/src/examples",
            "children": [
              {
                "type": "text",
                "value": "our orb examples page"
              }
            ]
          },
          {
            "type": "text",
            "value": "."
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "The Cypress  uses the\nCircle CI "
          },
          {
            "type": "link",
            "title": null,
            "url": "https://github.com/cypress-io/circleci-orb",
            "children": [
              {
                "type": "text",
                "value": "Cypress Orb"
              }
            ]
          },
          {
            "type": "text",
            "value": ", Codecov\nOrb, and Windows Orb to test over 300 test cases in parallel across 25 machines,\nmultiple browsers, multiple device sizes, and multiple operating systems with\nfull code-coverage reporting and\n"
          },
          {
            "type": "link",
            "title": null,
            "url": "https://cloud.cypress.io/projects/7s5okt",
            "children": [
              {
                "type": "text",
                "value": "Cypress Cloud recording"
              }
            ]
          },
          {
            "type": "text",
            "value": "."
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "/* prettier-ignore */"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Check out the full ."
          }
        ]
      },
      {
        "type": "heading",
        "depth": 2,
        "children": [
          {
            "type": "text",
            "value": "Additional Examples"
          }
        ]
      },
      {
        "type": "heading",
        "depth": 3,
        "children": [
          {
            "type": "text",
            "value": "Component Testing Example"
          }
        ]
      },
      {
        "type": "code",
        "lang": "yaml",
        "meta": "title=\".circleci/config.yml\"",
        "value": "version: 2.1\norbs:\n  cypress: cypress-io/cypress@6\nworkflows:\n  test:\n    jobs:\n      - cypress/run:\n          cypress-command: 'npx cypress run --component'"
      },
      {
        "type": "heading",
        "depth": 3,
        "children": [
          {
            "type": "text",
            "value": "Yarn Example"
          }
        ]
      },
      {
        "type": "code",
        "lang": "yaml",
        "meta": "title=\".circleci/config.yml\"",
        "value": "version: 2.1\norbs:\n  cypress: cypress-io/cypress@6\nworkflows:\n  test:\n    jobs:\n      - cypress/run:\n          package-manager: 'yarn'\n          start-command: 'yarn start'"
      },
      {
        "type": "heading",
        "depth": 3,
        "children": [
          {
            "type": "text",
            "value": "Chrome Example"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Cypress uses Electron by default to run your tests. The `install-browsers` flag\nis used to install Chrome, Chrome for Testing, Edge, Firefox and the geckodriver to run your tests.\nThis is only needed if you are passing the `--browser` flag in your `cypress-command`."
          }
        ]
      },
      {
        "type": "code",
        "lang": "yaml",
        "meta": "title=\".circleci/config.yml\"",
        "value": "version: 2.1\norbs:\n  cypress: cypress-io/cypress@6\nworkflows:\n  test:\n    jobs:\n      - cypress/run:\n          install-browsers: true\n          start-command: 'npm run start'\n          cypress-command: 'npx cypress run --browser chrome'"
      }
    ]
  },
  "token_estimate": 633
}