A developer you work with mentions “running axe” on the site, or a vendor’s report quotes rule names like button-name and color-contrast. You want to see the same results yourself, so you can follow the conversation and check that fixes really landed.
This guide covers the free axe DevTools browser extension: how to install it, run a scan, read what it reports, deal with the items it marks for review, and pass issues to a developer in a form they can act on. You do not need to be a developer. You do need to be willing to open your browser’s developer tools, which sounds scarier than it is.
What axe is and why so many tools use it
axe is an accessibility testing engine made by Deque Systems. The core engine, axe-core, is open source, and a lot of other tools are built on it, including the accessibility audits in Google Lighthouse. So if you have seen a Lighthouse report, you have already seen some axe rules at work.
The axe DevTools extension wraps that engine in a panel inside Chrome, Edge or Firefox developer tools. The free version scans the page you are on and lists the problems it finds. Deque also sells paid tiers that add guided tests, saved reports and more; this guide sticks to the free extension. Deque updates the interface from time to time, so button labels may differ slightly from what is described here.
Like every automated checker, axe catches only part of the barriers on a page. It is a strong first pass, not a full test.
Installing the axe accessibility checker and running a scan
- Install axe DevTools from your browser’s extension store (Chrome Web Store, Edge Add-ons or Firefox Add-ons).
- Open the page you want to test. Log in first if it is a member page, and use staging if you are testing changes before they go live.
- Open developer tools. The usual ways are pressing F12, or right-clicking the page and choosing Inspect.
- Find the axe DevTools tab along the top of the developer tools panel. If you do not see it, look under the double arrow that hides extra tabs.
- Start a full-page scan.
The scan tests the page as it is at that moment. That is a feature. Open the mobile menu, expand an FAQ, trigger a form error or open a popup, then scan again, and axe checks the content that just appeared. Many real problems live in those hidden states, and a scan of the closed page will never find them.
Developer tools can dock to the side or bottom of the window. Docking to the side and narrowing the page also lets you scan the mobile layout of a responsive theme.
Impact levels and rule names
After a scan, axe shows a total count and a list of issues grouped by rule. Each rule has a short name and a plain description, such as “Images must have alternate text” or “Buttons must have discernible text.”
Every issue carries an impact level:
| Impact | What it usually means in practice |
|---|---|
| Critical | Likely to block some users completely, for example a form field with no label or a button with no name |
| Serious | Causes real difficulty, for example low contrast body text |
| Moderate | Causes some friction, often structural problems |
| Minor | An annoyance, worth fixing when you are in that code anyway |
Impact is a helpful guide, but it is not the same as priority for your site. A “serious” contrast problem on the checkout button matters more than the same problem on a 2019 blog post nobody reads.
Open an issue and axe shows each affected element: a snippet of its HTML, a CSS selector that pinpoints it, and options to highlight it on the page or jump to it in the Elements panel. There is also a link to Deque’s explanation of the rule, which says why it matters and how to fix it. These explanations are clear and worth reading even if you will never write code.
Rules you will meet on most WordPress sites
image-alt: an image with no alt attribute. Often from sliders, galleries or page builder widgets.button-nameandlink-name: icon-only buttons and links with no accessible name. Menu toggles, search icons, social icons, carousel arrows. Our post on when aria-label helps and when it hurts covers the right fix.label: a form field with no label. Newsletter boxes and search fields are the usual suspects.color-contrast: text below the WCAG AA contrast ratio. Light gray text and white text on brand colors are common causes.html-has-lang: the page does not declare its language, so screen readers may guess the wrong pronunciation.
Best practices versus WCAG failures
Some axe rules map directly to WCAG success criteria. Others are best practices, such as region (content not inside a landmark) or heading-order. The extension’s settings let you include or leave out best-practice results. Best practices are worth fixing, but if you are working through a list against WCAG 2.2 AA, sort WCAG failures first and keep best practices as a second list.
Needs review: the part people skip
Some checks axe cannot decide with confidence. The classic case is color contrast on text over a background image or gradient: axe can see the text color but not reliably the pixels behind it. Instead of guessing, it puts these into a “needs review” group.
axe tends to be conservative about what it calls a violation, so this group often holds real problems that simply need a human to confirm. Go through it:
- Highlight each item on the page and look at it.
- For contrast items, sample the actual colors with a contrast checker, using the lightest part of the background behind the text.
- Mark each one as a real issue or as fine, and note why. Next time you scan, you will not have to decide again from scratch.
If you ignore needs review, you are throwing away some of the most useful information axe gives you.
Sharing issues with a developer
“axe says there are 23 problems” does not help anyone. Whoever fixes the site needs to find each issue fast and know when it is done. For each issue, send:
- The page URL, and the state the page was in (logged in, menu open, form submitted with errors).
- The axe rule name and its impact.
- The CSS selector and HTML snippet axe shows for the element.
- A screenshot with the element highlighted.
- The browser you used.
Group issues by template, not by page. If the footer newsletter field has no label on every page, that is one issue in the footer widget. Developers fix templates, and a list grouped that way is shorter and easier to plan.
The free extension’s export options vary by version. Copying the details into a shared spreadsheet or ticket system always works. If you later commission a full audit, compare its report against your own axe findings; our guide to reading an audit report lists what a good one should contain.
After the fixes, scan the same page in the same state again. If the issue count did not drop, the fix may have gone to the wrong template, or a caching plugin may be serving the old page.
What axe will not tell you
A page with zero axe issues can still be unusable. axe does not:
- Use the keyboard. It cannot tell whether a dropdown opens without a mouse or whether focus gets stuck in a popup.
- Judge words. alt=”logo” on a photo of your team passes. So do six links that all say “Learn more” if the code looks fine.
- Check whether the focus outline is visible, or hidden behind a sticky header.
- Listen. It cannot tell you whether a form error is announced or whether an “added to cart” message reaches a screen reader user.
- Test captions, transcripts or PDFs in any meaningful way.
Those need a person. The step-by-step testing method shows where the keyboard and screen reader passes fit after a scan.
Using axe alongside WAVE and Lighthouse
You do not have to pick one. WAVE draws icons on the page and is friendlier for non-developers; see our guide to reading WAVE. axe gives precise selectors that developers like. Lighthouse runs a subset of axe rules and wraps them in a score, which is quick but easy to misread; the post on what the Lighthouse score hides explains why. Using two of them on key pages catches more than either alone. For the wider toolkit, see the free testing tools sorted by job.
Frequently asked questions
Is axe DevTools free?
The axe DevTools browser extension has a free version that scans the current page and lists issues with explanations, which is enough for most small business owners and staff. Deque also sells paid tiers that add guided tests, saved reports and team features. The open source axe-core engine underneath is free and is built into many other tools.
Why does axe show fewer issues than WAVE?
They count differently. axe tends to report only issues it is confident about as violations, and puts uncertain ones in a needs review group. WAVE shows more alerts that a human should look at. Neither number tells you how accessible the page is; they are two different views of the same code, and both miss things only a person can test.
Does axe check against WCAG 2.2?
Yes. axe includes rules tagged for WCAG 2.0, 2.1 and 2.2 at levels A and AA, and the extension’s settings let you pick which standard to test against. Only a few of the 2.2 additions can be checked by a machine at all, such as target size. Most of the others, like focus not obscured or accessible authentication, still need a person.
Can I fix every axe issue myself in WordPress?
Some, yes. Missing alt text, unclear link text and heading levels can usually be fixed in the editor. Issues like unnamed icon buttons, missing form labels in a plugin or contrast in theme colors often need changes to theme settings, custom CSS or template code. Those are better left to a developer.
A scan is where testing starts. If you want a person to take your axe results further with keyboard and screen reader checks, our hands-on accessibility testing picks up there, and the wider picture of accessibility services for US businesses shows how testing, fixes and monitoring connect.
Next in this series: Lighthouse Accessibility Score: What 100 Really Means
