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 with this body:
{
"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"
}
]
}- 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.
- 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.
- 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.
The use case this job follows, with its automation and trigger: Write the missing tests.
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.