How to Use Cypress and AI Agents for Accessibility Testing

Cypress can scan the rendered page states your tests visit for common accessibility rule violations, while explicit Cypress assertions check application-specific behavior such as keyboard navigation and alternative text. AI agents can help write tests, inspect the DOM and accessibility tree, and triage failures. They cannot establish that an application is accessible on their own: human review and assistive technology testing still matter.

A practical workflow combines automated scans with behavioral assertions, gives an agent concrete test evidence to work from, and has a person review each proposed fix. This guide covers the code-first cypress-axe approach, Cypress Accessibility in Cloud, and Cypress’s documented AI tooling. Product requirements can change, so check the linked Cypress documentation when setting up version-sensitive features.

1. Choose where accessibility scans run

There are two documented ways to add automated accessibility checks to a Cypress workflow:

Scan inside your tests with cypress-axe. This is a code-first community plugin pattern. Your test injects axe-core and calls checkA11y() for the current page or component state. You control where scans run and how findings affect the test result. Scans add runtime, especially when repeated across many states.
Use Cypress Accessibility. Cypress describes this as a paid premium solution that analyzes recorded tests in Cypress Cloud. It supplements standard Axe Core rules with Cypress rules that can use test activity as context. Check current plan packaging before purchasing.

These approaches have different execution locations and setup tradeoffs. Pick based on whether you want scans to run as part of the test itself or in Cloud after tests are recorded. See Cypress’s accessibility testing guide and explanation of how Cypress Accessibility works.

2. Scan meaningful application states

A scanner can only inspect what is rendered when it runs. Start with the states your users actually encounter, then make tests reach them:

Visit each important route or render each important component.
Open interactive controls such as menus, dialogs, tabs, and disclosure panels.
Exercise forms far enough to show validation and error messages.
Run scans after the relevant content and state have appeared.
Keep a list of states not covered by automated scans, including cases that need manual checks.

For a large application, begin with high-use flows and unique interactive states. Repeating scans across hundreds or thousands of states increases runtime; prioritize coverage deliberately instead of scanning the same unchanged state repeatedly.

3. Add Cypress axe scans and explicit assertions

The Cypress documentation describes a cypress-axe pattern: inject axe-core with injectAxe(), then call checkA11y() on the page state under test. The following example shows the structure of a test. Install and configure the community plugin according to its current documentation for your Cypress and project versions.

// cypress/e2e/accessibility.cy.js
import 'cypress-axe'

describe('checkout accessibility', () => {
  it('scans the checkout and checks application-specific expectations', () => {
    cy.visit('/checkout')
    cy.injectAxe()

    // Scan the currently rendered page. Findings are reported by the plugin.
    cy.checkA11y()

    // Example of an explicit content expectation from Cypress documentation.
    cy.get('header img.site-logo').should('have.attr', 'alt', 'Acme home')
  })
})

To cover a dialog or expanded menu, perform the action first and scan that resulting state:

it('scans the open account menu', () => {
  cy.visit('/')
  cy.injectAxe()
  cy.get('[data-cy=account-menu-button]').click()
  cy.get('[role=menu]').should('be.visible')
  cy.checkA11y('[role=menu]')
})

Selectors in these examples are illustrative; use selectors that match your application. Cypress’s accessibility guide documents native Tab-event testing with cy.press(). A keyboard assertion might be structured like this:

it('moves focus into the navigation with Tab', () => {
  cy.visit('/')
  cy.get('body').click()
  cy.press('Tab')
  cy.focused().should('have.attr', 'data-cy', 'skip-link')
})

Use the expected focus target for your own page. Keyboard behavior, meaningful alternative text, and other product-specific expectations need explicit assertions because a general scanner cannot infer what your interface intends.

4. Use AI agents with grounded evidence

An agent is most useful when it can inspect a real failing test and the rendered interface, rather than guessing from a vague report. Cypress documents a workflow that combines skills for authoring and reviewing tests, cypress tap for working with a live Cypress session, and Cypress Cloud MCP or Cloud CLI for recorded-run failures and replay context.

Give the agent a narrow task. Ask it to inspect a named failing spec or accessibility finding and propose a test or code change.
Expose relevant context. With cypress tap, the agent can read the command log, failure, DOM, and accessibility tree from an open Cypress session. The tree can show landmarks, headings, forms, controls, roles, and accessible names.
Ask for evidence before a fix. Have the agent identify the reported rule, affected element, observed role or name, and the test state in which it appeared.
Review the proposed change. Check that the control’s semantics and accessible name match its purpose and that keyboard operation remains sensible.
Run the relevant test again. Make decisions from a fresh result, not from an agent’s description of an earlier run.

cypress tap has specific requirements in the cited Cypress documentation: Cypress 15.21.0 or later, a live cypress open session, and a supported Chromium-based browser (Chrome, Chromium, Edge, or Electron). It does not attach to headless cypress run sessions. Confirm current requirements before adopting it. Cypress says many AI capabilities, including skills, cypress tap, Cloud MCP, and Cloud CLI, work on the free Starter plan; agent-ready accessibility reports require Cypress Accessibility. Verify current packaging in the Cypress AI overview, cypress tap guide, and AI skills guide.

5. Review findings and fixes as a human

Automated results are evidence about detectable rules, not proof of complete accessibility or compliance. Axe Core catches common problems such as missing accessible names and image alternative text. Cypress’s documentation says it can detect up to 57% of issues that would appear in a manual audit, attributing the figure to Deque. Treat that as a reported ceiling, not a guaranteed detection rate for your site or test suite.

Some questions require product context or human judgment: does a name describe the control’s purpose, does focus move in an expected order, can a user recover from an error, and does a custom interaction work with assistive technology? Cypress Accessibility adds rules that use test interaction context; its documentation gives clickable div or span elements as examples where a semantic button or link may be appropriate. Automated scans still cannot determine whether every custom interface works well for every user.

The Cypress Team likewise says that language models cannot solve accessibility issues independently, though they can propose solutions and tradeoffs, triage findings, and offer in-browser help understanding reports. See Cypress Accessibility and AI Agents and the Cypress accessibility rules.

6. Troubleshoot common problems

Symptom	Likely cause	What to do
`checkA11y()` is unavailable	The community plugin is not installed, imported, or configured for the test setup.	Check the current `cypress-axe` setup instructions and ensure the plugin is loaded in the support file or spec as required.
The scan reports no issue, but a user-visible problem remains	The relevant route or interactive state was not rendered during the scan, or the issue needs human judgment.	Make the test reach the state, add explicit assertions for expected behavior, and perform keyboard and assistive technology checks.
A scan fails only after opening a dialog	The dialog state may expose a real issue, or the test may scan before the dialog finishes rendering.	Assert that the dialog is visible and its content is ready before scanning. Inspect the reported element and rule rather than suppressing the finding without review.
`cypress tap` cannot connect	The documented tool requires a live `cypress open` session and a supported Chromium-based browser; it does not attach to headless `cypress run`.	Start Cypress in open mode with a supported browser and verify the installed version against current requirements.
An AI-suggested fix makes the test pass but changes behavior	The agent optimized for the reported failure without enough knowledge of the control’s purpose or surrounding flow.	Review semantics, accessible name, keyboard operation, and nearby structure. Run the relevant tests again and have a person validate the experience.
Accessibility scans make the suite slow	Scans are repeated across many states, and scanning adds runtime.	Keep scans on important distinct states, avoid duplicate scans of unchanged content, and measure suite runtime after adjusting coverage.

7. Performance, reliability, and cost considerations

Runtime: In-test scans add work to the test run. Prioritize meaningful page and component states and account for scan time when planning a large suite.
Reliability: A passing scan only describes the rendered state and rules it checked. Ensure tests wait for the intended state and rerun the relevant test after a fix.
Coverage: More scans do not automatically mean better coverage if they all inspect the same state. Track route, component, and interaction coverage alongside findings.
Cloud workflow: Cypress Accessibility runs analysis in Cloud after tests are recorded, which changes where results are produced. It is documented as a paid premium solution; check current plan terms before estimating cost.
Human review: Keep time for keyboard navigation, assistive technology checks, and review of context-dependent findings. Automation and agents can reduce investigation effort, but they do not remove this work.

8. Or skip the browser setup

If you need screenshots of the pages in an accessibility review or agent workflow, ScreenshotNeo is a website screenshot API and MCP server. Its one-call API can return a screenshot or PDF. It is not a replacement for Cypress accessibility scans, keyboard assertions, or assistive technology checks; it helps capture page evidence without maintaining screenshot browser setup. See the ScreenshotNeo API documentation.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
    timeout=90,
)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
const image = Buffer.from(await res.arrayBuffer());
await import('node:fs/promises').then(fs => fs.writeFile('shot.webp', image));

ScreenshotNeo removes known cookie and consent banners, newsletter popups, and chat widgets before capture; each cleanup step can be turned off. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed, and response headers report the page verdict and billing status. Its MCP server includes take_screenshot, get_page_info, and capture_pdf for AI agents using Claude, Cursor, or another MCP client. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 screenshots. Sign up for 1,000 free screenshots a month with no card.

9. Frequently asked questions

Can Cypress and axe-core find WCAG issues automatically?

They can identify many rule-based issues in the rendered states your tests cover. They cannot determine that an application meets every WCAG requirement or that every interaction works for people using assistive technology.

Can an AI agent decide whether a reported issue is fixed?

An agent can inspect evidence, explain a finding, and propose a change. A human should review whether the fix matches the control’s purpose and verify the result with appropriate testing.

Should every Cypress test run an accessibility scan?

Not necessarily. Scan important distinct states and avoid paying the runtime cost of repeatedly scanning unchanged views. Choose coverage based on the routes and interactions your users depend on.

Does a passing accessibility scan mean the page is accessible?

No. It means the scanned state passed the rules that ran. Keyboard behavior, assistive technology support, content quality, and context-specific expectations still need review.