# Run the Cypress API Specs in CI

Yes. An agent finds the API specs your workflow never runs, adds a job that starts the app and runs them with no Cypress Cloud key or browser matrix, and opens a PR.

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

## 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`

```json
{
  "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"
    }
  ]
}
```

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

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.

## 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.

## More Cypress jobs

- [Shard Cypress Specs Across CI Containers Without Cypress Cloud](https://getrush.ai/run/add-test-sharding/cypress/)
- [Fix Flaky Tests in a Cypress Suite](https://getrush.ai/run/fix-flaky-tests/cypress/)
- [Migrate a Cypress Test Suite to Playwright](https://getrush.ai/run/migrate-cypress-to-playwright/cypress/)

## More jobs like this: Write the missing tests

- [Add Architecture Tests to a .NET Clean Architecture Solution](https://getrush.ai/run/add-architecture-tests/dotnet/)
- [Add ArchUnit Architecture Tests to a Maven Spring Boot Project](https://getrush.ai/run/add-architecture-tests/maven/)
- [Add Benchmarks That Catch Performance Regressions in a Python Library](https://getrush.ai/run/add-benchmarks-to-ci/python/)

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