{"id":13727436,"url":"https://github.com/cypress-io/circleci-orb","last_synced_at":"2025-10-10T13:17:50.398Z","repository":{"id":37549601,"uuid":"154135206","full_name":"cypress-io/circleci-orb","owner":"cypress-io","description":"Install, cache and run Cypress.io tests on CircleCI with minimal configuration.","archived":false,"fork":false,"pushed_at":"2025-08-22T14:10:34.000Z","size":3448,"stargazers_count":161,"open_issues_count":12,"forks_count":104,"subscribers_count":28,"default_branch":"master","last_synced_at":"2025-08-22T16:35:29.378Z","etag":null,"topics":["circle","circle-ci","circle-orb","circleci","circleci-orbs","cypress","cypress-io"],"latest_commit_sha":null,"homepage":"https://circleci.com/orbs/registry/orb/cypress-io/cypress","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cypress-io.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2018-10-22T11:54:58.000Z","updated_at":"2025-08-22T14:10:19.000Z","dependencies_parsed_at":"2024-01-07T21:07:26.756Z","dependency_job_id":"30052f22-7c02-4c97-902f-507dafbc09f7","html_url":"https://github.com/cypress-io/circleci-orb","commit_stats":null,"previous_names":[],"tags_count":71,"template":false,"template_full_name":null,"purl":"pkg:github/cypress-io/circleci-orb","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cypress-io%2Fcircleci-orb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cypress-io%2Fcircleci-orb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cypress-io%2Fcircleci-orb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cypress-io%2Fcircleci-orb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cypress-io","download_url":"https://codeload.github.com/cypress-io/circleci-orb/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cypress-io%2Fcircleci-orb/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279004072,"owners_count":26083665,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-10T02:00:06.843Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["circle","circle-ci","circle-orb","circleci","circleci-orbs","cypress","cypress-io"],"created_at":"2024-08-03T01:03:56.068Z","updated_at":"2025-10-10T13:17:50.367Z","avatar_url":"https://github.com/cypress-io.png","language":null,"funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"# Cypress CircleCI Orb [![CircleCI](https://circleci.com/gh/cypress-io/circleci-orb.svg?style=svg)](https://circleci.com/gh/cypress-io/circleci-orb) [![CircleCI Orb Version](https://badges.circleci.com/orbs/cypress-io/cypress.svg)](https://circleci.com/developer/orbs/orb/cypress-io/cypress) [![renovate-app badge][renovate-badge]][renovate-app] [![GitHub license](https://img.shields.io/github/license/cypress-io/circleci-orb?logo=license)](https://github.com/cypress-io/circleci-orb/blob/master/LICENSE.md)\n\n## About\n\nThe [Cypress CircleCI Orb](https://github.com/cypress-io/circleci-orb) is a\npiece of configuration set in your `.circleci/config.yml` file to correctly\ninstall, cache and run Cypress with very little effort.\n\n💡 In CircleCI, a **Job** is a collection of steps to carry out an action. A **Command** defines a sequence of steps as a map to be executed in a job. **Executors** define the underlying technology to run a job. Below are all of these options that will allow you to run your Cypress tests with an out-of-the-box or customized configuration.\n\nFor the Orb Quick Start Guide and usage cases, view the CircleCI\n[Cypress orb documentation](https://circleci.com/developer/orbs/orb/cypress-io/cypress).\n\n## How to enable\n\n**Note:** To use CircleCI Orbs in your projects, you need to enable some settings:\n\nFrom organization settings allow using uncertified orbs `Settings -\u003e Security -\u003e Allow uncertified orbs`\n\nSee the official [CircleCI documentation](https://circleci.com/docs/2.0/using-orbs/).\n\n---\n\n## Jobs\n\n### _run_\n\nA complete job to install your application's node modules and Cypress dependencies, handle caching and run your tests. This is the out-of-the-box solution that will work for most use cases.\n\n#### Basic Setup\n\nA typical project can have:\n\n```yaml\nversion: 2.1\norbs:\n  # \"cypress-io/cypress@5\" 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@5.x.y\"\n  # to lock the version and prevent unexpected CI changes\n  cypress: cypress-io/cypress@5\nworkflows:\n  build:\n    jobs:\n      - cypress/run: # \"run\" job comes from \"Cypress\" orb\n          start-command: \"npm run start\"\n```\n\nBy using the `run` job definitions that Cypress provides inside the orb, it\nbrings simplicity and static checks of parameters to your CircleCI\nconfiguration.\n\nYou can find more usage examples at\n[our official orb page](https://circleci.com/developer/orbs/orb/cypress-io/cypress).\n\n#### Arguments\n\nYou can pass arguments to the `cypress/run` job to override any default behaviors. See the [full list of arguments](https://circleci.com/developer/orbs/orb/cypress-io/cypress#jobs-run).\n\n### Parallelization\n\nA more complex project that needs to install dependencies\nand run tests across 4 CI machines [in parallel](https://docs.cypress.io/guides/guides/parallelization)\nmay have:\n\n```yaml\nversion: 2.1\norbs:\n  cypress: cypress-io/cypress@5\nworkflows:\n  build:\n    jobs:\n      - cypress/run:\n          # split specs across machines\n          # record results with Cypress Cloud\n          cypress-command: \"npx cypress run --parallel --record\"\n          start-command: \"npm run start\"\n          parallelism: 4 # use 4 CircleCI machines to finish quickly\n```\n\n**Note:** recording test results and spec parallelization requires [Cypress Cloud](https://on.cypress.io/dashboard-introduction) account. You should also set your [record key](https://on.cypress.io/projects#Record-key) as `CYPRESS_RECORD_KEY` environment variable in the CircleCI project.\n\n### ⚠️ Usage and Consumption\n\nThere are 2 key metrics to understand when running a CI job across multiple\nmachines:\n\n- **Consumption time** on CircleCI\n- **Actual time** it takes for tests to run\n\n**Consumption time** is essentially the amount of CircleCI resources that a job requires\nto execute. For example, you may have a job that runs on 5 machines and takes 1 minute\nfor all to complete. In this example it would only take 1 minute of **actual time** to execute\nall the jobs but would **consume** 5 minutes of CircleCI resources.\n\nThe Cypress CircleCI Orb\nwas designed to be as simple and fast as possible for the majority of use cases.\nIf you are running your tests in parallel across more than 5\nmachines, you may _not_ want to use the `cypress/run` job directly as it will consume\nmore CircleCI resources than are necessary.\n\n\u003e **Parallelization Across 5+ Machines**\n\u003e\n\u003e To lower your consumption time when running in parallel on more than 5 machines,\n\u003e see [this example](https://circleci.com/developer/orbs/orb/cypress-io/cypress#usage-commands).\n\u003e\n\u003e Here we use the `cypress/install` and\n\u003e `cypress/run-tests` commands separately to first install dependencies to a workspace and then run tests in parallel.\n\n## Commands\n\n### _install_\n\nCommand that installs your application's node modules and Cypress dependencies.\n\n\u003e ⚠️ Note: this command is only necessary if you plan to execute the `run-tests` command in a separate job. Especially if you run the tests on multiple machines in parallel.\n\n#### Arguments\n\nYou can pass arguments to the `cypress/install` command to override any default behaviors. See the [full list of arguments](https://circleci.com/developer/orbs/orb/cypress-io/cypress#commands-install).\n\n### _run-tests_\n\nCommand that runs Cypress tests (assuming your machine has already installed\nnecessary dependencies).\n\n#### Arguments\n\nYou can pass arguments to the `cypress/run-tests` command to override any default behaviors. See the [full list of arguments](https://circleci.com/developer/orbs/orb/cypress-io/cypress#commands-run-tests).\n\n## Executors\n\nA single Docker container used to run Cypress tests. This default executor extends the [circleci/browser-tools orb](https://circleci.com/developer/orbs/orb/circleci/browser-tools).\n\n```yaml\nversion: 2.1\norbs:\n  cypress: cypress-io/cypress@5\nexecutor: cypress/default\njobs:\n  - cypress/run:\n```\n\nYou can also use your own executor by passing in your own Docker image. See the full list of Cypress images on [Docker Hub](https://hub.docker.com/r/cypress/browsers/tags), or compose your own image with the [Cypress Docker Factory](https://github.com/cypress-io/cypress-docker-images#cypressfactory).\n\n```yaml\nversion: 2.1\norbs:\n  cypress: cypress-io/cypress@5\nexecutor:\n  docker:\n    image: cypress/browsers:22.17.0 # your Docker image here\njobs:\n  - cypress/run:\n```\n\n## Examples\n\n#### Example using the `cypress/default` executor with `cypress/install` and `cypress/run-tests` commands:\n\n```yaml\nversion: 2.1\norbs:\n  cypress: cypress-io/cypress@5\njobs:\n  install:\n    executor: cypress/default\n    steps:\n      - cypress/install:\n          install-browsers: true\n      - persist_to_workspace:\n          root: ~/\n          paths:\n            - .cache/Cypress\n            - project\n  run-tests:\n    executor: cypress/default\n    parallelism: 10\n    steps:\n      - run: echo \"This step assumes dependencies were installed using the cypress/install job\"\n      - attach_workspace:\n          at: ~/\n      - cypress/run-tests:\n          cypress-command: \"npx cypress run --parallel --record\"\n          start-command: \"npm run start\"\n```\n\n---\n\n## Additional Info\n\n### Effective config\n\nIf you install [CircleCI local CLI](https://circleci.com/docs/local-cli/), you can see the final _effective_ configuration your project resolves to by running `circleci config process \u003cconfig filename\u003e` from the terminal.\n\n### Versions\n\nCypress orb is _versioned_ so you can be sure that the configuration will _not_ suddenly change as we change orb commands. We follow semantic versioning to make sure you can upgrade project configuration to minor and patch versions without breaking changes.\n\nYou can find all changes and published orb versions for Cypress orb at [cypress-io/circleci-orb/releases](https://github.com/cypress-io/circleci-orb/releases).\n\nWe are using `cypress-io/cypress@5` version in our examples, so you get the latest published orb version `5.x.x`. But we recommend locking it down to an exact version to prevent unexpected changes from suddenly breaking your builds.\n\n### License\n\nThis project is licensed under the terms of the [MIT license](/LICENSE.md).\n\n[renovate-badge]: https://img.shields.io/badge/renovate-app-blue.svg\n[renovate-app]: https://renovateapp.com/\n[local-cli]: https://circleci.com/docs/2.0/local-cli/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcypress-io%2Fcircleci-orb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcypress-io%2Fcircleci-orb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcypress-io%2Fcircleci-orb/lists"}