> For the complete CircleCI developer hub index, see [llms.txt](https://circleci.com/developer/llms.txt)

# cypress-io/cypress

Run your Cypress.io end-to-end & component tests without spending time configuring CircleCI


## Commands

### install

Installs your application's node modules and cypress dependencies


| Parameter | Type | Default | Description |
|---|---|---|---|
| `cypress-cache-key` | string | cypress-cache-{{ arch }}-{{ checksum "package.json" }} | Cache key used to cache the Cypress binary. |
| `cypress-cache-path` | string | ~/.cache/Cypress | By default, this will cache the '~/.cache/Cypress' directory so that the Cypress binary is cached. You can override this by providing your own cache path.
 |
| `include-branch-in-node-cache-key` | boolean | false | If true, this cache will only apply to runs within the same branch. (Adds -{{ .Branch }}- to the node cache key)
 |
| `install-browsers` | boolean | false | Cypress runs by default in the Electron browser. Use this flag to install additional browsers to run your tests in.
This is only needed if you are passing the `--browser` flag in your `cypress-command`.
This parameter leverages the `circleci/browser-tools` orb and includes Chrome, Chrome for Testing, Edge, Firefox and the geckodriver.
If you need additional browser support you can set this to false and use an executor with a Docker image
that includes the browsers of your choosing. See https://hub.docker.com/r/cypress/browsers/tags
 |
| `install-command` | string |  | Overrides the default npm command (npm ci) |
| `node-cache-version` | string | v1 | Change the default node cache version if you need to clear the cache for any reason. |
| `package-manager` | enum | npm | Select the default node package manager to use. npm v5+ Required. |
| `post-install` | string |  | Additional commands to run after running install but before verifying Cypress and saving cache.
 |
| `skip-checkout` | boolean | false | Allow skipping the `checkout` command |
| `working-directory` | string |  | Directory containing package.json |

### run-tests

A single, complete job to run Cypress tests


| Parameter | Type | Default | Description |
|---|---|---|---|
| `cypress-command` | string | npx cypress run | Command used to run your Cypress tests |
| `start-command` | string |  | Command used to start your local dev server for Cypress to tests against |
| `working-directory` | string | . | Directory containing package.json |

## Jobs

### run

A single, complete job to run Cypress end-to-end tests in your application.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `cypress-cache-key` | string | cypress-cache-{{ arch }}-{{ checksum "package.json" }} | Cache key used to cache the Cypress binary. |
| `cypress-cache-path` | string | ~/.cache/Cypress | By default, this will cache the '~/.cache/Cypress' directory so that the Cypress binary is cached. You can override this by providing your own cache path.
 |
| `cypress-command` | string | npx cypress run | Command used to run your Cypress tests |
| `include-branch-in-node-cache-key` | boolean | false | If true, this cache will only apply to runs within the same branch. (Adds -{{ .Branch }}- to the node cache key)
 |
| `install-browsers` | boolean | false | Cypress runs by default in the Electron browser. Use this flag to install additional browsers to run your tests in.
This is only needed if you are passing the `--browser` flag in your `cypress-command`.
This parameter leverages the `circleci/browser-tools` orb and includes Chrome, Chrome for Testing, Edge, Firefox and the geckodriver.
If you need additional browser support you can set this to false and use an executor with a docker image
that includes the browsers of your choosing. See https://hub.docker.com/r/cypress/browsers/tags
 |
| `install-command` | string |  | Overrides the default npm command (npm ci) |
| `node-cache-version` | string | v1 | Change the default node cache version if you need to clear the cache for any reason. |
| `node-version` | string | 24.15.0 | The version of Node.js to run your tests with.
 |
| `package-manager` | enum | npm | Select the default node package manager to use. npm v5+ Required. |
| `parallelism` | integer | 1 | Number of Circle machines to use for load balancing, min 1
(requires `parallel` and `record` flags in your `cypress-command`)
 |
| `post-install` | string |  | Additional commands to run after running install but before verifying Cypress and saving cache.
 |
| `resource_class` | string | medium |  |
| `skip-checkout` | boolean | false | Whether to skip code checkout |
| `start-command` | string |  | Command used to start your local dev server for Cypress to tests against |
| `working-directory` | string |  | Directory containing package.json |

## Executors

### default

Single Docker container used to run Cypress Tests


| Parameter | Type | Default | Description |
|---|---|---|---|
| `node-version` | string | 24.15.0 | The version of Node.js to run your tests with.
 |

## Examples

### browser

Runs Cypress tests using specified browser. `install-browsers: true` installs the default browsers Chrome and Firefox with the geckodriver, and the optional browsers Chrome for Testing and Edge from the CircleCI Browser Tools orb at https://circleci.com/developer/orbs/orb/circleci/browser-tools#commands-install_browser_tools.


```yaml
version: '2.1'
orbs:
  cypress: cypress-io/cypress@6
workflows:
  use-my-orb:
    jobs:
      - cypress/run:
          cypress-command: npx cypress run --browser chrome
          install-browsers: true
          start-command: npm run start:dev
```

### caching

Runs Cypress tests and invalidates the current cache


```yaml
version: '2.1'
orbs:
  cypress: cypress-io/cypress@6
workflows:
  use-my-orb:
    jobs:
      - cypress/run:
          cypress-cache-key: custom-cypress-cache-v1-{{ arch }}-{{ checksum "package.json" }}
          cypress-cache-path: ~/.cache/custom-dir/Cypress
          cypress-command: npx cypress run --component
          node-cache-version: v2
```

### commands

Runs Cypress tests in your own job using commands


```yaml
version: '2.1'
orbs:
  cypress: cypress-io/cypress@6
jobs:
  install-and-persist:
    executor: cypress/default
    steps:
      - cypress/install
      - persist_to_workspace:
          paths:
            - .cache/Cypress
            - project
          root: ~/
  run-tests-in-parallel:
    executor: cypress/default
    parallelism: 8
    steps:
      - attach_workspace:
          at: ~/
      - cypress/run-tests:
          cypress-command: npx cypress run --component --parallel --record
workflows:
  use-my-orb:
    jobs:
      - install-and-persist:
          name: Install & Persist To Workspace
      - run-tests-in-parallel:
          name: Run Tests in Parallel
          requires:
            - Install & Persist To Workspace
```

### component

Runs Cypress component tests. Installs dependencies and caches npm modules together with the Cypress binary.


```yaml
version: '2.1'
orbs:
  cypress: cypress-io/cypress@6
workflows:
  use-my-orb:
    jobs:
      - cypress/run:
          cypress-command: npx cypress run --component
```

### custom-install

Runs Cypress tests and installs dependencies using a custom install and post-install script.


```yaml
version: '2.1'
orbs:
  cypress: cypress-io/cypress@6
workflows:
  use-my-orb:
    jobs:
      - cypress/run:
          install-command: npm install && echo hello
          post-install: npm run build
```

### edge

Runs Cypress tests in Microsoft Edge.


```yaml
version: '2.1'
orbs:
  cypress: cypress-io/cypress@6
workflows:
  use-my-orb:
    jobs:
      - cypress/run:
          cypress-command: npx cypress run --browser edge
          install-browsers: true
          start-command: npm run start:dev
```

### mono-repo

Runs Cypress tests in a monorepo or when your Cypress folder is somewhere other than the root directory.


```yaml
version: '2.1'
orbs:
  cypress: cypress-io/cypress@6
workflows:
  use-my-orb:
    jobs:
      - cypress/run:
          cypress-cache-key: >-
            cypress-cache-{{ arch }}-{{ checksum "libs/shared-ui/package.json"
            }}
          cypress-command: npx cypress run --component
          working-directory: libs/shared-ui
```

### node-version

Runs Cypress tests using the cypress/default executor with a specified Node.js version.


```yaml
version: '2.1'
orbs:
  cypress: cypress-io/cypress@6
jobs:
  run-cypress-in-specified-node-version:
    executor:
      name: cypress/default
      node-version: '24.15'
    steps:
      - cypress/install:
          package-manager: npm
      - cypress/run-tests:
          cypress-command: npx cypress run
          start-command: npm run start:dev
workflows:
  use-my-orb:
    jobs:
      - run-cypress-in-specified-node-version:
          name: Run Cypress in Node.js 24.15
```

### pnpm

Runs Cypress tests using pnpm. Installs dependencies and caches npm modules together with the Cypress binary.


```yaml
version: '2.1'
orbs:
  cypress: cypress-io/cypress@6
workflows:
  use-my-orb:
    jobs:
      - cypress/run:
          install-command: pnpm install --frozen-lockfile
          package-manager: pnpm
          start-command: pnpm start
```

### recording

Runs Cypress end-to-end tests in parallel and records results to Cypress Cloud. Installs dependencies and caches npm modules together with the Cypress binary.


```yaml
version: '2.1'
orbs:
  cypress: cypress-io/cypress@6
workflows:
  use-my-orb:
    jobs:
      - cypress/run:
          cypress-command: npx cypress run --parallel --record
          parallelism: 3
          start-command: npm run start
```

### run

Runs Cypress end-to-end tests without recording results to Cypress Cloud. Installs dependencies and caches npm modules together with the Cypress binary.


```yaml
version: '2.1'
orbs:
  cypress: cypress-io/cypress@6
workflows:
  use-my-orb:
    jobs:
      - cypress/run:
          start-command: npm run start
```

### wait-on

Runs Cypress tests after waiting for the local server to start using the wait-on package (https://github.com/jeffbski/wait-on).


```yaml
version: '2.1'
orbs:
  cypress: cypress-io/cypress@6
workflows:
  use-my-orb:
    jobs:
      - cypress/run:
          cypress-command: npx wait-on@latest http://localhost:8080 && npx cypress run
          start-command: npm start
```

### yarn

Runs Cypress tests using yarn. Installs dependencies and caches npm modules together with the Cypress binary.


```yaml
version: '2.1'
orbs:
  cypress: cypress-io/cypress@6
workflows:
  use-my-orb:
    jobs:
      - cypress/run:
          package-manager: yarn
          start-command: yarn start
```