# Add Accessibility Tests to a Cypress Suite

Yes. An agent wires cypress-axe into your support file, writes one spec that audits each signed-in page, fails on serious violations, and opens a PR.

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

## What the agent does

The agent reads the suite before adding to it. In an app laid out like cypress-io/cypress-realworld-app, `package.json` pins `cypress` at `^16.1.1` with `eslint-plugin-cypress`, `@percy/cypress` and `@cypress/code-coverage`, and no `cypress-axe` or `axe-core`. `cypress.config.ts` sets the e2e `specPattern` to `cypress/tests/**/*.spec.{js,jsx,ts,tsx}`, `retries.runMode: 2`, a `db:seed` task that posts to the backend's `/testData/seed`, and `find:database` and `filter:database` tasks. `cypress/support/e2e.ts` imports code coverage and `./commands`, where `getBySel`, `login`, `loginByApi` and `loginByXstate` live; `cypress/global.d.ts` declares them on `Chainable`, and `cypress/tsconfig.json` lists `types: ["cypress", "@percy/cypress"]`. `.github/workflows/main.yml` runs `cypress/tests/ui/*` in four jobs, Chrome and Firefox at desktop and at a 375 by 667 mobile viewport, five containers each.

It adds `cypress-axe` and `axe-core` as devDependencies, imports `cypress-axe` in `cypress/support/e2e.ts` next to the coverage import, and adds `cypress-axe` to the `types` array in `cypress/tsconfig.json` so `cy.injectAxe` and `cy.checkA11y` type-check. `cypress.config.ts` gains a `log` task that prints to the runner's terminal, because `cy.checkA11y` reports violations through a callback and the Cypress command log alone does not survive into CI output.

The spec is `cypress/tests/ui/accessibility.spec.ts`, so the existing `spec: cypress/tests/ui/*` glob picks it up in all four CI jobs with no workflow change. Its `beforeEach` runs `cy.task("db:seed")`, finds a user with `cy.database("find", "users")` and signs in with `cy.loginByXstate`, the way `user-settings.spec.ts` does. One `it` per page visits `/`, `/bankaccounts`, `/transaction/new`, `/user/settings` and `/notifications`, waits for the page's own data-test element, calls `cy.injectAxe()` and then `cy.checkA11y(undefined, { includedImpacts: ["critical", "serious"] }, violations => cy.task("log", ...))`, and a separate signed-out `it` covers `/signin` and `/signup`. On the mobile viewport it opens the sidenav through `sidenav-toggle` first, using the `isMobile()` helper from `cypress/support/utils.ts`, so the drawer's markup is audited too.

The agent starts the app with `yarn start:ci`, runs `yarn cypress:run --spec cypress/tests/ui/accessibility.spec.ts` at the default viewport and again with the mobile config the workflow uses, and reads the result. Violations of `moderate` and `minor` impact are logged, not failed, and the pull request lists them by rule and page so the team can decide what to fix. The agent does not change the app's markup; the task is the test, and a fix is a separate, reviewable change.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add accessibility tests to this Cypress suite. Read package.json, cypress.config.ts, cypress/support/e2e.ts, cypress/support/commands.ts, cypress/support/utils.ts, cypress/global.d.ts, cypress/tsconfig.json, cypress/tests/ui/user-settings.spec.ts and .github/workflows/main.yml first. Add cypress-axe and axe-core as devDependencies, import cypress-axe in the e2e support file, add it to the cypress tsconfig types, and add a log task to cypress.config.ts. Write cypress/tests/ui/accessibility.spec.ts: seed the database, sign in with loginByXstate, and for the home, bank accounts, new transaction, user settings and notifications pages, plus signin and signup signed out, inject axe and run checkA11y failing only on critical and serious impacts, logging the rest through the task, and opening the sidenav first on the mobile viewport. Start the app with yarn start:ci, run the spec at the default viewport and with the mobile viewport config from the workflow, do not change the app's markup, and open a pull request that lists every violation found by rule and page.",
  "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 the new spec, three small edits to the support file, the Cypress tsconfig and the config, and the two devDependencies in `package.json` and the lockfile. The description lists each page audited, the impact levels that fail the test, and every violation the agent's own runs reported, by axe rule id, page and viewport, split into the ones that fail and the ones that are only logged.

The run's record keeps the two `cypress run` outputs, so a reviewer can read the violation callback's table per page rather than rerun the suite to see what was found.

Before merging, a reviewer decides whether `moderate` belongs in `includedImpacts` from the start, and whether the `wcag2aa` tag set should be narrowed or widened with `runOnly`. Both are one option in the `checkA11y` call, and the pull request names where.

## Run it on every pull request

Once the spec is in, CI runs it on every push with the rest of `cypress/tests/ui/*`. For the violations it only logs, an automation in the Project with a `github` trigger on `pull_request.opened` and `pull_request.synchronize` can run the spec on the pull request's branch and post the logged `moderate` and `minor` findings as a review comment, so markup regressions that do not fail the build are still seen before merge. The trigger adds the event after the prompt; the prompt itself names the spec and the pages.

A team with several Cypress apps starts one run per repository with one `POST /o/{org}/sessions` each, this prompt as `input` and the repository in `resources`, with a `request_id` that is a UUID v5 of the repository's full name so a retry returns the run it already started. Each run reads its own support file and login commands, so an app that signs in through `cy.login` instead of `cy.loginByXstate` gets a spec that uses what it has.

## Why run it on Rush?

An accessibility spec is cheap to write and expensive to get wrong: inject axe before the page has rendered and every test passes for nothing, audit a drawer that is closed on mobile and the worst markup is never seen. The agent runs the spec against the real app at both viewports in its own sandbox, with the seeded database the suite expects, and keeps the output, so the first run's findings are in the pull request rather than discovered in CI.

The pull request is a spec plus four lines of wiring, so the review is the list of violations and the choice of impact levels, not a local checkout and a Cypress session. Several apps can be done at once, one sandbox each, with a separate pull request and a separate findings list for each.

## Frequently asked questions

### Will this fail CI the day it lands?

Only if a page has a `critical` or `serious` violation, which the pull request will have told you. The agent runs every page before opening it, so the list of failures is known in advance, and the spec can be merged with a narrower `includedImpacts` while the markup is fixed.

### Does it run in the mobile jobs too?

Yes. The workflow's `ui-chrome-mobile-tests` and `ui-firefox-mobile-tests` jobs pass a 375 by 667 viewport and the same `cypress/tests/ui/*` glob, so the spec runs there as it is. The spec opens the sidenav on mobile before auditing, so the drawer counts.

### Why a log task rather than the command log?

Because the Cypress command log lives in the browser and the recorded video, while CI output is the terminal. The callback passed to `cy.checkA11y` formats each violation as a line and `cy.task("log")` prints it where the job log keeps it.

### Can it audit a component test too?

Yes. The repository has component specs under `src/**/*.cy.tsx` with `cy.mount`, and importing `cypress-axe` in `cypress/support/component.ts` makes `cy.injectAxe` available there. The agent adds the import so a component spec can opt in; writing audits for each component is a follow-up.

## More Cypress jobs

- [Run the Cypress API Specs in CI](https://getrush.ai/run/add-api-tests-to-ci/cypress/)
- [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/)

## The same job on other stacks

- [Add Accessibility Tests to a Lit Component](https://getrush.ai/run/add-accessibility-tests/lit/)
- [Add Accessibility Tests to a Playwright Suite](https://getrush.ai/run/add-accessibility-tests/playwright/)
- [Add Accessibility Tests to Storybook](https://getrush.ai/run/add-accessibility-tests/storybook/)

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