All jobs

Add Accessibility Tests to a Vitest Component Suite

Yes. An agent adds axe checks to the React components your Vitest suite already renders, fixes what they find or reports it, 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 how the suite renders components before it adds a check to them. In a React app laid out like alan2207/bulletproof-react, apps/react-vite/vite.config.ts runs Vitest with environment: 'jsdom', globals: true and a setup file at src/testing/setup-tests.ts, which imports @testing-library/jest-dom/vitest, starts an MSW server, stubs ResizeObserver and resets a mock database between tests. Twelve test files sit under __tests__ directories: the dialog, confirmation dialog, drawer, form and notifications components, the login and register forms, the discussions routes, the SEO head, a hook and the authorization helper. src/testing/test-utils.tsx exports renderApp, which mounts a component inside AppProvider and a memory router with a signed-in user, and re-exports rtlRender for a bare render. The ESLint config already turns on plugin:jsx-a11y/recommended, and Storybook has @storybook/addon-a11y, so accessibility is checked in the editor and the Storybook panel but never fails yarn test.

It adds vitest-axe, which wraps axe-core for Vitest, as a devDependency, and registers its matchers once in the setup file: import * as matchers from 'vitest-axe/matchers' followed by expect.extend(matchers), with import 'vitest-axe/extend-expect' in vite-env.d.ts so toHaveNoViolations type-checks. Because jsdom does no layout, the agent turns off the color-contrast rule through configureAxe in the same setup file rather than in each test, and says so in a comment, so a reviewer knows contrast is still the Storybook addon's job.

Then it adds one accessibility assertion to each existing component test rather than a parallel suite: after the dialog opens, after the drawer renders, after the form shows a validation error, after renderApp has mounted the login form, it runs axe(container) and expects no violations. For the routes tests, which render whole pages with data from the mock database, the check runs once the loading state is gone, using the waitForLoadingToFinish helper the utils already export. New tests are written only for the components that have stories but no test, so the list of covered components grows without duplicating what Storybook's addon already shows.

It runs yarn test in the sandbox and reads every violation axe reports: a button with no accessible name, an input whose label is not associated, a dialog with no aria-labelledby. A violation in a shared ui component is fixed in that component, which fixes every consumer; a violation in a feature's markup is fixed there. One it cannot fix without a design decision is left as a failing assertion wrapped in a named test.todo-style skip with the rule id and the element in the message, and listed in the pull request. It finishes with yarn lint and yarn check-types, the checks .github/workflows/react-vite-ci.yml runs in all-cli-checks.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "claude",
  "input": "Add accessibility checks to the Vitest component tests in apps/react-vite. Read package.json, vite.config.ts, src/testing/setup-tests.ts, src/testing/test-utils.tsx, every test file under __tests__ and .eslintrc.cjs first. Add vitest-axe as a devDependency, register its matchers in the setup file, add the extend-expect types, and disable the color-contrast rule with configureAxe since jsdom does no layout. Add an axe assertion to each existing component and route test at the point where the component is fully rendered, and write a test for any ui component that has a story but no test. Run yarn test, fix every violation in the component that owns the markup, leave any that needs a design decision as a documented skip with the rule id, then run yarn lint and yarn check-types and open a pull request listing each violation found and what was done about it.",
  "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 that adds one devDependency, a few lines to the setup file and the type declarations, and an assertion in each test it touched, plus the component fixes those assertions forced. The description lists every violation by rule id and component, says which were fixed and which are skipped pending a design decision, and pastes the test output.

The run's record keeps the first yarn test run with axe's full report and the last one that passes, so a reviewer can see what the rules found before the fixes rather than only a green result.

Before merging, a reviewer looks at the component changes, which are the part that reaches users: a label association, an aria-label, a dialog title. The skipped assertions are the backlog, each with the rule id and the element, ready to become an issue.

Run it on every repository with a component suite and no axe check

A team with several React apps starts one run per repository with one POST /o/{org}/sessions each, this prompt as input and the repository in resources. Each run reads its own setup file and render helpers, so an app that renders through a different provider or has no MSW gets a setup that fits rather than a copy of this one.

Send a request_id that is a UUID v5 of the repository's full name so a retried call returns the run it already started. The key's webhook_url reports when each run finishes, with session_url to read the pull request from.

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

Why run it on Rush?

Accessibility lint catches what is visible in JSX, but a missing dialog title or an unlabeled input that only exists after a click is found when the rendered tree is checked. Adding axe to tests that already render those states is the cheapest way to make the check fail CI, and the work is mostly reading each violation and fixing the right component. The agent does that reading in its sandbox, runs the suite after each fix, and keeps the reports.

The pull request is one assertion per test and a handful of markup fixes, so review is a list of rule ids. Across several apps the runs go in parallel, each with its own report and pull request.

Frequently asked questions

Why turn off the color-contrast rule?

jsdom does not lay out or paint, so axe cannot compute the colors a rule needs and reports contrast as incomplete rather than failing. Disabling it in configureAxe keeps the output to rules jsdom can evaluate. Contrast stays with the Storybook a11y addon, which runs in a real browser.

Will this make the suite slow?

Each axe() call walks the rendered DOM once, after the test has already rendered it, so the cost is a fraction of the render and the MSW round-trips the tests already pay. The agent reports the suite's duration before and after from its own runs.

What if a violation is in a library component?

The ui components wrap Radix primitives, which ship accessible markup; most findings come from the wrapper's props, such as a missing title passed to the dialog. When a violation really is inside a dependency, the agent documents it with the rule id and leaves the assertion skipped rather than patching node_modules.

Does this replace the jsx-a11y ESLint rules?

No. The lint rules catch static problems in the editor before a test runs; axe checks the rendered tree, including states that only exist after interaction. The pull request keeps both, and CI already runs yarn lint in the same job as yarn test.

More Vitest jobs

The same job on other stacks

Keep reading