All jobs

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 RushOpens 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 with this body:

{
  "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.

The use case this job follows, with its automation and trigger: Write the missing tests.

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

The same job on other stacks

Keep reading