# Migrate a Cypress Test Suite to Playwright

Yes. The agent maps each Cypress command your specs use to its Playwright form, ports the suite beside the old one, runs both and lists what has no equivalent.

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

## What the agent does

How hard a migration is depends on which Cypress commands a suite uses, so the agent counts them before it ports a line. A suite like cypress-io/cypress-example-kitchensink is a useful worst case because it touches nearly all of them: twenty spec files under `cypress/e2e`, over two hundred `cy.get` calls, and beside the ordinary clicks and assertions there are `cy.intercept` with aliases, `cy.request` against a JSON API, `cy.clock` and `cy.tick`, `cy.viewport`, the cookie and storage commands, `cy.fixture`, `cy.readFile` and `cy.writeFile`, `cy.spy` and `cy.stub`, and a file of tests on the `Cypress.*` object itself. `cypress.config.js` sets no `baseUrl`; each spec visits `http://localhost:8080/...` in full, and `package.json` starts the app with `serve` on port 8080 through `scripts/start.js`.

The agent sorts those commands into three groups. The first translates directly. A `cy.get` chain with `.should` becomes a locator with a web-first `expect`. `cy.intercept` with a stubbed reply becomes `page.route` with `route.fulfill`, and `cy.wait('@alias')` becomes a `page.waitForResponse` promise created before the click that triggers the request. `cy.request` becomes the `request` fixture. `cy.clock(now)` and `cy.tick(10000)` become `page.clock.install` and `page.clock.fastForward`. `cy.viewport` becomes `page.setViewportSize`, the cookie commands become calls on the browser context, and `cy.go` and `cy.reload` become `page.goBack` and `page.reload`. `cy.fixture('example.json')` becomes an import of the same file from `cypress/fixtures`, so both suites read one copy.

The second group changes shape. Playwright tests run in Node, not in the browser, so `cy.readFile` and `cy.writeFile` become `fs` calls in the test, and anything that reached into the page with `cy.window()` or `cy.document()` becomes `page.evaluate`. The jQuery-style traversals in `traversal.cy.js`, such as `.prevUntil`, `.parentsUntil` and `.siblings`, have no locator method of the same name; each is rewritten as a CSS or XPath locator that selects the same elements, and the agent checks the match count against the Cypress test. The third group has no counterpart, and the agent says so instead of inventing one: `cy.spy`, `cy.stub` and `Cypress.sinon` rely on the Sinon that ships inside Cypress, and the tests in `cypress_api.cy.js` and `utilities.cy.js` exercise `Cypress.Commands`, `Cypress.config`, `Cypress._`, `Cypress.$` and `Cypress.Blob`, which are tests of the tool being replaced.

The new suite goes beside the old one. The agent adds `@playwright/test`, a `playwright.config.js` whose `webServer` runs `npm start` and waits for `http://localhost:8080`, a `baseURL` so tests visit paths, and projects for Chromium and Firefox, then writes one spec per Cypress file, in JavaScript like the originals. Style is enforced here: `eslint.config.mjs` applies `@stylistic` rules (single quotes, no semicolons, a space before function parentheses) together with the Mocha and Cypress plugins to every `.js` file, so the agent adds a block for the Playwright directory without those two plugins and runs `npm run lint`. It installs the browsers with `npx playwright install --with-deps`, runs the Playwright suite and the Cypress suite, and compares them test by test. Cypress stays installed, and its scripts keep their names.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Port this repository's Cypress end-to-end suite to Playwright, beside the existing suite. Read package.json, cypress.config.js, cypress/support, cypress/fixtures, every spec under cypress/e2e, the lint config and the CI workflows first. Count the Cypress commands in use and sort them into: direct translations, commands that change shape because Playwright tests run in Node, and commands with no Playwright equivalent. Add @playwright/test and a playwright.config.js with a webServer that runs npm start and waits for http://localhost:8080, a baseURL, and Chromium and Firefox projects. Write one Playwright spec per Cypress spec in JavaScript, keeping every test title. Use locators with web-first assertions, page.route and page.waitForResponse for intercepts, the request fixture for API calls, page.clock for time, context methods for cookies, fs for file reads and writes, and imports of the existing fixture files. For traversal tests, write a locator that selects the same elements and assert the same count. Do not port tests whose subject is the Cypress object or the bundled Sinon; list them. Extend the lint config so the new directory is linted without the Mocha and Cypress plugins, and run the linter. Run npx playwright install --with-deps, the Playwright suite in both projects and the Cypress suite. Do not remove Cypress, its scripts or its workflows. Open a pull request with a table of every Cypress test: ported and passing, ported with a note, or not ported and why.",
  "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 adds a Playwright directory with one spec per Cypress spec, `playwright.config.js`, the `@playwright/test` devDependency with its lockfile entry, a script to run the suite, and a block in the lint config. Nothing under `cypress/` is deleted or changed. The description is a table with a row for every existing test title and one of three states: ported and passing in both projects, ported with a note (a traversal rewritten as XPath, a wait replaced by an assertion), or not ported, with the reason.

The not-ported rows are the part to read first. They show how much of the old suite tested the application and how much tested Cypress, and they are where a team decides whether a spy on a plain object is worth a new dependency or belongs in a unit test. For a suite written against a product and not a demo, that list is usually short: custom commands in `cypress/support/commands.js` and the occasional `cy.task`.

A reviewer compares a handful of pairs side by side and checks the waits. A Cypress test that passed because the command queue serialised everything can pass in Playwright for the wrong reason if a `waitForResponse` is created after the click. Removing Cypress, its workflows and its recording setup is a second pull request, once the team has watched both suites agree in CI for a while.

## Run it on every repository still on Cypress

For a company with many front ends, a script on your own server reads `GET /o/{org}/github` for the repositories the Rush GitHub App reaches, keeps the ones with a `cypress.config` file, and sends this body to `POST /o/{org}/sessions` once for each with that repository in `resources`. Every call carries a `request_id` that is a UUID v5 of the repository's full name, so running the script again starts nothing twice. The key's concurrency limit decides how many run at once; the rest are created `queued` and start as slots free.

Put a `webhook_url` on the key and each run posts `run.completed` or `run.failed` with its `session_url` when the turn ends. A large suite does not have to finish in one turn: a follow-up to `POST /o/{org}/sessions/{id}/messages` asking for the next ten specs wakes the same sandbox, with the ported files and installed browsers still on its disk.

## Why run it on Rush?

A migration is only believable when both suites have been run against the same build and compared. That needs the app served, two test runners, three browser engines between them and a display server for Cypress. Setting that up on a laptop is a morning; in a Rush sandbox the agent installs it as part of the run and discards it afterwards, and the comparison table is built from the two runners' actual output.

The run also keeps its evidence. Each command the agent executed, with its output, is in the transcript at `GET /o/{org}/sessions/{id}/messages`, so when a ported test is questioned the reviewer can read what both runners printed for it, not a summary.

## Frequently asked questions

### Will the Playwright tests be TypeScript?

They match the suite they replace. Here the specs are `.cy.js` files and the repository has no type-check step, so the agent writes JavaScript. If your Cypress specs are TypeScript, the ported specs are too, and the type check runs before the pull request opens.

### What happens to custom commands?

A custom command added with `Cypress.Commands.add` becomes a plain helper function or a Playwright fixture, depending on whether it needs setup and teardown. The table lists each custom command with the helper that replaced it.

### Does it replace Cypress Cloud parallel runs?

It does not touch them. The recording workflows stay as they are while both suites run. When the team later removes Cypress, Playwright's `--shard` option splits the suite across CI jobs without an external service; that change is part of the removal, not of this pull request.

### Which browsers does the ported suite run in?

Chromium and Firefox by default, since those cover the Chrome and Firefox jobs most Cypress pipelines already have. Electron, the browser bundled with Cypress, has no Playwright project. WebKit can be added in the prompt, and the agent then reports any test that fails only there.

## More Cypress jobs

- [Upgrade Cypress to the Current Major Version](https://getrush.ai/run/upgrade-cypress/cypress/)
- [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/)

## The same job on other stacks

- [Migrate Cypress Tests to Playwright in a Node.js App](https://getrush.ai/run/migrate-cypress-to-playwright/nodejs/)
- [Migrate Cypress Tests to Playwright in a React App](https://getrush.ai/run/migrate-cypress-to-playwright/react/)
- [Migrate Cypress Tests to Playwright in a Vue App](https://getrush.ai/run/migrate-cypress-to-playwright/vue/)

## 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/)
