# Upgrade Cypress to the Current Major Version

Yes. The agent moves the Cypress pin, the Docker images and the lint plugin together, runs every spec in three browsers, fixes what broke and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/upgrade-cypress/cypress/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

A Cypress version is written in more places than `package.json`, and a major upgrade that misses one of them passes locally and fails in CI. So the agent lists them first. In a project like cypress-io/cypress-example-kitchensink, `package.json` pins `cypress` at exactly `16.2.1` and `eslint-plugin-cypress` at `7.0.2`, lists `cypress` under `allowScripts`, and sets `engines.node` to `^22.22.2 || ^24.15.0 || >=26.0.0`. `.npmrc` has `save-exact=true` and a `min-release-age` of 7 with `cypress` excluded from it. Six GitHub workflows run the suite: four of them through `cypress-io/github-action` pinned by commit, and four inside the `cypress/browsers:24.22.1` container image, whose tag fixes the browser versions the recorded jobs use. `.node-version` names the Node that CI installs.

It then reads why the upgrade has not already happened. `renovate.json` automerges updates, with two exceptions that matter here: `major` updates have `automerge` off, and the `cypress/base` and `cypress/browsers` images are grouped and capped by `allowedVersions`. A new Cypress major therefore sits as an open pull request until a person takes it. The agent takes it. It reads the changelog and the migration guide for each major between the pinned version and the target, and turns them into a checklist: commands and config keys that were removed or renamed, the Node versions the new major supports, the browser versions it supports, and the plugin majors that match.

The specs are the test of the upgrade. After `npm install --save-exact cypress@<target>` and `npx cypress verify`, the agent installs Chrome and Firefox in its sandbox and runs the three scripts the repository already has for this: `npm run test:ci`, `test:ci:chrome` and `test:ci:firefox`, each of which starts the static server with `run-p --race` and runs all twenty spec files. No record key exists in the sandbox, so it uses these non-recording scripts and not the `:record` ones. A spec that fails only on the new major points at a line in the checklist; the agent applies the documented replacement in the spec and, where a helper is shared, in `cypress/support/commands.js`. In a suite that also documents the commands, as this one does under `app/commands/*.html`, the page that shows the old usage changes in the same commit.

Then the surrounding pins move as far as the checklist allows. If the new major drops a Node line, `engines.node` and `.node-version` follow. The container tag moves to an image whose browsers the new major supports, within the cap `renovate.json` sets. `eslint-plugin-cypress` moves if the new major needs a newer plugin, and `npm run lint` must pass afterwards, since here `npm run build` is an alias for the lint and it covers the workflow YAML as well as the JavaScript. The action pin is left alone unless the migration guide names a minimum version. The lockfile is whatever `npm install` wrote; the agent does not edit `package-lock.json` by hand.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Upgrade Cypress in this repository to the current major version. Read package.json, .npmrc, .node-version, cypress.config.js, cypress/support, renovate.json, every workflow under .github/workflows and AGENTS.md if present, and list every place a Cypress version, a cypress/ Docker image tag or a supported Node version is written. Read the Cypress changelog and migration guide for each major between the pinned version and the target and write a checklist of removed or renamed commands and config keys, supported Node versions, supported browsers and matching plugin versions. Install the target with npm install --save-exact, run npx cypress verify, install Chrome and Firefox, and run npm run test:ci, npm run test:ci:chrome and npm run test:ci:firefox; do not use the record scripts. Fix each spec that fails with the replacement the migration guide documents, and update any page under app/ that documents the old usage. Move engines.node, .node-version, the Docker image tags and eslint-plugin-cypress only as far as the new major requires, staying within the limits renovate.json sets. Run npm run lint. Do not add retries, skip tests, add a yarn.lock or change the npm scripts' names. Open a pull request with the checklist, each item marked applied or not applicable with the file it touched, and the summary lines of the three browser runs.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

A pull request that changes `package.json` and `package-lock.json`, the specs and support files the new major required, any documentation page that showed a removed usage, and whichever of `.node-version`, `engines.node` and the workflow image tags had to follow. The description carries the migration checklist with every item marked `applied`, with the file it touched, or `not applicable`, with the search that found no use of it.

Under the checklist are the summary tables Cypress prints at the end of each run, for Electron, Chrome and Firefox, from the agent's sandbox. They are not a substitute for the repository's own CI, which runs on the pull request with the pinned container image and, for recorded jobs, the project's record key. They show the reviewer that the spec changes were made against a passing run and not from reading alone.

A reviewer checks that no spec lost an assertion in the rewrite, and reads any change to `.node-version` with care: in a repository that other pipelines clone and run, as this one's `AGENTS.md` describes, that file is read by someone else's CI as well.

## Run it on every new Cypress major release

Renovate already opens a pull request when a major lands, and with `major` automerge off it waits. A label on that pull request starts nothing: a `github` trigger fires only for a pull request an owner, member or collaborator wrote, and Renovate's was written by a bot. So a maintainer opens an issue that names the target major, and an automation in the Project with this prompt and a `github` trigger on `issues.labeled`, with the label the team uses for upgrades they want worked in `labels`, starts one run when that label is applied. The trigger puts the issue after the prompt, so the agent reads the target version from it.

Across many repositories, a script on your server lists them with `GET /o/{org}/github` and sends this body once per repository to `POST /o/{org}/sessions`, each with a `request_id` that is a UUID v5 of the repository name and the target major, so a rerun of the script starts nothing twice. A key runs a limited number at once and queues the rest, oldest first.

## Why run it on Rush?

The work is mostly waiting on browsers. Three full runs of the suite, repeated after each batch of fixes, with Chrome and Firefox installed beside the Cypress binary, is the kind of job that takes over a laptop for an afternoon. In a Rush sandbox it runs unattended, and the commands and their output, failed attempts included, are kept in the run's transcript.

It is also work where the proof matters more than the diff. A version bump is one line; whether the suite still passes in every browser the team supports is the question. The pull request arrives with that answer attached, and the session read at `GET /o/{org}/sessions/{id}` names the pull request and what the run cost.

## Frequently asked questions

### Why not let Renovate do it?

Renovate changes the version and stops there. A major release that removes a command leaves the specs failing, and the bot's pull request stays red until someone rewrites them. The agent starts from the same bump and does the rewriting, with the browser runs to show it worked.

### Does it upgrade across several majors at once?

It reads the migration guide for every major in between and applies them in order, running the suite after each step so a failure is tied to one guide. If one step cannot be completed, the pull request stops at the last major that passes and lists what blocked the next.

### Can the sandbox record to Cypress Cloud?

Not without a record key, and the prompt tells the agent to use the non-recording scripts. Recording, parallel groups and the commit statuses they produce belong to your CI, which runs them on the pull request with its own secrets.

### What about the Docker image tags?

The agent moves them only when the new Cypress major needs browsers or a Node line the current image lacks, and it stays within the cap set in `renovate.json`. The tag change is in the same pull request so the recorded jobs and the binary change together.

## More Cypress jobs

- [Write Cypress Component Tests for the Untested Forms in a React App](https://getrush.ai/run/write-component-tests/cypress/)
- [Add Accessibility Tests to a Cypress Suite](https://getrush.ai/run/add-accessibility-tests/cypress/)
- [Run the Cypress API Specs in CI](https://getrush.ai/run/add-api-tests-to-ci/cypress/)

## More jobs like this: Upgrade dependencies weekly

- [Upgrade dbt and Its Packages](https://getrush.ai/run/upgrade-dbt-packages/dbt/)
- [Upgrade ASP.NET Core Dependencies Every Week](https://getrush.ai/run/upgrade-dependencies-weekly/aspnet-core/)
- [Upgrade Astro Dependencies Every Week](https://getrush.ai/run/upgrade-dependencies-weekly/astro/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
