Forem: Cameron Cundiff

Introducing @accesslint/jest: progressive accessibility testing for Jest

Cameron Cundiff — Sat, 18 Apr 2026 18:18:18 +0000

This post is for the team rolling out accessibility testing: developer tooling, CI platform, design systems, frontend tooling, or their engineering managers. Enabling accessibility tests on greenfield code is straightforward. On an existing codebase it's harder: the suites typically contain hundreds or thousands of known violations no team has prioritized.

Teams have typically tried four approaches and watched each erode. Gating on zero turns CI red across the suite. A suppressions file decays as reviewers add entries faster than they retire them. Per-test opt-in grows coverage slowly and leaves untouched components unchecked. Audit-once-and-ticket produces a backlog that drifts from reality. The common thread: none of them separate "the backlog that already exists" from "new regressions."

@accesslint/jest addresses this rollout problem with two features: a snapshot-baseline workflow that gates CI on new violations rather than total count, and a trend-report sidecar that produces the evidence leadership typically asks for to justify continued accessibility investment. It adds a toBeAccessible() matcher on @accesslint/core, an independent WCAG 2.2 engine validated against the W3C ACT-R corpus. The rest of this post covers the rollout path, the reporting layer, the migration from jest-axe, and where the two libraries overlap.

For the migration command:

npx @accesslint/codemod jest-axe 'src/**/*.test.{ts,tsx}'

Snapshot baselines with auto-ratchet

Snapshot baselines address that gap directly. toBeAccessible({ snapshot: "name" }) locks the current violations as a baseline and fails only on new ones. When violations get fixed, the baseline shrinks automatically.

test("login form has no new a11y violations", () => {
  const { container } = render(<LoginForm />);
  expect(container).toBeAccessible({ snapshot: "login-form" });
});

On the first run, the matcher creates accessibility-snapshots/login-form.json and passes, capturing whatever violations exist today. Commit that file alongside your tests. On later runs:

New violations appear, the assertion fails with the diff (only the new ones).
Some existing violations get fixed and no new ones appear, the matcher trims them from the baseline. You commit the smaller snapshot file and move on.
Force a full refresh by running with ACCESSLINT_UPDATE=1 (for intentional scope changes).

jest-axe doesn't offer this workflow directly. Adopting it on an existing codebase usually means either gating all tests on zero violations or writing per-test suppressions.

A rollout path

For a platform-team rollout across several repos or teams:

Pilot in one repo with a known backlog. Wrap a handful of existing tests with toBeAccessible({ snapshot: "..." }). Run once to generate baselines, commit them with the tests. Verify the workflow end to end: CI stays green on the first push, a regression PR fails cleanly, a fix PR produces a baseline diff reviewers can read.
Publish the matcher as a shared preset. Add @accesslint/jest to the setupFilesAfterEnv of your org's internal Jest preset (or the shared test-config package your teams consume). Teams pick it up by upgrading the preset, not by hand-editing each repo.
Let teams opt in at their pace, with the preset on by default. Each repo that adopts the preset generates its own accessibility-snapshots/ directory on first run. CI passes. The platform team isn't responsible for each repo's a11y debt; the matcher reports rather than enforcing.
Track the trendline automatically. The matcher writes a history sidecar next to each snapshot, and @accesslint/report aggregates those into trend data for leadership. See the next section for details.
Raise the gate per test, not per project. When a baseline reaches zero for a given test, the owning team drops the snapshot option. That test becomes a strict gate. The transition from "managed backlog" to "strict gate" is incremental and self-directed by the owning team, and you as the platform team don't have to orchestrate a flag day.

The practical effect from the platform side: adoption doesn't block on a cleanup sprint, and rollback is cheap (remove from the preset). The cost is the baseline JSON files committed per repo, which stay inside the repos that own them.

Evidence that the initiative is working

Accessibility initiatives tend to die between budget cycles. Leadership approves the work in Q1, developers fix violations through Q2, and by Q3 someone asks "where did the number go?" Without a quantitative trend, the answer is usually a screenshot of last quarter's number. Which works for one cycle.

@accesslint/jest emits a .history.ndjson sidecar next to every snapshot. Each line records a snapshot event (created, ratchet-down, or force-update):

{"ts":"2026-04-18T10:42:03Z","name":"login-form","event":"ratchet-down","added":0,"removed":3,"total":12,"addedRules":[],"removedRules":["text-alternatives/img-alt","labels-and-names/form-label","distinguishable/color-contrast"]}

The sidecar is append-only, committed to git alongside the snapshot JSON, and written automatically. Test authors don't need to be aware of it.

@accesslint/report reads the sidecars and produces a trend at whatever scope you point it to: a single repo, a directory of repos, or the whole monorepo. Output can be rolled into whatever cadence fits: a weekly digest for the platform channel, a JSON feed for an existing reporting system, a quarterly summary for a leadership review.

The property that matters: the measurement is a byproduct of the matcher running. Product teams don't instrument anything. Platform teams don't operate a service. The trend data exists because the test suite ran.

Actionable failure messages

When an assertion fails, the matcher writes a failure block that's designed to be useful in your test-runner output without opening a browser tab:

Expected element to have no accessibility violations, but found 2:

  [critical] text-alternatives/img-alt (WCAG 1.1.1, A) — Image element missing alt attribute.
    selector: div > img
    fix: add-attribute alt=""
    guidance: Every image needs an alt attribute. For informative images, describe the content or function concisely. For decorative images (backgrounds, spacers, purely visual flourishes), use alt='' to hide them from screen readers. [...]

  [critical] labels-and-names/form-label (WCAG 4.1.2, A) — Form element has no accessible label.
    selector: div > input
    context: type: email
    fix: Add a <label> element associated via the for attribute, or add an aria-label attribute
    guidance: Every form input needs an accessible label so users understand what information to enter. [...]

Each violation includes the impact in brackets, the namespaced rule ID, the WCAG success criterion and level, a one-line fix suggestion, and prose guidance, all pulled from rule metadata in @accesslint/core. The goal is that a developer reading a failing test log can usually tell what to change without leaving the terminal.

Component-scoped auditing, by default

When the element you assert on isn't document.documentElement, page-level rules (html-has-lang, document-title, region, bypass, and others) are skipped automatically. Most Testing Library tests render into a container, so the matcher applies the right rule set for component tests without extra configuration:

test("SubmitButton is accessible", () => {
  const { container } = render(<SubmitButton label="Send" />);
  // region / document-title / html-has-lang rules skip automatically
  expect(container).toBeAccessible();
});

For full-page audits, pass document.documentElement or use { componentMode: false } to force them back on. It's a small thing, but it means component tests stop flagging landmark rules that don't apply to the unit under test.

Smaller ergonomic additions

Smaller conveniences:

Auto-registration. setupFilesAfterEnv: ["@accesslint/jest"] is the whole setup. No explicit expect.extend() call, no separate /extend-expect entry.
Synchronous matcher. expect(container).toBeAccessible() returns immediately: no await, no intermediate results variable. Reads the same as other jest-dom matchers (toBeInTheDocument, toHaveStyle).
Impact threshold. toBeAccessible({ failOn: "serious" }) only fails on serious and critical violations, useful when gating CI on a policy line rather than zero-tolerance. (jest-axe has an equivalent via its impactLevels config; the AccessLint variant is per-call rather than per-project.)
TypeScript out of the box. The package augments both the modern @jest/globals expect.Matchers interface and the legacy global jest.Matchers namespace, so expect(el).toBeAccessible(...) type-checks under either setup.

Migrating from `jest-axe`

The codemod handles the common patterns. Run with --dry --print first to inspect the diff:

npx @accesslint/codemod jest-axe 'src/**/*.test.{ts,tsx}' --dry --print

A typical test file transforms to:

- import { axe, toHaveNoViolations } from "jest-axe";
- expect.extend(toHaveNoViolations);
+ import "@accesslint/jest";

  test("form is accessible", async () => {
    const { container } = render(<Form />);
-   const results = await axe(container);
-   expect(results).toHaveNoViolations();
+   expect(container).toBeAccessible();
  });

What the codemod leaves for human review:

configureAxe({ rules: ... }) globals. AccessLint passes options per call rather than per project. The codemod leaves configureAxe imports in place and adds a TODO(accesslint-codemod): comment reminding you to reapply those settings via toBeAccessible({ disabledRules, failOn, ... }) where needed.
Per-call rule filters with axe IDs. axe(container, { rules: { "color-contrast": { enabled: false } } }) collapses to expect(container).toBeAccessible() with a TODO. AccessLint uses namespaced IDs. Remap to toBeAccessible({ disabledRules: ["distinguishable/color-contrast"] }). The jest package README includes a mapping table for the most common rules.
Swapping the devDep. The codemod doesn't touch package.json. Run npm install --save-dev @accesslint/jest && npm uninstall jest-axe after you're happy with the diff.

Full transform rules and flags are documented in the @accesslint/codemod README.

What doesn't change

Plenty stays the same across the two libraries, which is the point:

WCAG 2.2 Level A and AA coverage is the goal both implementations aim at. AccessLint and axe-core are independent rule engines; expect rule outputs to agree on most violations and differ in count or phrasing on others.
Testing Library compatibility is identical. toBeAccessible() accepts any Element: container, screen.getByRole('form'), document.body, or a plain document.createElement(...). React, Vue, Svelte, and Angular Testing Library all work the same way they did before.
Jest setup shape is the same. testEnvironment: "jsdom" and a setupFilesAfterEnv entry, one line added to your config.

Violation counts can differ from what axe-core reports on the same markup. That's expected from independent implementations of the same specifications, not a bug. Treat those differences as a point to investigate rather than a regression signal.

Install and first test

For a new project, or to try the matcher alongside an existing test file:

npm install --save-dev @accesslint/jest

// jest.config.js
module.exports = {
  testEnvironment: "jsdom",
  setupFilesAfterEnv: ["@accesslint/jest"],
};

// LoginForm.test.tsx
import { render } from "@testing-library/react";
import { LoginForm } from "./LoginForm";

test("LoginForm is accessible", () => {
  const { container } = render(<LoginForm />);
  expect(container).toBeAccessible();
});

The package README has deeper coverage of snapshot baselines, options, and framework-specific recipes for Vue / Svelte / Angular.

Status and roadmap

A few things a platform team evaluating adoption should know:

Versioning. @accesslint/jest is on semver. The 0.x series is still settling, so minor bumps may change behavior in documented ways; patch releases are reserved for bug fixes. Published with npm provenance so attestations are verifiable in your registry. License is MIT.
Rule-engine stability. The rule catalog ships in @accesslint/core and is pinned by @accesslint/jest as a workspace dependency. Rule additions arrive in core minor versions; the matcher surfaces them only on upgrade. New rules that fire on existing content appear as new violations the snapshot baselines don't yet account for, so they're treated as regressions until the owning team fixes them or force-refreshes the baseline with ACCESSLINT_UPDATE=1. Plan core upgrades accordingly.
Sibling packages. Equivalent matchers ship for Vitest (@accesslint/vitest) and Playwright (@accesslint/playwright). All three share a runner-agnostic matcher core, so the option surface and failure-message format are consistent across stacks. Useful if your org runs mixed runners.
Reporting. @accesslint/report ships alongside the matcher packages; see the Evidence section above for how it fits into the rollout.
Testing Library ecosystem listing. A page is pending review at testing-library-docs PR #1535.
Feedback channel. GitHub Issues is the primary signal mechanism. Rule-coverage gaps, migration patterns the codemod doesn't cover, and framework integrations that aren't documented are all useful inputs for the v0.x series.

If @accesslint/jest ends up in your org's Jest setup, please report anything you run into.

Accessibility Tooling for Agentic Coding Loops

Cameron Cundiff — Mon, 23 Feb 2026 00:41:23 +0000

Coding agents are writing and modifying front-end code at scale. If your team maintains a design system or owns accessibility on a product, this changes the calculus: code that once went through a human review loop is now generated in seconds, often without any accessibility check at all.

Existing tools weren't designed for this. They assume a human in the loop; run a scan, read the report, interpret the findings, figure out the fix. That workflow requires domain expertise at every step.

An agent operating in a coding loop needs something different. Not a report to interpret, but structured diagnostics it can act on directly: machine-executable fix instructions, DOM context for reasoning, a fixability classification for triage, and a verification mechanism to confirm fixes landed.

@accesslint/mcp is an MCP server built on @accesslint/core, a rule engine designed from the ground up for agent consumption. It exposes tools for auditing HTML (as a string, file, or URL), diffing before-and-after audits, and listing rules; for Claude Code, Cursor, Windsurf, or any MCP-compatible agent.

This post walks through the design decisions behind the tool: how violations are structured, how fixability classification works, what context collection looks like per rule, and how the diff loop closes the audit-fix-verify cycle.

Does it actually help?

Before getting into the design, here's the evidence. Both approaches - agent with MCP tools vs. agent alone - were benchmarked across 25 HTML test cases covering 67 fixable WCAG violations (3 runs each, Claude Opus):

	With @accesslint/mcp	Agent alone
Violations fixed	99.5% (200/201)	93.5% (188/201)
Regressions	1.7 / run	2.0 / run
Cost	$0.56 / run	$0.62 / run
Duration	270s / run	377s / run
Timeouts	0 / 63 tasks	2 / 63 tasks

The MCP-assisted path uses 23% fewer output tokens per run. Without tools, the agent has to recall WCAG rules from training data, reason about which rules apply to which elements, and then fix them. The MCP replaces that open-ended reasoning with structured output: specific rule IDs, CSS selectors pointing to exact elements, and concrete fix suggestions. The agent skips straight to applying fixes. Fewer reasoning steps, fewer tokens, less time, lower cost.

The largest gains are on complex cases. A test case with 6 violations across nested landmark structures completed in 25-38 seconds with MCP tooling. The agent alone timed out at 90 seconds in 2 of 3 runs.

Anatomy of a violation

When an agent calls audit_html, each violation includes:

1. [CRITICAL] labels-and-names/button-name
   Button has no discernible text.
   Element: button.icon-search
   HTML: <button class="icon-search" onclick="openSearch()"><svg aria-hidden="true">...</svg></button>
   Fix: add-text-content
   Fixability: contextual
   Browser hint: Screenshot the button to identify its icon or visual label,
   then add a matching aria-label.
   Context: Classes: icon-search
   Guidance: Screen reader users need to know what a button does. Add visible
   text content, aria-label, or aria-labelledby. For icon buttons, use
   aria-label describing the action (e.g., aria-label='Close'). If the button
   contains an image, ensure the image has alt text describing the button's
   action.

Each field is deliberate:

Fix is a structured instruction from a closed set: add-attribute, set-attribute, remove-attribute, add-element, remove-element, add-text-content, or suggest. The first six are mechanically executable. suggest is the escape hatch for violations where the fix depends on intent. About 75% of rules provide a mechanical fix; the remaining 25% use suggest.

Fixability classifies the violation, not the fix. The button-name rule provides a mechanical fix type (add-text-content) that satisfies the rule. But its contextual classification signals that the agent should use the collected context to determine what text to add. More on this below.

Context is collected per-rule from the DOM. Guidance provides the remediation principle behind the rule, written for direct LLM consumption. Browser hint, present on 26 of 92 rules, tells agents with browser access how to verify or improve a fix using screenshots or DevTools.

Determining "Fixability"

Every rule carries a fixability classification that the MCP server surfaces on each violation:

Mechanical (20 rules): Deterministic. A positive tabindex gets set to "0". A non-valid ARIA role gets flagged with the correct value. No ambiguity.
Contextual (65 rules): Requires surrounding context, but an LLM can reason about it. The violation's context and guidance fields provide the inputs. The structured fix provides a safe floor.
Visual (4 rules): Requires rendered output. Color contrast, primarily. Browser hints tell the agent how to inspect computed styles or screenshot the element.

The interaction between fixability and the structured fix is the core design decision. Take button-name: the fix type is add-text-content, which is mechanically executable. But what text? The contextual classification is the signal to use the collected context. The violation reports Classes: icon-search. That's developer intent that never made it into the accessible name. The agent reads the class, infers the action, and adds aria-label="Search".

This also maps to list_rules filtering. An agent or workflow can query rules by fixability to scope an audit pass: mechanical-only for automated batch remediation, contextual for agent-assisted passes, visual for flagging to human review.

Gathering context

Each rule gathers the specific context its violation type needs. This is where the design diverges most from existing tools, which tend to report the element and stop.

button-name reports CSS class names (btn-close, icon-search), the enclosing form's label, and the nearest heading. Class names are the key signal. They encode developer intent that never made it into the accessible name. A button with class icon-search inside a form labeled "Site search" gives the agent two independent signals pointing to aria-label="Search".

img-alt checks whether the image is inside a link (and captures the href), looks for a figcaption, and captures adjacent text. If a figcaption already describes the image, alt="" avoids redundant adjacent text. If the image is a standalone link, the href helps the agent infer purpose.

form-label reports the input's type, name, placeholder, and id, plus the full accessible name computation chain: aria-labelledby resolution, aria-label, associated <label>, title, and placeholder fallback.

link-name captures the href, nearby heading text, and parent element context. For a link wrapping only an icon, the href and surrounding headings are often enough to infer purpose.

The goal is to front-load enough information that the agent can reason about the fix in a single pass, without a round-trip to read more of the document.

Looping on diffs

The diff loop is the verification mechanism. The workflow:

The agent calls audit_html with name: "before" to audit and store the result.
The agent applies fixes.
The agent calls diff_html with the updated markup and before: "before".

The server audits the new HTML, diffs against the stored result, and returns:

Summary: 2 fixed, 1 new, 3 remaining

FIXED:
  - [CRITICAL] text-alternatives/img-alt at img[src="photo.jpg"]
  - [CRITICAL] labels-and-names/button-name at button.icon-search

NEW:
  - [SERIOUS] aria/aria-roles at div[role="buton"]
    ARIA role "buton" is not a valid role value.
    Fix: set-attribute role="button"

REMAINING:
  - [MODERATE] navigable/heading-order at h4
  - [MODERATE] distinguishable/link-in-text-block at a.subtle
  - [MINOR] text-alternatives/image-alt-words at img[alt="image of logo"]

Violations are matched by ruleId + selector. The agent gets a clear signal: what was fixed, what regressed (with the diagnosis and fix instruction for self-correction), and what remains.

The NEW category is critical. An agent that adds role="buton" (a typo) gets the regression surfaced immediately, with a structured fix to correct it. The loop is: audit, fix, diff, self-correct. No human in the middle.

Opening up the browser

26 rules carry a browser hint: an instruction for agents with browser access (screenshots, DevTools MCP) on how to verify or improve a fix.

For a visual rule like color-contrast:

Violation context includes computed colors and ratio. After changing colors, use JavaScript to read getComputedStyle() on the element and recalculate the contrast ratio. Screenshot the element to verify the fix looks correct in context.

For a contextual rule like button-name:

Screenshot the button to identify its icon or visual label, then add a matching aria-label.

These are opt-in. An agent without browser tools ignores them. An agent with browser MCP tools (Chrome DevTools, Playwright) can use them to bridge the gap between static analysis and rendered output, particularly for the 4 visual rules where static analysis alone can't fully verify the fix.

Handling page fragments

When the input HTML lacks <!DOCTYPE html> or <html>, the server auto-enables component mode, suppressing 22 page-level rules (document title, landmarks, lang attribute, etc.) that would produce false positives on isolated markup. The agent can override this with the component_mode parameter.

This means an agent auditing a React component, a partial template, or a code snippet gets relevant results without noise.

Architecture

The MCP server is a thin integration layer. The rule engine is @accesslint/core: 92 rules, zero runtime dependencies, synchronous execution. The API is runAudit(doc: Document): AuditResult. The server handles HTML parsing (happy-dom), fragment detection, audit state for diffing, and violation enrichment (joining each violation with its rule's fixability, browser hint, and guidance).

The core library covers 23 WCAG 2.1 success criteria across Level A and AA, scoped to what static DOM analysis can meaningfully check. Rules that throw during execution are caught and skipped; the audit always completes.

The library also exports lower-level primitives (getAccessibleName, getComputedRole, isAriaHidden) and a declarative rule engine for authoring rules as JSON with validateDeclarativeRule and compileDeclarativeRule. An agent can write, validate, and register new rules at runtime.

A note on the core engine

Every MCP tool call is a round-trip through the protocol, and an agent running audit-fix-diff in a loop may make dozens of them. Latency per call matters. Engines like axe-core were designed at the outset for the browser; the execution model is async and demonstrably slow¹. The latency accrues.

The rule engine is @accesslint/core: 92 rules, 23 WCAG 2.1 success criteria (Level A and AA), zero runtime dependencies, synchronous execution. The MCP server parses HTML with happy-dom and calls runAudit(doc): AuditResult. A typical component audit completes in single-digit milliseconds. At that speed, the bottleneck is the LLM, not the tooling.

The structured output described throughout this post (fix suggestions, fixability classifications, per-rule context, browser hints) are first-class fields on every violation, not bolted on after the fact. The rules are authored with agent consumption in mind.

To add the MCP server to Claude Code:

claude mcp add accesslint -- npx -y @accesslint/mcp

Or add it to any MCP client configuration:

{
  "mcpServers": {
    "accesslint": {
      "command": "npx",
      "args": ["-y", "@accesslint/mcp"]
    }
  }
}

What's next

Testing in the DOM is important for many accessibility tests, and doesn't have to be slow. Keep an eye out for improvements to the AccessLint StoryBook Addon soon that will help.

I'd love to hear from you! Please share questions and comments, or drop me a note, I'm always happy to nerd out on accessibility.

@accesslint/core vs axe-core benchmarks ↩