What the agent does
The agent starts by reading the suite it is replacing, in its own cloud sandbox with the repository cloned. In an app like cypress-io/cypress-realworld-app (React on Vite, an Express backend in backend/app.ts, Yarn, Node 22.20.0 from .nvmrc), cypress.config.ts sets baseUrl to http://localhost:3000, specPattern to cypress/tests/**/*.spec.{js,jsx,ts,tsx}, a 1280 by 1000 viewport, two retries in run mode, and expose.apiUrl at http://localhost:3001. Its setupNodeEvents defines the tasks the specs lean on: db:seed posts to /testData/seed on the API, filter:database and find:database fetch /testData/<entity> and filter with lodash, and four tasks read auth-provider credentials from the environment. cypress/support/commands.ts adds getBySel and getBySelLike over data-test attributes, a login command that visits /signin, intercepts POST /login and GET checkAuth, and visualSnapshot for Percy; cypress/support/e2e.ts strips if-none-match from every API request and throttles responses when isMobile(), which compares the viewport width to a breakpoint of 414.
Then it maps that to Playwright and decides what to migrate first. The seven files under cypress/tests/ui/ (auth, bank accounts, new transaction, notifications, transaction feeds, transaction view, user settings) are the product tests and go first; the nine cypress/tests/api/ specs become request-only tests; cypress/tests/ui-auth-providers/ needs real Auth0, Okta, Cognito or Google credentials and is left on Cypress with a note; cypress/tests/demo/cypress-studio.spec.ts is a tooling demo and is not ported. Every custom command becomes a fixture in e2e/fixtures.ts: getBySel is a locator helper, login fills /signin and waits for the POST /login response, seed calls the same /testData/seed route through Playwright's request, and database.find and database.filter call /testData/<entity>. The if-none-match header is dropped with page.route, and the mobile project sets a viewport under 414 so isMobile logic ports as a project condition.
The config comes from what the app already runs. playwright.config.ts gets a webServer that runs yarn start:ci, the script .github/workflows/main.yml already uses, which serves the build folder through scripts/testServer.ts and starts the API, with url set to the frontend and the SEED_DEFAULT_USER_PASSWORD from .env available to tests as it is to Cypress. Projects are chromium and a mobile viewport, retries match the two Cypress has in run mode, and traces are kept on first retry. cy.visualSnapshot calls are replaced with Playwright's screenshot assertion by default, or with Percy's Playwright SDK if the issue asks to keep Percy; the pull request says which.
Each spec is ported, run and fixed before the next. Cypress's cy.task("db:seed") in beforeEach becomes the seed fixture; cy.database("find", "users") and cy.login(user.username, "s3cret", { rememberUser: true }) in auth.spec.ts become database.find and login; cy.getCookie("connect.sid") becomes a context.cookies() check. The agent runs yarn build:ci and then yarn playwright test after every file, keeps yarn cypress:run passing until the last UI spec is ported, and adds a playwright job to main.yml that installs browsers with --with-deps and shards across the same number of containers the Cypress job uses, so CI time does not grow.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Migrate the end-to-end tests in this React app from Cypress to Playwright. Read cypress.config.ts, cypress/support/commands.ts, cypress/support/e2e.ts and every spec under cypress/tests first, and list each custom command, task and intercept the specs depend on. Add @playwright/test and a playwright.config.ts whose webServer runs the same start script CI uses, with the same base URL, retries and a mobile project matching the existing mobile viewport. Port the custom commands and tasks to Playwright fixtures (data-test locators, login, database seed and lookup through the test-data API, the if-none-match header removal) and then port the UI specs one file at a time, running each before moving on, keeping data-test attributes and test names. Port the API specs as request-only tests. Leave the third-party auth-provider specs on Cypress and say so. Replace visual snapshot calls with Playwright screenshot assertions unless Percy is required. Keep the Cypress suite passing until the last UI spec is ported, then remove the ported Cypress specs and add a Playwright job to the CI workflow with browsers installed and sharding. Open a pull request listing every spec with its old and new path and anything that could not be ported.",
"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
What comes back is a pull request on its own branch with a new e2e/ directory holding fixtures.ts and one Playwright file per ported Cypress spec, a playwright.config.ts, the @playwright/test entry in package.json and yarn.lock, the ported Cypress specs removed, and a new job in .github/workflows/main.yml. The description is a table: each spec's old path, new path, test count, and a note for anything left on Cypress, such as the auth-provider specs.
The transcript carries the proof: yarn build:ci, the yarn playwright test runs after each ported file with their output, including any that failed before a selector or timing fix, and the final yarn cypress:run showing what remains on Cypress still passes. If the repository runs CI on pull requests, the new Playwright job runs there with the sharded containers and uploads its report.
Before merging, a reviewer checks that every it in a ported Cypress spec has a Playwright counterpart with the same name, that waits are on responses and locators rather than fixed sleeps, that the mobile project covers the cases Cypress ran under isMobile(), and that the seed fixture resets state between tests as db:seed did.
Run it on every React repository still on Cypress
From your own server, start one run per repository that still has a cypress/ directory: POST /o/{org}/sessions with this prompt and the repository in resources, one call each. GET /o/{org}/github lists every repository the Rush GitHub App installation reaches, so a script can pick the ones with Cypress specs and start them in a loop. Each run gets its own sandbox and branch and opens its own pull request.
Set a webhook_url on the key and each run POSTs run.completed or run.failed with its session_url when the turn finishes, within about 30 seconds, so the pull request links collect on your side without polling. A migration with many specs can be continued with a follow-up POST …/sessions/{id}/messages in the same sandbox, which wakes where it left off with the ported files on disk.
The use case this job follows, with its automation and trigger: Write the missing tests.
Why run it on Rush?
A test migration is only done when both suites run against the real app, and that means the backend, the seeded database and a browser all up at once, for every spec, many times. In a Rush sandbox the agent runs yarn start:ci the way CI does, installs Playwright's browsers with their system dependencies, and loops through port, run, fix, run on its own disk, while your laptop stays free and your CI minutes stay unspent.
The result is a pull request with its evidence attached rather than a branch someone has to trust. The transcript shows the agent reading commands.ts before writing fixtures, every Playwright run with its output, and the Cypress run that proves nothing still on Cypress broke. Several repositories can migrate at once, each in its own sandbox, up to the key's max_concurrent limit.
Frequently asked questions
Will it delete the Cypress setup?
It removes the Cypress specs it has ported and keeps the ones it could not, such as the third-party auth-provider specs that need live credentials. cypress.config.ts and the support files stay while anything still runs on Cypress; a follow-up can remove them once the last spec moves.
How does it handle custom commands like `cy.login` and `cy.getBySel`?
Each becomes a Playwright fixture or helper in e2e/fixtures.ts: getBySel is a [data-test=…] locator, login fills the sign-in form and waits for the login response, and the database helpers call the same /testData routes the Cypress tasks called. The specs keep reading the same way.
What about Percy visual snapshots and code coverage?
Visual snapshot calls become Playwright's toHaveScreenshot unless the prompt asks to keep Percy, which has a Playwright SDK. The @cypress/code-coverage plugin has no direct Playwright equivalent; the agent notes that coverage from end-to-end runs is not collected in the new job and leaves the unit-test coverage path untouched.
Can it do the migration in stages?
Yes. The prompt can name the specs to port in this run, and a follow-up message to the same session continues with the next batch in the same sandbox, with the fixtures and config already in place. Each stage ends with both suites passing.