What the agent does
The agent begins with what the workflow runs and what the repository has. In a React and Express app laid out like cypress-io/cypress-realworld-app, cypress.config.ts sets specPattern to cypress/tests/**/*.spec.{js,jsx,ts,tsx}, and cypress/tests/ holds ui/ with seven specs, api/ with nine (api-users, api-transactions, api-bankaccounts, api-contacts, api-notifications, api-comments, api-likes, api-banktransfers, api-testdata, 44 it blocks between them), a demo/ spec and ui-auth-providers/. .github/workflows/main.yml has an install job that runs yarn types, yarn lint, yarn test:unit:ci and yarn build:ci, then four jobs, Chrome, Chrome mobile, Firefox and Firefox mobile, each a five-container matrix running spec: cypress/tests/ui/*. The API specs run on nobody's machine but the author's: package.json has a test:api script, yarn cypress:run --spec 'cypress/tests/api/*', and no job calls it.
It then reads what those specs need. Each starts with cy.task("db:seed"), which the config implements as a POST to ${apiUrl}/testData/seed, and cy.database("filter", "users"), a GET on /testData/users; backend/app.ts mounts those routes only when NODE_ENV is test or development. They sign in with cy.loginByApi, a cy.request to /login with the defaultPassword from SEED_DEFAULT_USER_PASSWORD in .env, and api-users.spec.ts makes one cy.request("GET", "/") first so the front end answers too. The start:ci script sets NODE_ENV=test and starts scripts/testServer.ts, an Express server for the build/ folder on port 3000, beside the API on 3001; precypress:run waits on both.
The new job follows the shape of the four that exist. It needs: install, runs in the same cypress/browsers:22.20.0 container, downloads the build artifact, and calls cypress-io/github-action@v6 with start: yarn start:ci, the same wait-on for 3000 and 3001, and spec: cypress/tests/api/*. It has no record, parallel or group, and no CYPRESS_RECORD_KEY: the API specs use cy.request and never load a page, so one container with the Electron browser Cypress bundles runs them, and a run without the Cypress Cloud secret, such as a pull request from a fork, still runs them. With no matrix there is nothing for fail-fast to do.
In its sandbox the agent runs yarn install --frozen-lockfile, yarn build:ci and yarn start:ci, waits for both ports, and runs yarn test:api to see the nine specs execute against the seeded data/database.json. One detail it checks before writing the job: cypress.config.ts sets retries.runMode to 2, so a spec that depends on seed order gets two more tries in CI, and the agent reads each spec's beforeEach to confirm every one reseeds. The output goes in the description, spec by spec.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Run the Cypress API specs in this app's CI. Read cypress.config.ts, package.json, .github/workflows/main.yml, cypress/support/commands.ts, backend/app.ts and the specs under cypress/tests/api first. Add a job to main.yml that depends on install, downloads the build artifact, starts the app with yarn start:ci, waits for ports 3000 and 3001, and runs cypress-io/github-action with spec set to cypress/tests/api/*, without record or parallel so it needs no Cypress Cloud key. Do not change the UI jobs or the specs. Run yarn build:ci, yarn start:ci and yarn test:api in the sandbox, quote the per-spec results, and open a pull request.",
"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 with one file changed, .github/workflows/main.yml, and one job added, api-tests, between install and the UI matrices in the file. No spec changes, no package.json change, and no new secret: the job runs with what a fork's pull request has.
The description quotes the Cypress summary from the agent's run, each of the nine API specs with its test count and result, and the start:ci output showing the API on 3001 and the test server on 3000. The run's record keeps the full Cypress output, including any retry the config's runMode setting triggered.
Before merging, a reviewer decides whether the job should block the UI jobs, which the agent leaves parallel since it depends only on install, and whether the demo/ spec should get the same treatment, which the agent leaves out because cypress-studio.spec.ts exists to show the Studio feature.
Run it on every failed Cypress workflow
Once the job is in main.yml it runs on every push, so the run worth starting on Rush is the one that reads a failure. An automation with a github trigger on workflow_run.failure starts a run when the workflow fails, reads the log for the api-tests job, reruns the failing spec in a sandbox against the seeded database, and opens a pull request with the fix when the cause is in backend/, or a comment naming the spec and the response it got when the cause is in the test.
The trigger puts the failed run after the prompt. A failure in a UI job is not this automation's; the prompt says to open nothing for it.
The use case this job follows, with its automation and trigger: Write the missing tests.
Why run it on Rush?
A test suite nobody runs is one that has been failing for an unknown time. Finding that out needs the app built, both servers up and the specs run against the seed, which is setup on a laptop and nothing in a sandbox that starts clean. The pull request opens with the nine results already in it.
The run keeps what Cypress printed and what the servers logged, so a reviewer reads the actual result of yarn test:api rather than a promise that the job will pass. Across a team's Cypress projects the same request runs at once, one sandbox each, each pull request showing which specs its workflow had been skipping.
Frequently asked questions
Why no browser matrix for API specs?
They use cy.request, which runs from the Cypress process, and never call cy.visit. Cypress still opens a browser to run a spec, and the Electron it bundles is enough; there is no Chrome or Firefox install step and no reason to run the same requests four times.
Will the job work on a pull request from a fork?
Yes. The four UI jobs pass record: true and read CYPRESS_RECORD_KEY from secrets, which a fork's pull request does not receive. The API job records nothing, so it runs with the repository alone.
Does the backend expose /testData in production?
No. backend/app.ts mounts the test-data router only when NODE_ENV is test or development. start:ci sets test, which is why the seed and database tasks work in the job.
Should the API specs replace the UI matrix?
No. They cover the Express routes; the UI specs cover the React app and the mobile viewport. The job adds coverage the workflow did not have and leaves the rest as it is.