How to Use axe-core for Accessibility Audits
Deque Systems created axe-core in 2015 with a design philosophy they call "the axe manifesto": automated accessibility testing should have zero false positives. While no tool achieves absolute zero, axe-core's rule definitions are deliberately conservative, only flagging issues where the tool can determine with high confidence that a genuine WCAG violation exists. This means axe-core may not flag every issue on a page, but when it does flag something, the finding is almost always a real problem that needs fixing. This low false positive rate is why axe-core became the dominant engine: developers trust its results and act on them rather than dismissing findings as noise.
Understand What axe-core Tests
axe-core organizes its 100+ rules into categories tagged by WCAG version and conformance level. The main tags are wcag2a (WCAG 2.0 Level A), wcag2aa (WCAG 2.0 Level AA), wcag21a (WCAG 2.1 Level A), wcag21aa (WCAG 2.1 Level AA), wcag22aa (WCAG 2.2 Level AA), and best-practice (rules that improve accessibility but are not required by any specific WCAG criterion). Each rule maps to one or more specific WCAG success criteria, so when a violation is reported, you know exactly which requirement it fails.
The rules fall into several testing categories. Structural rules check HTML semantics like heading hierarchy, landmark roles, list markup, and table structure. Attribute rules verify that elements have required accessibility attributes like alt text on images, labels on form controls, and lang on the html element. ARIA rules validate that ARIA roles, states, and properties are used correctly, including checking for valid role values, required owned elements, and attribute compatibility. Color rules evaluate text and non-text contrast ratios against WCAG minimums. Keyboard rules check for elements that are visible and interactive but not keyboard-focusable.
axe-core evaluates the rendered DOM, not the source HTML. This is an important distinction because many accessibility issues only appear after JavaScript execution, CSS application, and dynamic content loading. An image might have its alt text set via JavaScript after page load; a form label might be hidden by CSS display:none (making it visually absent but programmatically present); an ARIA attribute might be added dynamically by a framework. axe-core sees the page as the browser renders it, catching issues in the actual user experience rather than just the source code.
Use the axe DevTools Browser Extension
The axe DevTools browser extension is the fastest way to start using axe-core. Install it from the Chrome Web Store, Firefox Add-ons, or Edge Add-ons. Once installed, open your browser's developer tools (F12), find the "axe DevTools" tab, and click "Scan ALL of my page." The extension runs axe-core against the current page and displays results organized by severity.
Results are grouped into four impact levels. Critical violations completely prevent users from accessing content or functionality, such as a form with no submit mechanism that keyboard users can activate. Serious violations cause significant difficulty, such as text with insufficient contrast that low-vision users struggle to read. Moderate violations cause some difficulty or confusion, such as a heading hierarchy that skips a level. Minor violations have a small but measurable impact, such as a missing landmark role on a secondary navigation section.
Clicking a violation expands its details, showing the specific WCAG criterion violated, a description of the issue, the HTML of each affected element, and a "More info" link to Deque University's detailed remediation guidance for that rule. The extension also highlights the affected element on the page, making it easy to locate visually. You can re-scan the page after making fixes to verify that the issue is resolved.
The free version of axe DevTools runs the full automated rule set with no limitations. The paid Pro version adds Intelligent Guided Tests (IGTs) that structure manual testing into step-by-step workflows, helping evaluators check the 60-70% of WCAG criteria that automation cannot cover. If your budget allows it, Pro is worth the investment because it extends axe from an automated-only tool into a complete audit tool that guides manual evaluation.
Integrate axe-core Into Your Test Framework
For Playwright, install @axe-core/playwright (npm install --save-dev @axe-core/playwright). In your test file, import AxeBuilder from the package. After navigating to a page with page.goto(), create an AxeBuilder instance with new AxeBuilder({ page }), call .analyze(), and assert that the returned results.violations array is empty. This runs a full axe-core scan as part of your test, failing the test if any violations are found.
For Cypress, install cypress-axe (npm install --save-dev cypress-axe axe-core). In your support file (cypress/support/e2e.js or equivalent), import 'cypress-axe'. In your test, call cy.injectAxe() after cy.visit() to load axe-core into the page, then call cy.checkA11y() to run the scan and fail the test on violations. cy.checkA11y() accepts optional parameters for element scope, rule configuration, and violation callback, giving you the same configurability as the direct axe-core API.
For Selenium WebDriver, install axe-webdriverjs (npm install --save-dev @axe-core/webdriverjs for Node.js). Create an AxeBuilder instance with new AxeBuilder(driver), call .analyze(), and process the results. The Selenium integration works with all WebDriver-compatible browsers including Chrome, Firefox, Safari, and Edge. Java, Python, Ruby, and C# bindings are also available through language-specific axe packages.
For React development, @axe-core/react runs axe-core during development and logs accessibility violations directly to the browser console as you work. It runs only in development mode (not production builds) and provides immediate feedback as you write components, catching issues before they even reach the test phase. Import and initialize it in your application's entry point, and violations appear in the console as warnings with element references and remediation links.
Configure Rules and Tags
axe-core's configuration API lets you control which rules run, which elements are analyzed, and how results are categorized. The withTags() method (or the runOnly.values option in the raw API) selects rules by their WCAG tag. Using ['wcag2a', 'wcag2aa', 'wcag21aa'] runs all rules relevant to WCAG 2.1 Level AA conformance, which is the standard most laws require. Adding 'wcag22aa' includes the newer WCAG 2.2 criteria if your compliance target includes those.
The disableRules() method suppresses specific rules by ID. This is appropriate for known issues with planned remediation timelines, third-party content you cannot modify, or rules that conflict with your application's specific accessibility requirements. Document every disabled rule with a justification and a ticket reference so the suppression is transparent and temporary. Common candidates for temporary suppression include color-contrast (while a design system update is in progress), landmark-one-main (on pages with intentional multi-main layouts), and region (on legacy pages being migrated to landmark-based layouts).
The include() and exclude() methods control which DOM subtrees are analyzed. Exclude third-party widgets, advertising iframes, and embedded content whose accessibility you cannot control. Include specific components when running focused component-level tests. These scope controls prevent irrelevant violations from cluttering your results and ensure your team focuses on issues within their control.
Custom rules can be added to axe-core's rule set using the axe.configure() method or the withRules() option. Custom rules are useful for enforcing project-specific accessibility standards beyond WCAG, such as requiring specific ARIA patterns on custom components, enforcing minimum target sizes that exceed WCAG minimums, or checking for organization-specific accessibility requirements. Creating effective custom rules requires understanding axe-core's check and rule architecture, which is documented in the axe-core developer guide on GitHub.
Interpret and Act on Results
The results object from analyze() contains four arrays. The violations array lists definite WCAG failures that need fixing. The passes array lists elements that passed applicable checks, useful for confirming that specific accessibility features are in place. The incomplete array lists elements that need human review because axe-core could not determine pass or fail automatically. The inapplicable array lists rules that did not apply to the page, for example, the video-caption rule on a page with no video elements.
Each violation object includes the rule id (like "image-alt" or "color-contrast"), a human-readable description, the WCAG tags that categorize the violation, the impact level (critical, serious, moderate, minor), a help URL linking to Deque's remediation documentation, and a nodes array listing each affected element. The nodes array is the actionable part: each entry contains the element's HTML, its CSS selector, an XPath, and a failureSummary explaining why it failed.
Prioritize remediation by impact level first, then by frequency. A single critical violation (like a form that cannot be submitted via keyboard) takes priority over ten moderate violations (like skipped heading levels). Among equal-impact violations, fix the ones affecting the most elements first, because these are usually template or component-level issues where one code change resolves many instances across the site.
Track violations over time to measure progress. Record the total violation count and breakdown by impact level after each scan. Set a target, such as reducing violations by 20% per sprint or reaching zero critical violations within a quarter. Tracking creates accountability and demonstrates progress to stakeholders, auditors, and legal counsel.
Common axe-core Rules and What They Mean
Understanding the most frequently triggered rules helps developers fix issues faster. The image-alt rule checks that every img element has an alt attribute. The fix is adding descriptive alt text for informational images or alt="" for decorative ones. The color-contrast rule verifies that text meets minimum contrast ratios (4.5:1 for normal text, 3:1 for large text). The fix is adjusting text or background colors. The label rule checks that every form input has an associated label. The fix is adding a label element with a for attribute matching the input's id.
The heading-order rule checks that headings do not skip levels (for example, h2 followed by h4 with no h3). The landmark-one-main rule verifies that the page has exactly one main landmark. The document-title rule checks that the page has a title element with content. The html-has-lang rule verifies that the html element has a lang attribute. These structural rules are all straightforward to fix and address fundamental accessibility requirements.
ARIA-specific rules like aria-allowed-attr, aria-required-attr, aria-valid-attr-value, and aria-roles check that ARIA attributes are used according to the WAI-ARIA specification. These rules catch common ARIA mistakes like using role="header" (not a valid ARIA role; use role="banner"), adding aria-expanded to an element that does not support it, or setting aria-hidden="true" on a focusable element (which hides it from screen readers but leaves it keyboard-reachable, creating a confusing ghost element).
axe-core is the standard engine for automated accessibility testing. Use the browser extension for manual page auditing, integrate it into your test framework for continuous regression prevention, and configure rules and exclusions to match your WCAG compliance target and remediation timeline.